Neo-ZQYY/.kiro/specs/etl-task-documentation/tasks.md

实施计划：ETL 任务说明文档

概述

基于对 tasks/、loaders/、orchestration/、cli/ 目录下源代码的分析，生成 7 个 Markdown 文档文件，放置于 docs/etl_tasks/ 目录下。每个任务按照设计文档中定义的结构和内容范围编写。

任务

• 1. 创建 docs/etl_tasks/base_task_mechanism.md

  • 说明 BaseTask 的 execute → extract → transform → load 模板方法流程
  • 说明 TaskContext 字段含义（store_id、window_start、window_end、window_minutes、cursor）
  • 说明时间窗口计算逻辑（手动覆盖 > 游标 > 闲忙时段默认值）
  • 说明窗口分段（build_window_segments）切分策略
  • 说明 TaskRegistry 注册方式与 TaskMeta 元数据结构（layer、task_type、requires_db_config）
  • 说明 PipelineRunner 管道执行流程与校验框架概述
  • Requirements: 8.1, 8.2, 8.3, 8.4, 8.5

• 2. 创建 docs/etl_tasks/ods_tasks.md

  • 2.1 编写独立 ODS 任务说明（14 个任务：ORDERS、PAYMENTS、MEMBERS、PRODUCTS、TABLES、ASSISTANTS、PACKAGES_DEF、REFUNDS、COUPON_USAGE、INVENTORY_CHANGE、TOPUPS、TABLE_DISCOUNT、ASSISTANT_ABOLISH、LEDGER）
    • 每个任务列出：任务代码、Python 类、API 端点、请求参数、字段解析逻辑、目标表、写入策略
    • Requirements: 2.1, 2.2, 2.3, 2.4
  • 2.2 编写通用 ODS 任务说明（BaseOdsTask + OdsTaskSpec 模式）
    • 说明 OdsTaskSpec 配置结构（endpoint、table、columns、pk_columns、snapshot_mode 等）
    • 说明 BaseOdsTask 的通用 execute 流程（API 调用、schema-aware 插入、content_hash 去重、软删除标记）
    • 列出由 ODS_TASK_CLASSES 动态注册的所有任务
    • Requirements: 2.5, 2.6

• 3. 创建 docs/etl_tasks/dwd_tasks.md

  • 3.1 编写 DWD_LOAD_FROM_ODS 核心任务说明
    • 列出完整的 TABLE_MAP 映射表（DWD 表 → ODS 表）
    • 说明维度/事实分流逻辑（dim_* 走 SCD2 或 Type1 Upsert，其余走增量插入）
    • 说明 SCD2 处理流程（最新快照选取、变更检测、版本关闭与新建）
    • 说明事实表增量装载（fetched_at 水位线、upsert/insert-only、FACT_MAPPINGS 列映射）
    • Requirements: 3.2, 3.3, 3.4
  • 3.2 编写独立 DWD 任务说明（TICKET_DWD、PAYMENTS_DWD、MEMBERS_DWD）
    • 每个任务列出：源 ODS 表、目标 DWD 表、处理特点
    • Requirements: 3.6
  • 3.3 编写 DWD_QUALITY_CHECK 任务说明
    • 说明行数/金额核对逻辑、金额列自动扫描规则、JSON 报表输出格式
    • Requirements: 3.5

• 4. 创建 docs/etl_tasks/dws_tasks.md

  • 4.1 编写 BaseDwsTask 公共机制说明
    • 说明时间分层（TimeLayer）、配置缓存（ConfigCache）、delete-before-insert 策略、bulk_insert/upsert 方法
    • Requirements: 4.1
  • 4.2 编写助教业绩域任务说明（5 个任务）
    • DWS_ASSISTANT_DAILY：日度服务明细聚合，数据来源、聚合维度、输出字段
    • DWS_ASSISTANT_MONTHLY：月度汇总，业绩档位计算、排名逻辑、新人封顶规则
    • DWS_ASSISTANT_CUSTOMER：助教-客户关系统计
    • DWS_ASSISTANT_SALARY：工资计算公式（基础工资+提成+奖金+扣款）
    • DWS_ASSISTANT_FINANCE：助教收支分析（收入 vs 日均成本、毛利率）
    • Requirements: 4.2, 4.3, 4.4
  • 4.3 编写会员分析域任务说明（2 个任务）
    • DWS_MEMBER_CONSUMPTION：会员消费汇总、客户分层
    • DWS_MEMBER_VISIT：会员到店明细、服务时长、折扣计算
    • Requirements: 4.2, 4.3, 4.4
  • 4.4 编写财务统计域任务说明（4 个任务）
    • DWS_FINANCE_DAILY：财务日报（结算汇总、团购、充值、赠卡消费、费用、平台）
    • DWS_FINANCE_RECHARGE：充值统计（首充/续充、现金/赠送、卡余额）
    • DWS_FINANCE_INCOME_STRUCTURE：收入结构分析（按类型、按区域）
    • DWS_FINANCE_DISCOUNT_DETAIL：折扣明细统计
    • Requirements: 4.2, 4.3, 4.4
  • 4.5 编写运维任务说明（4 个任务）
    • DWS_BUILD_ORDER_SUMMARY：订单汇总中间表构建
    • DWS_RETENTION_CLEANUP：时间分层清理策略、配置参数（enabled、layer、tables、table_layers）
    • DWS_MV_REFRESH_FINANCE_DAILY / DWS_MV_REFRESH_ASSISTANT_DAILY：物化视图分层刷新机制、L1-L4 层级、配置方式
    • Requirements: 4.5, 4.6

• 5. 创建 docs/etl_tasks/index_tasks.md

  • 编写 BaseIndexTask 公共机制（参数加载、百分位历史）
  • 编写 4 个指数任务说明：WBI（回流指数）、NCI（新客转化指数）、RS（关系指数）、ML（手动台账导入）
  • 说明 cfg_index_parameters 配置表结构和参数含义
  • 说明 ML_MANUAL_IMPORT 的 Excel 模板格式和导入逻辑
  • Requirements: 5.1, 5.2, 5.3, 5.4

• 6. 创建 docs/etl_tasks/utility_tasks.md

  • 编写 8 个工具类任务说明：INIT_ODS_SCHEMA、INIT_DWD_SCHEMA、INIT_DWS_SCHEMA、MANUAL_INGEST、ODS_JSON_ARCHIVE、CHECK_CUTOFF、SEED_DWS_CONFIG、DATA_INTEGRITY_CHECK
  • 每个任务列出：用途、执行的 DDL/操作、配置参数
  • 重点说明 MANUAL_INGEST 的文件匹配规则和入库流程
  • Requirements: 6.1, 6.2, 6.3, 6.4, 6.5

• 7. 创建 docs/etl_tasks/README.md（总览）

  • 编写系统简介和数据流向图（API → ODS → DWD → DWS）
  • 编写按层分组的任务清单表格（任务代码、Python 类、简要说明、跳转链接）
  • 编写管道类型说明（7 种管道的层组合）
  • 编写处理模式说明（increment_only / verify_only / increment_verify）
  • 编写数据源模式说明（online / offline / hybrid）
  • 编写 CLI 参数速查表（所有参数的表格）
  • 编写常见命令示例
  • Requirements: 1.1, 1.2, 1.3, 7.1, 7.2, 7.3, 7.5, 7.6

• 8. 检查点 - 验证文档完整性

  • 确认 7 个文件全部存在于 docs/etl_tasks/ 目录下
  • 确认 README.md 中的任务清单覆盖所有已注册任务
  • 确认各分层文件中的任务代码与 task_registry.py 一致
  • Ensure all files are valid Markdown, ask the user if questions arise.

• 9. 编写文档覆盖完整性验证脚本

  • 9.1 编写 ODS 任务覆盖验证
    • Property 1: ODS 任务文档覆盖完整性
    • Validates: Requirements 2.1, 2.4
  • 9.2 编写 DWD 任务覆盖验证
    • Property 2: DWD 任务文档覆盖完整性
    • Validates: Requirements 3.1
  • 9.3 编写 DWS 任务覆盖验证
    • Property 3: DWS 任务文档覆盖完整性
    • Validates: Requirements 4.1, 4.4
  • 9.4 编写 INDEX 和 Utility 任务覆盖验证
    • Property 4: INDEX 任务文档覆盖完整性
    • Property 5: Utility 任务文档覆盖完整性
    • Validates: Requirements 5.1, 6.1
  • 9.5 编写 CLI 参数和管道类型覆盖验证
    • Property 6: CLI 参数文档覆盖完整性
    • Property 7: 管道类型文档覆盖完整性
    • Validates: Requirements 7.1, 7.2

• 10. 最终检查点

  • Ensure all tests pass, ask the user if questions arise.

说明

• 任务标记 * 的为可选项，可跳过以加快 MVP 进度
• 每个任务引用了具体的需求编号以便追溯
• 检查点确保增量验证
• 文档编写顺序：先写公共机制（task 1），再按层写各任务（task 2-6），最后写总览（task 7）