init: 项目初始提交 - NeoZQYY Monorepo 完整代码

2026-02-15 14:58:14 +08:00
commit ded6dfb9d8
769 changed files with 182616 additions and 0 deletions
--- a/.kiro/specs/etl-task-documentation/.config.kiro
+++ b/.kiro/specs/etl-task-documentation/.config.kiro
@@ -0,0 +1 @@
+{"generationMode": "requirements-first"}
--- a/.kiro/specs/etl-task-documentation/design.md
+++ b/.kiro/specs/etl-task-documentation/design.md
@@ -0,0 +1,285 @@
+# 设计文档：ETL 任务说明文档
+
+## 概述
+
+本设计描述如何为飞球 ETL 系统生成一套完整的任务说明文档，放置于 `docs/etl_tasks/` 目录下。文档以 Markdown 格式编写，按数据层（ODS / DWD / DWS / INDEX / Utility）分文件组织，并提供一个总览 README 作为入口。
+
+文档的目标读者是开发者和运维人员，需要覆盖：
+- 每个任务的代码标识、Python 类、数据来源与目标
+- Extract / Transform / Load 各阶段的处理逻辑
+- CLI 参数与管道执行方式
+- BaseTask 公共机制
+
+## 架构
+
+文档为纯静态 Markdown 文件，不涉及运行时代码变更。整体结构如下：
+
+```
+docs/etl_tasks/
+├── README.md                  # 总览：任务清单 + 跳转链接 + 执行方式
+├── ods_tasks.md               # ODS 层任务详解
+├── dwd_tasks.md               # DWD 层任务详解
+├── dws_tasks.md               # DWS 层任务详解
+├── index_tasks.md             # INDEX 层任务详解
+├── utility_tasks.md           # 工具类任务详解
+└── base_task_mechanism.md     # BaseTask 公共机制与执行参数
+```
+
+```mermaid
+graph TD
+    README["README.md<br/>总览入口"] --> ODS["ods_tasks.md"]
+    README --> DWD["dwd_tasks.md"]
+    README --> DWS["dws_tasks.md"]
+    README --> IDX["index_tasks.md"]
+    README --> UTL["utility_tasks.md"]
+    README --> BASE["base_task_mechanism.md"]
+```
+
+## 组件与接口
+
+本 spec 不涉及代码组件。产出物为 7 个 Markdown 文件，各文件的内容范围如下：
+
+### README.md（总览）
+
+| 章节 | 内容 |
+|------|------|
+| 系统简介 | 飞球 ETL 系统概述、数据流向（API → ODS → DWD → DWS） |
+| 任务清单 | 按层分组的表格：任务代码、Python 类、简要说明、跳转链接 |
+| 管道类型 | 7 种管道（api_ods / api_ods_dwd / api_full / ods_dwd / dwd_dws / dwd_dws_index / dwd_index）的层组合 |
+| 处理模式 | increment_only / verify_only / increment_verify 的区别 |
+| 数据源模式 | online / offline / hybrid 的区别 |
+| CLI 参数速查 | 所有 CLI 参数的表格（参数名、类型、默认值、说明） |
+| 常见命令示例 | 典型使用场景的命令行示例 |
+
+### ods_tasks.md（ODS 层）
+
+每个 ODS 任务一个小节，包含：
+- 任务代码与 Python 类
+- API 端点与请求参数
+- 字段解析逻辑（transform 阶段）
+- 目标 ODS 表与写入策略
+- 特殊说明（如分页、去重、content_hash 等）
+
+需区分两种 ODS 任务模式：
+1. 独立任务类（如 OrdersTask、MembersTask）：继承 BaseTask，有独立的 E/T/L 实现
+2. 通用 ODS 任务（由 `ods_tasks.py` 中 OdsTaskSpec + BaseOdsTask 动态生成）：通过声明式配置定义端点、列映射等
+
+已注册的 ODS 任务（14 个独立 + N 个通用）：
+
+| 任务代码 | Python 类 | API 端点 | 目标表 |
+|----------|-----------|----------|--------|
+| ORDERS | OrdersTask | /Site/GetAllOrderSettleList | billiards_ods.fact_order |
+| PAYMENTS | PaymentsTask | 支付相关端点 | billiards_ods.fact_payment |
+| MEMBERS | MembersTask | /MemberProfile/GetTenantMemberList | billiards_ods.dim_member |
+| PRODUCTS | ProductsTask | 商品相关端点 | billiards_ods 商品表 |
+| TABLES | TablesTask | 台桌相关端点 | billiards_ods 台桌表 |
+| ASSISTANTS | AssistantsTask | 助教相关端点 | billiards_ods 助教表 |
+| PACKAGES_DEF | PackagesDefTask | 套餐相关端点 | billiards_ods 套餐表 |
+| REFUNDS | RefundsTask | 退款相关端点 | billiards_ods 退款表 |
+| COUPON_USAGE | CouponUsageTask | 优惠券相关端点 | billiards_ods 优惠券表 |
+| INVENTORY_CHANGE | InventoryChangeTask | 库存变动端点 | billiards_ods 库存表 |
+| TOPUPS | TopupsTask | 充值相关端点 | billiards_ods 充值表 |
+| TABLE_DISCOUNT | TableDiscountTask | 台费折扣端点 | billiards_ods 折扣表 |
+| ASSISTANT_ABOLISH | AssistantAbolishTask | 助教取消端点 | billiards_ods 取消表 |
+| LEDGER | LedgerTask | 台账端点 | billiards_ods 台账表 |
+
+通用 ODS 任务由 `ODS_TASK_CLASSES` 字典动态注册，每个任务通过 `OdsTaskSpec` 声明：
+- `endpoint`：API 端点路径
+- `table`：目标 ODS 表名
+- `columns`：列定义列表（ColumnSpec）
+- `page_size`、`data_path`、`list_key`：分页参数
+- `pk_columns`：主键列
+- `snapshot_mode`：快照模式（content_hash 去重）
+
+### dwd_tasks.md（DWD 层）
+
+DWD 层有 5 个已注册任务：
+
+| 任务代码 | Python 类 | 说明 |
+|----------|-----------|------|
+| DWD_LOAD_FROM_ODS | DwdLoadTask | 核心装载任务：遍历 TABLE_MAP，维度走 SCD2，事实走增量 |
+| TICKET_DWD | TicketDwdTask | 结账小票明细 → fact_order / fact_order_goods / fact_table_usage / fact_assistant_service |
+| PAYMENTS_DWD | PaymentsDwdTask | ODS 支付记录 → fact_payment |
+| MEMBERS_DWD | MembersDwdTask | ODS 会员记录 → dim_member |
+| DWD_QUALITY_CHECK | DwdQualityTask | ODS 与 DWD 行数/金额核对，输出 JSON 报表 |
+
+核心任务 DWD_LOAD_FROM_ODS 的处理逻辑：
+- TABLE_MAP 定义了 40+ 对 DWD→ODS 表映射
+- 维度表（dim_*）：检测 SCD2 列是否存在，有则执行 SCD2 合并（关闭旧版+插入新版），无则执行 Type1 Upsert
+- 事实表（dwd_*、fact_*）：按 fetched_at 水位线增量插入，支持 upsert 或 insert-only
+- FACT_MAPPINGS 定义了列名映射（ODS 驼峰命名 → DWD 下划线命名）
+- 每张表独立事务，单表失败不影响后续表
+
+SCD2 处理流程：
+1. 从 ODS 取最新快照（DISTINCT ON 按业务主键 + fetched_at DESC）
+2. 与 DWD 当前版本（scd2_is_current=1）逐列对比
+3. 有变更：关闭旧版（scd2_end_time=now, scd2_is_current=0）+ 插入新版（version+1）
+4. 无变更：跳过
+
+### dws_tasks.md（DWS 层）
+
+DWS 层有 15 个已注册任务，按业务域分组：
+
+**助教业绩域：**
+
+| 任务代码 | Python 类 | 目标表 | 粒度 |
+|----------|-----------|--------|------|
+| DWS_ASSISTANT_DAILY | AssistantDailyTask | dws_assistant_daily_detail | 日期+助教 |
+| DWS_ASSISTANT_MONTHLY | AssistantMonthlyTask | dws_assistant_monthly_summary | 月份+助教 |
+| DWS_ASSISTANT_CUSTOMER | AssistantCustomerTask | dws_assistant_customer_stats | 日期+助教+会员 |
+| DWS_ASSISTANT_SALARY | AssistantSalaryTask | dws_assistant_salary_calc | 月份+助教 |
+| DWS_ASSISTANT_FINANCE | AssistantFinanceTask | dws_assistant_finance_analysis | 日期+助教 |
+
+**会员分析域：**
+
+| 任务代码 | Python 类 | 目标表 | 粒度 |
+|----------|-----------|--------|------|
+| DWS_MEMBER_CONSUMPTION | MemberConsumptionTask | dws_member_consumption_summary | 日期+会员 |
+| DWS_MEMBER_VISIT | MemberVisitTask | dws_member_visit_detail | 日期+会员+结账单 |
+
+**财务统计域：**
+
+| 任务代码 | Python 类 | 目标表 | 粒度 |
+|----------|-----------|--------|------|
+| DWS_FINANCE_DAILY | FinanceDailyTask | dws_finance_daily_summary | 日期 |
+| DWS_FINANCE_RECHARGE | FinanceRechargeTask | dws_finance_recharge_summary | 日期 |
+| DWS_FINANCE_INCOME_STRUCTURE | FinanceIncomeStructureTask | dws_finance_income_structure | 日期+收入类型 |
+| DWS_FINANCE_DISCOUNT_DETAIL | FinanceDiscountDetailTask | dws_finance_discount_detail | 日期+折扣类型 |
+
+**运维任务：**
+
+| 任务代码 | Python 类 | 说明 |
+|----------|-----------|------|
+| DWS_BUILD_ORDER_SUMMARY | DwsBuildOrderSummaryTask | 构建订单汇总中间表 |
+| DWS_RETENTION_CLEANUP | DwsRetentionCleanupTask | 按时间分层清理历史数据 |
+| DWS_MV_REFRESH_FINANCE_DAILY | DwsMvRefreshFinanceDailyTask | 刷新财务日报物化视图 |
+| DWS_MV_REFRESH_ASSISTANT_DAILY | DwsMvRefreshAssistantDailyTask | 刷新助教日报物化视图 |
+
+所有 DWS 任务继承 BaseDwsTask，共享以下机制：
+- 时间分层范围计算（TimeLayer: LAST_2_DAYS / LAST_1_MONTH / LAST_3_MONTHS / LAST_6_MONTHS / ALL）
+- 配置缓存（ConfigCache）：业绩档位、等级价格、奖金规则、区域分类、技能类型
+- delete-before-insert 更新策略（按日期范围先删后插，保证幂等）
+- bulk_insert / upsert 写入方法
+
+### index_tasks.md（INDEX 层）
+
+INDEX 层有 4 个已注册任务：
+
+| 任务代码 | Python 类 | 目标表 | 指数类型 |
+|----------|-----------|--------|----------|
+| DWS_WINBACK_INDEX | WinbackIndexTask | dws_member_winback_index | WBI（回流指数） |
+| DWS_NEWCONV_INDEX | NewconvIndexTask | dws_member_newconv_index | NCI（新客转化指数） |
+| DWS_RELATION_INDEX | RelationIndexTask | dws_relation_index | RS（关系指数） |
+| DWS_ML_MANUAL_IMPORT | MlManualImportTask | dws_ml_manual_ledger | ML（手动台账导入） |
+
+所有指数任务继承 BaseIndexTask，共享：
+- 参数从 `billiards_dws.cfg_index_parameters` 表加载
+- 百分位历史记录（PercentileHistory）
+- 标准化的指数计算流程
+
+### utility_tasks.md（工具类）
+
+| 任务代码 | Python 类 | 用途 |
+|----------|-----------|------|
+| INIT_ODS_SCHEMA | InitOdsSchemaTask | 执行 ODS + etl_admin DDL，创建必要目录 |
+| INIT_DWD_SCHEMA | InitDwdSchemaTask | 执行 DWD DDL |
+| INIT_DWS_SCHEMA | InitDwsSchemaTask | 执行 DWS DDL |
+| MANUAL_INGEST | ManualIngestTask | 从本地 JSON 文件手动入库到 ODS |
+| ODS_JSON_ARCHIVE | OdsJsonArchiveTask | 归档 ODS JSON 文件 |
+| CHECK_CUTOFF | CheckCutoffTask | 检查数据截止时间 |
+| SEED_DWS_CONFIG | SeedDwsConfigTask | 初始化 DWS 配置种子数据 |
+| DATA_INTEGRITY_CHECK | DataIntegrityTask | 数据完整性校验 |
+
+### base_task_mechanism.md（公共机制）
+
+覆盖内容：
+- BaseTask 模板方法流程（execute → build_context → [分段] → extract → transform → load → commit）
+- TaskContext 字段说明
+- 时间窗口计算逻辑（优先级：手动覆盖 > 游标 > 闲忙时段默认值）
+- 窗口分段（build_window_segments）
+- TaskRegistry 注册方式与元数据（TaskMeta: task_class, requires_db_config, layer, task_type）
+- PipelineRunner 管道执行流程
+- 校验框架（Verifier）概述
+
+## 数据模型
+
+本 spec 不涉及数据模型变更。文档中引用的数据模型均为现有系统中的表结构，包括：
+
+**ODS 层表**（billiards_ods schema）：
+- settlement_records, table_fee_transactions, assistant_service_records, member_profiles, payment_transactions, refund_transactions 等 20+ 表
+
+**DWD 层表**（billiards_dwd schema）：
+- 维度表：dim_site, dim_table, dim_assistant, dim_member, dim_member_card_account, dim_tenant_goods, dim_store_goods, dim_goods_category, dim_groupbuy_package（各含 _ex 扩展表）
+- 事实表：dwd_settlement_head, dwd_table_fee_log, dwd_table_fee_adjust, dwd_store_goods_sale, dwd_assistant_service_log, dwd_assistant_trash_event, dwd_member_balance_change, dwd_groupbuy_redemption, dwd_platform_coupon_redemption, dwd_recharge_order, dwd_payment, dwd_refund（各含 _ex 扩展表）
+
+**DWS 层表**（billiards_dws schema）：
+- 助教域：dws_assistant_daily_detail, dws_assistant_monthly_summary, dws_assistant_customer_stats, dws_assistant_salary_calc, dws_assistant_finance_analysis
+- 会员域：dws_member_consumption_summary, dws_member_visit_detail
+- 财务域：dws_finance_daily_summary, dws_finance_recharge_summary, dws_finance_income_structure, dws_finance_discount_detail
+- 指数域：dws_member_winback_index, dws_member_newconv_index, dws_relation_index, dws_ml_manual_ledger
+- 配置表：cfg_index_parameters, cfg_skill_type, cfg_performance_tier, cfg_level_price, cfg_bonus_rule, cfg_area_category
+
+
+## 正确性属性
+
+*正确性属性是一种在系统所有有效执行中都应成立的特征或行为——本质上是关于系统应该做什么的形式化陈述。属性是人类可读规范与机器可验证正确性保证之间的桥梁。*
+
+由于本 spec 的产出物是文档（Markdown 文件），而非运行时代码，正确性属性主要关注文档的完整性和一致性——即文档是否覆盖了所有已注册任务。
+
+Property 1: ODS 任务文档覆盖完整性
+*对于所有*在 `task_registry.py` 中注册且 layer="ODS" 的任务代码，`ods_tasks.md` 中应包含该任务代码的说明章节，并列出其目标表。
+**Validates: Requirements 2.1, 2.4**
+
+Property 2: DWD 任务文档覆盖完整性
+*对于所有*在 `task_registry.py` 中注册且 layer="DWD" 的任务代码，`dwd_tasks.md` 中应包含该任务代码的说明章节，并列出其源表和目标表。
+**Validates: Requirements 3.1**
+
+Property 3: DWS 任务文档覆盖完整性
+*对于所有*在 `task_registry.py` 中注册且 layer="DWS" 的任务代码，`dws_tasks.md` 中应包含该任务代码的说明章节，并标注其更新策略。
+**Validates: Requirements 4.1, 4.4**
+
+Property 4: INDEX 任务文档覆盖完整性
+*对于所有*在 `task_registry.py` 中注册且 layer="INDEX" 的任务代码，`index_tasks.md` 中应包含该任务代码的说明章节。
+**Validates: Requirements 5.1**
+
+Property 5: Utility 任务文档覆盖完整性
+*对于所有*在 `task_registry.py` 中注册且 task_type="utility" 的任务代码，`utility_tasks.md` 中应包含该任务代码的说明章节。
+**Validates: Requirements 6.1**
+
+Property 6: CLI 参数文档覆盖完整性
+*对于所有*在 `cli/main.py` 的 `parse_args()` 中定义的 CLI 参数，`README.md` 或 `base_task_mechanism.md` 中应包含该参数的说明。
+**Validates: Requirements 7.1**
+
+Property 7: 管道类型文档覆盖完整性
+*对于所有*在 `PipelineRunner.PIPELINE_LAYERS` 中定义的管道类型，`README.md` 中应包含该管道类型的层组合说明。
+**Validates: Requirements 7.2**
+
+## 错误处理
+
+本 spec 为文档生成任务，不涉及运行时错误处理。文档编写过程中需注意：
+
+1. 若源代码中的任务类或注册信息发生变更，文档可能过时——应在 README.md 中注明"最后更新日期"和"基于代码版本"
+2. 若某个任务的 API 端点或参数无法从代码中直接读取（如动态配置），应在文档中标注"参见配置文件"
+
+## 测试策略
+
+**单元测试（示例验证）：**
+- 验证所有 7 个 Markdown 文件存在于 `docs/etl_tasks/` 目录下
+- 验证 README.md 包含指向其他 6 个文件的链接
+- 验证每个分层文件中包含对应层的所有已注册任务代码
+
+**属性测试（覆盖完整性验证）：**
+- 使用 pytest 编写脚本，从 `task_registry.py` 动态读取已注册任务列表
+- 解析对应的 Markdown 文件，检查每个任务代码是否出现在文档中
+- 从 `cli/main.py` 解析 CLI 参数列表，检查文档中是否覆盖
+- 属性测试库：pytest（本项目已使用），配合 parametrize 实现参数化验证
+- 每个属性测试标注对应的设计属性编号
+
+**测试标注格式：**
+```python
+# Feature: etl-task-documentation, Property 1: ODS 任务文档覆盖完整性
+def test_ods_task_coverage():
+    ...
+```
+
+由于本 spec 的产出物是静态文档，属性测试的核心价值在于确保文档与代码的一致性，防止文档遗漏任务。测试应在文档生成后运行一次即可，无需持续集成。
--- a/.kiro/specs/etl-task-documentation/requirements.md
+++ b/.kiro/specs/etl-task-documentation/requirements.md
@@ -0,0 +1,119 @@
+# 需求文档：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）
--- a/.kiro/specs/etl-task-documentation/tasks.md
+++ b/.kiro/specs/etl-task-documentation/tasks.md
@@ -0,0 +1,125 @@
+# 实施计划：ETL 任务说明文档
+
+## 概述
+
+基于对 `tasks/`、`loaders/`、`orchestration/`、`cli/` 目录下源代码的分析，生成 7 个 Markdown 文档文件，放置于 `docs/etl_tasks/` 目录下。每个任务按照设计文档中定义的结构和内容范围编写。
+
+## 任务
+
+- [x] 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_
+
+- [x] 2. 创建 `docs/etl_tasks/ods_tasks.md`
+  - [x] 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_
+  - [x] 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_
+
+- [x] 3. 创建 `docs/etl_tasks/dwd_tasks.md`
+  - [x] 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_
+  - [x] 3.2 编写独立 DWD 任务说明（TICKET_DWD、PAYMENTS_DWD、MEMBERS_DWD）
+    - 每个任务列出：源 ODS 表、目标 DWD 表、处理特点
+    - _Requirements: 3.6_
+  - [x] 3.3 编写 DWD_QUALITY_CHECK 任务说明
+    - 说明行数/金额核对逻辑、金额列自动扫描规则、JSON 报表输出格式
+    - _Requirements: 3.5_
+
+- [x] 4. 创建 `docs/etl_tasks/dws_tasks.md`
+  - [x] 4.1 编写 BaseDwsTask 公共机制说明
+    - 说明时间分层（TimeLayer）、配置缓存（ConfigCache）、delete-before-insert 策略、bulk_insert/upsert 方法
+    - _Requirements: 4.1_
+  - [x] 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_
+  - [x] 4.3 编写会员分析域任务说明（2 个任务）
+    - DWS_MEMBER_CONSUMPTION：会员消费汇总、客户分层
+    - DWS_MEMBER_VISIT：会员到店明细、服务时长、折扣计算
+    - _Requirements: 4.2, 4.3, 4.4_
+  - [x] 4.4 编写财务统计域任务说明（4 个任务）
+    - DWS_FINANCE_DAILY：财务日报（结算汇总、团购、充值、赠卡消费、费用、平台）
+    - DWS_FINANCE_RECHARGE：充值统计（首充/续充、现金/赠送、卡余额）
+    - DWS_FINANCE_INCOME_STRUCTURE：收入结构分析（按类型、按区域）
+    - DWS_FINANCE_DISCOUNT_DETAIL：折扣明细统计
+    - _Requirements: 4.2, 4.3, 4.4_
+  - [x] 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_
+
+- [x] 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_
+
+- [x] 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_
+
+- [x] 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_
+
+- [x] 8. 检查点 - 验证文档完整性
+  - 确认 7 个文件全部存在于 `docs/etl_tasks/` 目录下
+  - 确认 README.md 中的任务清单覆盖所有已注册任务
+  - 确认各分层文件中的任务代码与 task_registry.py 一致
+  - Ensure all files are valid Markdown, ask the user if questions arise.
+
+- [x] 9. 编写文档覆盖完整性验证脚本
+  - [x] 9.1 编写 ODS 任务覆盖验证
+    - **Property 1: ODS 任务文档覆盖完整性**
+    - **Validates: Requirements 2.1, 2.4**
+  - [x] 9.2 编写 DWD 任务覆盖验证
+    - **Property 2: DWD 任务文档覆盖完整性**
+    - **Validates: Requirements 3.1**
+  - [x] 9.3 编写 DWS 任务覆盖验证
+    - **Property 3: DWS 任务文档覆盖完整性**
+    - **Validates: Requirements 4.1, 4.4**
+  - [x] 9.4 编写 INDEX 和 Utility 任务覆盖验证
+    - **Property 4: INDEX 任务文档覆盖完整性**
+    - **Property 5: Utility 任务文档覆盖完整性**
+    - **Validates: Requirements 5.1, 6.1**
+  - [x] 9.5 编写 CLI 参数和管道类型覆盖验证
+    - **Property 6: CLI 参数文档覆盖完整性**
+    - **Property 7: 管道类型文档覆盖完整性**
+    - **Validates: Requirements 7.1, 7.2**
+
+- [x] 10. 最终检查点
+  - Ensure all tests pass, ask the user if questions arise.
+
+## 说明
+
+- 任务标记 `*` 的为可选项，可跳过以加快 MVP 进度
+- 每个任务引用了具体的需求编号以便追溯
+- 检查点确保增量验证
+- 文档编写顺序：先写公共机制（task 1），再按层写各任务（task 2-6），最后写总览（task 7）