Neo-ZQYY/docs/_overview/04c-feedback/P2-4-course-system-deep-research.md

# P2-4 课程体系深度调研(第二轮)

> 日期:2026-05-04
> 触发:Neo 否决 H-1 调研结论(`P2-4-and-P2-7-research.md`):"课程的调研不对,不够深入,课程全部应该有 包厢课 麻将课 基础课 激励课 但应该分布在不同的表中"
> 范围:**重新调研课程体系**,把上游 SaaS 真实 skill、配置表、DWD 明细、DWS 派生列、ETL 代码、前端文案统一对齐
> 数据库:`test_etl_feiqiu`(只读 SELECT)
> 替代关系:**本文件取代 `P2-4-and-P2-7-research.md` 中的 P2-4 部分。P2-7 部分仍以原文件为准。**

---

## 一、Neo 提示的关键(逐字引用)

> "category_code 不是课程,是项目分类。课程的调研不对,不够深入,课程全部应该有 **包厢课 麻将课 基础课 激励课** 但应该分布在不同的表中。"

解读:

1. **课程 ≠ 场地分类(`category_code`)**:H-1 把 `cfg_area_category` 当成课程候选,这条路是错的(它在 `category_code` 列里映射的是 `BILLIARD/SNOOKER/MAHJONG/KTV` 等"项目分类",描述台桌而非课程)。
2. **课程至少 4 类**:基础课 / 包厢课 / 麻将课 / 激励课。
3. **分布在不同表中**:不是一张表的 4 行,是多张表的不同列、不同模块各自表达一部分。

---

## 二、表搜索全集(只读,2026-05-04)

### 2.1 schema 全表名搜索结果(命中 course/lesson/class/room/mahjong/incentive/bonus/skill)

| schema | table | 命中关键字 |
|--------|-------|-----------|
| dws | `cfg_skill_type` | skill |
| dws | `cfg_bonus_rules` | bonus |
| app | `v_cfg_bonus_rules` | bonus(RLS 视图) |

注意:**没有任何表名以 `cfg_course_*`、`dim_course_*`、`mahjong_*`、`incentive_*`、`lesson_*` 命名**。也就是说"课程"在 NeoZQYY 中**不是一个独立的实体**,而是依附在助教服务记录上的一个**类型属性**。

### 2.2 含课程相关字段的表(course/lesson/class_type/room_type/mahjong/bonus_type/incentive)

| 模块 | 表 | 字段 | 用途 |
|------|---|------|------|
| 配置 | `dws.cfg_skill_type` | `skill_id`, `skill_name`, `course_type_code`(BASE/BONUS/ROOM), `course_type_name` | skill_id → 课程类型映射 |
| 配置 | `dws.cfg_assistant_level_price` | `base_course_price`, `bonus_course_price` | 等级 × 课程类型定价 |
| DWS 明细 | `dws.dws_assistant_daily_detail` | `base_*`、`bonus_*`、`room_*`(共 12 列:count/seconds/hours/ledger_amount × 3 类型) | 助教日级三维拆分 |
| DWS 工资 | `dws.dws_assistant_salary_calc` | `base_hours`、`bonus_hours`、`room_hours`、`base_income`、`bonus_income`、`room_income` | 工资按 3 类计算 |
| DWS 财务 | `dws.dws_assistant_finance_analysis` | `revenue_base`、`revenue_bonus`、`revenue_room`、`room_service_count`、`room_service_hours` | 助教营收按 3 类拆分 |
| DWS 关系 | `dws.dws_member_assistant_intimacy` | `basic_session_count`、`incentive_session_count` | 会员-助教亲密度按 2 类拆分 |
| DWS 关系 | `dws.dws_member_assistant_relation_index` | `basic_session_count`、`incentive_session_count` | 关系指数按 2 类拆分 |
| DWS 区域 | `dws.dws_coach_area_hours` | `base_hours`、`bonus_hours`、`room_hours`、`*_service_count` | 助教区域工时按 3 类 |
| DWD 明细 | `dwd.dwd_assistant_service_log` | `skill_id`, `skill_name`(原始字符串) | 单笔服务原始 skill |
| ODS 上游 | `ods.assistant_service_records` | `skill_id`, `skillname`(飞球 SaaS 原始字段) | 来自飞球 API |

---

## 三、4 类课程的实际分布

> **核心结论**:NeoZQYY 中"课程"以三个不同抽象层、四个不同模块各自表达,不存在统一的课程表。

### 3.1 基础课(BASE) — 全链路一等公民

| 层 | 实例 |
|---|------|
| ODS | `assistant_service_records.skillname='基础课'`,9 095 条有效订单(2025-09-16 ~ 2026-04-23) |
| 配置 | `cfg_skill_type` 映射 `skill_id ∈ {2790683529513797(基础课), 2791903611396869(台球基础陪打)}` → `course_type_code='BASE'`(`course_type_name='基础课'`) |
| 代码 | `base_dws_task.py::CourseType.BASE` |
| DWS 列 | `dws_assistant_daily_detail.base_service_count/base_hours/base_seconds/base_ledger_amount`(已写入,2026 年 1-4 月有数据) |
| 工资 | `dws_assistant_salary_calc.base_hours / base_income`(按 `cfg_assistant_level_price.base_course_price` × 等级 计价,初/中/高/星 = 98/108/118/138 元) |
| 关系指数 | `dws_member_assistant_intimacy.basic_session_count`(注意:这里是 `basic` 不是 `base`,命名不一致) |
| 前端文案 | "基础课"(performance/coach-detail/task-list/customer-detail) |
| 别名 | "陪打"、"PD"、`assistant_pd_money` |

### 3.2 包厢课(ROOM) — 设计存在但**实际未生效**

| 层 | 实例 |
|---|------|
| ODS | `skillname='包厢课'`,**174 条有效订单**(2026-01-06 ~ 2026-04-26) |
| 配置 | `cfg_skill_type` 中"包厢课"(`skill_id=3039912271463941`)和"包厢服务"(`skill_id=2807440316432198`)**被映射为 `course_type_code='BASE'`**(注释说"包厢服务:归入基础课统计,统一按 138 元/小时计价";"包厢课:与'包厢服务'同类") |
| 代码 | `base_dws_task.py::CourseType.ROOM` 枚举存在;`get_course_type()` 中 `if code == 'ROOM': return CourseType.ROOM` 分支存在,**但永不命中**(因配置表无 ROOM 行) |
| DWS 列 | `dws_assistant_daily_detail.room_service_count/room_hours/room_seconds/room_ledger_amount` 列存在,**全 0**(2942 行均为 0) |
| 工资 | `dws_assistant_salary_calc.room_hours / room_income` 列存在,**全 0**(10 个月全 0) |
| 财务 | `dws_assistant_finance_analysis.revenue_room` SQL 中 `WHEN ... = 'ROOM'` 分支存在,**永不命中** |
| 现状 | 174 条飞球原始包厢课订单**实际被合并进 BASE**(因为 cfg_skill_type 把它们都标成 BASE) |
| 文档 | `CLAUDE.md` 写"包厢课统一 138 元/小时(`dws.salary.room_course_price`)";`assistant_finance_task.py:146` 注释写 ROOM 分类 |

**这是 H-1 漏掉的最关键发现**:**ROOM 是设计预留 + 死代码组合**,不是 H-1 说的"纯死代码可移除"。
174 条真实包厢订单存在,Neo 心目中"包厢课要独立"是合理需求,只是配置表没把它们标出来。

### 3.3 麻将课(MAHJONG) — **数据库与代码层完全空白**

| 层 | 实例 |
|---|------|
| ODS | `assistant_service_records.skillname` 中**没有"麻将课"**(只有"基础课"/"附加课"/"包厢课"/NULL 共 4 种) |
| 飞球上游 | 飞球 SaaS **没有"麻将"作为助教 skill** |
| 配置 | `cfg_skill_type` 没有 MAHJONG 行 |
| 代码 | `CourseType` 枚举**没有 MAHJONG**(只有 BASE/BONUS/ROOM) |
| DWS 列 | 没有 `mahjong_*` 列 |
| 文档 | 仅在 `cfg_area_category.category_code='MAHJONG'` 中出现(场地分类,**不是课程**) |
| 前端 | 没有"麻将课"文案 |

**结论**:"麻将课"在 NeoZQYY **完全不存在**。它是 Neo 在业务规划层提出的概念,**当前所有表、代码、配置、上游都没有对应的载体**。

可能的语义:店铺用麻将台桌时,助教提供的服务可能也叫"麻将课"。但飞球助教 skill 当前不区分这种,落到 ODS 时 `skillname` 仍是"基础课"。

### 3.4 激励课(INCENTIVE) — **实际就是 BONUS,有别名混乱**

| 层 | 实例 |
|---|------|
| ODS | `skillname='附加课'`,985 条有效订单 |
| 配置 | `cfg_skill_type` `skill_id ∈ {2790683529513798(附加课), 2807440316432197(台球超休服务)}` → `course_type_code='BONUS'`,`course_type_name='附加课'`,`description='附加课:超休/激励课,固定 190 元/小时'` |
| 代码 | `CourseType.BONUS`;`relation_index_task.py:268` `is_incentive = course_type == CourseType.BONUS` |
| DWS 列 | `bonus_service_count/bonus_hours/bonus_seconds/bonus_ledger_amount`(已写入,2 942 行中 574 行有 bonus) |
| 关系 | `incentive_session_count`(BD 手册写"附加课服务次数",但列名用 `incentive`) |
| 工资 | `bonus_income`(单价 190,`bonus_deduction_ratio` 35%~50%) |
| 前端文案 | **"激励课" / "超休" / "打赏课" 三种说法在前端都用** — `performance.ts` 和 `performance-records.ts` 中明确写 `'超休': 'incentive', '激励课': 'incentive', '打赏课': 'incentive'`(三个上游别名都映射到 `incentive` CSS 标签) |
| BD-DWD-DOC | 称为"助教激励课正价 / `assistant_cx_money`",规则 2 强制要求 `assistant_cx_money` 表示 BONUS |
| 别名总集 | "附加课"(配置/ODS) / "激励课"(前端文案/Neo 用语) / "超休"(用户口语) / "打赏课"(用户口语) / `BONUS`(代码枚举) / `cx`(SQL/费用字段) |

**结论**:"激励课"和"BONUS"和"附加课"和"超休"是**同一个东西**,只是叫法不一致。Neo 提的"激励课"不是新维度,只是更口语化的命名。

---

## 四、4 类是否真的"分布在不同表中"

回答 Neo 的核心判断:**部分正确,但分布的不是"4 类"而是"多种抽象组合"**。

| 类别 | 是否独立存在 | 在哪些表/列体现 |
|------|------------|----------------|
| 基础课(BASE) | 是,完整 | cfg_skill_type、dwd_assistant_service_log.skill_id、dws.*.base_*(daily/salary/finance/coach_area) + intimacy.basic_session_count |
| 激励课(BONUS) | 是,完整 | 同上替换为 bonus_*、intimacy.incentive_session_count |
| 包厢课(ROOM) | **半残**:DWD 有 174 条原始订单,DWS 列预留但全 0,代码 ROOM 分支永不命中 | dws.*.room_*(daily/salary/finance/coach_area)全 0;cfg_skill_type 把它们标成 BASE 而不是 ROOM |
| 麻将课(MAHJONG) | **不存在**:仅在台桌分类中有 MAHJONG 区(`cfg_area_category`),从未作为课程类型落库 | 没有任何相关列、配置、代码 |

所以"分布在不同表"只对前两类成立(基础课和激励课确实在 daily/salary/finance/intimacy/relation_index 多表多列各自展开)。
**包厢课是半成品,麻将课是空白**。

---

## 五、与 H-1 调研对照(必须修正的错误)

H-1 报告(`P2-4-and-P2-7-research.md` 第 87-115 行)说:

| H-1 结论 | 实际情况 | 修正 |
|---------|---------|------|
| "cfg_skill_type 只有 2 行" | **6 行**(基础课/附加课各 3 个 skill_id 别名都已建好) | H-1 漏掉了 SKill_id 4/5/6(2026-03-24 通过 `add_missing_cfg_skill_type.sql` 补齐的"基础课/附加课/包厢课"原始 skill) |
| "ROOM 是死代码,所有 ROOM 分支永不命中" | 命中是真的不命中(配置无 ROOM 行),但**DWD 有 174 条真实包厢订单**正在被错误合并进 BASE | 不是"死代码可移除",而是"配置缺失导致包厢数据被吞" |
| "包厢课在 NeoZQYY 不需要" | Neo 明确要求"包厢课"独立 | 需要补齐(改 cfg_skill_type 把包厢类 skill 标成 ROOM) |
| 完全没提"麻将课" | Neo 提的 4 类之一 | 需在产品层决策"是否新增麻将课作为第 4 类" |
| 没区分"激励课 / 附加课 / 超休 / 打赏课"的别名问题 | 前端 4 套文案,后端 BONUS,配置"附加课",上游 SaaS"附加课/超休服务" | 应在"统一术语"层面收口 |

H-1 漏掉的 5 个关键点:

1. **174 条飞球包厢课订单已落 ODS / DWD,被错误归入 BASE**(因 cfg_skill_type 把它们标成 BASE)
2. **room_* 列在 4 张 DWS 表(daily/salary/finance/coach_area)同时预留,全 0**
3. **`assistant_finance_task.py:146` 写了 `WHEN ... = 'ROOM'` 的 SQL 分支**(永不命中,但代码意图清晰)
4. **关系指数模块用 `basic_session_count` / `incentive_session_count` 命名,不与 `base_*` / `bonus_*` 对齐**(同概念两套命名)
5. **前端文案 4 个别名("激励课"/"超休"/"打赏课"/"附加课")混用,没有统一术语表**

---

## 六、修正后的 P2-4 选项(给 Neo 决策)

### 选项 A:统一术语 + 启用 ROOM(最小改动,贴近现状)

1. 把 `cfg_skill_type` 中"包厢课"和"包厢服务"两行的 `course_type_code` 从 `BASE` 改为 `ROOM`
2. 重跑 dws_assistant_daily_detail / salary_calc / finance_analysis / coach_area_hours,让 174 条订单进入 `room_*` 列
3. 决定 `room_course_price` 真实值(目前 CLAUDE.md 写 138 元/小时,但 cfg_assistant_level_price 没有 room_price 列 — 需要补字段或借用现有规则)
4. 统一前端"激励课"术语:performance.ts 已经做了别名映射,但其他页面要全检
5. **不引入麻将课**

适用场景:Neo 只是想看到包厢课独立,不想全面铺开。
代价:1 次 cfg_skill_type 数据修改 + 1 次回填 + 前端术语清理 + 价格字段补齐。

### 选项 B:课程类型完整化(4 类全开,新增 MAHJONG)

1. `cfg_skill_type.course_type_code` CHECK 约束扩展支持 `BASE/BONUS/ROOM/MAHJONG`
2. `dws_assistant_daily_detail` / `salary_calc` / `coach_area_hours` 增加 `mahjong_*` 列(count/seconds/hours/ledger_amount)
3. `cfg_assistant_level_price` 增加 `room_course_price`、`mahjong_course_price` 两列
4. 关系指数表增加 `room_session_count`、`mahjong_session_count`(以及把 `basic_session_count` 重命名为 `base_session_count` 对齐)
5. ETL 4 任务全部改写
6. 飞球上游目前没有"麻将课" skill 数据 — 需要店铺侧手动在飞球后台新建 skill,或在 NeoZQYY 侧用台桌区域(area_category=MAHJONG)反推
7. 前端 task-list / performance / coach-detail / customer-detail / board-coach 全部增加第 3、4 类展示

适用场景:Neo 真的要按 4 类做长期产品规划。
代价:大改动,4 张 DWS 表 schema + 5 个 ETL 任务 + 前端多页 + 飞球上游配合。

### 选项 C:三层澄清(暂不增数据列,先消除认知冲突)

1. **不动 schema**,只产出权威术语对照表归档 `docs/_overview/04c-glossary-courses.md`
2. 明确:"激励课 = 附加课 = 超休 = 打赏课 = BONUS"是同一概念
3. 明确:"包厢课"目前合并在 BASE,需要后续单独建模(选项 A)
4. 明确:"麻将课"目前不存在,需要后续业务决策(选项 B 或不做)
5. 把现有 `room_*` 列 + `CourseType.ROOM` 枚举 + `mahjong_*` 概念 全部标记为"预留,未启用"
6. 修正 BD 手册中"附加课"/"激励课"不一致的注释

适用场景:Neo 只是想确认"我提的 4 类系统当前实际分布",不一定要立刻改实现。
代价:零代码改动,只写文档。

---

## 七、给 Neo 的决策清单

| 编号 | 决策点 | 选项 | 影响范围 |
|-----|--------|------|---------|
| D1 | "包厢课"是否独立成第 3 类 | (a)合并 BASE 不变 (b)启用 ROOM(改 cfg_skill_type+回填) (c)不动 schema 只标记 | DWS 4 表回填 + 前端展示 |
| D2 | "麻将课"是否新增为第 4 类 | (a)不引入 (b)新增 MAHJONG(大改) | DWS 列新增 + 前端 + 飞球上游配合 |
| D3 | "激励课/附加课/超休/打赏课" 是否统一术语 | (a)前端统一为"激励课" (b)统一为"附加课" (c)保持现状 | 前端 5+ 页面 + BD 手册 + 后端 schema 注释 |
| D4 | `room_*` / `CourseType.ROOM` 当前状态 | (a)启用并回填 (b)删除并清理 (c)保留预留并文档化 | 4 张 DWS 表 + ETL 4 任务 + 后端服务 |
| D5 | 关系指数模块 `basic_session_count` vs DWS 通用 `base_*` 命名不一致 | (a)统一命名(改列名) (b)在文档说明同义 (c)保持现状 | 关系表迁移 + 后端 schema |
| D6 | `cfg_assistant_level_price.room_course_price` 缺失 | (a)增加列 (b)用单一常量 138 写死 (c)等 D1 决策后再处理 | cfg_assistant_level_price 表结构 |

---

## 八、命名一致性问题(派生发现)

| 概念 | DWS 主流命名 | 关系指数命名 | 前端 CSS | 后端字段 | 上游 |
|-----|------------|-------------|---------|---------|------|
| 基础课 | `base_*` | `basic_session_count` | `course-tag--base` | `assistant_pd_money`(PD) | "基础课"/"台球基础陪打" |
| 激励课 | `bonus_*` | `incentive_session_count` | `course-tag--incentive` | `assistant_cx_money`(CX) | "附加课"/"台球超休服务" |
| 包厢课 | `room_*`(全 0) | 无 | 无 | 无 | "包厢课"/"包厢服务" |
| 麻将课 | 无 | 无 | 无 | 无 | 无 |

5 套命名混用是高熵问题,长期容易踩坑。建议在 D3/D5 决策时一并收口。

---

## 九、实际 ODS / DWD 课程数据样本(2026-05-04 测试库,脱敏)

ODS 上游 `assistant_service_records` skillname 实际分布(有效订单,`is_trash=0 AND is_delete=0`):

| skillname | 订单数 | 首次日期 | 最近日期 |
|-----------|--------|----------|----------|
| 基础课 | 9 095 | 2025-09-16 | 2026-04-23 |
| (NULL) | 7 382 | 2025-07-21 | 2025-11-30 |
| 附加课 | 985 | 2025-09-18 | 2026-04-18 |
| 包厢课 | 174 | 2026-01-06 | 2026-04-26 |

注意:NULL 7 382 条主要在 2025-07~11 期间,2025-12 起 skillname 全部填充。说明飞球 SaaS 在 2025-12 之后才补全 skillname 字段 — 这是另一个数据质量问题。

cfg_skill_type 全量(6 行):

| id | skill_id | skill_name | course_type_code | description |
|---|----------|-----------|------------------|-------------|
| 1 | 2791903611396869 | 台球基础陪打 | BASE | 基础课:陪打服务,按助教等级计价 |
| 2 | 2807440316432197 | 台球超休服务 | BONUS | 附加课:超休/激励课,固定 190 元/小时 |
| 3 | 2807440316432198 | 包厢服务 | BASE | 包厢服务:归入基础课统计,统一按 138 元/小时计价 |
| 4 | 2790683529513797 | 基础课 | BASE | 基础课:飞球系统原始课程类型,与"台球基础陪打"同类 |
| 5 | 2790683529513798 | 附加课 | BONUS | 附加课:飞球系统原始课程类型,与"台球超休服务"同类 |
| 6 | 3039912271463941 | 包厢课 | BASE | 包厢课:飞球系统原始课程类型,与"包厢服务"同类 |

**注意**:第 3、6 行注释里写"包厢服务/包厢课"但 `course_type_code` 是 `BASE` — 这是**配置数据有意为之的合并**,不是 bug。
要让 ROOM 列生效,需要把它们改成 `ROOM` + 给 `cfg_assistant_level_price` 加 `room_course_price` 列(或使用现有的 BASE 价 + 一个 ROOM 专属规则)。

DWS `dws_assistant_daily_detail` 整体统计(2 942 行):

| 指标 | base | bonus | room |
|-----|------|-------|------|
| 非零行数 | 2 833 | 574 | **0** |
| 累计服务次数 | 5 237 | 645 | **0** |
| 累计金额 | 1 546 983.80 | 301 910.00 | **0.00** |

DWS `dws_assistant_salary_calc` 月度统计(10 个月):**room_hours / room_income 全部为 0.00**。

DWS `dws_member_assistant_intimacy` 整体统计(219 行):

| 指标 | 数值 |
|------|------|
| 总会话 | 698 |
| basic_session_count | 698 |
| incentive_session_count | **0** |

注意:亲密度模块的 incentive_session_count 也全 0。这与 daily_detail 的 bonus(574 行非零)不一致,值得在选项 A 决策后再深查 `relation_index_task.py` 的归类口径。

---

## 十、总结(给主流程)

1. **课程实际分布**:不是 H-1 说的"BASE+BONUS 两类",也不是 Neo 提的"4 类独立分布",而是 **"BASE + BONUS 完整,ROOM 半残空表,MAHJONG 空白"**。
2. **5 处分布载体**:`cfg_skill_type`(配置)、`cfg_assistant_level_price`(定价)、`dws_assistant_daily_detail/salary_calc/finance_analysis/coach_area_hours`(派生汇总)、`dws_member_assistant_intimacy/relation_index`(关系)、`dwd_assistant_service_log` + `ods.assistant_service_records`(原始)。
3. **关键 H-1 错误**:漏报 cfg_skill_type 实际 6 行(不是 2 行)、漏报 174 条真实包厢课订单被错误合并进 BASE、未提"激励课"4 套别名混用、未识别关系指数模块的命名错位。
4. **不存在统一课程表**:NeoZQYY 用"skill_id → course_type_code"映射 + DWS 派生列展开的方式表达课程,没有 `dim_course` / `cfg_course` 这种独立维度。
5. **决策清单 6 项**:D1(包厢课独立) / D2(麻将课新增) / D3(术语统一) / D4(ROOM 处置) / D5(关系指数命名) / D6(包厢定价字段)。