# 需求文档：ETL 任务说明文档

## 简介

为飞球 ETL 系统（etl-billiards）生成一份完整的任务说明文档，覆盖 ODS、DWD、DWS、INDEX 四层所有已注册任务的逻辑、执行方式、参数含义及处理流程。文档面向开发者和运维人员，放置于 `docs/etl_tasks/` 目录下。

## 术语表

- **ETL_System**：飞球 ETL 系统，负责从上游 API 抽取数据并经 ODS → DWD → DWS 三层处理
- **Task_Document**：本次生成的 ETL 任务说明文档
- **ODS**：操作数据存储层（Operational Data Store），保留 API 原始 payload
- **DWD**：明细数据层（Data Warehouse Detail），清洗后的维度表和事实表
- **DWS**：数据服务层（Data Warehouse Service），汇总统计表
- **INDEX**：指数算法层，基于 DWS 数据计算自定义业务指数
- **BaseTask**：所有 ETL 任务的基类，提供 Extract → Transform → Load 模板方法
- **TaskRegistry**：任务注册表，维护任务代码与任务类的映射关系
- **TaskContext**：运行期上下文，包含 store_id、时间窗口等信息
- **Pipeline**：管道，定义多层任务的执行顺序（如 api_ods、api_full、dwd_dws 等）
- **Loader**：加载器，负责将转换后的数据写入目标表（upsert/insert）

## 需求

### 需求 1：文档结构与组织

**用户故事：** 作为开发者，我希望文档按数据层分章节组织，以便快速定位特定层的任务说明。

#### 验收标准

1. THE Task_Document SHALL 包含一个总览文件（`README.md`），列出所有层及其任务清单，并提供跳转链接
2. THE Task_Document SHALL 按 ODS、DWD、DWS、INDEX、Utility 五个分类分别生成独立的 Markdown 文件
3. THE Task_Document SHALL 放置于 `docs/etl_tasks/` 目录下
4. WHEN 新增或删除任务时，THE Task_Document SHALL 通过总览文件的任务清单反映当前已注册任务的完整列表

### 需求 2：ODS 层任务说明

**用户故事：** 作为开发者，我希望了解每个 ODS 任务的 API 端点、参数、解析逻辑和目标表，以便排查数据抓取问题。

#### 验收标准

1. THE Task_Document SHALL 为每个 ODS 任务列出任务代码、对应的 Python 类、源 API 端点
2. THE Task_Document SHALL 说明每个 ODS 任务的 extract 阶段调用的 API 参数及其含义
3. THE Task_Document SHALL 说明每个 ODS 任务的 transform 阶段的字段解析和类型转换逻辑
4. THE Task_Document SHALL 说明每个 ODS 任务的 load 阶段的目标表名和写入策略（upsert/insert）
5. THE Task_Document SHALL 区分"独立 ODS 任务"（如 OrdersTask）和"通用 ODS 任务"（由 ODS_TASK_CLASSES 动态生成）两种模式
6. THE Task_Document SHALL 说明通用 ODS 任务的 OdsTaskSpec 配置结构（端点、表名、列映射、分页参数等）

### 需求 3：DWD 层任务说明

**用户故事：** 作为开发者，我希望了解 DWD 层任务如何从 ODS 读取数据并清洗装载到维度表和事实表，以便理解数据血缘。

#### 验收标准

1. THE Task_Document SHALL 为每个 DWD 任务列出任务代码、Python 类、源 ODS 表和目标 DWD 表
2. THE Task_Document SHALL 说明 DWD_LOAD_FROM_ODS 任务的 TABLE_MAP 映射关系及维度/事实分流逻辑
3. THE Task_Document SHALL 说明维度表的 SCD2 处理方式（生效区间、变更检测、历史版本管理）
4. THE Task_Document SHALL 说明事实表的增量装载方式（水位线、去重、冲突处理）
5. THE Task_Document SHALL 说明 DWD_QUALITY_CHECK 任务的行数/金额核对逻辑和报表输出格式
6. THE Task_Document SHALL 说明 TICKET_DWD、PAYMENTS_DWD、MEMBERS_DWD 三个独立 DWD 任务各自的处理特点

### 需求 4：DWS 层任务说明

**用户故事：** 作为开发者，我希望了解 DWS 层每个汇总任务的业务含义、数据来源和计算规则，以便验证业务报表的正确性。

#### 验收标准

1. THE Task_Document SHALL 为每个 DWS 任务列出任务代码、Python 类、目标表、主键和统计粒度
2. THE Task_Document SHALL 说明每个 DWS 任务的数据来源表（DWD 层的哪些表）
3. THE Task_Document SHALL 说明每个 DWS 任务的核心业务计算规则（如工资计算公式、业绩档位、排名逻辑等）
4. THE Task_Document SHALL 说明每个 DWS 任务的更新策略（delete-before-insert 或 upsert）
5. THE Task_Document SHALL 说明物化视图刷新任务（MV_REFRESH）的分层刷新机制和配置方式
6. THE Task_Document SHALL 说明数据保留清理任务（RETENTION_CLEANUP）的时间分层策略和配置参数

### 需求 5：INDEX 层任务说明

**用户故事：** 作为开发者，我希望了解指数算法任务的计算逻辑和参数含义，以便调优指数模型。

#### 验收标准

1. THE Task_Document SHALL 为每个 INDEX 任务列出任务代码、Python 类、目标表和指数类型
2. THE Task_Document SHALL 说明每个指数的计算公式或算法概要（WBI/NCI/RS/ML）
3. THE Task_Document SHALL 说明指数参数的配置来源（cfg_index_parameters 表）和参数含义
4. THE Task_Document SHALL 说明 ML_MANUAL_IMPORT 任务的 Excel 导入逻辑和模板格式

### 需求 6：工具类任务说明

**用户故事：** 作为运维人员，我希望了解 Schema 初始化、手动入库等工具类任务的用途和使用方式。

#### 验收标准

1. THE Task_Document SHALL 为每个工具类任务列出任务代码、Python 类和用途说明
2. THE Task_Document SHALL 说明 INIT_ODS_SCHEMA、INIT_DWD_SCHEMA、INIT_DWS_SCHEMA 三个初始化任务执行的 DDL 文件和创建的目录
3. THE Task_Document SHALL 说明 MANUAL_INGEST 任务的文件匹配规则、JSON 解析逻辑和入库流程
4. THE Task_Document SHALL 说明 ODS_JSON_ARCHIVE 任务的归档策略
5. THE Task_Document SHALL 说明 CHECK_CUTOFF 和 DATA_INTEGRITY_CHECK 任务的校验逻辑

### 需求 7：执行方式与参数说明

**用户故事：** 作为运维人员，我希望了解如何通过 CLI 和管道模式执行任务，以及各参数的含义。

#### 验收标准

1. THE Task_Document SHALL 说明 CLI 入口（`python -m cli.main`）的所有参数及其含义
2. THE Task_Document SHALL 说明管道类型（api_ods、api_ods_dwd、api_full、ods_dwd、dwd_dws、dwd_dws_index、dwd_index）各自包含的层和执行顺序
3. THE Task_Document SHALL 说明处理模式（increment_only、verify_only、increment_verify）的区别和适用场景
4. THE Task_Document SHALL 说明时间窗口参数（window-start、window-end、window-split、lookback-hours、overlap-seconds）的计算逻辑
5. THE Task_Document SHALL 说明数据源模式（online、offline、hybrid）的区别
6. THE Task_Document SHALL 提供常见使用场景的命令示例

### 需求 8：BaseTask 与公共机制说明

**用户故事：** 作为开发者，我希望了解任务基类的模板方法和公共机制，以便开发新任务时遵循统一模式。

#### 验收标准

1. THE Task_Document SHALL 说明 BaseTask 的 Execute → Extract → Transform → Load 模板方法流程
2. THE Task_Document SHALL 说明 TaskContext 的字段含义（store_id、window_start、window_end、window_minutes、cursor）
3. THE Task_Document SHALL 说明时间窗口的计算逻辑（游标优先、闲忙时段、手动覆盖）
4. THE Task_Document SHALL 说明窗口分段（build_window_segments）的切分策略
5. THE Task_Document SHALL 说明任务注册表（TaskRegistry）的注册方式和元数据结构（layer、task_type、requires_db_config）