Neo
509cf43284
建立项目级标杆文档 docs/_overview/ 作为产品全景索引, 解决"PRD 零碎、文档膨胀、跨子系统调研无入口"的问题。 主要内容: - 00-index 总索引 + 维护协议 + 与 CLAUDE.md 关系 - 01-product-overview 产品全景脑图(6 角色 / 6 子系统 / 数据流 / 7 业务概念 / 8+1 AI 矩阵 / 22 术语) - 02a-miniprogram-page-matrix 小程序 21 页业务指纹 - 02b-adminweb-page-matrix admin-web 19 路由业务指纹 - 03-test-spec 测试规范 (L1-L5 分层 + 走查模板 + 75-95 case 估算) - 04-doc-conflicts 39 条冲突索引(P0×8 / P1×13 / P2×13 + 5 子项) - 04a/b/c-conflicts-*-detail 业务故事卡(7 字段:关联/逻辑/影响/选项/判定) - 05-orphan-pages-cleanup admin-web 6 孤儿页面处置(1 归档 + 4 保留) - WAVES-MASTER-PLAN.md 全 Wave 主计划(0-5,共 22-32 工作日) - WAVE-1-KICKOFF.md Wave 1 实施 kickoff - GLOBAL-DECISION-DASHBOARD.md 全局决策仪表板 反馈调研产物: - 04a-feedback/ P0 两轮反馈(8+8 项决策 + D-1/2/3 + F-1/2 子代理产出) - 04b-feedback/ P1 两轮反馈(13+1+5 项 + E-1/2/3/4 + G-1/2 子代理产出) - 04c-feedback/ P2 反馈(13 项 + 5 子项 + H-1/2/3 子代理产出) - NEO-DECISIONS-LOG 累积决策记录 关键追加发现 8 处 D Bug(原蓝本 0): - P0-3 看板沙箱接入(Wave 1 W1-T1) - P0-5 致命 1 (4 处 fdw_etl 残留, 已修 commit17f045a) - P0-5 致命 2 (JWT aud 缺失, 已修 commit17f045a) - P0-6 clearAllTasks 守卫 (Wave 3) - P0-8 DBViewer 黑名单漏 (已修 commit17f045a) - P1-3 task-detail 跳转传 task_id 而非 customer_id - P2-7 board-finance 隐式 null - 2 个独立 Bug (page_context.created_at + ClueCategory 字典) 参考: docs/_overview/00-index.md
286 lines
12 KiB
Markdown
286 lines
12 KiB
Markdown
# 全 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 收尾后请刷新本文件 §六 进度仪表板。
|