Neo-ZQYY/docs/audit/changes/2026-05-05__wave1_f1_5b_mp2_prep.md

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 收益),不需要本次额外处理

回滚策略

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