Neo-ZQYY/docs/_overview/WAVES-MASTER-PLAN.md

全 Wave 主计划(Wave 0 ~ Wave 5)

日期:2026-05-04 / 用途:NeoZQYY 项目从调研基线到上线的完整 Wave 规划 基础:Wave 0 调研产出 + 39 条文档冲突 + Neo 全部反馈决策 + 8 处追加 D Bug 发现

维护协议:每个 Wave 收尾后更新本文件 + 各 Wave kickoff 文档

一、Wave 全景图

Wave 0  调研基线         [已完成]   ████████████  Neo 全部反馈两轮 + 决策入档
Wave 1  沙箱 + 致命 Bug  [已 kickoff] ████░░░░░░░░  5-7 工作日
Wave 2  Schema 迁移      [待启动]   ░░░░░░░░░░░░  4-6 工作日
Wave 3  业务功能补强     [待启动]   ░░░░░░░░░░░░  3-5 工作日
Wave 4  DWS/RLS/数据     [待启动]   ░░░░░░░░░░░░  5-7 工作日
Wave 5  文档收尾 + 上线门槛验收 [待启动] ░░░░░░░░░░░░  5-7 工作日(去除正式环境部署)

跨 Wave  admin API PRD(P1-7)── 5 批分散到 Wave 1-5

总耗时估算:23-33 工作日(约 5-7 周,单人)

二、各 Wave 详细规划

Wave 0 — 调研基线([已完成])

目标:把"问题域"摸清,建立项目级标杆文档,所有反馈拍板,准备 Wave 1-5 实施。

核心交付:

• docs/_overview/ 标杆目录(00-index / 01-05 + 04a/b/c-feedback 子目录,30+ 文件)
• 21 页小程序业务指纹 + 19 路由 admin-web 业务指纹
• 39 条文档冲突清单 + 业务故事卡(P0×8 / P1×13 / P2×13 + 5 子项)
• Neo 反馈两轮 + 全部决策入 NEO-DECISIONS-LOG
• 8 处追加 D Bug 发现(P0-3/5/6/8 + P1-3 + P2-7 + 2 独立 Bug)
• P20 SPEC docs/prd/specs/P20-runtime-context-sandbox.md 起草 + §14 成果层走查 patch
• WAVE-1-KICKOFF.md

收尾标志:已达成。

---

Wave 1 — Runtime Context 沙箱 + 致命 D Bug 三连修

目标:沙箱端到端可用 + 修生产致命 Bug + 启动 P11 上线门槛之"看板沙箱接入"。

任务(8 项):

#	任务	工时	关键依赖
W1-T1	P0-3 看板沙箱接入(必修)	5-7h	P20 SPEC §5.3
W1-T2	P0-1 SCD2 视图入口 + base_dws_task 工资 Bug	0.5 天	F-1 调研
W1-T3	P0-5 致命 1 — 4 处 fdw_etl 残留	1-2h	F-2 D Bug
W1-T4	P0-5 致命 2 — JWT aud 缺失	2-3h	F-2 D Bug
W1-T5	P0-8 DBViewer 白名单 + 只读账号	1h	D Bug
W1-T6	P1-11 chat 多入口后端契约	1-2h	E-2 调研
W1-T7	P1-7 admin API PRD 批 1(Runtime Context + AI 管理)	1.5 天	跨 Wave
W1-T8	P0-7 §14 成果层走查 + 多角色身份提醒	1 天	P20 §14

总耗时:5-7 工作日

验收:

• 沙箱模式下三大看板显示虚拟日期数据(P0-3 修复)
• 致命 1+2 修复后 tenant-admin 用户审核 / Excel 上传 / 维客线索 恢复正常
• §14 走查产物 2026-XX-XX__sandbox_acceptance_wave1.md 归档
• 跨端 token 互不可用(JWT aud 校验生效)

详细见:WAVE-1-KICKOFF.md

---

Wave 2 — admin-web AI 套件 + Schema 迁移协同

目标:重大 schema 迁移(维客线索 public→biz)+ admin-web 触发器 API 合并 + 跨包共享枚举。

任务(7 项):

#	任务	工时	关键依赖
W2-T1	P1-1 维客线索 schema 迁移(public → biz)	9 人时 / 1.5 天	E-1 调研 / 后端 11 处硬编码 + 25+ 文档
W2-T2	顺带 2 个独立 Bug(page_context.created_at + ClueCategory 字典)	1-2h	E-1 副发现
W2-T3	P1-6 触发器 API 完全合并(扩展 /trigger-jobs PATCH + 业务守卫,保留 unified)	0.5-1 天	E-3 调研
W2-T4	P1-5 packages/shared 跨包枚举(ai_cache_types)	0.5 天	E-3 推荐
W2-T5	P0-5 Wave 协同 6 项: business_date 透传 / ETL 写连接 / consume_money 划线价 / note_service 调度 / 测试 DSN 加载 / camelCase 一致性	1.5-2 天	F-2 调研
W2-T6	P1-7 admin API PRD 批 2-3(ETL 任务管理 + 触发器)	1 天	跨 Wave
W2-T7	Wave 2 走查 + 审计归档	0.5 天	—

总耗时:4-6 工作日

验收:

• biz.member_retention_clue 表迁移完成,所有 SQL / FDW / RLS 视图引用同步
• admin-web 触发器面板用统一 API,字段集互补合并
• packages/shared/ai_cache_types.py + aiCacheTypes.ts 上线,前后端共享枚举
• P0-5 Wave 协同 6 项偏离修复

前置:Wave 1 完成 + Neo Review

---

Wave 3 — 业务功能补强 + P1 中等任务收尾

目标:补齐用户可见的业务功能 + 跨页传值规范化 + 测试覆盖补漏。

任务(6 项):

#	任务	工时	关键依赖
W3-T1	P1-3 task-detail 跳转传 customer_id(后端补字段 + 前端改参数)	1-2h	P1 D Bug
W3-T2	P1-8 应用 4 触发条件 3 种实施(新结算 + 优先召回 + 高优先召回任务分配)	0.5 天	P1 已确认
W3-T3	P0-6 阶段 1 临时守卫(admin-web 二次确认 + 输入门店简称)	1h	P0-6 记录
W3-T4	P1-3 SPEC 化"cross-page-params-spec.md"(53 跳转矩阵作起点)	0.5 天	E-2 调研
W3-T5	P1-7 admin API PRD 批 4(租户管理 / 用户审核)	1 天	跨 Wave
W3-T6	Wave 3 走查 + 审计归档	0.5 天	—

总耗时:3-5 工作日

验收:

• task-detail / performance 跳转传值正确
• 应用 4 触发频率提升 3x(任务分配也触发)
• admin-web 危险操作按钮加二次确认守卫
• cross-page-params-spec.md 入仓

前置:Wave 2 完成

---

Wave 4 — DWS / RLS / 数据正确性

目标:解决 4.1 财务看板 5 项 P2 修复 + 散客约定 + RLS 业务日上界视图 + ETL 幂等性。P11 上线门槛之"5 项 ETL 数据准确"。

任务(8 项):

#	任务	工时	关键依赖
W4-T1	4.1 财务看板 P2 修复 1:卡余额快照不变(ETL Task)	0.5-1 天	看板优化 PRD
W4-T2	4.1 P2 修复 2:首充/续费指标全 0	0.5 天	同上
W4-T3	4.1 P2 修复 3:优惠占比口径	0.5 天	同上
W4-T4	4.1 P2 修复 4:充值笔数缺口	0.5 天	同上
W4-T5	4.1 P2 修复 5:团购订单标签	0.5-1 天	同上
W4-T6	P1-12 散客 0 约定校验 + API 加 isScattered: bool 扁平字段	0.5-1 天	E-4 调研
W4-T7	P0-7 todos P1×8 项消化 + RLS 业务日上界视图重建对照 + ETL 幂等性测试	1-2 天	P0-7 todos
W4-T8	P1-7 admin API PRD 批 5(系统设置 / 日志)+ Wave 4 走查归档	1 天	跨 Wave

总耗时:5-7 工作日

验收:

• 5 项财务看板 P2 全部修复,小程序看板数据准确
• 散客 isScattered API 字段联调通过,前端不再 <=0 自判
• 39 个 RLS 业务日上界视图 pg_get_viewdef 重建无差异
• ETL 任务双跑同窗口幂等性 PASS
• P11 上线门槛之"5 项 ETL 数据准确" 达成

前置:Wave 3 完成

---

Wave 5 — 文档收尾 + 上线门槛验收(不含正式环境部署)

目标:全部 P2 主体落地 + 大批文档同步 + dev-trace 移除 + P0-6 阶段 2 + P11 上线门槛全部达标(不在本 Wave 推上线,正式环境部署由 Neo 后续手动决定)。

任务(13 项):

#	任务	工时
W5-T1	P2-9 no-permission 编辑入口实施(后端 + tenant-admin + 小程序 + 测试)	1.7 人天
W5-T2	P2-4 课程体系修正(选项 A:cfg_skill_type 改 ROOM + 174 条回填 + 启用现有死代码)	0.5-1 天
W5-T3	dev-trace Drop 移除(单 PR)	1-2h
W5-T4	P0-6 阶段 2 沙箱内/全局清空语义重设计	3-5h
W5-T5	P2-13.2 cfg_event_types 代码源 + 文档自动生成	0.5 天
W5-T6	P2-7 board-finance 隐式 null Bug 修复(Neo 反馈"找到的 Bug 修")	1-2h
W5-T7	文档批改 P0 系:P0-1 SPI 26→27 三处 + P0-2 BD 手册 + 3 链接 + P0-4 PRD 备注评分 + P0-5 文档说明 + P0-7 todos P2×7 项	1 天
W5-T8	文档批改 P1 系:P1-2 mvp 路径(3 处)+ P1-9 User_ID/userId 文档 + P1-10 移除冲突 + P1-13 文件名修正	0.5 天
W5-T9	文档批改 P2 系:P2-1/2/3/5/8/10/11/12 + P2-13.1/3/4/5	1 天
W5-T10	P0-5 长期治理 5 项(global_readonly RLS / DWS 双 schema 30+ 缺失 / 飞球 API 硬编码)	1-2 天
W5-T11	P0-5 可接受偏离 4 项文档化归档	0.5 天
W5-T12	P0-5 CI 自动化校验落地(pre-commit hook + 周报)	1 天
W5-T13	P11 上线门槛验收(看板沙箱 + 5 项 ETL + 致命 1+2)— 不含正式环境部署	0.5 天

总耗时:5-7 工作日

验收(P11 上线门槛达标,正式环境部署由 Neo 后续手动决定):

• ✅ 看板沙箱接入(Wave 1)
• ✅ 5 项 ETL 数据准确(Wave 4)
• ✅ 致命 1+2 修(Wave 1)
• ✅ 全部文档批改完成
• ✅ no-permission 编辑入口可用
• ✅ dev-trace 已移除
• ✅ CI 自动化校验上线
• ✅ Neo 最终 Review 通过 → 达标(本 Wave 至此终止,正式环境部署不在 Wave 5 范围内)

前置:Wave 4 完成

---

三、跨 Wave 任务:P1-7 admin API PRD(B+D 混合)

批次	模块	时机	工作量
批 1	OpenAPI 总表 + Runtime Context + AI 管理	Wave 1	1.5 天
批 2-3	ETL 任务管理 + 触发器	Wave 2	1 天
批 4	租户管理 / 用户审核	Wave 3	1 天
批 5	系统设置 / 日志	Wave 4	1 天
最终聚合	5 批合并成 NS-admin-web-backend-api.md	Wave 5	0.5 天

累计:8-10 工作日,分散到 5 Wave。

---

四、风险点与缓解

风险	触发条件	缓解
Wave 1 看板沙箱接入失败	xcx_board.py 改造影响其他业务接口	先 staging 验证,失败回滚 5 个 commit 即可
Wave 2 schema 迁移破坏 RLS	后端 11 处硬编码漏改	E-1 已列清单,严格按清单逐处改
Wave 4 ETL 数据修复影响生产数据	4.1 修复涉及历史数据回填	测试库先跑,生产灰度
Wave 5 上线门槛卡住	任一前置 Wave 未完成	严格按 Wave 1→2→3→4→5 顺序,不并行
工作量超估	P1-7 admin API PRD 实际工作量比估算大	主线告知,Neo 决定是否调整范围(灰区)
沙箱模式下生产事故	沙箱写入污染生产	P20 SPEC §11.1 设计共识 + 双 mode 字段隔离

---

五、Wave 之间的协议

5.1 启动条件

每个 Wave 启动前必须满足:

• 上一个 Wave 已 Neo Review 通过
• 上一个 Wave 审计记录归档到 docs/audit/changes/
• 当前 Wave kickoff 文档已写

5.2 收尾条件

每个 Wave 收尾必须产出:

• 所有 W*-T* 任务完成 + 各任务审计记录
• 走查产物归档(若涉及成果层走查)
• Wave 收尾 commit + push 到 dev 分支
• 更新 NEO-DECISIONS-LOG + 本文件状态栏

5.3 中断协议

任一 Wave 中途若发现:

• 重大新 Bug → 立即评定 P0/P1/P2 + 告知 Neo + 决定是否插队
• 工作量超估 50%+ → 主线告知,Neo 决定是否调整范围或延期
• 阻塞性依赖未解决 → 立即停止当前 Wave,先解决依赖

5.4 灰区协议(主线给建议 + Neo 1 句确认)

主线在以下情况给推荐 + Neo 1 句确认即可:

• 实施方案多选(选 A/B/C)
• 工作量大于预期
• 调研中新挖的 Bug 优先级评定

---

六、当前进度仪表板

Wave	状态	已完成	进行中	阻塞
Wave 0	✅ 完成	全部	—	—
Wave 1	🟡 已 kickoff	—	8 任务待启动	等 Neo 一句"开 Wave 1"
Wave 2	⚪ 待启动	—	—	Wave 1
Wave 3	⚪ 待启动	—	—	Wave 2
Wave 4	⚪ 待启动	—	—	Wave 3
Wave 5	⚪ 待启动	—	—	Wave 4

---

七、最终验收清单(Wave 5 末尾)

• 看板沙箱接入(Wave 1 W1-T1)
• 5 项 ETL 数据准确(Wave 4 W4-T1~T5)
• 致命 D Bug 修复(Wave 1 W1-T3/T4/T5 + 7 处独立 Bug)
• 39 条文档冲突全部处理
• P20 沙箱 SPEC §14 成果层走查 PASS
• cross-page-params-spec.md 入仓(Wave 3 W3-T4)
• admin-web API PRD 全套(NS-admin-web-backend-api.md,Wave 5 聚合)
• no-permission 编辑入口可用(Wave 5 W5-T1)
• dev-trace 已移除
• CI 自动化校验上线
• 课程体系修正(Wave 5 W5-T2)
• Neo 最终 Review 通过 → P11 上线门槛达标(本计划至此终止,正式环境部署由 Neo 后续手动决定)

---

总耗时:22-32 工作日(约 4.5-6.5 周,单人;不含正式环境部署) Wave 收尾后请刷新本文件 §六 进度仪表板。