---
inclusion: fileMatch
fileMatchPattern: "**/tasks/**,**/loaders/**,**/scd/**,**/dws/**,**/dwd/**,**/quality/**,**/business-rules/**,**/schemas/**,**/routers/**,**/financial*,**/settlement*,**/consume*,**/accounting*,**/salary*,**/assistant*,**/member*,**/index*,**/winback*,**/newconv*,**/relation_index*,**/spending*,**/stock*,**/finance_*,**/income_*,**/discount_*,**/order_contribution*,**/cfg_*,**/orchestration/**,**/config/**"
name: dws-doc-authority
description: DWS 层权威规范。涉及 ETL 任务/财务/结算/消费/助教/会员/指数/统计/配置相关文件时自动加载。
---

# DWS 层权威规范（强制优先参考）

DWS（Data Warehouse Summary）层从 DWD 明细层按业务维度聚合计算，输出汇总统计表，服务于助教业绩、会员分析、财务统计、指数算法等业务场景。

> DWD-DOC（`docs/reports/DWD-DOC/`）中的强制规则在 DWS 层同样生效，本文档不重复列出。两者冲突时以 DWD-DOC 为准。

## 一、任务体系（19 个已注册任务）

### 1.1 助教业绩域（6 个）

| 任务代码 | 目标表 | 粒度 | 核心指标 |
|----------|--------|------|----------|
| `DWS_ASSISTANT_DAILY` | `dws_assistant_daily_detail` | 日期+助教 | 服务次数/时长/金额、去重客户数、废除统计、惩罚检测 |
| `DWS_ASSISTANT_MONTHLY` | `dws_assistant_monthly_summary` | 月份+助教 | 月度累计、有效业绩、档位匹配、排名（考虑并列） |
| `DWS_ASSISTANT_CUSTOMER` | `dws_assistant_customer_stats` | 日期+助教+会员 | 全量累计、6 个滚动窗口（7/10/15/30/60/90 天）、活跃度 |
| `DWS_ASSISTANT_SALARY` | `dws_assistant_salary_calc` | 月份+助教 | 课时收入、奖金明细、应发工资、假期 |
| `DWS_ASSISTANT_FINANCE` | `dws_assistant_finance_analysis` | 日期+助教 | 日度收入、日均成本、毛利润、毛利率 |
| `DWS_ASSISTANT_ORDER_CONTRIBUTION` | `dws_assistant_order_contribution` | 日期+助教 | 订单总流水、净流水、时效贡献、时效净贡献 |

### 1.2 会员分析域（2 个）

| 任务代码 | 目标表 | 粒度 | 核心指标 |
|----------|--------|------|----------|
| `DWS_MEMBER_CONSUMPTION` | `dws_member_consumption_summary` | 日期+会员 | 全量累计消费、6 个滚动窗口、卡余额、活跃度、客户分层 |
| `DWS_MEMBER_VISIT` | `dws_member_visit_detail` | 日期+会员+结账单 | 消费金额拆分、支付方式拆分、台桌时长、助教服务明细（JSON） |

### 1.3 财务统计域（4 个）

| 任务代码 | 目标表 | 粒度 | 核心指标 |
|----------|--------|------|----------|
| `DWS_FINANCE_DAILY` | `dws_finance_daily_summary` | 日期 | 发生额、优惠合计、确认收入、现金流入/流出/净变动、卡消费、充值统计 |
| `DWS_FINANCE_RECHARGE` | `dws_finance_recharge_summary` | 日期 | 充值笔数/总额、首充/续充拆分、去重会员数、全店卡余额快照 |
| `DWS_FINANCE_INCOME_STRUCTURE` | `dws_finance_income_structure` | 日期+收入类型 | 按收入类型（台费/商品/助教基础课/附加课）和区域分析 |
| `DWS_FINANCE_DISCOUNT_DETAIL` | `dws_finance_discount_detail` | 日期+折扣类型 | 折扣类型拆分（GROUPBUY/VIP/ROUNDING/GIFT_CARD_*/BIG_CUSTOMER/OTHER） |

### 1.4 库存汇总域（3 个）

| 任务代码 | 目标表 | 粒度 | 更新策略 |
|----------|--------|------|----------|
| `DWS_GOODS_STOCK_DAILY` | `dws_goods_stock_daily_summary` | 日期+商品 | upsert |
| `DWS_GOODS_STOCK_WEEKLY` | `dws_goods_stock_weekly_summary` | ISO 周+商品 | upsert |
| `DWS_GOODS_STOCK_MONTHLY` | `dws_goods_stock_monthly_summary` | 月份+商品 | upsert |

### 1.5 运维任务（2 个）

| 任务代码 | 说明 |
|----------|------|
| `DWS_BUILD_ORDER_SUMMARY` | 构建订单汇总中间表 `dws_order_summary` |
| `DWS_MAINTENANCE` | 统一维护：物化视图刷新 + 历史数据清理 |


## 二、强制规则（所有 session 生效）

### 2.1 幂等更新策略
1. **汇总表默认 delete-before-insert**：按日期范围 + `site_id` 先删后插，保证幂等
2. **库存表使用 upsert**：`ON CONFLICT DO UPDATE`，因库存快照需保留最新值
3. **禁止 TRUNCATE**：DWS 表数据量大，TRUNCATE 会导致全表锁定

### 2.2 课程类型与定价
4. **课程类型通过 `cfg_skill_type` 映射**：`skill_id` → `course_type_code`（BASE/BONUS/ROOM），禁止硬编码 skill_id 判断课程类型
5. **定价通过 `cfg_assistant_level_price` 取值**：按 SCD2 生效期 as-of join，禁止硬编码价格
6. **包厢课统一价格**：`dws.salary.room_course_price = 138`（元/小时），从配置读取

### 2.3 绩效档位与工资
7. **绩效档位通过 `cfg_performance_tier` 取值**：按有效业绩小时数匹配 `[min_hours, max_hours)` 区间
8. **新入职折算规则**：入职日期在当月 1 日后视为新入职，按日均业绩 × 30 定档；入职日期 > 25 日最高定档至 T2
9. **奖金规则通过 `cfg_bonus_rules` 取值**：SPRINT 类型不累计取最高档，TOP_RANK 类型按排名发放（第 1 名 1000 元、第 2 名 600 元、第 3 名 400 元）
10. **排名计算考虑并列**：使用 `calculate_rank_with_ties()`，相同业绩小时数并列同名次

### 2.4 会员与散客
11. **散客判断**：`member_id ≤ 0` 为散客，不计入会员统计（但计入助教业绩）
12. **客户分层规则**：高价值（90 天 ≥ 3 次且 ≥ 1000 元）→ 中等（30 天内有消费）→ 低活跃（90 天内有但 30 天内无）→ 流失
13. **会员信息一律通过 ID 关联维度表**：结算单上所有会员冗余字段均不可靠（DQ-6/DQ-7），通过 `member_id` LEFT JOIN `dwd.dim_member`（`scd2_is_current=1`）

### 2.5 时间窗口与调度
14. **滚动窗口标准集**：7/10/15/30/60/90 天，使用 `calculate_rolling_stats()` 统一计算
15. **月度任务宽限期**：月初前 `dws.monthly.prev_month_grace_days`（默认 5）天可处理上月数据
16. **工资计算周期**：月初前 `dws.salary.run_days`（默认 5）天运行，超期需 `dws.salary.allow_out_of_cycle = true`

### 2.6 SCD2 维度取值
17. **助教等级 as-of 取值**：工资计算按月份生效期取历史版本，日度统计按 `stat_date` 取当日版本
18. **会员卡余额 as-of 取值**：通过 `get_member_card_balance_asof()` 按日期取快照

### 2.7 台桌分类
19. **`cfg_area_category` 仅精确匹配 + 兜底**：2026-03-07 改版后无 LIKE 匹配，分类为 BILLIARD/SNOOKER/OTHER，`BILLIARD_VIP` 已废弃

## 三、指数算法体系

### 3.1 总览

| 指数 | 全称 | 输出表 | 作用 |
|------|------|--------|------|
| WBI | Winback Index | `dws_member_winback_index` | 老客挽回优先级 |
| NCI | Newconv Index | `dws_member_newconv_index` | 新客转化优先级 |
| RS | Relation Index | `dws_member_assistant_relation_index` | 助教-会员关系强度 |
| OS | Ownership Index | — | 所有权指数 |
| MS | Maintenance Score | — | 维护分 |
| ML | Manual Ledger | `dws_ml_manual_order_alloc` | 人工台账（唯一真源） |
| SPI | Spending Power Index | `dws_member_spending_power_index` | 消费力指数 |

### 3.2 WBI（老客挽回指数）强制规则
20. **分项得分**：Overdue（超期分，加权经验 CDF）+ Drop（降频分，近 14 天差值）+ Recharge（充值压力，衰减分）+ Value（价值分，对数压缩）
21. **Raw Score 公式**：`WBI_raw = w_over × overdue + w_drop × drop + w_re × recharge + w_value × value`
22. **近访抑制（Recency Suppression）**：距今 < 14 天 suppression = 0（Hard floor）；14-17 天 Sigmoid 衰减
23. **分流规则**：STOP（距今 ≥ 60 天，高余额例外可选）→ NEW（到店 ≤ 2 次或首访 ≤ 30 天或充值未回访）→ OLD（其他）

### 3.3 NCI（新客转化指数）强制规则
24. **分项得分**：Welcome（欢迎分，首访/单访 3 天内触发）+ Need（转化紧迫度）+ Salvage（可救度，30-60 天线性衰减）+ Recharge/Value（同 WBI）
25. **活跃抑制**：新客近 14 天来店 ≥ 2 次且最近活跃，用 0.2 系数抑制转化召回分

### 3.4 指数参数配置
26. **参数通过 `cfg_index_parameters` 加载**：按 `index_type` 分组，支持 EWMA 平滑，禁止硬编码权重/阈值


## 四、配置表体系

### 4.1 绩效档位（`dws.cfg_performance_tier`）

| 档位 | 小时区间 | 抽成（元/小时） | 打赏抽成 | 假期 |
|------|----------|-----------------|----------|------|
| T0（0 档） | 0-120 | 28 | 50% | 3 天 |
| T1（1 档） | 120-150 | 18 | 40% | 4 天 |
| T2（2 档） | 150-180 | 13 | 35% | 5 天 |
| T3（3 档） | 180-210 | 10 | 30% | 6 天 |
| T4（4 档） | 210+ | 8 | 25% | 自由假期 |

> 以上为 2026-03-01 起生效版本，历史版本通过 `effective_from/effective_to` SCD2 管理。

### 4.2 助教等级定价（`dws.cfg_assistant_level_price`）

| 等级 | 基础课（元/小时） | 附加课（元/小时） |
|------|-------------------|-------------------|
| 8（助教管理） | 98 | 190 |
| 10（初级） | 98 | 190 |
| 20（中级） | 108 | 190 |
| 30（高级） | 118 | 190 |
| 40（星级） | 138 | 190 |

### 4.3 奖金规则（`dws.cfg_bonus_rules`）

| 规则类型 | 生效期 | 说明 |
|----------|--------|------|
| SPRINT（冲刺奖金） | ≤ 2026-02-28 | 不累计，取最高档 |
| TOP_RANK（排名奖金） | ≥ 2026-03-01 | 第 1 名 1000 元、第 2 名 600 元、第 3 名 400 元 |

### 4.4 技能→课程类型映射（`dws.cfg_skill_type`）

| 课程类型代码 | 名称 | 定价规则 |
|-------------|------|----------|
| BASE | 基础课（陪打/PD） | 按等级定价 98-138 元/小时 |
| BONUS | 附加课（超休/CX） | 固定 190 元/小时 |
| ROOM | 包厢课 | 统一 138 元/小时（`dws.salary.room_course_price`） |

### 4.5 台桌分类（`dws.cfg_area_category`）

| 分类代码 | 说明 | 备注 |
|----------|------|------|
| BILLIARD | 台球（含原 V1-V4） | 2026-03-07 改版 |
| SNOOKER | 斯诺克（含原 V5） | 2026-03-07 改版 |
| OTHER | 兜底 | 未匹配时归入 |

> `BILLIARD_VIP` 已废弃（2026-03-07），禁止引用。

### 4.6 指数参数（`dws.cfg_index_parameters`）

按 `index_type`（WBI/NCI/RS/OS/MS/ML/SPI）分组加载，支持 EWMA 平滑。所有权重和阈值从此表读取，禁止硬编码。

## 五、BaseDwsTask 公共机制

### 5.1 时间分层（TimeLayer）

| 枚举值 | 范围 | 用途 |
|--------|------|------|
| LAST_2_DAYS | 近 2 天 | 日度增量 |
| LAST_1_MONTH | 近 30 天 | 月度汇总 |
| LAST_3_MONTHS | 近 90 天 | 季度分析 |
| LAST_6_MONTHS | 近 6 个月（不含本月） | 半年趋势 |
| ALL | 从 2000-01-01 起 | 全量重算 |

### 5.2 配置缓存（ConfigCache）
- 类级别共享，TTL 5 分钟
- 包含：绩效档位、等级定价、奖金规则、区域分类、技能类型
- 支持 SCD2 生效期过滤

### 5.3 数据读写方法
- `iter_dwd_rows()`：分批迭代 DWD 数据（默认 1000 行/批）
- `query_dwd()`：直接执行任意 SQL
- `delete_existing_data()`：按日期范围 + site_id 删除
- `bulk_insert()`：批量插入
- `upsert()`：ON CONFLICT DO UPDATE

### 5.4 辅助计算
- `calculate_rolling_stats()`：滚动窗口统计
- `calculate_rank_with_ties()`：并列排名
- `is_new_hire_in_month()`：新入职判断
- `is_guest()`：散客判断（member_id ≤ 0）
- `safe_decimal()` / `safe_int()`：安全类型转换
- `seconds_to_hours()` / `hours_to_seconds()`：时间单位转换
- `get_assistant_level_asof()`：SCD2 助教等级
- `get_member_card_balance_asof()`：SCD2 会员卡余额

## 六、字段命名规范

### 6.1 金额字段
- 统一 `NUMERIC(12,2)`，货币单位 CNY
- 储值卡：DWS 层使用 `balance_pay`（总额）、`recharge_card_pay`（现金充值卡）、`gift_card_pay`（赠送卡）
- 财务日报：使用 `recharge_card_consume`
- 助教费用：`assistant_pd_money`（陪打）、`assistant_cx_money`（超休），禁止使用 `service_fee`

### 6.2 时间字段
- `stat_date`：统计日期（DATE）
- `stat_month`：统计月份（CHAR(7)，格式 YYYY-MM）
- `created_at` / `updated_at`：TIMESTAMPTZ

### 6.3 标识字段
- `site_id`：门店 ID（多门店隔离，RLS）
- `tenant_id`：租户 ID
- `member_id`：会员 ID（≤ 0 为散客）
- `assistant_id`：助教 ID

## 七、调度与 Flow 类型

| Flow 类型 | 包含阶段 | 说明 |
|-----------|----------|------|
| `dwd_dws` | 仅 DWS 汇总 | 日常增量 |
| `dwd_dws_index` | DWS 汇总 + 指数计算 | 含指数更新 |
| `api_full` | ODS → DWD → DWS → INDEX | 全流程 |

处理模式：`increment_only`（默认）、`verify_only`（仅校验修复）、`increment_verify`（先增量后校验）

## 八、DWS 层完整表清单

### 汇总表
`dws_assistant_daily_detail`、`dws_assistant_monthly_summary`、`dws_assistant_customer_stats`、`dws_assistant_salary_calc`、`dws_assistant_finance_analysis`、`dws_assistant_order_contribution`、`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_goods_stock_daily_summary`、`dws_goods_stock_weekly_summary`、`dws_goods_stock_monthly_summary`、`dws_order_summary`

### 指数表
`dws_member_winback_index`、`dws_member_newconv_index`、`dws_member_recall_index`、`dws_member_assistant_relation_index`、`dws_member_assistant_intimacy`、`dws_member_spending_power_index`、`dws_index_percentile_history`

### 其他表
`dws_platform_settlement`、`dws_ml_manual_order_source`、`dws_ml_manual_order_alloc`、`dws_assistant_recharge_commission`、`dws_assistant_project_tag`、`dws_member_project_tag`

### 视图
`v_member_recall_priority`

### 配置表
`cfg_performance_tier`、`cfg_assistant_level_price`、`cfg_bonus_rules`、`cfg_skill_type`、`cfg_area_category`、`cfg_index_parameters`

## 九、废弃对象（禁止引用）

| 对象 | 删除日期 | 替代方案 |
|------|----------|----------|
| `BILLIARD_VIP` 分类代码 | 2026-03-07 | V1-V4 归入 BILLIARD，V5 归入 SNOOKER |
| `dwd_assistant_trash_event` | 2026-02-22 | `dwd_assistant_service_log_ex.is_trash` |
| `RecallIndexTask` / `IntimacyIndexTask` | 2026-02-13 | WBI + NCI + RelationIndexTask |
| SPRINT 奖金规则 | 2026-02-28 止 | TOP_RANK 排名奖金（2026-03-01 起） |

## 十、关键文档索引

| 文档 | 路径 |
|------|------|
| DWS 任务详解 | `apps/etl/connectors/feiqiu/docs/etl_tasks/dws_tasks.md` |
| DWS 指标定义 | `apps/etl/connectors/feiqiu/docs/business-rules/dws_metrics.md` |
| 指数算法说明 | `apps/etl/connectors/feiqiu/docs/business-rules/index_algorithm_cn.md` |
| BaseDwsTask 机制 | `apps/etl/connectors/feiqiu/docs/etl_tasks/base_task_mechanism.md` |
| BD 手册（DWS 表） | `apps/etl/connectors/feiqiu/docs/database/DWS/main/` |
| DWD-DOC 权威规则 | `.kiro/steering/dwd-doc-authority.md` |

## 与其他文档的优先级

DWS 层开发时的参考优先级：DWD-DOC > 本文档 > BD 手册 > ETL 任务文档 > 业务规则文档 > DDL 注释。

> 本文档基于 2026-03-19 对项目代码、配置表、BD 手册和审计记录的全面收集整理。