# 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",主线立即按 §五 路径执行。