Files

T

jesse-uxandClaude Code 10baeb2fa8 docs: split meeting product work into task books

Co-Authored-By: Claude Code <noreply@anthropic.com>

2026-09-22 11:19:35 +08:00

5.4 KiB

Raw Blame History

任务书 · 首页加载失败可恢复性与 BUG-936 收口（2026-09-22）

0. 基线与已有任务关系

基线 commit：1bc6a954c597e2817fe72bfedad93119ab19a527；执行方开工前 fetch 并重核最新 origin/staging。
执行分支：codex/home-bootstrap-reliability-20260922；工作树：.worktrees/home-bootstrap-reliability-20260922。
既有 docs/tasks/TASK-first-paint-dead-screen-fallback-20260917.md 已定义 BUG-936 的首屏内联 fallback 方案。本单不是另起炉灶：若该任务尚未合入，执行方应直接按其未完成项执行并以本单产品验收为准；若已合入，禁止重复添加第二套 fallback。
本单与 /chart 数据真值任务独立；不要用首页 bootstrap 改动掩盖星盘 API 问题。
本单与人物选择器都涉及首页装配时，优先完成并合入本单的 bundle 无关 fallback，再开始 TASK-chat-subject-picker-20260922.md 的首页接线；执行方不得同时修改 page.tsx 或同一 loading/reveal 符号。

1. 事故实证

BUG-936（docs/BUG_HISTORY.md）记录：iPhone Safari 可能永久停在“正在载入账户 / 同步个人资料与对话记录”。已确认 /api/account、/api/sessions、/api/models 等接口返回 200；预渲染 HTML 本身包含加载屏；4 秒揭幕、8 秒 bootstrap timeout 和 401 处理全部在可能未执行的客户端 bundle 中。只要 chunk 未加载、解析失败、旧缓存损坏或 hydrate 失败，CSS 转圈会无限继续。

现有任务书已确认：根 layout 需要与 bundle 无关的内联经典脚本；不能自动刷新；本仓自有后行断言需移除，但不能声称因此解决所有 Safari 版本兼容问题。

2. 根因与边界

本单负责的是“首屏失败时用户没有恢复出口和诊断”的确定性缺陷；具体设备 iOS 版本、chunk、缓存或内容拦截器根因仍需 staging/真人分流，不得提前编造。正常接口速度不是本单的优化目标。

3. 决策记录

首屏必须在 JS 未执行、关键 chunk 失败或 hydrate 超时时给出可读失败状态和“重新加载”动作。
兜底必须与主 bundle 无关：内联、经典 <script>、ES5、无外部依赖、无 React、不得自动循环刷新。
正常加载不能闪现 fallback；成功揭幕后不恢复阻塞 spinner。
支持的浏览器基线与低版本 Safari 的行为需在 docs/testing 记录，不通过继续降低 Next 构建目标解决。
不升级 Next/React/依赖，不重写首页 bootstrap，不改后端账户/会话 API。

4. 硬红线

不新增第二套 loading animation；不改变“一个等待、一次揭幕”的现有语义。
不能把失败详情、出生资料、聊天内容、token、secret 或完整请求体写入观测日志。
不自动刷新，不制造刷新循环；重试只能由用户明确点击。
/ 必须保持 ○ Static，首屏 gzip 变化在 ±2%；不增加 Home() 状态/引用。
既有测试名不减少；断言变化写原值/新值/原因。

5. 任务分解与验收标准

T1 · 复核并补齐 bundle 无关 fallback

复核既有 TASK-first-paint-dead-screen-fallback-20260917.md 的 layout inline script、hydrated 标记、超时和可读文案。
触发条件必须同时满足“仍是 .app-loading”与“尚未 hydrated”；正常 hydrate 不替换内容。
fallback 提供重新加载按钮和低版本/清除站点数据的分流提示，文案遵循 VOICE；不暴露内部异常原文。

验收：JS 完全不执行或关键 chunk 失败时，fallback 能独立显示；按钮可用；正常现代浏览器不闪现；不依赖 module/React/外部脚本。

T2 · 运行时错误分流与观测

覆盖 hydrate 超时、chunk 404/解析失败、旧缓存、弱网、接口错误五类场景；不把它们都伪装成接口慢。
如增加匿名观测，只记录类别、构建标识（非用户资料）和耗时；不得记录敏感 payload。
说明 BUG-936 仍需用户侧 iOS/缓存信息才能完成根因确认；兜底补上不等于所有 Safari 用户都已修复。

验收：每类场景有源码合同或测试；至少一份 docs/testing/home-bootstrap-reliability-20260922.md 真人/模拟清单；低版本 Safari 和 chunk 失败的环境缺口如实列出。

T3 · 既有语法下限清理与回归

若尚未完成既有任务中的 sentence split 清理：统一工具替代本仓后行断言，逐例锁定行为；不得扩大到无关依赖。验收 git grep -n '(?<=' frontend/src 无结果（若已有任务已完成，只保留验证，不重复改）。

6. 让步顺序

T1 > T2 > T3。T1 必须可独立交付；T2 没有真实 iPhone/Chrome 时只能写环境缺口；不得以 build 成功代替浏览器验收。

7. 开工前置命令

git status -sb
git fetch origin --prune
git worktree add -b codex/home-bootstrap-reliability-20260922 .worktrees/home-bootstrap-reliability-20260922 origin/staging
cd .worktrees/home-bootstrap-reliability-20260922/frontend
./node_modules/.bin/tsc --noEmit
npm run lint
npm test
npm run build

8. 记录

更新 docs/BUG_HISTORY.md BUG-936（只能从 investigating 改为“兜底已补、根因待分流”，有真实证据后再 resolved），写 docs/tasks/PROGRESS-home-bootstrap-reliability-20260922.md 和 docs/testing/ 清单；必要时更新 CHANGELOG.md、frontend/DESIGN.md、frontend/docs/VOICE.md。不得声称 staging 已部署，除非 health SHA 已核对。

5.4 KiB Raw Blame History Unescape Escape