8.6 KiB
8.6 KiB
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 个第三）
规则：
- 过档后，所有时长按新档位进行计算。举例：当前某中级助教已完成 185 小时，基础课 170 小时，附加课 15 小时：
170 × (108 - 10) + 15 × 190 × (1 - 0.30) - 本月新入职助教定档：按日均 × 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 个月，可能需要额外聚合层。