docs(rectification): timeline progress notes, walkthrough and blockers

No BUG entry: this is new capability and no existing defect surfaced. Records the block-scan concession and the width-transition guard that the first attempt tripped. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016P5RoqzmUQEbeC2qjAkeGr
2026-09-09 04:23:11 +00:00
parent ce91a0d23c
commit 724a1215fe
4 changed files with 143 additions and 0 deletions
@@ -0,0 +1,64 @@
+# PROGRESS · 生时校正常驻时间轴（2026-09-09）
+
+- 任务书：`docs/tasks/TASK-rectification-timeline-20260909.md`
+- 分支：`codex/rectification-timeline-20260909`，基线 `origin/staging` = `109b1d7f`
+- BUG 编号：**未开条目**。开工核对最大号为 601（任务书预期 602 仍可用）。本单是新增能力，实现中未发现既有缺陷，按任务书任务 7「不强开」。
+- 服务端与数据库：**未改一行**。
+
+## 任务 0 · 数据源确认
+
+| 用途 | 字段 | 结论 |
+| --- | --- | --- |
+| 轴的两端 | `candidate_range` | **可得**。服务端已在 `api/rectification/cases/[caseId]/route.ts:125` 下发；客户端类型 `RectificationCaseSnapshotPayload.case` 此前只声明 `status` / `accepted_time` / `confirmed_time`，本轮把 `candidate_range` 与 `stage` 补进该类型并加解析器。**这是读一个已经在网线上的字段，不是新增服务端字段。** |
+| 阶段 | `stage` | **可得**，同上 :126，取值 `"minute" \| "block_scan"` |
+| 区间带 | `credibleRange` | **可得**，`rectification-candidate-result.ts:95`，会话中途即有 |
+| 候选标记 | `candidates[].time` | **可得**，同上 :71 |
+
+**一处任务书未预料的事实：`stage === "block_scan"` 时 `latest_result` 恒为 `null`**（`route.ts:145` 显式短路），因此该阶段既没有 `credibleRange` 也没有候选分钟。处理见让步 1。
+
+## 让步
+
+**让步 1（任务书 §6 第 1 条）：时段阶段不画区块。** 区块边界在客户端只以显示字符串存在（`BLOCK_PERIOD_LABELS` 形如 `"清晨 04:00—07:59"`，`block-scan.ts:39-44`），没有结构化的 `start/end` 到达客户端；把展示文案反解析成几何太脆。
+
+按任务书让步条款，该阶段只画轴与区间带。结合上面 `latest_result === null` 的事实，具体呈现是：**区间带铺满整个窗口，读数写窗口宽度**（如 `00:00–23:59 · 23 小时 59 分`）。这不是占位——那一刻确实一分钟都还没排除，写满宽是事实。时段选定后窗口收窄、轴随之缩放，读数跟着变小，收敛感仍然成立。
+
+**未让步**：任务 4 的轴缩放动画照做（用 CSS transition）；任务 6 的移动端照做（56px）。不可让步的五条全部落地。
+
+## 一处与任务书写法不同（行为不变）
+
+任务书任务 1 写「按当前轴跨度换算百分比」，未规定用哪个 CSS 属性落位。初版用 `left` / `width` 加 transition，**撞上既有红线**：`tests/sidebar-contract.test.ts:314` 有一条全文件断言 `doesNotMatch(globalStyles, /transition:[^;}]*\b(?:width|grid-template-columns)\b/)`，对应 `DESIGN.md` 的 "Sidebar state changes are immediate"——`globals.css` 里禁止任何 width 过渡。
+
+改为**只用 `transform` 落位与过渡**：区间带是满宽元素，`transform-origin: left` 加 `translateX(起点%) scaleX(跨度)`，一个 transform 同时承载起点与宽度；候选点套一层满宽定位元素用 `translateX(百分比)`。副作用是区间带不能再用 `border-inline`（`scaleX` 会把边框一起压扁），改为纯色块——`--color-action-soft` 的填充边缘本身就是边界，且更符合本单「越简约越好」的口径。刻度仍用静态 `left`（不过渡：轴一缩放整套刻度就重建，滑动它没有意义）。
+
+这个改法比原写法更好：`transform` 走合成层，不像 `left`/`width` 每帧触发布局。既有断言未修改、未弱化。
+
+## 数字
+
+| 项 | 基线 `109b1d7f` | 改后 | 结论 |
+| --- | --- | --- | --- |
+| `npm test` 总数 | 2949 | **2966**（+17） | 不低于基线 ✅ |
+| pass | 2907 | **2924**（+17） | |
+| fail | 28 | **28** | 失败清单与基线 `diff` **逐条一致**（全部为无 Docker 的数据库/部署套件） |
+| skipped | 14 | 14 | |
+| `tsc --noEmit` | 退出码 0 / 0 行 | **退出码 0 / 0 行** | ✅ |
+| `npm run lint` | 0 error / 108 warning | **0 error / 108 warning** | ✅ 无一条新 warning |
+| `next build` | — | 退出码 0，`┌ ○ /` | `/` 仍 Static ✅ |
+| 首屏 CSS gzip | 38,916 B | **39,287 B（+0.95%）** | ±2% 内 ✅ |
+
+gzip 口径：`next build` 输出不含体积列，故量 `.next/static/chunks/*.css` 的 gzip 合计。基线数字是在同一 worktree 里把 `globals.css` 临时换回 `origin/staging` 版本重新构建所得，量完已还原（`git status` 干净）。新增 JS 不进首屏：`page.tsx` 不引用时间轴，校正面本来就是 `dynamic()` 分包。
+
+**`frontend/src/hooks/use-conversation-scroll-anchor.ts` 的 `git diff` 为空**（任务 2 验收标准）。
+
+## 中途修掉的一次自伤
+
+初版全量测试 fail 从 28 涨到 29，新增的是 `sidebar-contract.test.ts` 的 "selects desktop and tablet shell widths from provider data"。原因即上面那条 width 过渡。改用 transform 后失败数回到 28，并在本单测试里加了一条锁（band/mark 不得出现内联 `left`/`width`，条的样式块不得出现 width/left/height 过渡），防止后人改回去。
+
+## 环境缺口
+
+无登录态、无 Chrome、无 Docker，**浏览器级验收全部未做**，写成 `docs/testing/rectification-timeline-20260909.md`（6 节）交给有真实会话的人，未标记为通过。其中两条是任务书点名、本环境判断不了的：桌面端与右侧板「换升时刻」是否重复；移动端键盘弹出后是否仍同屏。
+
+第 2 节「贴底跟随」是本设计最大的技术风险点：代码上条高固定、合同测试也锁了，但「贴底时内容不会滑出视野」这件事只有真实滚动才能确认。
+
+## 交付
+
+- 未 push，本地提交，等验收。
@@ -0,0 +1,63 @@
+# 生时校正常驻时间轴：真实环境走查清单（2026-09-09）
+
+分支 `codex/rectification-timeline-20260909`，任务书 `docs/tasks/TASK-rectification-timeline-20260909.md`。
+
+执行环境无登录态、无 Chrome、无 Docker，以下条目**全部未做**，交给有真实会话的人。自动化替代证据见 `frontend/tests/rectification-timeline-20260909.test.ts`（17 项）：它锁得住 DOM、类名、CSS 声明与几何换算，**锁不住浏览器里的真实像素与滚动行为**。BUG-218/252 的教训正是这一条——纯源码合同测试能固定属性，固定不了几何位置。
+
+## 1. 两条任务书点名、本环境判断不了的
+
+### 1.1 桌面端时间轴与右侧板「换升时刻」是否显得重复
+
+桌面宽屏打开一个已进入分钟阶段的 Case，让时间轴与右侧板同屏。
+
+- [ ] 两者是否读起来像同一份信息重复了两遍？
+- [ ] 时间轴的刻度只标整点/整刻（不标每个候选分钟的数字），板上的「换升时刻」才逐分钟列出并带 LayerChips——这个粗细差别在真实屏幕上是否足以让人不觉得重复？
+- [ ] 若判断为重复，产品需在两条出路里选一条：时间轴取代板上「换升时刻」段，或时间轴只留区间带、把分钟点也去掉。**本轮未做取舍**（任务书决策记录第 7 条留下的问题）。
+
+### 1.2 移动端键盘弹出后是否仍同屏
+
+iOS Safari 与 Android Chrome 各走一次，在校正对话里点输入框唤起键盘。
+
+- [ ] 时间轴 + 输入框 + 至少一条完整消息气泡是否仍同屏可见？
+- [ ] 时间轴是否随视觉视口收缩按比例缩小，而不是被键盘顶出屏幕或盖住输入框？
+- [ ] 键盘收起后布局是否回到原样、没有残留空白？
+
+## 2. 贴底跟随（本设计最大的技术风险）
+
+时间轴在滚动容器之外，它的高度变化不会被 `useConversationScrollAnchor` 的 `ResizeObserver` 看到。代码上高度是固定的，但需要真实验证没有别的路径改变它。
+
+- [ ] 滚到底部后连续答 3 道题：新消息到达时是否始终自动贴底，没有内容停在视野下缘之外？
+- [ ] 手动向上滚一段，再答一题：是否正确解除贴底（不强行拉回），且「跳到最新」按钮出现？
+- [ ] 「跳到最新」按钮是否仍挂在输入框上沿，**没有被时间轴遮住**，点击后正常落底？
+- [ ] Case 从未载入切到已载入的那一瞬间，时间轴是否**没有**改变高度（不应看到对话区跳动，也不应看到「跳到最新」凭空弹出）？
+
+## 3. 轴缩放与两个阶段
+
+需要一个「完全不知道出生时间」的 Case 才能走到时段阶段。
+
+- [ ] 开场（整天或 ±120）时：条上是否**不出现**分钟圆点，区间带铺满整条轴，读数写整个窗口的宽度（如「23 小时 59 分」）？
+- [ ] 选定时段后：轴是否重新对到新窗口，读数变小？
+- [ ] 进入分钟阶段后：候选圆点是否出现？
+- [ ] 触发一次放宽（吻合率低且代表分钟贴边缘，BUG-572）：轴是否向外扩，区间带**没有**被裁掉或溢出轴外？
+- [ ] 系统开启「减弱动效」后，上述变化是否瞬间完成、没有过渡动画？
+
+## 4. 二元编码与只读
+
+- [ ] 答完一道区分题后，被排除的分钟是否**留在原地变成空心**而不是消失？
+- [ ] 所有圆点是否**一样大**？（不得有任何按可能性大小分级的迹象——BUG-560 状态是 blocked）
+- [ ] 鼠标悬停在条上任何位置：是否**没有**任何浮层、提示、文案变化？
+- [ ] 点击条上任何位置：是否**没有**任何反应？（采用只在交付卡上）
+- [ ] 条上是否只有两样东西：轴，和形如 `05:07–05:09 · 2 分钟` 的读数？不应出现计数、图例、阶段名、「已对照 N 件经历」或任何注脚。
+
+## 5. 跨午夜窗口
+
+需要一个声明为「夜里到凌晨」（23:00–03:59）的 Case。
+
+- [ ] 轴是否从 23:00 单调走到 03:59（刻度依次 23:00 / 00:00 / 01:00 / 02:00 / 03:00），而不是首尾颠倒或空白？
+- [ ] 区间带与圆点是否落在正确位置？
+
+## 6. 视觉
+
+- [ ] 浅色与深色主题下条的背景、发丝线、区间带、空心点是否都清晰可辨？
+- [ ] 开启「增强对比度」与「减少透明度」后是否仍可读？（本条用纯色背景、未用 `backdrop-filter`，预期不受影响）
+- [ ] 长时间会话滚动时，条是否稳定不抖动？