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

> 日期:2026-05-04 / 用途:NeoZQYY 项目从调研基线到上线的完整 Wave 规划
> 基础:Wave 0 调研产出 + 39 条文档冲突 + Neo 全部反馈决策 + 8 处追加 D Bug 发现
>
> 维护协议:每个 Wave 收尾后更新本文件 + 各 Wave kickoff 文档

## 一、Wave 全景图

```text
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-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 收尾后请刷新本文件 §六 进度仪表板。