# P0-3 财务看板与沙箱衔接 — 初步分析

> 日期:2026-05-04 / 触发:Neo 在 04a-conflicts 反馈
> Neo 原话:"另外,此项内容包括财务看板页的所有数据是否受到之后开发上线的时间沙盒模块的影响?逻辑是否调通有待进一步调研走查。"

## 一、初步结论(基于静态 grep 证据)

**重大风险:小程序三大看板(board-finance / board-customer / board-coach)在沙箱模式下不会切换到虚拟时间数据。**

证据:
- 小程序 `pages/board-finance/` `pages/board-customer/` `pages/board-coach/` — **零处引用** `runtime-clock` / `runtimeClock` / `getBusinessClock` / `business_year` / `business_month`
- 后端 `apps/backend/app/routers/xcx_board.py` — **零处引用** `runtime_context` / `runtime-clock`
- D-3 子代理报告同样发现:"**小程序 board 三大看板未确认 runtime-clock 接入,风险高**"

**意味着**:
1. 运维在 admin-web 切换 sandbox 模式 → 设置虚拟日期(如 2026-03-01)
2. 小程序 task-list / customer-records 等其他页面**会**显示虚拟日期数据(它们读 runtime-clock)
3. 但小程序看板三页**仍然显示真实今天的数据**
4. 用户混淆:"为什么任务列表是 3 月 1 号但看板显示 5 月数据?"

## 二、P0-3 与 P0-7(Runtime Context 收口)的关系

P0-3 是 P0-7 "Runtime Context 远未收口" 的**最具体证据之一**。D-3 子代理产出的 P20 SPEC 草稿 + todos 清单已经把这条列为 P0 级待办之一。

P0-3 不是独立问题,**它本质是 P0-7 跨模块覆盖率不足的子症状**。

## 三、与 P0-3 原始上下文(财务看板 5 项 P2 修复)的关系

Neo 在 04a 中标"偏向选项 A(数据准确再上线)",同时反问"沙箱影响是否调通"。两个问题需要**分开看待**:

| 子问题 | 当前状态 | 推荐处理 |
|---|---|---|
| 5 项 P2 修复(卡余额 / 首充续费 / 优惠占比 / 充值笔数 / 团购标签) | 4.1 PRD 已记录但未实施 | **Wave 4 实施**(对应 ETL Task 修复)|
| 看板与沙箱衔接 | **未实现**(本文核心发现) | **Wave 1 必修**(D Bug,影响沙箱主线收口)|

**两者都是 P0,但触发的 Wave 不同**:沙箱衔接更紧急(Wave 1 必修),5 项数据准确性可以放到 Wave 4 ETL 验证时一并修。

## 四、Wave 1 必测的看板沙箱场景(8 条)

基于本次发现,Wave 1 走查时必须覆盖:

1. admin-web 切 sandbox(虚拟日期 = 2026-03-01) → 小程序 board-finance 营收数字应为 2026-03-01 当日数据
2. admin-web 切 sandbox → board-finance 折线图横轴应是虚拟"近 7 日"(2026-02-23 ~ 03-01)而非真实近 7 日
3. admin-web 切 sandbox → board-finance AI 洞察应基于虚拟日期数据
4. admin-web 切 sandbox → board-customer 客户分类(SPI / 充值频次)应反映虚拟日期截止状态
5. admin-web 切 sandbox → board-coach 助教绩效应反映虚拟日期当月累计
6. 切回 live → 三大看板应立即恢复真实数据
7. 跨门店切换:site_A sandbox + site_B live → site_A 的看板用虚拟,site_B 的看板用真实
8. 验证 AI 洞察 cache_type:虚拟日期下应使用独立 cache_key 避免污染 live cache

## 五、P0-3 推荐处理方案(给 Neo 拍板)

### 选项 A — Wave 1 修(推荐)

**做法**:把"看板接入 runtime-clock + xcx_board.py 接入 runtime_context"作为 Wave 1 必交付项,Wave 1 走查同步验证 8 条场景。

**工作量**:
- 后端:`xcx_board.py` 加 runtime_context 上下文 + 查询时用虚拟时间替代 `now()` — 中(2-4h)
- 小程序:三大看板页 `onLoad` / `pullDownRefresh` 调 `getBusinessClock` 拿虚拟日期 → 传给后端 — 小(1h)
- 测试:8 条场景 case + Wave 1 走查 — 中(2h)
- **合计:5-7h**

**优点**:沙箱真正能演示"看板回放"场景;P0-7 收口前进一大步
**缺点**:Wave 1 工作量多 1 个主题

### 选项 B — Wave 1 仅验证不修复

**做法**:Wave 1 走查时记录"看板不接沙箱"的现状,标 P0 待修但不在 Wave 1 修;Wave 5 末再修。

**优点**:Wave 1 节奏稳定
**缺点**:沙箱演示价值打折扣;两次走查同一组件(Wave 1 测一次发现 bug,Wave 5 修后再测一次)

### 选项 C — 先评估能否给 sandbox 加"看板降级文案"

**做法**:在沙箱模式下,看板页顶部加 banner 提示"沙箱模式中,看板仍为真实数据(限制说明)",让用户预期管理。后续再补真实接入。

**优点**:零代码改动,文档级解决
**缺点**:不解决根本问题;给沙箱使用者埋认知坑

## 六、与 5 项 P2 修复的合并建议

Neo 反馈"满足数据准确才上线"指 5 项 P2 修复。这两个问题最佳路径:

```
Wave 1 — 修看板沙箱接入(P0-3 看板侧) + 验证沙箱整体收口(P0-7)
Wave 4 — 修 5 项 ETL 数据准确(原 P0-3 主体)
Wave 5 — 验证 P11 上线门槛(数据准确 + 沙箱收口都达标)
```

不在同一 Wave 但在同一收口路径上。

## 七、给 Neo 的决策提问

1. P0-3 选 A(Wave 1 修)还是 B(Wave 1 仅验证)?**推荐 A**
2. 5 项 P2 修复是否纳入 Wave 4?
3. P11 上线门槛是否要求"看板沙箱接入 + 5 项数据准确"双满足?

---

> 本分析基于 grep 静态证据,真正"逻辑是否调通"需要 Wave 1 实测验证。
