# 需求文档：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` 环境变量指定的目录
