91 lines
4.4 KiB
Markdown
91 lines
4.4 KiB
Markdown
# tasks/ — ETL 任务
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
tasks/
|
||
├── base_task.py # BaseTask 基类（Extract → Transform → Load 模板方法）
|
||
├── ods/ # ODS 层：从 API 抓取或离线 JSON 回放，写入 ODS 表
|
||
├── dwd/ # DWD 层：从 ODS 清洗装载到 DWD（维度 SCD2 + 事实增量）
|
||
├── dws/ # DWS 层：汇总统计（助教业绩、财务日报、会员分析等）
|
||
│ ├── base_dws_task.py # BaseDwsTask 基类（默认 extract/load 模板方法）
|
||
│ ├── dws_helpers.py # 公共辅助函数（mask_mobile, calc_days_since, parse_id_list, safe_division）
|
||
│ ├── finance_base_task.py # FinanceBaseTask 财务任务共享基类
|
||
│ ├── maintenance_task.py # DwsMaintenanceTask 统一维护（MV 刷新 + 数据清理）
|
||
│ └── index/ # 指数计算（WBI/NCI/RS/OS/MS/ML）
|
||
│ ├── base_index_task.py # BaseIndexTask 指数算法基类
|
||
│ └── member_index_base.py # MemberIndexBaseTask 会员指数共享基类（模板 execute）
|
||
├── utility/ # 工具类任务（Schema 初始化、手动入库、完整性检查等）
|
||
└── verification/ # 校验任务（ODS/DWD/DWS/指数层的数据一致性校验）
|
||
```
|
||
|
||
## 类继承体系
|
||
|
||
```
|
||
BaseTask # E/T/L 模板方法 + 窗口分段
|
||
├── ODS 任务（OdsTaskSpec 声明式）
|
||
├── DwdLoadTask # DWD 装载
|
||
└── BaseDwsTask # DWS 层基类（默认 extract/load）
|
||
│ 子类声明 DATE_COL + 实现 _do_extract()/transform()
|
||
├── AssistantDailyTask 等 # 助教/会员/财务 DWS 任务
|
||
├── FinanceBaseTask # 财务任务共享基类
|
||
│ ├── FinanceDailyTask
|
||
│ ├── FinanceRechargeTask
|
||
│ ├── FinanceIncomeStructureTask
|
||
│ └── FinanceDiscountDetailTask
|
||
├── DwsMaintenanceTask # 统一维护（MV 刷新 + 数据清理）
|
||
└── BaseIndexTask # 指数算法基类
|
||
└── MemberIndexBaseTask # 会员指数共享（模板 execute）
|
||
├── WinbackIndexTask # 实现 _calculate_scores/_save_results
|
||
└── NewconvIndexTask
|
||
```
|
||
|
||
## 新增任务流程
|
||
|
||
### DWS 任务（推荐模式）
|
||
|
||
1. 在 `tasks/dws/` 下创建任务文件，继承 `BaseDwsTask`
|
||
2. 声明 `DATE_COL` 类属性（日期列名）
|
||
3. 实现 `get_task_code()`、`get_target_table()`、`get_primary_keys()`
|
||
4. 实现 `_do_extract(context)` 返回原始行列表
|
||
5. 实现 `transform(extracted, context)` 进行数据转换
|
||
6. 默认 `extract()` 和 `load()` 由基类提供，有自定义需求时可覆盖
|
||
7. 在 `orchestration/task_registry.py` 中注册任务
|
||
|
||
```python
|
||
# 示例：注册一个新的 DWS 任务（带依赖声明）
|
||
registry.register(
|
||
task_code="DWS_NEW_REPORT",
|
||
task_class=NewReportTask,
|
||
layer="DWS",
|
||
task_type="ETL",
|
||
requires_db_config=True,
|
||
depends_on=["DWS_ASSISTANT_DAILY"], # 声明依赖关系
|
||
)
|
||
```
|
||
|
||
### 通用任务
|
||
|
||
1. 在对应子目录创建任务文件，继承 `BaseTask`
|
||
2. 实现 `get_task_code()` 返回大写蛇形任务代码（如 `DWS_MEMBER_VISIT`）
|
||
3. 实现 `execute(context)` 方法，包含 Extract → Transform → Load 逻辑
|
||
4. 在 `orchestration/task_registry.py` 中注册任务，指定元数据：
|
||
- `layer`：`ODS` / `DWD` / `DWS` / `UTILITY` / `VERIFICATION`
|
||
- `task_type`：`ETL` / `UTILITY` / `VERIFICATION`
|
||
- `requires_db_config`：是否需要数据库连接
|
||
- `depends_on`：依赖的任务代码列表（可选）
|
||
|
||
### 任务依赖
|
||
|
||
通过 `depends_on` 参数声明任务间的依赖关系。`FlowRunner._resolve_tasks()` 会对任务列表执行拓扑排序（Kahn's algorithm），确保被依赖任务先于依赖方执行。
|
||
|
||
## 任务命名约定
|
||
|
||
- 任务代码：大写蛇形（`DWD_LOAD_FROM_ODS`、`DWS_ASSISTANT_DAILY`）
|
||
- 文件名：小写蛇形 + `_task.py` 后缀（`assistant_daily_task.py`）
|
||
- 类名：驼峰 + `Task` 后缀（`AssistantDailyTask`）
|
||
|
||
## ODS 任务特殊说明
|
||
|
||
ODS 任务通过 `ods/ods_tasks.py` 中的 `ODS_TASK_SPECS` 声明式定义，无需为每个实体单独写 execute 逻辑。新增 ODS 实体只需在 `ODS_TASK_SPECS` 列表中添加一条 spec 记录。
|