HSAP/docs/DATA_LAKE_CHECKLIST.md

上传到数据湖实施清单

本文档用于执行“上传压缩包/文件夹 -> 自动分析 -> 审核 -> 版本入湖 -> 数据目录展示”的完整闭环。

1. 目标与边界

• 目标：把人工回传落盘升级为可追溯的数据入湖流水线。
• 范围：DMS（检测）与 Lane（2D 车道线）两条数据线。
• 原则：先入候选区，再自动分析，审核通过后才晋级正式版本。

2. 端到端流程

flowchart LR
uploadClient[UploadClient] --> stagingArea[StagingArea]
stagingArea --> qualityWorker[QualityWorker]
qualityWorker --> qualityReport[QualityReport]
qualityReport --> approvalQueue[ApprovalQueue]
approvalQueue --> curatedLake[CuratedDataLake]
curatedLake --> catalogIndex[CatalogIndex]
catalogIndex --> dataDirectory[DataDirectoryUI]

3. 阶段清单

阶段 A：上传接入

• 检查项：支持 zip 与目录上传，展示实时进度、失败重试、取消上传。
  • 完成标准：前端可看到 0-100% 进度，失败可重传，上传完成返回 candidate_id。
  • 责任角色：前端工程师、平台后端工程师。
• 检查项：上传文件落到 staging 区，不直接进入正式数据目录。
  • 完成标准：路径落到 lake/staging/<project>/<candidate_id>/；正式目录无未审数据。
  • 责任角色：平台后端工程师、运维工程师。
• 检查项：上传元数据落库（上传人、时间、来源、文件 hash、项目/任务）。
  • 完成标准：数据库可按 candidate_id 查询到完整元数据。
  • 责任角色：平台后端工程师。

阶段 B：自动分析

• 检查项：上传完成后自动触发异步分析任务（非阻塞 API）。
  • 完成标准：Redis/Worker 中出现分析任务，任务状态可在前端轮询或订阅。
  • 责任角色：平台后端工程师。
• 检查项：DMS 自动分析报告生成。
  • 完成标准：输出类别分布、框宽高分布、bbox 密度、train/val/test 计数。
  • 责任角色：算法工程师、平台后端工程师。
• 检查项：Lane 自动分析报告生成。
  • 完成标准：输出车道线数量分布、长度分布、曲率分布、train/val/test 计数。
  • 责任角色：算法工程师、平台后端工程师。
• 检查项：质量报告结构化落地（JSON）并可追溯。
  • 完成标准：lake/reports/<candidate_id>/quality.json 可读取，且数据库保存报告摘要。
  • 责任角色：平台后端工程师。

阶段 C：审核流

• 检查项：自动分析完成后自动提交审核单（附质量报告与关键指标）。
  • 完成标准：approvals 中出现对应记录，状态为 pending。
  • 责任角色：平台后端工程师。
• 检查项：审核通过后触发“晋级入湖”动作；驳回则保留候选并记录原因。
  • 完成标准：审批动作写入审计日志，审批意见可查询。
  • 责任角色：审核员、平台后端工程师。
• 检查项：审批链路可回放、可追责。
  • 完成标准：能按 candidate_id 追溯上传人、审核人、审核意见、执行任务、最终版本。
  • 责任角色：平台后端工程师、运维工程师。

阶段 D：版本入湖

• 检查项：通过审批的数据原子晋级到 curated 正式版本目录。
  • 完成标准：路径形如 lake/curated/<project>/<task>/v0001/，且不会覆盖已有版本。
  • 责任角色：平台后端工程师。
• 检查项：版本号规范化管理。
  • 完成标准：版本号连续递增（v0001, v0002），支持回查父版本/来源候选集。
  • 责任角色：平台后端工程师、数据治理负责人。
• 检查项：catalog/data-directory 自动刷新展示新版本。
  • 完成标准：前端数据目录可见新版本与质量摘要，不需手工改配置。
  • 责任角色：前端工程师、平台后端工程师。

阶段 E：运维与安全

• 检查项：失败重试与死信策略。
  • 完成标准：分析失败可重跑；超过阈值进入死信并告警。
  • 责任角色：平台后端工程师、运维工程师。
• 检查项：容量与配额控制（单包大小、单用户日配额、生命周期清理）。
  • 完成标准：超过限制明确拒绝并返回原因；staging 过期数据自动清理。
  • 责任角色：运维工程师、平台后端工程师。
• 检查项：权限与审计。
  • 完成标准：上传/审核/晋级都受 RBAC 控制，关键操作有审计日志。
  • 责任角色：平台后端工程师、安全负责人。

4. 数据目录展示规范（必须）

4.1 版本信息最小字段

• project / task / version
• created_at / source_candidate_id
• status（候选、待审、已晋级、已驳回）
• train_count / val_count / test_count

4.2 DMS 展示最小字段

• 类别分布（可视化）
• bbox 宽高分布（散点或密度）
• 框密度（box per image）
• train/val/test 样本计数

4.3 Lane 展示最小字段

• 每帧车道线数量分布
• 线长度分布
• 曲率分布
• train/val/test 样本计数

5. 目录与命名建议

• lake/raw/<project>/<date>/<upload_id>/：原始上传留存
• lake/staging/<project>/<candidate_id>/：待分析/待审核候选区
• lake/curated/<project>/<task>/v0001/：正式数据湖区
• lake/reports/<candidate_id>/quality.json：质量报告

6. 验收标准

• 文档可直接给工程团队逐条执行，不依赖口头补充。
• DMS 与 Lane 都有明确的自动分析指标与展示字段。
• 数据目录必须明确显示每个版本的 train/val/test，不允许只给总量。
• 上传、分析、审核、入湖全链路具备可追溯 ID（upload_id / candidate_id / approval_id / job_id）。
• 任一阶段失败时，系统能给出可读错误原因与重试入口。