# 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>