feat(db,docs): F1-5b MP-2 prep + 沙箱时光机模块 spec (W1)
MP-2 经 4 轮调研 + Neo 反馈,采纳方案 C(推迟到 F1-6 沙箱时光机阶段 B): - 第 1 轮原方案 D(双口径) → 第 2 轮 D'(单口径) - 第 3 轮 Neo 架构纠正:不读 DWD,走 Core/DWS/app - 第 4 轮 DWS 视图靠谱性审计:dws_assistant_daily_detail 是计费明细 (ledger_amount),不是助教工资(gross_salary 需等级时薪 + 抽成 + 罚分),且缺 effective_hours / work_days - 结论:MP-2 真正实施需要新建 dws_assistant_daily_salary 表(ETL 改造),跟其他 14 个 P1 指标一起做更高效 → 推迟到 F1-6 本次 Wave B 只做 prep:DB schema + 模块 spec + tasks.md 状态调整。 DB 迁移(zqyy_app): - db/zqyy_app/migrations/20260505__add_effective_date_for_excel_adjustments.sql - 3 张 Excel 暂存表(全空,Neo 确认尚无 Excel 上传)ADD COLUMN effective_date DATE NOT NULL(无 DEFAULT,强制未来 Excel 上传必须带): * biz.salary_adjustments(助教薪资扣款/奖励) * biz.stg_finance_expense(月度支出) * biz.stg_platform_income(平台结算收入) - 3 个复合索引 (site_id, effective_date) 支持后续 daily 截断查询 - biz.stg_recharge_commission 已有 recharge_date,无需改造 测试库执行 + 5/5 校验 PASS: - 字段存在(NOT NULL DATE 无 default) - 复合索引存在 + 列序正确 - 字段注释含 'F1-5b MP-2 prep' - INSERT 不带 effective_date 触发 NotNullViolation docs/database/ 同步: - docs/database/changes/2026-05-05__add_effective_date_for_excel_adjustments.md 完整变更说明 + 兼容性 + 回滚 + 5 条校验 SQL + 正式库执行说明 沙箱时光机模块 spec(主干任务排期登记): - docs/_overview/sandbox-replay-engine-spec.md - 22 个相关指标分 P1/P2/P3 优先级: * P1 14 项(daily 视图已有,后端切换) * P2 5 项(算法重算,含 MP-2 完整 daily salary) * P3 3 项(状态算法 + sandbox_audit_log 用户行为) - 4 阶段实施路径: * 阶段 0(本次 prep) * 阶段 A(F1-5a/b 已完成) * 阶段 B(F1-6,2-3 周)— MP-2 真正实施在此 * 阶段 C(F1-7+,1-2 周) - sandbox_replay 模块结构 + runtime_aware decorator 接口契约 - 性能 + 测试 + 前置依赖清单 F1-5b-tasks.md 状态调整: - §4.3 顺序 15:MP-2 从"待开始/C4" → "延期 F1-6" - §6 进度表 MP-2 行同步标"延期 F1-6 + 改方向说明" - 关联到 mp2_prep.md 审计 业务影响: - board-coach sandbox 行为暂遗留(F1-6 解决) - 旧 Excel 模板上传将因 NOT NULL 失败,需 F1-6 同期 ETL UI 改造 + 操作员培训 - 跨页面已 audit:board-finance / customer-records / coach-service-records / customer-service-records 等已合规(F1-5b A1/A3 + MP-1/3/5 收益) 审计:docs/audit/changes/2026-05-05__wave1_f1_5b_mp2_prep.md Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
121
docs/audit/changes/2026-05-05__wave1_f1_5b_mp2_prep.md
Normal file
121
docs/audit/changes/2026-05-05__wave1_f1_5b_mp2_prep.md
Normal file
@@ -0,0 +1,121 @@
|
||||
# 2026-05-05 · F1-5b MP-2 准备工作 + 沙箱时光机模块 spec
|
||||
|
||||
> Wave 1 / F1-5b Wave B 第 3 项任务调整(详见 `docs/_overview/wave1-findings/F1-5b-tasks.md` §4.2 顺序 15)
|
||||
>
|
||||
> 工作量评估 L / 4-6h(原方案)→ **本次仅 prep 1.5h**,完整实施延期到 F1-6
|
||||
>
|
||||
> **MP-2 决策路径**:经 4 轮调研 + Neo 反馈后,采纳方案 C(推迟到 F1-6 沙箱时光机阶段 B)
|
||||
|
||||
## 决策路径回顾
|
||||
|
||||
### 第 1 轮:原方案 D(双口径)
|
||||
推荐 partial(daily 累计) + settled(monthly 全量)双字段并存。
|
||||
|
||||
### 第 2 轮:Neo 反馈 — 助教薪资业务流程澄清
|
||||
- 系统先算工资,Excel 导入再修正(扣款/奖励对应到某一天)
|
||||
- 任务完成率应按沙箱日截至
|
||||
- 支出(房租)应按支出日期 + 沙箱日处理
|
||||
- "信任危机"业务侧担心是伪命题(沙箱本就是产品功能)
|
||||
- → 改方案 D''(单一口径,按 business_date 实时累计;DB 加 effective_date 字段)
|
||||
|
||||
### 第 3 轮:Neo 架构纠正 — 不要直接读 DWD
|
||||
- DWD 是连接器层(飞球/未来其他),后续会做 DWD 处理 + 更新 Core
|
||||
- Core 跨连接器保持表/字段一致(标准化)
|
||||
- DWS / app 视图 / RLS 都基于 Core
|
||||
- 后端应该读 Core / DWS / app,不读 DWD
|
||||
- → 改方案 D'''(走 app.v_dws_assistant_daily_detail 已有 daily 视图)
|
||||
|
||||
### 第 4 轮:DWS 视图靠谱性审计 — 发现 daily_detail 不能替代 salary_calc
|
||||
- `dws_assistant_daily_detail` 是计费明细(ledger_amount = 台费金额)
|
||||
- 不是助教工资(gross_salary,需助教等级时薪 + 抽成 + 罚分)
|
||||
- 缺 effective_hours / work_days 字段(monthly 表才有)
|
||||
- → **MP-2 真正实施需要新建 dws_assistant_daily_salary 表(ETL 改造,工作量 M)**
|
||||
- → 推迟到 F1-6 沙箱时光机阶段 B,跟其他 14 个 P1 指标一起做(更高效)
|
||||
|
||||
### 第 5 轮:Neo 同意方向 1(推迟 + prep)
|
||||
本次 Wave B 只做 prep:DB 迁移 + sandbox_replay spec 文档 + tasks.md 状态调整。
|
||||
|
||||
## 改动清单
|
||||
|
||||
### 1. DB 迁移(zqyy_app)
|
||||
|
||||
**文件**:`db/zqyy_app/migrations/20260505__add_effective_date_for_excel_adjustments.sql`
|
||||
|
||||
3 张 stg 表(全空)ADD COLUMN effective_date DATE NOT NULL(无 DEFAULT,因 Neo 反馈"截至当前还没有任何 Excel 被上传",强制未来必须带):
|
||||
|
||||
- `biz.salary_adjustments`(助教薪资扣款/奖励)
|
||||
- `biz.stg_finance_expense`(月度支出)
|
||||
- `biz.stg_platform_income`(平台结算收入)
|
||||
|
||||
3 个复合索引 `(site_id, effective_date)` 支持 daily 截断查询。
|
||||
|
||||
`biz.stg_recharge_commission` 已有 `recharge_date DATE` 字段,无需改造。
|
||||
|
||||
### 2. docs/database/ 同步
|
||||
|
||||
**文件**:`docs/database/changes/2026-05-05__add_effective_date_for_excel_adjustments.md`
|
||||
|
||||
完整变更说明 + 兼容性 + 回滚 + 5 条校验 SQL + 正式库执行说明。
|
||||
|
||||
### 3. 沙箱时光机模块 spec
|
||||
|
||||
**文件**:`docs/_overview/sandbox-replay-engine-spec.md`
|
||||
|
||||
完整模块设计:
|
||||
- 22 个相关指标分 P1/P2/P3 优先级
|
||||
- 14 个 P1 指标(daily 视图已有,后端切换即可)
|
||||
- 5 个 P2 指标(算法重算,含 MP-2 完整 daily salary)
|
||||
- 3 个 P3 指标(状态算法 + sandbox_audit_log 用户行为)
|
||||
- 4 阶段实施路径:阶段 0(本次 prep) → 阶段 A(F1-5a/b 已完成) → 阶段 B(F1-6,2-3 周) → 阶段 C(F1-7+,1-2 周)
|
||||
- sandbox_replay 模块结构 + runtime_aware decorator 接口契约
|
||||
- 性能 + 测试模式建议
|
||||
|
||||
### 4. F1-5b-tasks.md 状态调整
|
||||
|
||||
§4.3 MP-2 行从 `待开始 / C4` → `延期 F1-6`,理由 + 关联文档已登记。
|
||||
§4.2 顺序 15 行类似调整。
|
||||
|
||||
## Step 4 验证
|
||||
|
||||
DB 迁移在测试库执行 + 5/5 校验全 PASS:
|
||||
1. ✓ 3 表 effective_date 字段存在(NOT NULL DATE 无 default)
|
||||
2. ✓ 3 个复合索引存在
|
||||
3. ✓ 索引列序 (site_id, effective_date)
|
||||
4. ✓ 字段注释含 'F1-5b MP-2 prep'
|
||||
5. ✓ INSERT 不带 effective_date 触发 NotNullViolation
|
||||
|
||||
走查脚本:`_DEL/walkthrough_f1_5b/step_mp2_prep_apply_migration.py`
|
||||
|
||||
## 影响范围
|
||||
|
||||
| 端 | 改动 | 影响 |
|
||||
|----|------|------|
|
||||
| zqyy_app DB | 3 表 schema + 3 索引 | 当前数据为空,无既有数据迁移风险 |
|
||||
| ETL Excel 上传 | **未改**(F1-6 同期实施) | 旧模板上传会因 NOT NULL 失败 → 等 F1-6 ETL 改造同步 |
|
||||
| 后端 service | **未改**(MP-2 主体延期) | board-coach sandbox 行为暂未修复(F1-6 解决) |
|
||||
| admin-web / 小程序 | 无影响 | — |
|
||||
|
||||
## 风险与未覆盖
|
||||
|
||||
- **board-coach sandbox 行为遗留**:sandbox=2026-04-20 时,board-coach 仍展示月度全量(含 4-21~30 未发生数据),F1-6 才彻底修复
|
||||
- **Excel 上传未来兼容**:旧模板上传将因 NOT NULL 失败,需要 F1-6 同期完成 ETL UI 改造 + 操作员培训
|
||||
- **跨页面 audit 已识别**:board-finance / customer-records / coach-service-records / customer-service-records 等已合规(F1-5b A1/A3 + MP-1/3/5 收益),不需要本次额外处理
|
||||
|
||||
## 回滚策略
|
||||
|
||||
```sql
|
||||
BEGIN;
|
||||
DROP INDEX IF EXISTS biz.idx_salary_adj_site_eff_date;
|
||||
DROP INDEX IF EXISTS biz.idx_stg_finance_expense_site_eff;
|
||||
DROP INDEX IF EXISTS biz.idx_stg_platform_income_site_eff;
|
||||
ALTER TABLE biz.salary_adjustments DROP COLUMN IF EXISTS effective_date;
|
||||
ALTER TABLE biz.stg_finance_expense DROP COLUMN IF EXISTS effective_date;
|
||||
ALTER TABLE biz.stg_platform_income DROP COLUMN IF EXISTS effective_date;
|
||||
COMMIT;
|
||||
```
|
||||
|
||||
详见 `docs/database/changes/2026-05-05__add_effective_date_for_excel_adjustments.md`。
|
||||
|
||||
## Co-Authored-By
|
||||
|
||||
Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
||||
Reference in New Issue
Block a user