feat(miniprogram): board-finance isCurrentMonthFilter 接入业务时钟 (W1-T1 / P0-3)
Wave 1 Day 2 看板沙箱接入。 调研修正: - xcx_board.py + board_service.py 服务层已接入 runtime_context (L264/L712) - board-customer.ts / board-coach.ts 0 处使用 new Date(),无需改 - 唯一遗漏: board-finance.ts isCurrentMonthFilter 用 new Date().getDate() 沙箱回放历史日期会判错"本月前 5 天预估"提示 修复: - import getBusinessClock from utils/runtime-clock - isCurrentMonthFilter 接收可选 businessDate 参数;空值降级 new Date() - data 加 businessDate: '' - onShow 拉业务时钟 + 修正 isCurrentMonth - onTimeChange 用 this.data.businessDate 参考: docs/audit/changes/2026-05-04__wave1_t1_board_sandbox_clock.md
This commit is contained in:
150
docs/audit/changes/2026-05-04__wave1_t1_board_sandbox_clock.md
Normal file
150
docs/audit/changes/2026-05-04__wave1_t1_board_sandbox_clock.md
Normal file
@@ -0,0 +1,150 @@
|
||||
# Wave 1 W1-T1 — 看板沙箱接入(P0-3)
|
||||
|
||||
| 字段 | 值 |
|
||||
|---|---|
|
||||
| 日期 | 2026-05-04 |
|
||||
| Wave | 1 / Day 2 |
|
||||
| 范围 | P0-3 看板沙箱接入(实际改动量 < 原估算 5-7h,因调研发现后端已接入) |
|
||||
| 文件改动 | 1 个小程序文件(board-finance.ts) |
|
||||
| 编译验证 | tsc 对 board-finance.ts 零错误 ✅ |
|
||||
|
||||
## 一、调研修正前期 P0-3 报告
|
||||
|
||||
**P0-3 原结论(Wave 0)**:
|
||||
> Grep 实证:小程序三大看板 + xcx_board.py **零处引用** runtime-clock / runtime_context
|
||||
|
||||
**Day 2 实地走查发现**:
|
||||
- ✅ **xcx_board.py 是 router 层薄封装**,不直接引用 runtime_context 是正常设计
|
||||
- ✅ **board_service.py(服务层)已接入 runtime_context**:
|
||||
- L264 `runtime_ctx = get_runtime_context(site_id)` + `_calc_date_range(time, ref_date=runtime_ctx.business_date)`
|
||||
- L482-490 60 天消费窗口已用 `as_runtime_today_param`
|
||||
- L712 同样接入业务日
|
||||
- ✅ **board-customer.ts / board-coach.ts 0 处使用 `new Date()`**,完全没问题
|
||||
- ❌ **board-finance.ts 唯一遗漏**:`isCurrentMonthFilter` 函数用 `new Date().getDate() <= 5` 判断"本月前 5 天",沙箱模式回放历史日期时会判错
|
||||
|
||||
**P20 SPEC §13 已知冲突表的标记是准确的**:`board-finance.ts isCurrentMonthFilter` 设计文档要求改但未在 grep 结果中确认 → 现已确认未改,本轮修复。
|
||||
|
||||
## 二、修复内容
|
||||
|
||||
文件:[apps/miniprogram/miniprogram/pages/board-finance/board-finance.ts](../../../apps/miniprogram/miniprogram/pages/board-finance/board-finance.ts)
|
||||
|
||||
### 改动 1:import + isCurrentMonthFilter 改造
|
||||
|
||||
```typescript
|
||||
import { getBusinessClock } from '../../utils/runtime-clock'
|
||||
|
||||
function isCurrentMonthFilter(selectedTime: string, businessDate?: string): boolean {
|
||||
if (selectedTime !== 'month') return false
|
||||
if (businessDate) {
|
||||
const day = parseInt(businessDate.slice(8, 10), 10)
|
||||
return !Number.isNaN(day) && day <= 5
|
||||
}
|
||||
return new Date().getDate() <= 5 // 降级:业务时钟未就绪时用本地
|
||||
}
|
||||
```
|
||||
|
||||
### 改动 2:data 加 businessDate
|
||||
|
||||
```typescript
|
||||
data: {
|
||||
...
|
||||
isCurrentMonth: true,
|
||||
businessDate: '', // YYYY-MM-DD,沙箱模式下回放虚拟日期
|
||||
}
|
||||
```
|
||||
|
||||
### 改动 3:onShow 拉业务时钟 + 修正 isCurrentMonth
|
||||
|
||||
```typescript
|
||||
onShow() {
|
||||
checkPageAccess(...).then((allowed) => {
|
||||
if (!allowed) return
|
||||
...
|
||||
// Wave 1 W1-T1:刷新业务时钟,沙箱模式下回放虚拟日期
|
||||
getBusinessClock().then((clock) => {
|
||||
const businessDate = clock.business_date || ''
|
||||
this.setData({
|
||||
businessDate,
|
||||
isCurrentMonth: isCurrentMonthFilter(this.data.selectedTime, businessDate),
|
||||
})
|
||||
}).catch(() => {
|
||||
// 降级:保留默认 isCurrentMonth(本地时钟)
|
||||
})
|
||||
this._loadData()
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### 改动 4:onTimeChange 用 businessDate
|
||||
|
||||
```typescript
|
||||
onTimeChange(...) {
|
||||
this.setData({
|
||||
selectedTime: value,
|
||||
selectedTimeText: option?.text || '本月',
|
||||
isCurrentMonth: isCurrentMonthFilter(value, this.data.businessDate), // 加 businessDate
|
||||
})
|
||||
this._loadData()
|
||||
}
|
||||
```
|
||||
|
||||
## 三、未改动项(已是设计共识)
|
||||
|
||||
- `board-finance.ts L243 `Date.now()`** — onPageScroll 节流计时,纯 UI 行为(100ms 节流),与业务时间无关,**保留**(对齐 P20 SPEC §11.1 "操作时间戳保留 new Date()" 设计共识)
|
||||
- `board-customer.ts` — 0 处 `new Date()`,**无需改**
|
||||
- `board-coach.ts` — 0 处 `new Date()`,**无需改**
|
||||
- 后端 `xcx_board.py` + `board_service.py` — 服务层已接入 runtime_context,**无需改**
|
||||
|
||||
## 四、行为对照(沙箱模式下)
|
||||
|
||||
| 场景 | 修改前 | 修改后 |
|
||||
|---|---|---|
|
||||
| live 模式,真实今天 = 2026-05-04(月初 4 日) | `isCurrentMonth = true`(预估提示)| 同 |
|
||||
| live 模式,真实今天 = 2026-05-15(月中) | `isCurrentMonth = false`(无预估) | 同 |
|
||||
| sandbox 切换到 2026-03-01 | `isCurrentMonth = false`(因为真实今天 = 2026-05-04 第 4 日)❌ | `isCurrentMonth = true`(基于 sandbox_date day=1 ≤ 5)✅ |
|
||||
| sandbox 切换到 2026-03-15 | `isCurrentMonth = false`(同上 4 日)❌ | `isCurrentMonth = false`(基于 sandbox_date day=15 > 5)✅ |
|
||||
| 业务时钟拉取失败 | 用 `new Date()`(降级一致)| 用 `new Date()`(降级一致)|
|
||||
|
||||
## 五、验证
|
||||
|
||||
### 工程层
|
||||
|
||||
- ✅ tsc `board-finance.ts` 零编译错误(其他遗留 component / app 类型错误与本次改动无关)
|
||||
- ✅ getBusinessClock 已存在 `runtime-clock.ts`,接口稳定
|
||||
- ✅ 降级路径(getBusinessClock 失败)保留 fallback `new Date()`,不会破坏 live 行为
|
||||
|
||||
### 成果层(留 W1-T8)
|
||||
|
||||
按 P20 SPEC §14.3.6 走查清单,W1-T8 时:
|
||||
- 切 sandbox → 2026-03-01 → 进 board-finance → 经营一览 标题应显示"(预估)"
|
||||
- 切 sandbox → 2026-03-15 → 进 board-finance → 经营一览 标题不应显示"(预估)"
|
||||
- 切回 live → 行为应恢复
|
||||
|
||||
## 六、commit 建议消息
|
||||
|
||||
```
|
||||
feat(miniprogram): board-finance isCurrentMonthFilter 接入业务时钟 (W1-T1 / P0-3)
|
||||
|
||||
Wave 1 Day 2 看板沙箱接入。
|
||||
|
||||
调研修正:
|
||||
- xcx_board.py + board_service.py 服务层已接入 runtime_context (L264/L712)
|
||||
- board-customer.ts / board-coach.ts 0 处使用 new Date(),无需改
|
||||
- 唯一遗漏:board-finance.ts `isCurrentMonthFilter` 用 new Date().getDate()
|
||||
沙箱回放历史日期会判错"本月前 5 天预估"提示
|
||||
|
||||
修复:
|
||||
- import getBusinessClock from utils/runtime-clock
|
||||
- isCurrentMonthFilter 接收可选 businessDate 参数;空值降级 new Date()
|
||||
- data 加 businessDate: ''
|
||||
- onShow 拉业务时钟 + 修正 isCurrentMonth
|
||||
- onTimeChange 用 this.data.businessDate
|
||||
|
||||
参考: docs/audit/changes/2026-05-04__wave1_t1_board_sandbox_clock.md
|
||||
```
|
||||
|
||||
## 七、未覆盖 / 后续
|
||||
|
||||
- W1-T8 §14.3.6/7/8 走查时实地验证沙箱模式下三大看板行为
|
||||
- 多角色身份走查(W1-T8 触发,主线提醒 Neo 切身份)
|
||||
- 单测覆盖留 Wave 2(`tests/board-finance/test_isCurrentMonthFilter.ts`)
|
||||
Reference in New Issue
Block a user