Jesse_ChenandClaude Opus 5.5
514951d708
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017eEAG8HD3mm8gsKXgk8uU8
61 lines
5.4 KiB
Markdown
61 lines
5.4 KiB
Markdown
# TASK · 首页 page.tsx 拆分：启动流程、恢复轮询、错误 / 引导屏移出（2026-09-25）
|
||
|
||
## 基线
|
||
|
||
- 开工时 `origin/staging`（写单时 `824647f2` 代码 + 文档）。分支 `codex/home-page-split-20260925`。
|
||
- **串行**：排在 `TASK-chart-ephemeris-fixes-20260924.md` 合入之后（其 T3 碰设置深链与首页打开设置的入口）；排在 `TASK-people-archive-p1-20260924.md` **之前**（P1 要在首页加当前人物，拆完后改动落在 hook 里）。与 `TASK-chart-dasha-western-redesign` 文件不交叉，可并行。
|
||
|
||
## 事故实证（`origin/staging` 824647f2）
|
||
|
||
- `frontend/src/app/(app)/page.tsx` 1849 行：68 行 import、16 个 `useState`、17 个 `useRef`、22 个 `useEffect`，JSX 从 `return (` 约第 1597 行才开始。
|
||
- **启动流程约 285 行**：`useEffect` 内 `async function loadCloudData()`（约第 851–1125 行），一次性负责 provider 等待、模型列表、pending 恢复、会话 lookup / 详情、落点、`set*` 一串、错误与超时。09-24 慢网 bug（BUG-1021）和随后 5 条红测试都出在这一块；测试只能靠按源码字符串切片（`new-chat-recovery.test.ts`、`consultation-recovery.test.ts`）来测它。
|
||
- **咨询恢复轮询约 100 行**：约第 1143–1240 行的 `useEffect`（`consultationStatusMissingCount` 计数、404 重放、4 次放弃）。
|
||
- 错误屏（「暂时无法进入 Jyotisha」）、引导（onboarding）分支的 JSX 内联在 `Home()`。
|
||
- `824647f2` 为满足任务书"不得净增行"把多条 import 挤在同一行（第 7–9 行），属格式凑数，需还原。AGENTS §6 已于 09-25 明确禁止此类做法。
|
||
|
||
## 根因
|
||
|
||
`Home()` 仍承担装配之外的业务流程（启动编排、恢复轮询），只能以源码切片测试，每次改动都牵连合同测试。
|
||
|
||
## 决策记录（产品 2026-09-25）
|
||
|
||
- D1 本单**只搬代码、不改行为**：落点规则、20 秒错误屏、局部重试、pending 优先级、恢复轮询次数与文案全部不变。
|
||
- D2 遵守既定模式「参数式 hook / lib 函数内部 0 个 React hook」：启动流程抽成 `frontend/src/lib/home-bootstrap-run.ts` 的纯异步函数 `runHomeBootstrap(deps, signal)`（`deps` 注入 fetch 函数、provider 读取、storage、setter），`Home()` 里只保留一个 `useEffect` 调用它；恢复轮询抽成 `frontend/src/lib/consultation-recovery-poll.ts` 同样方式。
|
||
- D3 错误屏、引导屏 JSX 抽成 `frontend/src/components/home-bootstrap-error.tsx`、`home-onboarding-shell.tsx`（或按现有组件命名习惯），`Home()` 只传 props。
|
||
- D4 目标 `page.tsx` ≤ **1300 行**；达成后把 `home-shell-growth-contract.test.ts` 的 `PAGE_LINE_COUNT_BASELINE` 下调到新实测值（余量仍 +150），`HOME_USE_STATE_CAP` / `HOME_USE_REF_CAP` 若减少同步下调——锁住拆分成果。
|
||
- D5 还原 `824647f2` 挤在一行的 import（每行一条语句）。
|
||
- D6 两个源码切片测试改为**直接调用** `runHomeBootstrap` / 恢复轮询函数（注入假依赖），删除对 `page.tsx` 源码字符串的切片；这是"原值 / 新值 / 原因"类改写，不是弱化——断言的行为必须等价或更强。
|
||
|
||
## 硬红线
|
||
|
||
1. 行为零变化：全量测试失败名单与开工基线**逐条一致、新增 0**（Linux 跑；进度记录附对比命令与结果）；`next build` 后 `/` 仍 `○ Static`，首屏 gzip ±2%。
|
||
2. `Home()` 的 `useState` / `useRef` 不得增加；新文件内不得调用 React hook（D2）。
|
||
3. 不得用合并语句、删注释等改格式方式减行（AGENTS §6）。
|
||
4. 不改接口、数据库、workflow；不顺手修 warning；不升级依赖。
|
||
5. 既有断言改动写三栏；测试总数不低于基线。
|
||
|
||
## 任务分解
|
||
|
||
- T1 `runHomeBootstrap` 抽出。验收：新测试 `home-bootstrap-run.test.ts` 直接调用，覆盖——全部成功一次性回填、模型失败 → 错误态（不半揭幕）、pending 优先于全局状态、`new-chat` 落点与 reserved 恢复共存、超时 abort；`new-chat-recovery.test.ts` 与 `consultation-recovery.test.ts` 改为调用函数，不再切 `page.tsx`。
|
||
- T2 恢复轮询抽出。验收：假计时器测试覆盖 404 第 1 次重放、第 4 次放弃、成功清零。
|
||
- T3 错误屏 / 引导屏组件抽出。验收：渲染测试文案与按钮不变；「重试」仍走 `retryHomeBootstrap`。
|
||
- T4 还原 import 格式；下调增长合同基线。验收：`page.tsx` ≤ 1300；`grep -nE "^import .*; import " "frontend/src/app/(app)/page.tsx"` = 0。
|
||
- T5 记录：DESIGN 不变（无 UI 变化）；CHANGELOG 一条"首页内部重构，无用户可见变化"；PROGRESS；不新开 BUG 号。
|
||
|
||
## 让步顺序
|
||
|
||
1. 若 1300 行达不到，允许先到 ≤ 1450，写明剩余大块与下一步。
|
||
2. 若注入依赖过多（> 15 个），允许按阶段拆成 `runAccountPhase` / `resolveLanding` 两个函数。
|
||
3. 不得让步：红线 1、2、3。
|
||
|
||
## 开工前置命令
|
||
|
||
```bash
|
||
git fetch origin --prune
|
||
git worktree add -b codex/home-page-split-20260925 .worktrees/home-page-split-20260925 origin/staging
|
||
git worktree add --detach .worktrees/split-baseline-20260925 origin/staging
|
||
cd .worktrees/split-baseline-20260925/frontend && npm test > /tmp/split-base.log 2>&1
|
||
cd ../../home-page-split-20260925/frontend && ./node_modules/.bin/tsc --noEmit && npm run lint
|
||
# 完成后：npm test > /tmp/split-head.log 并与基线逐条 diff（见 TASK-staging-gate-fix 的命令）
|
||
```
|