# DWS 需求与口径（合并版）

> 合并自原 `DWS 数据库处理需求.md`、`DWS财务口径补充.md`、`DWS口径与规则补充.md`（2026-02-19）。
> 指数算法需求已独立至 `关系指数PRD.txt`（RS/OS/MS/ML）和 `指数运营场景矩阵.txt`，本文不再包含。
> 财务页面 UI 原型见 `财务页面需求.md`。

---

## 一、总体目标

在 ETL 已完成的 DWD 层数据基础上，完成 DWS 层的数据处理：
- 数据库设计（DDL）
- DWD 读取 → Python 处理 → SQL 写入
- SQL 和 Python 代码需要详尽的中文注释

参考路径：
- DWD schema 文档：`docs/database/`
- DWS DDL：`docs/database/ddl/etl_feiqiu__dws.sql`
- DWS 种子数据：`db/etl_feiqiu/seeds/`

---

## 二、通用需求

### 2.1 数据时间分层
四层时间分层（按更新时间），以符合业务层面的查询效率：
- 第一层：回溯两天前到当前数据
- 第二层：回溯 1 个月前到当前数据
- 第三层：回溯 3 个月前到当前数据
- 第四层：全量数据
- 需要有配套的机制及时添加删除整理数据

实现方式：分区策略/分层表或物化汇总层/定期归档与清理作业。

### 2.2 统计口径注意
- 计算助教业绩/工资时，需参考助教废除表，排除相关业务数据的影响
- 计算助教业绩/工资时，注意辨别基础课/附加课影响
- 散客处理：`member_id=0` 的客户是散客，不进入客户维度统计
- 门店/租户范围：当前只有一个门店，一个租户

### 2.3 时间口径定义
- 本周/上周/本季度/上季度/最近半年不含本月等窗口的"起止边界"为月第一天 0 点
- 周起始日为周一
- 环比规则：开启对比时，是"对比上一个等长区间"

---

## 三、系统设置（薪酬方案）

助教绩效与工资结算方案需落库并标记生效时间（按月取生效规则）。

### 3.1 旧方案（2025 年 7 月生效，历史口径）
- 球房统一抽成：18 元/小时
- 保底奖励机制：

| 保底线等级 | 对应完成小时数 | 保底收入 |
|-----------|----------------|----------|
| 初级 | 130 | 12000 |
| 中级 | 150 | 16000 |
| 高级 | 160 | 18000 |
| 星级 | 170 | 23000 |

- 保底与助教分成（客户支付减去球房抽成）取最大值发放

### 3.2 新方案（2026-03-01 起，现行口径）

| 档位 | 总业绩小时数阈值 | 专业课抽成（元/小时） | 打赏课抽成 | 次月休假（天） |
|------|------------------|----------------------|------------|----------------|
| 0档 淘汰压力 | H < 120 | 28 | 50% | 3 |
| 1档 及格档 | 120 ≤ H < 150 | 18 | 40% | 4 |
| 2档 良好档 | 150 ≤ H < 180 | 13 | 35% | 5 |
| 3档 优秀档 | 180 ≤ H < 210 | 10 | 30% | 6 |
| 4档 销冠竞争 | H ≥ 210 | 8 | 25% | 休假自由 |

课程类型（`dwd_assistant_service_log` 表的 `skill_name`，实际用 `skill_id` 枚举判断）：
- 基础课：又名专业课/上桌/上钟，按分钟计时
- 附加课：又名超休/激励/打赏，按整小时计时
- 包厢课：归入基础课口径，客户支付统一 138 元/小时
- 总业绩小时数阈值 = 基础课 + 附加课

客户支付价格：
- 基础课：初级 98 元/小时，中级 108 元/小时，高级 118 元/小时，星级 138 元/小时
- 附加课：统一 190 元/小时
- 包厢课（基础课）：统一 138 元/小时

Top3 销冠奖（2026-03-01 起）：第 1 名 1000 元，第 2 名 600 元，第 3 名 400 元。
- 排名口径：按绩效总小时数。如遇并列则都算（如 2 个第一，则记为 2 个第一，1 个第三）

规则：
1. 过档后，所有时长按新档位进行计算。举例：当前某中级助教已完成 185 小时，基础课 170 小时，附加课 15 小时：`170 × (108 - 10) + 15 × 190 × (1 - 0.30)`
2. 本月新入职助教定档：按日均 × 30 的总业绩小时数定档。月 1 日 0 点之后入职的计算为新入职，入职日以助教表入职时间为准。在当月 25 日后入职的新助教，最高定档至 2 档（T2）。该折算仅用于定档，不适用于 Top3 奖的计算口径。

### 3.3 薪酬规则与生效期
- 档位、奖金、规则有"按月/按时间生效"的要求
- 配置表：`cfg_performance_tier`、`cfg_bonus_rules`，需补充生效期字段或独立"规则生效期配置表"
- SCD2 / as-of 口径：助教等级是 SCD2 维度，历史月份不能直接用"当前等级"，需按有效期 as-of join 取数
- 技能枚举规范：用 `skill_id` 判断基础课/附加课，通过 `cfg_skill_type` 配置表映射

---

## 四、业务需求

### 4.1 助教维度
以每个助教个体的视角：
- 业绩档位：历史月份与本月档位进度，档位影响的收入单价，相邻月份的变化
- 有效业绩：历史月份与本月的基础课课时、激励课课时、全部课课时，相邻月份的变化
- 收入：历史月份与本月的收入（注意助教等级、业绩档位、课程种类等因素的总和计算），相邻月份的变化
- 客户情况：过去 7/10/15/30/60/90 天的跨度统计，服务过的客户数据，关联每次服务的时间、时长、台桌、分类等详细信息
- 有效业绩的排除规则：仅对"助教废除表"的记录进行处理排除

### 4.2 客户维度
统计每个客户的信息：
- 过去 7/10/15/30/60/90 天的跨度统计，来店消费情况
- 关联每次服务的时间、食品饮品、时长、台桌、分类、助教服务等详细信息

### 4.3 财务维度
详见 `财务页面需求.md`（UI 原型级需求）。

---

## 五、财务口径补充

### 5.1 支出/成本数据
- DWD 里只有商品成本 `dwd_store_goods_sale.cost_money`
- 房租、水电、物业、工资、报销、平台服务费等现金支出 → 数据库结构中预留，后期通过 Excel 手动导入

### 5.2 平台回款与团购差价
- DWD 只有团购核销/验券记录（`dwd_groupbuy_redemption` / `dwd_platform_coupon_redemption`）
- 平台结算/回款/佣金/服务费明细 → 数据库结构中预留，后期通过 Excel 手动导入
- 导入数据字段包含：回款金额、佣金、服务费、回款日期、平台类型、订单关联键

### 5.3 优惠分类口径
- 赠送卡抵扣 = 酒水卡 + 台费卡 + 活动抵用券结账抵扣
- 团购优惠 = `ledger_amount` + `assistant_promotion_money` - `ledger_unit_price`
- 大客户优惠和其他优惠 = 手动调账产生的优惠（订单中的折扣、台桌折扣、商品折扣、手动优惠，需抽样分析确认）

### 5.4 发生额/正价口径
- 结账记录中的正价：`table_charge_money`（台费正价）、`goods_money`（商品正价）、`assistant_pd_money`（助教基础课正价）、`assistant_cx_money`（助教激励课正价）
- 团购中的正价：`ledger_amount`（台桌正价）+ `assistant_promotion_money`（助教正价）
- 团购中的核销价：`ledger_unit_price`

### 5.5 订单支付信息
- 会员卡支付金额：`recharge_card_amount`（卡类型需从 `dwd_settlement_head` 的 `order_settle_id` 去 `dwd_member_balance_change` 表找到卡的类型）
- 收银实付：`pay_amount`
- 团购抵消的台费：`coupon_amount`
- 团购支付的金额：若 `pl_coupon_sale_amount` 非 0 则使用；若为 0 且 `coupon_amount` 不为 0，则到 `dwd_groupbuy_redemption` 找对应订单的 `ledger_unit_price`
- 台费打折：`adjust_amount`
- 团购券优惠 = 团购抵消的台费 - 团购支付的金额

### 5.6 区域/房型维度
- `BD_manual_dim_table.md` 中有台区分布的对应关系
- 配置表 `cfg_area_category` 需落地具体映射规则 + 默认兜底 + 异常值处理

### 5.7 充值与赠送卡口径
- 酒水卡、台费卡、活动抵用券是赠送卡，分类在 `dim_member_card_account` 的 `card_type_id`
- 储值卡是充值的"现金卡"
- 充值提成：数据库结构中预留，后期通过 Excel 手动导入（记录月份、充值金额、储值卡关联、提成金额）

### 5.8 财务口径矩阵
需扩展至财务页面每一项指标（发生额/优惠拆分/确认收入/现金流/充值/平台回款/支出结构），确保每一项都有明确字段 + 公式 + 来源表。

### 5.9 手工导入表规范
支出/平台回款/充值提成的 Excel 导入需补"字段定义、时间粒度、门店维度、去重与校验规则"。

---

## 六、实现要点备忘

### 6.1 滚动区间统计
需求中明确 7/10/15/30/60/90 天窗口，在 `dws_assistant_customer_stats`、`dws_member_consumption_summary` 中直接落多窗口字段。

### 6.2 DDL 完整性
所有方案中列出的表需在 `docs/database/ddl/etl_feiqiu__dws.sql` 中落全 DDL。

### 6.3 时间分层实现
UI 需要"最近半年不含本月、上季度"等时间维度，并满足上个周期的环比。DWS 分层仅到 3 个月，可能需要额外聚合层。