87 lines
4.6 KiB
Markdown
87 lines
4.6 KiB
Markdown
# 实现计划：ETL 全流程前后端联调（etl-fullstack-integration）
|
||
|
||
## 概述
|
||
|
||
基于 `admin-web-console` 已完成的前后端代码，进行端到端联调验证。通过后端 API 提交 api_full 全流程 ETL 任务（自定义窗口 2025-11-01~2026-02-20，30天切分，force-full，全选常用任务），实时监控执行过程，收集性能数据，最终生成综合报告。
|
||
|
||
## 任务
|
||
|
||
- [ ] 1. 服务启动与健康检查
|
||
- [ ] 1.1 启动后端服务（`apps/backend/`，uvicorn :8000），确认 API 可达
|
||
- 启动 `uvicorn app.main:app --host 0.0.0.0 --port 8000`，cwd 为 `apps/backend/`
|
||
- 验证 `GET /api/tasks/flows` 返回 200
|
||
- _Requirements: 1.1_
|
||
|
||
- [ ] 1.2 启动前端服务（`apps/admin-web/`，pnpm dev :5173），确认页面可访问
|
||
- 启动 `pnpm dev`，cwd 为 `apps/admin-web/`
|
||
- 验证 `http://localhost:5173` 可达
|
||
- _Requirements: 1.2_
|
||
|
||
- [ ] 1.3 API 健康检查：登录获取 JWT，验证任务注册表，执行 sync-check
|
||
- `POST /api/auth/login` 使用默认管理员账号（admin / admin123），获取 JWT
|
||
- `GET /api/tasks/registry` 确认返回非空任务列表
|
||
- `GET /api/tasks/sync-check` 确认 `in_sync=true`（后端注册表与 ETL 真实注册表一致）
|
||
- 如果 sync-check 不一致，记录差异并向用户报告
|
||
- _Requirements: 1.3, 1.4, 1.5_
|
||
|
||
- [ ] 2. 全流程任务提交
|
||
- [ ] 2.1 构建 TaskConfig 并调用 validate 预览 CLI 命令
|
||
- 构建 TaskConfig：flow=api_full, processing_mode=full_window, window_mode=custom, window_start="2025-11-01 00:00", window_end="2026-02-20 00:00", window_split=day, window_split_days=30, force_full=True, tasks=全选 is_common=True 的任务
|
||
- 调用 `POST /api/tasks/validate` 验证配置有效
|
||
- 记录生成的 CLI 命令预览，确认参数完整（--flow api_full --processing-mode full_window --window-start ... --window-end ... --window-split day --window-split-days 30 --force-full --store-id 1 --tasks ...）
|
||
- _Requirements: 2.1_
|
||
|
||
- [ ] 2.2 提交任务执行（`POST /api/execution/run`），记录 execution_id
|
||
- 调用 `POST /api/execution/run` 提交任务
|
||
- 记录返回的 execution_id
|
||
- 确认任务状态变为 running
|
||
- _Requirements: 2.2, 2.4_
|
||
|
||
- [ ] 3. 执行监控与 DEBUG
|
||
- [ ] 3.1 启动监控循环：每 30 秒轮询状态和日志，检测错误/警告，最长等待 30 分钟
|
||
- 轮询 `GET /api/execution/queue` 检查任务状态
|
||
- 轮询 `GET /api/execution/{id}/logs` 获取增量日志
|
||
- 检测日志中的 ERROR / CRITICAL / Traceback / Exception / WARNING
|
||
- 记录每次轮询的时间戳和日志增量行数
|
||
- 如果连续 30 分钟无新日志输出，报告超时警告
|
||
- 任务完成（success/failed/cancelled）时停止轮询
|
||
- _Requirements: 3.1, 3.2, 3.3, 3.4, 3.5_
|
||
|
||
- [ ] 3.2 对执行过程中发现的错误/警告进行 DEBUG 分析
|
||
- 收集所有 ERROR 和 WARNING 日志行及其上下文（前后各 5 行）
|
||
- 分析错误类型：API 超时、数据库连接、数据质量、配置问题等
|
||
- 如果任务失败，获取完整 stderr 并分析根因
|
||
- 记录 DEBUG 发现到报告中
|
||
- _Requirements: 3.2, 3.5_
|
||
|
||
- [ ] 4. 性能计时与报告生成
|
||
- [ ] 4.1 解析执行日志，提取精细计时数据
|
||
- 从日志中提取每个窗口切片（30天）的开始/结束时间
|
||
- 计算每个切片的耗时
|
||
- 识别 ODS / DWD / DWS / INDEX 各阶段的耗时
|
||
- 标注 Top-5 耗时最长的阶段/任务
|
||
- _Requirements: 4.1, 4.2, 4.3, 4.4_
|
||
|
||
- [ ] 4.2 生成综合联调报告，输出到 SYSTEM_LOG_ROOT
|
||
- 报告包含：执行概要（参数、时间、退出码）
|
||
- 报告包含：性能报告（各切片耗时对比、Top-5 瓶颈）
|
||
- 报告包含：DEBUG 报告（如有错误/警告）
|
||
- 输出路径：`{SYSTEM_LOG_ROOT}/{date}__etl_integration_report.md`
|
||
- 路径通过 `SYSTEM_LOG_ROOT` 环境变量获取，缺失时报错
|
||
- _Requirements: 5.1, 5.2, 5.3, 5.4_
|
||
|
||
- [ ] 5. 服务清理
|
||
- [ ] 5.1 停止后端和前端服务，清理资源
|
||
- 停止 uvicorn 进程
|
||
- 停止 pnpm dev 进程
|
||
- 报告联调完成状态
|
||
|
||
## 说明
|
||
|
||
- 本 Spec 为运维联调任务，不涉及新功能代码开发
|
||
- 不编写属性测试或单元测试，联调本身即为集成验证
|
||
- 全选常用任务 = 任务注册表中 `is_common=True` 的所有任务（共 41 个）
|
||
- "全部门店"：当前系统仅有 site_id=1（默认管理员绑定），如需多门店需逐个执行
|
||
- 监控允许空闲等待，最长 30 分钟无新日志才报超时
|
||
- 报告输出路径遵循 export-paths 规范，通过 SYSTEM_LOG_ROOT 环境变量获取
|