在准备环境前提交次全部更改。
This commit is contained in:
176
apps/etl/connectors/feiqiu/docs/requirements/DWS需求与口径.md
Normal file
176
apps/etl/connectors/feiqiu/docs/requirements/DWS需求与口径.md
Normal file
@@ -0,0 +1,176 @@
|
||||
# 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：`db/etl_feiqiu/schemas/`
|
||||
- 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 完整性
|
||||
所有方案中列出的表需在 `db/etl_feiqiu/schemas/` 中落全 DDL。
|
||||
|
||||
### 6.3 时间分层实现
|
||||
UI 需要"最近半年不含本月、上季度"等时间维度，并满足上个周期的环比。DWS 分层仅到 3 个月，可能需要额外聚合层。
|
||||
Reference in New Issue
Block a user