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
201 lines
7.4 KiB
Markdown
201 lines
7.4 KiB
Markdown
# Wave 1 实施 Kickoff — Runtime Context 沙箱 + 必修 D Bug
|
|
|
|
> 日期:2026-05-04 / 状态:**Neo 全部反馈已答 + 主线全部调研已完成,可启动 Wave 1**
|
|
>
|
|
> 上线门槛:看板沙箱接入(本 Wave) + 5 项 ETL 数据准确(Wave 4) + 致命 1+2 修(Wave 1-3) 全部满足才推 P11
|
|
|
|
## 一、Wave 1 目标
|
|
|
|
**主题**:Runtime Context 沙箱**真正端到端可用** + 启动 P11 上线门槛中的"看板沙箱接入"。
|
|
|
|
**判据**(对照 P20 SPEC §14 成果层走查):
|
|
- admin-web 12 路由 Playwright 走查全部 PASS(尤其 §14.2.10 RuntimeContext 完整切换流程)
|
|
- 小程序 10 页微信开发者工具走查 PASS(尤其 §14.3.6/7/8 看板 3 页必修)
|
|
- 跨页时间漂移 60s 缓存语义验证(AC12 实地化)
|
|
- 各端日志 0 error
|
|
|
|
## 二、Wave 1 任务清单(共 8 项)
|
|
|
|
### 任务 W1-T1: P0-3 看板沙箱接入(必修)
|
|
|
|
**优先级**:P0 / 主交付
|
|
**工作量**:5-7h
|
|
|
|
**范围**:
|
|
- 后端 `apps/backend/app/routers/xcx_board.py` 加 runtime_context 上下文
|
|
- 查询 `now()` 改为 `business_clock(site_id)`(用 P20 SPEC §5.1 的 helper)
|
|
- 小程序 `pages/board-finance/board-finance.ts` `pages/board-customer/board-customer.ts` `pages/board-coach/board-coach.ts` 三页:
|
|
- `onLoad / pullDownRefresh` 调 `getBusinessClock` 拿虚拟日期
|
|
- 传给后端 board API
|
|
- 8 条沙箱测试场景(P0-3 报告 §四)逐条验证
|
|
|
|
**验收**:P20 SPEC §14.3.6 / 14.3.7 / 14.3.8 走查 PASS
|
|
|
|
---
|
|
|
|
### 任务 W1-T2: P0-1 SCD2 视图入口改造
|
|
|
|
**优先级**:P0 / 沙箱根基
|
|
**工作量**:0.5 天 (4h)
|
|
|
|
**范围**(F-1 调研结论):
|
|
- ETL 任务改 3 处 SQL 直读 `dws.cfg_*` → `app.v_cfg_*` 视图
|
|
- 修复 NULL 兼容 bug(`v_cfg_index_parameters` 的 `effective_to IS NULL` 兼容)
|
|
- 顺手修 `base_dws_task.py:540-581` 工资任务 3 处 `_load_*` 函数不带 `effective_from` 的历史 Bug
|
|
|
|
**验收**:沙箱回放 2026-03-01 时 SPI 参数用当时生效版
|
|
|
|
**配套文档**:P20 SPEC §1.4 / §3.5 / §5.6 / AC14-15 / §11.2 / T16-T17 patch 落地
|
|
|
|
---
|
|
|
|
### 任务 W1-T3: P0-5 致命 1 — 4 处 fdw_etl 残留修复
|
|
|
|
**优先级**:P0 / **D Bug 影响生产**
|
|
**工作量**:1-2h
|
|
|
|
**范围**(F-2 调研发现):
|
|
- `apps/backend/app/routers/tenant_users.py:425, 450` — `FROM fdw_etl.*` → 直查 ETL 库 schema
|
|
- `apps/backend/app/routers/tenant_excel.py:390, 407` — 同上
|
|
- `apps/backend/app/routers/tenant_clues.py:113-119` — 同上
|
|
|
|
每处把 `fdw_etl.` 改为对应 schema(`dwd.` 或 `app.`),**不补 FDW**(P0-5 主体已结论 FDW 不能用 GUC)。
|
|
|
|
**验收**:tenant-admin 用户审核 / Excel 上传 / 维客线索 3 个功能从"接口永远返回空列表"恢复正常
|
|
|
|
---
|
|
|
|
### 任务 W1-T4: P0-5 致命 2 — JWT aud 缺失修复
|
|
|
|
**优先级**:P0 / **D Bug 跨端越权**
|
|
**工作量**:2-3h
|
|
|
|
**范围**:
|
|
- `apps/backend/app/auth/jwt.py` `generate_access_token` 加 `audience=` 参数
|
|
- `decode_access_token` 校验 aud
|
|
- 跨端 token 兼容性测试:admin / miniapp / tenant-admin 三套 token 互相不能用
|
|
- 旧 token 过期前的灰度兼容(可选:校验失败 fallback "no aud" 接受 1 周)
|
|
|
|
**验收**:用 admin token 调 /api/xcx/* 应 403,反之亦然
|
|
|
|
---
|
|
|
|
### 任务 W1-T5: P0-8 DBViewer 白名单 + 只读账号
|
|
|
|
**优先级**:P0 / D Bug
|
|
**工作量**:1h
|
|
|
|
**范围**:
|
|
- `apps/backend/app/routers/db_viewer.py` 改黑名单为白名单
|
|
- 必须以 `SELECT / WITH ... SELECT / EXPLAIN / SHOW` 开头
|
|
- 校验 `get_etl_readonly_connection` 用的账号确实只读(`pg_user.usesuper=false`)
|
|
|
|
**验收**:执行 `ALTER TABLE` / `CREATE TABLE` / `GRANT` 应被前端校验拒绝(若漏后端兜底)
|
|
|
|
---
|
|
|
|
### 任务 W1-T6: P1-11 chat 多入口后端契约
|
|
|
|
**优先级**:P1
|
|
**工作量**:1-2h
|
|
|
|
**范围**(E-2 发现):前端已 6 分支处理,只缺后端契约
|
|
- 后端补 `GET /api/xcx/chat/by-context?customerId|coachId|historyId` 派生 chatId
|
|
- 或前端调 `loadMessages` 时传完整入口语义,后端按入口分支查
|
|
|
|
**验收**:chat 页从 task-detail / chat-history / coach-detail 三入口都能正确加载历史
|
|
|
|
---
|
|
|
|
### 任务 W1-T7: P1-7 admin API PRD 批 1
|
|
|
|
**优先级**:P1 / 跨 Wave 第一批
|
|
**工作量**:1.5 工作日(B+D 混合)
|
|
|
|
**范围**(P1-7 评估):
|
|
- 用 OpenAPI 自动生成 80 个 API 总表 → `docs/_overview/admin-web-api-overview.md`(0.5 天)
|
|
- 细化 Wave 1 涉及的 5-8 个 API(Runtime Context + AI 管理):每个 API 加业务语义 / 权限 / 调用方 / 问题点
|
|
- 发现的设计 / 性能 / 安全问题立即立工单(预估 5-15 个)
|
|
|
|
**验收**:`admin-web-api-overview.md` 落地 + Runtime Context + AI 管理批 PRD 完成
|
|
|
|
---
|
|
|
|
### 任务 W1-T8: P0-7 §14 成果层走查执行
|
|
|
|
**优先级**:P0 / 验收
|
|
**工作量**:1 天
|
|
|
|
**范围**(已落入 P20 SPEC §14):
|
|
- admin-web Playwright 走查 12 路由(§14.2)
|
|
- 小程序微信开发者工具走查 10 页(§14.3)
|
|
- 跨页时间漂移走查(§14.4)
|
|
- 走查产物归档到 `docs/audit/changes/2026-XX-XX__sandbox_acceptance_wave1.md`
|
|
|
|
**多角色身份提醒**:14.3.6/7/8 看板 3 页 PASS 后,**主线主动提醒 Neo 切身份**走 §14.5 矩阵。
|
|
|
|
**验收**:全部走查 PASS + 截图归档
|
|
|
|
---
|
|
|
|
## 三、Wave 1 不做的事(挪到后续)
|
|
|
|
| 项 | 时点 |
|
|
|---|---|
|
|
| P0-6 阶段 2 沙箱内/全局清空语义重设计 | P0-7 收口后(Wave 1-3 后) |
|
|
| P1-13 P4 前置修复 | **关闭**(以现状为准,Neo 决定) |
|
|
| P1-1 schema 迁移 | Wave 2 |
|
|
| P1-5 跨包枚举 / P1-6 触发器合并 | Wave 2 |
|
|
| P1-12 散客 isScattered | Wave 4 |
|
|
| P2-4 课程体系 ROOM 启用 / 174 条回填 | **Wave 5**(选项 A 最小改动) |
|
|
| P2-7 board-finance 隐式 null 修(原行为可接受) | **改为 Wave 5**(Neo 反馈) |
|
|
| P0-1 / P0-2 / P0-4 / P0-5 / P0-7 文档批改 | Wave 5 |
|
|
| dev-trace Drop | Wave 5 |
|
|
| tasks.md 真实性审计 | **关闭**(Neo 决定) |
|
|
| CI hook 防再撒谎 | **关闭** |
|
|
|
|
## 四、Wave 1 启动前置检查
|
|
|
|
- [x] Wave 0 主交付(产品全景 / 21 页 / 19 路由 / 测试规范 / 39 冲突清单 / 6 孤儿)完成
|
|
- [x] P0 两轮反馈调研完成(8 + 8 项 决策)
|
|
- [x] P1 两轮反馈调研完成(13 + 1 + 5 项 决策)
|
|
- [x] P2 反馈调研完成(13 项 + 5 子项 + H-3 课程体系修正)
|
|
- [x] Neo 全部决策入档 NEO-DECISIONS-LOG.md
|
|
- [x] P20 SPEC §14 成果层走查 patch 落地
|
|
- [x] 当前工作区无高风险未审计变更(SessionStart hook 检查)
|
|
|
|
## 五、Wave 1 启动后路径
|
|
|
|
1. **Day 1**(立即):W1-T3 + W1-T4 + W1-T5(3 个 D Bug 修代码,合计 4-6h,1 个 PR)
|
|
2. **Day 2**:W1-T1 P0-3 看板沙箱接入(后端 + 小程序三页 + 8 场景验证,5-7h)
|
|
3. **Day 3**:W1-T2 SCD2 视图入口改造(0.5 天)+ W1-T6 chat 后端契约(1-2h)
|
|
4. **Day 4**:W1-T7 admin API PRD 批 1(1.5 天起步)
|
|
5. **Day 5**:W1-T8 §14 走查 + 多角色提醒 + 归档
|
|
|
|
总耗时:**约 5-7 工作日**,跨多个 PR 提交。
|
|
|
|
## 六、Wave 1 收尾标志
|
|
|
|
- 8 个 W1-T* 任务全部完成 + 审计记录归档
|
|
- P20 SPEC §14 走查产物 `2026-XX-XX__sandbox_acceptance_wave1.md` 落地
|
|
- 沙箱模式下三大看板显示虚拟日期数据(P0-3 主体修复)
|
|
- 4 处 fdw_etl 残留 + JWT aud + DBViewer 白名单 全部修复
|
|
- Wave 1 收尾 commit + push 到 dev 分支
|
|
- Neo Review 通过 → 启动 Wave 2
|
|
|
|
---
|
|
|
|
## 七、Wave 2 预告(P1-1 schema 迁移协同)
|
|
|
|
Wave 1 收尾后立即启动:
|
|
- P1-1 维客线索 public → biz 迁移(9 人时,与 Wave 2 后端 PR 合并)
|
|
- P1-6 触发器 API 合并
|
|
- P1-5 packages/shared 跨包枚举
|
|
- P0-5 Wave 协同 6 项
|
|
|
|
详见 [GLOBAL-DECISION-DASHBOARD.md](GLOBAL-DECISION-DASHBOARD.md) §1.2。
|
|
|
|
---
|
|
|
|
> 等 Neo 一句"开 Wave 1",主线立即按 §五 路径执行。
|