86 lines
5.9 KiB
Markdown
86 lines
5.9 KiB
Markdown
# 需求文档：ETL 全流程前后端联调（etl-fullstack-integration）
|
||
|
||
## 简介
|
||
|
||
基于已完成的 `admin-web-console` Spec 产出的前后端代码，进行一次完整的端到端联调验证。通过管理后台 API 提交 ETL 全流程任务（api_full），覆盖 ODS → DWD → DWS → INDEX 全链路，验证前后端协作、子进程执行、日志推送、错误处理等环节的正确性。同时收集精细计时数据，定位性能瓶颈。
|
||
|
||
## 术语表
|
||
|
||
- **联调**：将 admin-web 后端 API 与 feiqiu ETL CLI 串联，通过真实 API 调用触发 ETL 全流程执行
|
||
- **全选常用任务**：任务注册表中 `is_common=True` 的所有任务（排除工具类、手动导入、维护类等 `is_common=False` 的任务）
|
||
- **精细计时**：在 ETL 执行过程中，通过日志解析或 CLI 输出，记录每个阶段（ODS/DWD/DWS/INDEX）和每个子任务的耗时
|
||
|
||
## 需求
|
||
|
||
### 需求 1：服务启动与健康检查
|
||
|
||
**用户故事：** 作为开发者，我希望一键启动后端和前端服务，并确认服务健康可用，以便开始联调。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 启动后端服务, THE Backend_API SHALL 在 `http://localhost:8000` 上响应请求
|
||
2. WHEN 启动前端服务, THE Admin_Web SHALL 在 `http://localhost:5173` 上可访问
|
||
3. WHEN 调用 `POST /api/auth/login`, THE Backend_API SHALL 返回有效的 JWT 令牌
|
||
4. WHEN 调用 `GET /api/tasks/registry`, THE Backend_API SHALL 返回非空的任务注册表
|
||
5. WHEN 调用 `GET /api/tasks/sync-check`, THE Backend_API SHALL 确认后端任务注册表与 ETL 真实注册表同步
|
||
|
||
### 需求 2：全流程任务提交与执行
|
||
|
||
**用户故事：** 作为开发者，我希望通过后端 API 提交一个覆盖全链路的 ETL 任务，验证任务配置、CLI 构建、子进程执行的完整流程。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 提交 TaskConfig（api_full + full_window + 全选常用任务 + 自定义窗口 2025-11-01~当前时间 + 30天切分 + force-full）, THE Backend_API SHALL 验证配置有效并返回 CLI 命令预览
|
||
2. WHEN 提交任务到执行队列, THE Backend_API SHALL 创建队列任务并自动开始执行
|
||
3. WHILE ETL 子进程运行中, THE Backend_API SHALL 通过 WebSocket 推送实时日志
|
||
4. WHEN ETL 子进程完成, THE Backend_API SHALL 记录退出码、执行时长、完整日志到 task_execution_log
|
||
|
||
### 需求 3：执行监控与错误处理
|
||
|
||
**用户故事：** 作为开发者，我希望在任务执行过程中实时监控状态，对报错或警告及时发现并进行 DEBUG。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHILE 任务执行中, THE 监控脚本 SHALL 每 30 秒轮询执行状态和日志
|
||
2. WHEN 日志中出现 ERROR 或 WARNING 级别信息, THE 监控脚本 SHALL 立即记录并标记
|
||
3. WHEN 任务执行完成（成功或失败）, THE 监控脚本 SHALL 停止轮询并收集最终状态
|
||
4. IF 任务执行超过 30 分钟无新日志输出, THEN THE 监控脚本 SHALL 报告超时警告
|
||
5. IF 任务执行失败, THEN THE 监控脚本 SHALL 收集完整的 stderr 和错误上下文
|
||
|
||
### 需求 4：性能计时与瓶颈分析
|
||
|
||
**用户故事：** 作为开发者，我希望获得精细粒度的执行计时数据，以便发现性能瓶颈。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 任务执行完成, THE 报告 SHALL 包含总执行时长
|
||
2. WHEN 日志中包含阶段性时间戳, THE 报告 SHALL 解析并展示每个窗口切片的耗时
|
||
3. THE 报告 SHALL 标注耗时最长的 Top-5 阶段/任务
|
||
4. THE 报告 SHALL 包含每个窗口切片（30天）的独立耗时对比
|
||
|
||
### 需求 5：黑盒数据一致性测试
|
||
|
||
**用户故事：** 作为开发者，我希望在 ETL 全流程执行完成后，以黑盒视角对比数据上下游的字段差异和值差异，验证数据从 API 到 ODS 再到 DWD 再到 DWS 的完整性和正确性。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN ETL 全流程执行完成后, THE 联调脚本 SHALL 运行全链路检查器 `scripts/ops/etl_consistency_check.py`，执行 API→ODS→DWD→DWS 四层数据一致性检查
|
||
2. WHEN 执行 API vs ODS 检查时, THE 检查器 SHALL 对比 API JSON 落盘数据与 ODS 落库数据的字段完整性和值采样（随机 5 条记录的关键字段），覆盖所有已采集的 ODS 表
|
||
3. WHEN 执行 ODS vs DWD 检查时, THE 检查器 SHALL 对比 ODS 数据与 DWD 落库数据的行数、字段映射正确性和值一致性（含 EX 表合并比对）
|
||
4. WHEN 执行 DWD vs DWS 检查时, THE 检查器 SHALL 验证 DWS 聚合表的行数非空、数值列健全性（NULL 率、负值、min/max），标注异常指标
|
||
5. WHEN 值比对遇到白名单场景时, THE 检查器 SHALL 将 ETL 元数据列（`source_file`、`source_endpoint`、`fetched_at`、`payload`、`content_hash`）和 SCD2 管理列排除在值比对之外，并将 API 空字符串 `""` vs DB `None` 视为等价（标记为 whitelist）
|
||
6. WHEN 黑盒测试完成后, THE 检查器 SHALL 输出 Markdown 报告到 `ETL_REPORT_ROOT` 环境变量指定的目录
|
||
7. WHEN 黑盒测试报告生成后, THE 报告 SHALL 包含每张表的检查结果、差异明细（含白名单差异折叠展示）、通过/失败状态、字段级统计、以及汇总统计
|
||
|
||
### 需求 6：联调报告输出
|
||
|
||
**用户故事：** 作为开发者，我希望联调完成后获得一份综合报告，包含执行情况、性能数据、黑盒测试结果和可能的 DEBUG 信息。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE 报告 SHALL 包含：执行概要（任务参数、开始/结束时间、总时长、退出码）
|
||
2. THE 报告 SHALL 包含：性能报告（各阶段耗时、窗口切片耗时对比、Top-5 瓶颈）
|
||
3. THE 报告 SHALL 包含：黑盒测试结果摘要（API vs ODS 通过数/总数、ODS vs DWD 通过数/总数、DWD vs DWS 表概览、失败表清单、白名单差异数量）
|
||
4. IF 执行过程中出现错误或警告, THEN THE 报告 SHALL 包含 DEBUG 报告（错误摘要、相关日志片段、可能的原因分析）
|
||
5. THE 报告 SHALL 输出到 `SYSTEM_LOG_ROOT` 环境变量指定的目录
|