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

.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）