在前后端开发联调前 的提交20260223

docs/prd/specs/P2-etl-dws-miniapp-extensions.md

@@ -0,0 +1,69 @@
+# P2：ETL 扩展层 — etl-dws-miniapp-extensions
+
+> 优先级：P2（依赖 P1）
+> 预估工作量：大
+
+---
+
+## 需求（Requirements）
+
+### 用户故事
+
+1. 作为产品经理，我需要 SPI 消费力指数来评估客户消费层级，替代现有的 `customer_tier` 分层。
+2. 作为产品经理，我需要助教订单流水四项统计（订单总流水/订单净流水/时效贡献流水/时效净贡献），以便评估助教个人能力。
+3. 作为产品经理，我需要客户 30/60/90 天充值次数和金额、次均消费，以便在客户看板中展示。
+4. 作为产品经理，我需要定档折算惩罚数据，以便在绩效页面展示折算详情。
+
+### 验收标准
+
+- AC1：`dws_member_spending_power_index` 表存在，SPI 展示分 0-10 分布合理
+- AC2：`dws_assistant_order_contribution` 表存在，四项统计数值可对照 PRD 示例验算
+- AC3：`dws_member_consumption_summary` 新增字段有值（`recharge_count_30d/60d/90d`、`recharge_amount_30d/60d/90d`、`avg_ticket_amount`）
+- AC4：`dws_assistant_daily_detail` 新增字段在符合惩罚条件的订单上正确填充
+- AC5：新表的 RLS 视图和 FDW 映射已同步创建
+- AC6：`cfg_index_parameters` 中新增 `SPI` 类型的配置行
+
+---
+
+## 设计要点
+
+### SPI 指数
+- 完整算法见 `docs/prd/SPI 消费力指数.md`
+- 新建 ETL 任务 `SpendingPowerIndexTask`，继承 `BaseIndexTask`
+- 粒度：`(site_id, member_id)`，每日计算
+
+### 助教订单流水四项统计
+- 新建 ETL 任务 `AssistantOrderContributionTask`
+- 粒度：`(site_id, assistant_id, stat_date)`
+- 计算逻辑见 PRD "新增统计"节
+
+### 命名方案
+
+| 中文名 | 字段名 | 含义 |
+|--------|--------|------|
+| 订单总流水 | `order_gross_revenue` | 助教参与订单的全部流水 |
+| 订单净流水 | `order_net_revenue` | 总流水 - 助教服务分成 |
+| 时效贡献流水 | `time_weighted_revenue` | 按服务时长折算的个人贡献 |
+| 时效净贡献 | `time_weighted_net_revenue` | 时效贡献 - 助教服务分成 |
+
+### 定档折算惩罚
+- 扩展 `dws_assistant_daily_detail`：`penalty_minutes`、`penalty_reason`、`is_exempt`、`per_hour_contribution`
+- 检测逻辑：同一台桌同一时段 >2 名助教 → 计算单人贡献流水 → <24 元则按比例折算
+- 豁免标记：在订单级别打标（`is_exempt` 字段）
+- 每日 ETL 自动计算
+
+---
+
+## 任务清单
+
+- [ ] T1：设计并创建 `dws_member_spending_power_index` 表
+- [ ] T2：实现 `SpendingPowerIndexTask`（含 Level/Speed/Stability 子分）
+- [ ] T3：在 `cfg_index_parameters` 中插入 SPI 默认参数
+- [ ] T4：设计并创建 `dws_assistant_order_contribution` 表
+- [ ] T5：实现 `AssistantOrderContributionTask`
+- [ ] T6：扩展 `dws_member_consumption_summary`（充值窗口 + 次均消费字段）
+- [ ] T7：修改 `MemberConsumptionSummaryTask` 填充新字段
+- [ ] T8：扩展 `dws_assistant_daily_detail`（定档折算惩罚字段）
+- [ ] T9：实现定档折算惩罚检测与计算逻辑
+- [ ] T10：为新表创建 RLS 视图 + FDW 映射
+- [ ] T11：影子跑数验证（SPI 分布、流水统计对账）