127 lines
4.8 KiB
Markdown
127 lines
4.8 KiB
Markdown
# 设计文档：ETL 全流程前后端联调（etl-fullstack-integration）
|
||
|
||
## 概述
|
||
|
||
本 Spec 是一个运维联调任务，不涉及新功能开发。目标是验证 `admin-web-console` Spec 产出的前后端代码在真实环境下的端到端正确性，同时收集性能数据。
|
||
|
||
核心流程：
|
||
1. 启动后端 + 前端服务
|
||
2. 通过 API 登录获取 JWT
|
||
3. 提交全流程 ETL 任务（api_full, full_window, force-full, 全选常用任务, 自定义窗口 2025-11-01~2026-02-20, 30天切分, 全部门店）
|
||
4. 实时监控执行过程，捕获错误/警告
|
||
5. 执行完成后生成综合报告
|
||
|
||
## 架构
|
||
|
||
```
|
||
联调脚本 (scripts/ops/)
|
||
│
|
||
├── 1. 启动服务
|
||
│ ├── uvicorn app.main:app (后端 :8000)
|
||
│ └── pnpm dev (前端 :5173)
|
||
│
|
||
├── 2. API 调用链
|
||
│ ├── POST /api/auth/login → JWT
|
||
│ ├── GET /api/tasks/registry → 任务列表
|
||
│ ├── GET /api/tasks/sync-check → 同步检查
|
||
│ ├── POST /api/tasks/validate → CLI 预览
|
||
│ └── POST /api/execution/run → 触发执行
|
||
│
|
||
├── 3. 监控循环
|
||
│ ├── GET /api/execution/queue → 状态轮询
|
||
│ ├── GET /api/execution/{id}/logs → 日志获取
|
||
│ └── 错误/警告检测
|
||
│
|
||
└── 4. 报告生成
|
||
└── 输出到 SYSTEM_LOG_ROOT
|
||
```
|
||
|
||
## 任务参数
|
||
|
||
根据用户需求，联调任务的具体参数：
|
||
|
||
```python
|
||
INTEGRATION_TASK_CONFIG = {
|
||
"flow": "api_full", # 全流程：API → ODS → DWD → DWS → INDEX
|
||
"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, # 30天一个切片
|
||
"force_full": True, # 强制全量
|
||
"dry_run": False,
|
||
"tasks": [ # 全选 is_common=True 的任务
|
||
# ODS 层（22 个）
|
||
"ODS_ASSISTANT_ACCOUNT", "ODS_ASSISTANT_LEDGER", "ODS_ASSISTANT_ABOLISH",
|
||
"ODS_SETTLEMENT_RECORDS", "ODS_TABLE_USE", "ODS_TABLE_FEE_DISCOUNT",
|
||
"ODS_TABLES", "ODS_PAYMENT", "ODS_REFUND", "ODS_PLATFORM_COUPON",
|
||
"ODS_MEMBER", "ODS_MEMBER_CARD", "ODS_MEMBER_BALANCE", "ODS_RECHARGE_SETTLE",
|
||
"ODS_GROUP_PACKAGE", "ODS_GROUP_BUY_REDEMPTION",
|
||
"ODS_INVENTORY_STOCK", "ODS_INVENTORY_CHANGE",
|
||
"ODS_GOODS_CATEGORY", "ODS_STORE_GOODS", "ODS_STORE_GOODS_SALES", "ODS_TENANT_GOODS",
|
||
# DWD 层（1 个常用）
|
||
"DWD_LOAD_FROM_ODS",
|
||
# DWS 层（15 个常用，排除 DWS_MAINTENANCE）
|
||
"DWS_BUILD_ORDER_SUMMARY", "DWS_ASSISTANT_DAILY", "DWS_ASSISTANT_MONTHLY",
|
||
"DWS_ASSISTANT_CUSTOMER", "DWS_ASSISTANT_SALARY", "DWS_ASSISTANT_FINANCE",
|
||
"DWS_MEMBER_CONSUMPTION", "DWS_MEMBER_VISIT",
|
||
"DWS_FINANCE_DAILY", "DWS_FINANCE_RECHARGE", "DWS_FINANCE_INCOME_STRUCTURE",
|
||
"DWS_FINANCE_DISCOUNT_DETAIL",
|
||
"DWS_GOODS_STOCK_DAILY", "DWS_GOODS_STOCK_WEEKLY", "DWS_GOODS_STOCK_MONTHLY",
|
||
# INDEX 层（3 个常用，排除 DWS_ML_MANUAL_IMPORT）
|
||
"DWS_WINBACK_INDEX", "DWS_NEWCONV_INDEX", "DWS_RELATION_INDEX",
|
||
],
|
||
# store_id 由后端从 JWT 注入（默认管理员 site_id=1）
|
||
# 注意：用户要求"全部门店"，但当前系统只有 site_id=1，后续多门店需逐个执行
|
||
}
|
||
```
|
||
|
||
## 监控策略
|
||
|
||
- 轮询间隔：30 秒
|
||
- 最长等待：30 分钟（无新日志输出时）
|
||
- 错误检测：日志行匹配 `ERROR`、`CRITICAL`、`Traceback`、`Exception`
|
||
- 警告检测：日志行匹配 `WARNING`、`WARN`
|
||
- 计时解析：从日志中提取时间戳，计算阶段耗时
|
||
|
||
## 报告格式
|
||
|
||
报告输出为 Markdown 文件，路径：`{SYSTEM_LOG_ROOT}/{date}__etl_integration_report.md`
|
||
|
||
```markdown
|
||
# ETL 全流程联调报告
|
||
|
||
## 执行概要
|
||
- 任务参数：...
|
||
- 开始时间 / 结束时间 / 总时长
|
||
- 退出码 / 最终状态
|
||
|
||
## 性能报告
|
||
- 各窗口切片耗时对比表
|
||
- Top-5 耗时阶段
|
||
- 总体吞吐量估算
|
||
|
||
## DEBUG 报告（如有）
|
||
- 错误摘要
|
||
- 警告摘要
|
||
- 相关日志片段
|
||
- 可能的原因分析
|
||
```
|
||
|
||
## 正确性属性
|
||
|
||
本 Spec 为运维联调任务，不涉及新功能代码开发，因此不定义形式化的属性测试。验证通过以下方式进行：
|
||
- 服务健康检查通过
|
||
- 任务提交成功并开始执行
|
||
- 执行完成后退出码和日志符合预期
|
||
- 报告文件成功生成
|
||
|
||
## 测试策略
|
||
|
||
本 Spec 本身就是一次集成测试。不额外编写单元测试或属性测试。验证标准：
|
||
- 后端 API 响应正确
|
||
- ETL CLI 子进程正常启动和执行
|
||
- 日志正确捕获和推送
|
||
- 报告文件正确生成到 SYSTEM_LOG_ROOT
|