# 实现计划：ETL DWS 层扩展 — 小程序数据支撑 ## 概述 基于设计文档，将实现拆分为：DDL 建表/扩展 → 助教订单流水统计任务 → 会员消费汇总扩展 → 定档折算惩罚 → RLS 视图 + FDW 映射 → 影子跑数验证 六个阶段。所有数据库操作在测试库（`test_etl_feiqiu` / `test_zqyy_app`）中进行。 ## 任务 - [x] 1. DDL 建表与字段扩展 - [x] 1.1 编写迁移脚本创建 `dws.dws_assistant_order_contribution` 表 - 新建 `db/etl_feiqiu/migrations/<日期>__create_dws_assistant_order_contribution.sql` - 包含表定义、唯一索引 `idx_aoc_site_assistant_date`、查询索引 `idx_aoc_stat_date` - 字段参照设计文档数据模型章节 - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5_ - [x] 1.2 编写迁移脚本扩展 `dws_member_consumption_summary` 字段 - 新建 `db/etl_feiqiu/migrations/<日期>__alter_member_consumption_add_recharge_fields.sql` - ALTER TABLE 添加 `recharge_count_30d/60d/90d`、`recharge_amount_30d/60d/90d`、`avg_ticket_amount` - _Requirements: 3.1, 3.2_ - [x] 1.3 编写迁移脚本扩展 `dws_assistant_daily_detail` 字段 - 新建 `db/etl_feiqiu/migrations/<日期>__alter_assistant_daily_add_penalty_fields.sql` - ALTER TABLE 添加 `penalty_minutes`、`penalty_reason`、`is_exempt`、`per_hour_contribution` - _Requirements: 5.1, 5.2_ - [x] 1.4 在测试库 `test_etl_feiqiu` 执行全部迁移脚本 - 通过 `PG_DSN`（指向测试库）连接执行 SQL - _Requirements: 1.5, 3.2, 5.2_ - [x] 1.5 运行 `gen_consolidated_ddl.py` 导出最新 DDL - 执行 `python scripts/ops/gen_consolidated_ddl.py` - 验证 `docs/database/ddl/etl_feiqiu__dws.sql` 已包含新表和扩展字段 - _Requirements: 1.6_ - [x] 2. 实现助教订单流水统计任务 - [x] 2.1 创建数据结构和 `AssistantOrderContributionTask` 骨架 - 新建 `apps/etl/connectors/feiqiu/tasks/dws/assistant_order_contribution_task.py` - 定义 `TableUsage`、`AssistantService`、`OrderData` dataclass - 定义 `AssistantOrderContributionTask` 类继承 `BaseDwsTask` - 实现 `get_task_code`、`get_target_table`、`get_primary_keys` - _Requirements: 1.1, 2.7_ - [x] 2.2 实现四项统计核心计算（纯函数） - 实现 `compute_order_gross_revenue` 静态方法 - 实现 `compute_order_net_revenue` 静态方法 - 实现 `compute_time_weighted_revenue` 静态方法（含台费分摊、酒水均分逻辑） - 实现 `compute_time_weighted_net_revenue` 静态方法 - 处理超休/打赏课特殊情况 - _Requirements: 2.2, 2.3, 2.4, 2.5, 2.6_ - [x] 2.3 编写属性测试：订单级统计不变量 - **Property 1: 订单级统计不变量 — gross/net 各助教相等** - **Validates: Requirements 2.2, 2.3, 10.1, 10.2** - [x] 2.4 编写属性测试：时效贡献流水之和约束 - **Property 2: 时效贡献流水之和 ≤ order_gross_revenue** - **Validates: Requirements 2.4, 10.3** - [x] 2.5 编写属性测试：时效净贡献减法关系 - **Property 3: time_weighted_net_revenue = time_weighted_revenue - commission** - **Validates: Requirements 2.5, 10.4** - [x] 2.6 实现 `extract` 方法 - 从 `dwd_settlement_head`、`dwd_table_fee_log`、`dwd_assistant_service_log` 提取数据 - 按 `order_settle_id` 聚合为 `OrderData` 结构 - _Requirements: 2.1_ - [x] 2.7 实现 `transform` 方法 - 遍历订单，调用四项统计计算函数 - 按 `(assistant_id, stat_date)` 聚合日度统计 - _Requirements: 2.2, 2.3, 2.4, 2.5, 2.6_ - [x] 2.8 注册任务到 task_registry 并导出模块 - 在 `tasks/dws/__init__.py` 中导出 `AssistantOrderContributionTask` - 在 `orchestration/task_registry.py` 中注册 `DWS_ASSISTANT_ORDER_CONTRIBUTION`，`layer="DWS"`，`depends_on=["DWD_LOAD_FROM_ODS"]` - _Requirements: 2.7, 2.8_ - [x] 3. 检查点 — 确保助教订单流水统计测试通过 - 运行属性测试：`cd C:\NeoZQYY && pytest tests/test_dws_contribution_properties.py -v` - 确保所有属性测试通过，如有问题请询问用户。 - [x] 4. 扩展会员消费汇总任务 - [x] 4.1 在 `MemberConsumptionTask` 中新增充值统计提取 - 新增 `_extract_recharge_stats` 方法，从 `dwd.dwd_recharge_order` 按 30/60/90 天窗口聚合 - 在 `extract` 方法中调用并返回充值统计数据 - _Requirements: 4.1, 3.3_ - [x] 4.2 在 `MemberConsumptionTask.transform` 中填充新字段 - 合并充值统计到输出记录 - 计算 `avg_ticket_amount = total_consume_amount / MAX(total_visit_count, 1)` - 处理无充值/无消费的边界情况 - _Requirements: 4.2, 4.3, 4.4, 3.4_ - [x] 4.3 编写属性测试：次均消费公式 - **Property 5: avg_ticket_amount = total_consume_amount / MAX(total_visit_count, 1)** - **Validates: Requirements 3.4, 10.7** - [x] 5. 实现定档折算惩罚检测与计算 - [x] 5.1 实现时间重叠检测逻辑 - 在 `AssistantDailyTask` 中新增 `detect_overlap_violations` 静态方法 - 定义惩罚区域集合（大厅 A/B/C/S/TV + 麻将房 M1–M7） - 按 `(table_id, service_date)` 分组，检测时间段重叠且助教数 > 2 - _Requirements: 6.1_ - [x] 5.2 实现惩罚分钟数计算 - 在 `AssistantDailyTask` 中新增 `compute_penalty_minutes` 静态方法 - 计算 `per_hour_contribution = 台费每小时单价 / 助教人数` - 按分段公式计算 `penalty_minutes` - 处理 `is_exempt = TRUE` 豁免逻辑 - _Requirements: 6.2, 6.3, 6.4, 6.5_ - [x] 5.3 集成惩罚逻辑到 `AssistantDailyTask.transform` - 在现有聚合逻辑后调用重叠检测和惩罚计算 - 将 `penalty_minutes`、`penalty_reason`、`is_exempt`、`per_hour_contribution` 填充到输出记录 - _Requirements: 6.6, 6.7_ - [x] 5.4 编写属性测试：惩罚分钟数分段公式 - **Property 4: 惩罚分钟数符合分段公式且在 [0, actual_minutes] 范围内** - **Validates: Requirements 6.3, 6.4, 10.5, 10.6** - [x] 5.5 编写属性测试：重叠检测正确性 - **Property 6: 3+ 助教时间重叠时应检测到违规** - **Validates: Requirements 6.1** - [x] 6. 检查点 — 确保惩罚计算和消费汇总测试通过 - 运行属性测试：`cd C:\NeoZQYY && pytest tests/test_dws_contribution_properties.py -v` - 运行单元测试：`cd apps/etl/connectors/feiqiu && pytest tests/unit/ -k "contribution or penalty or consumption" -v` - 确保所有测试通过，如有问题请询问用户。 - [x] 7. RLS 视图与 FDW 映射 - [x] 7.1 创建 `dws_assistant_order_contribution` 的 RLS 视图 - 在测试库 `test_etl_feiqiu` 的 `app` schema 中创建 `v_dws_assistant_order_contribution` 视图 - 使用 `current_setting('app.current_site_id')::bigint` 过滤 - 授予 `app_reader` 角色 SELECT 权限 - _Requirements: 7.1, 7.3_ - [x] 7.2 验证已有 RLS 视图自动包含新增字段 - 确认 `app.v_dws_member_consumption_summary` 和 `app.v_dws_assistant_daily_detail` 使用 `SELECT *`，新增字段自动包含 - _Requirements: 7.2_ - [x] 7.3 创建/更新 FDW 外部表映射 - 在测试库 `test_zqyy_app` 的 `fdw_etl` schema 中创建 `dws_assistant_order_contribution` 外部表 - 重建 `dws_member_consumption_summary` 和 `dws_assistant_daily_detail` 的 FDW 外部表以包含新字段 - FDW 映射通过 `app` schema RLS 视图访问 - _Requirements: 8.1, 8.2, 8.3_ - [x] 8. 影子跑数验证 - [x] 8.1 编写验证脚本 - 新建 `apps/etl/connectors/feiqiu/scripts/verify_dws_extensions.py` - 验证四项统计：对照 PRD 示例数据验算，检查 gross/net 各助教相等 - 验证充值窗口：检查新增字段有值，充值金额与源数据一致 - 验证惩罚字段：检查符合条件的记录正确填充 - _Requirements: 9.1, 9.2, 9.3, 9.4_ - [x] 8.2 编写数据库手册文档 - 新建 `docs/database/BD_Manual_dws_assistant_order_contribution.md` - 包含表结构、字段说明、索引、验证 SQL（至少 3 条）、兼容性说明、回滚策略 - 更新 `docs/database/` 中 `dws_member_consumption_summary` 和 `dws_assistant_daily_detail` 的文档 - _Requirements: 1.1_ - [x] 9. 最终检查点 — 确保所有测试通过 - 运行属性测试：`cd C:\NeoZQYY && pytest tests/test_dws_contribution_properties.py -v` - 运行单元测试：`cd apps/etl/connectors/feiqiu && pytest tests/unit/ -k "contribution or penalty or consumption" -v` - 确保所有测试通过，如有问题请询问用户。 ## 备注 - 标记 `*` 的子任务为可选（属性测试），可跳过以加速 MVP - 每个任务引用具体需求编号以确保可追溯 - 所有数据库操作在测试库（`test_etl_feiqiu` / `test_zqyy_app`）中进行 - 检查点确保增量验证 - 属性测试验证全称正确性属性，单元测试验证具体示例和边界情况