Neo-ZQYY/docs/_overview/WAVE-1-KICKOFF.md

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 启动前置检查

• Wave 0 主交付(产品全景 / 21 页 / 19 路由 / 测试规范 / 39 冲突清单 / 6 孤儿)完成
• P0 两轮反馈调研完成(8 + 8 项 决策)
• P1 两轮反馈调研完成(13 + 1 + 5 项 决策)
• P2 反馈调研完成(13 项 + 5 子项 + H-3 课程体系修正)
• Neo 全部决策入档 NEO-DECISIONS-LOG.md
• P20 SPEC §14 成果层走查 patch 落地
• 当前工作区无高风险未审计变更(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 §1.2。

---

等 Neo 一句"开 Wave 1",主线立即按 §五 路径执行。