79 lines
5.4 KiB
Markdown
79 lines
5.4 KiB
Markdown
# 任务书 · 首页加载失败可恢复性与 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. 硬红线
|
||
|
||
1. 不新增第二套 loading animation；不改变“一个等待、一次揭幕”的现有语义。
|
||
2. 不能把失败详情、出生资料、聊天内容、token、secret 或完整请求体写入观测日志。
|
||
3. 不自动刷新，不制造刷新循环；重试只能由用户明确点击。
|
||
4. `/` 必须保持 `○ Static`，首屏 gzip 变化在 ±2%；不增加 `Home()` 状态/引用。
|
||
5. 既有测试名不减少；断言变化写原值/新值/原因。
|
||
|
||
## 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. 开工前置命令
|
||
|
||
```bash
|
||
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 已核对。
|