baa-conductor

BUG-036-projector-cursor-updated-at-unit-mismatch.md

 1# BUG-036: projector cursor updatedAt 秒级与 observedAt 毫秒级不一致
 2
 3> 提交者：Claude
 4> 日期：2026-03-30
 5
 6## 现象
 7
 8`projector.ts` 的 `saveCursor` 使用 `Math.floor(now / 1000)` 将毫秒转为秒级写入 `system_state.updated_at`：
 9
10```typescript
11await repository.putSystemState({
12  stateKey: cursorStateKey,
13  updatedAt: Math.floor(now / 1000),  // 秒级
14  valueJson: JSON.stringify({
15    message_id: cursor.id,
16    observed_at: cursor.observedAt     // 毫秒级
17  })
18});
19```
20
21而 `system_state` 表的 `updated_at` 列定义为 `INTEGER NOT NULL`，没有明确单位约定。如果后续有其他代码读 `system_state.updated_at` 并假设毫秒级，会出现约 1000 倍的时间偏差。
22
23## 当前影响
24
25cursor 本身的值存在 `valueJson` 里（`observed_at` 是毫秒级），cursor 恢复时读的是 `valueJson` 而不是 `updated_at`，因此当前功能不受影响。
26
27但 `updated_at` 的单位不一致是潜在的混淆源。
28
29## 建议修复
30
31统一 `system_state.updated_at` 为毫秒级（与其他所有 `*_at` 字段一致），或在 `system_state` schema 注释中明确标注单位。
32
33`ops/sql/schema.sql` 中现有的 `system_state` 初始化使用 `CAST(strftime('%s', 'now') AS INTEGER)` 即秒级。如果要统一为毫秒级，需要一起改。
34
35## 优先级
36
37低。当前不影响功能，但单位不一致是后续维护的隐患。