在准备环境前提交次全部更改。

.kiro/specs/etl-dws-flow-refactor/tasks.md

@@ -0,0 +1,190 @@
+# 实施计划：ETL DWS/Flow 重构
+
+## 概述
+
+按 4 个阶段顺序实施：BaseDwsTask 模板方法重构 → --layers CLI 参数 → 任务依赖声明 → 关键词/路径重命名。每个阶段完成后运行回归测试。
+
+## 任务
+
+- [x] 1. BaseDwsTask 默认模板方法
+  - [x] 1.1 在 BaseDwsTask 中添加 DATE_COL 类属性和默认 extract()/load() 实现
+    - 添加 `DATE_COL: str | None = None` 类属性
+    - 添加 `_do_extract(self, context) -> list[dict]` 抽象方法（raise NotImplementedError）
+    - 实现默认 `extract()`：调用 `_do_extract()` 并包装为标准字典
+    - 实现默认 `load()`：delete_existing_data + bulk_insert，返回标准统计字典
+    - _Requirements: 1.1, 1.2, 1.4, 1.5_
+
+  - [x] 1.2 编写 BaseDwsTask 默认模板方法的属性测试
+    - **Property 1: 默认 extract() 返回标准结构**
+    - **Validates: Requirements 1.1, 1.4**
+    - **Property 2: 默认 load() 幂等写入与标准统计**
+    - **Validates: Requirements 1.2, 1.5**
+
+  - [x] 1.3 迁移 DWS 子类使用默认模板方法
+    - 为每个 DWS 子类声明 DATE_COL
+    - 将各子类的 extract() 逻辑迁移到 _do_extract()
+    - 移除与默认 load() 行为一致的子类 load() 覆盖
+    - 保留有自定义逻辑的子类覆盖（如 AssistantSalaryTask 的月度删除）
+    - 涉及文件：assistant_daily_task.py, assistant_monthly_task.py, assistant_customer_task.py, assistant_finance_task.py, member_consumption_task.py, member_visit_task.py, finance_daily_task.py, finance_recharge_task.py, finance_income_task.py, finance_discount_task.py
+    - _Requirements: 1.1, 1.2, 1.3_
+
+  - [x] 1.4 运行现有 DWS 单元测试确认无回归
+    - `cd apps/etl/pipelines/feiqiu && pytest tests/unit/test_dws_tasks.py -v`
+    - _Requirements: 11.1_
+
+- [x] 2. 公共辅助方法提取与财务基类
+  - [x] 2.1 创建 dws_helpers.py 公共辅助模块
+    - 创建 `tasks/dws/dws_helpers.py`
+    - 提取 mask_mobile()、calc_days_since()、parse_id_list()、safe_division() 等函数
+    - 更新各 DWS 子类的导入，替换内联实现为 dws_helpers 调用
+    - _Requirements: 2.1, 2.2_
+
+  - [x] 2.2 编写 dws_helpers 函数等价性属性测试
+    - **Property 3: dws_helpers 函数等价性**
+    - **Validates: Requirements 2.3**
+
+  - [x] 2.3 创建 FinanceBaseTask 共享提取层
+    - 创建 `tasks/dws/finance_base_task.py`
+    - 从 FinanceDailyTask 提取共享方法：_extract_settlement_summary, _extract_recharge_summary, _extract_groupbuy_summary, _extract_platform_summary
+    - 迁移 FinanceDailyTask, FinanceRechargeTask, FinanceIncomeStructureTask, FinanceDiscountDetailTask 继承 FinanceBaseTask
+    - _Requirements: 3.1, 3.2, 3.3_
+
+- [x] 3. MV 刷新与数据清理合并 + MemberIndexBaseTask 模板
+  - [x] 3.1 创建 DwsMaintenanceTask 合并任务
+    - 创建 `tasks/dws/maintenance_task.py`
+    - 合并 BaseMvRefreshTask 和 DwsRetentionCleanupTask 的核心逻辑
+    - 在 TaskRegistry 中注册 DWS_MAINTENANCE，移除原三个任务注册
+    - 更新 `tasks/dws/__init__.py` 导出
+    - _Requirements: 4.1, 4.2, 4.3, 4.4, 4.5_
+
+  - [x] 3.2 编写 DwsMaintenanceTask 属性测试和单元测试
+    - **Property 4: DwsMaintenanceTask 配置控制**
+    - **Validates: Requirements 4.3, 4.4**
+    - 单元测试：执行顺序（先刷新后清理）、注册项替换
+
+  - [x] 3.3 重构 MemberIndexBaseTask 模板方法
+    - 在 MemberIndexBaseTask 中实现 execute() 模板方法
+    - 添加 _calculate_scores() 和 _save_results() 抽象方法
+    - 迁移 WinbackIndexTask 和 NewconvIndexTask 使用新模板
+    - _Requirements: 5.1, 5.2, 5.3, 5.4_
+
+- [x] 4. 检查点 - 阶段 1 回归测试
+  - 运行 `cd apps/etl/pipelines/feiqiu && pytest tests/unit -v` 确保所有测试通过
+  - 确保所有测试通过，如有问题请询问用户
+
+- [x] 5. --layers CLI 参数与统一层解析
+  - [x] 5.1 实现 --layers CLI 参数
+    - 在 cli/main.py 中添加 `--layers` 参数
+    - 实现 parse_layers() 函数：解析逗号分隔的层名，校验合法性
+    - 添加 --layers 和 --pipeline 互斥校验
+    - 更新 main() 函数：当指定 --layers 时，构造层列表传递给 PipelineRunner
+    - _Requirements: 6.1, 6.2, 6.3, 6.4_
+
+  - [x] 5.2 编写 --layers 解析属性测试
+    - **Property 5: --layers 解析正确性**
+    - **Validates: Requirements 6.1, 6.2**
+
+  - [x] 5.3 统一 _resolve_tasks() 去掉硬编码回退
+    - 移除 _resolve_tasks() 中所有硬编码回退列表
+    - 统一走 TaskRegistry.get_tasks_by_layer() 获取任务
+    - 保留配置优先级：run.ods_tasks / run.dws_tasks / run.index_tasks > Registry
+    - 空 Registry + 无配置时记录警告并返回空列表
+    - _Requirements: 7.1, 7.2, 7.3_
+
+  - [x] 5.4 编写配置优先级属性测试
+    - **Property 6: 配置优先级——配置值优先于 Registry**
+    - **Validates: Requirements 7.2**
+
+  - [x] 5.5 实现 DWS/INDEX 层轻量级校验
+    - 当 --layers 包含 DWS 或 INDEX 时，跳过完整性校验或仅执行行数校验
+    - _Requirements: 6.5_
+
+- [x] 6. 任务依赖声明与拓扑排序
+  - [x] 6.1 扩展 TaskMeta 添加 depends_on 字段
+    - 在 TaskMeta 数据类中添加 `depends_on: list[str] = field(default_factory=list)`
+    - 更新 TaskRegistry.register() 接受 depends_on 参数
+    - 为已知依赖关系添加声明（DWS_ASSISTANT_FINANCE → DWS_ASSISTANT_SALARY 等）
+    - _Requirements: 8.1, 8.2_
+
+  - [x] 6.2 实现拓扑排序函数
+    - 创建 `orchestration/topological_sort.py`
+    - 实现 Kahn's algorithm 拓扑排序
+    - 处理循环依赖检测（抛出 ValueError）
+    - 处理缺失依赖警告（记录日志继续执行）
+    - 在 PipelineRunner._resolve_tasks() 中集成拓扑排序
+    - _Requirements: 8.3, 8.4, 8.5_
+
+  - [x] 6.3 编写拓扑排序属性测试
+    - **Property 7: 拓扑排序正确性**
+    - **Validates: Requirements 8.3**
+    - **Property 8: 循环依赖检测**
+    - **Validates: Requirements 8.4**
+
+- [x] 7. 检查点 - 阶段 2+3 回归测试
+  - 运行 `cd apps/etl/pipelines/feiqiu && pytest tests/unit -v` 确保所有测试通过
+  - 运行 `cd C:\NeoZQYY && pytest tests/ -v` 确保 Monorepo 属性测试通过
+  - 确保所有测试通过，如有问题请询问用户
+
+- [x] 8. 关键词重命名 pipeline → flow
+  - [x] 8.1 重命名 PipelineRunner → FlowRunner
+    - 将 `orchestration/pipeline_runner.py` 重命名为 `orchestration/flow_runner.py`
+    - 类名 PipelineRunner → FlowRunner
+    - 常量 PIPELINE_LAYERS → FLOW_LAYERS
+    - 更新所有导入引用（task_executor.py, cli/main.py, scheduler.py 等）
+    - _Requirements: 9.1, 9.2, 9.5_
+
+  - [x] 8.2 更新 CLI 参数 --pipeline → --flow
+    - 将 `--pipeline` 重命名为 `--flow`
+    - 保留 `--pipeline` 作为已弃用别名（使用 argparse dest 映射）
+    - 使用已弃用参数时输出 DeprecationWarning
+    - 更新 --layers 互斥校验同时检查 --flow 和 --pipeline
+    - _Requirements: 9.3, 9.4_
+
+  - [x] 8.3 更新所有日志消息和注释中的 pipeline 术语
+    - 全局搜索替换日志中的 "Pipeline" / "pipeline" → "Flow" / "flow"
+    - 更新代码注释中的术语
+    - _Requirements: 9.6_
+
+- [x] 9. 路径重命名 pipelines → connectors
+  - [x] 9.1 重命名目录 apps/etl/pipelines → apps/etl/connectors
+    - 执行目录重命名
+    - 更新 pyproject.toml workspace 成员声明
+    - 更新所有 Python 导入路径
+    - _Requirements: 10.1, 10.2, 10.4_
+
+  - [x] 9.2 更新所有配置文件、脚本和文档中的路径引用
+    - 更新 .env / .env.template 中的路径
+    - 更新 run_etl.bat / run_etl.sh 中的路径
+    - 更新 scripts/ 目录下引用旧路径的脚本
+    - _Requirements: 10.3_
+
+  - [x] 9.3 运行全量测试确认路径重命名无回归
+    - `cd apps/etl/connectors/feiqiu && pytest tests/unit -v`
+    - `cd C:\NeoZQYY && pytest tests/ -v`
+    - _Requirements: 10.5_
+
+- [x] 10. 文档同步更新
+  - [x] 10.1 更新架构文档和模块文档
+    - 更新 `docs/etl-feiqiu-architecture.md`：类名、方法名、术语、路径
+    - 更新 `apps/etl/connectors/feiqiu/docs/` 下所有文档
+    - 更新 `tasks/README.md`：任务列表和继承关系
+    - _Requirements: 12.1, 12.2, 12.4_
+
+  - [x] 10.2 更新 CLI 帮助文本和示例
+    - 更新 cli/main.py 中的 epilog 示例
+    - 更新 argparse 帮助文本反映 --layers 和 --flow 参数
+    - _Requirements: 12.3_
+
+- [x] 11. 最终检查点 - 全量回归测试
+  - 运行 `cd apps/etl/connectors/feiqiu && pytest tests/unit -v`
+  - 运行 `cd C:\NeoZQYY && pytest tests/ -v`
+  - 确保所有测试通过，如有问题请询问用户
+  - _Requirements: 11.1, 11.2, 11.3, 11.4, 11.5_
+
+## 备注
+
+- 标记 `*` 的子任务为可选，可跳过以加速 MVP
+- 每个任务引用具体需求编号以确保可追溯性
+- 检查点确保增量验证
+- 属性测试验证普遍正确性属性，单元测试验证具体示例和边界条件
+- 阶段 4（关键词/路径重命名）风险最高，建议在独立 Git 分支上执行