Neo-ZQYY/.kiro/specs/etl-fullstack-integration/requirements.md

需求文档：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~2026-02-20 + 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：联调报告输出

用户故事： 作为开发者，我希望联调完成后获得一份综合报告，包含执行情况、性能数据和可能的 DEBUG 信息。

验收标准

1. THE 报告 SHALL 包含：执行概要（任务参数、开始/结束时间、总时长、退出码）
2. THE 报告 SHALL 包含：性能报告（各阶段耗时、窗口切片耗时对比、Top-5 瓶颈）
3. IF 执行过程中出现错误或警告, THEN THE 报告 SHALL 包含 DEBUG 报告（错误摘要、相关日志片段、可能的原因分析）
4. THE 报告 SHALL 输出到 SYSTEM_LOG_ROOT 环境变量指定的目录