From 65260ca7e0aa6af806b1e5401d07982a8500e06b Mon Sep 17 00:00:00 2001 From: Jesse_Chen Date: Sat, 26 Sep 2026 05:59:41 +0800 Subject: [PATCH] docs(tasks): brief for warm return to home without replaying the loader Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_017eEAG8HD3mm8gsKXgk8uU8 --- docs/tasks/README.md | 1 + docs/tasks/TASK-home-warm-return-20260926.md | 60 ++++++++++++++++++++ 2 files changed, 61 insertions(+) create mode 100644 docs/tasks/TASK-home-warm-return-20260926.md diff --git a/docs/tasks/README.md b/docs/tasks/README.md index 25ac954e..9ecff523 100644 --- a/docs/tasks/README.md +++ b/docs/tasks/README.md @@ -119,6 +119,7 @@ | 任务书 | 进度 | 主题 | 状态 | 落点 | | --- | --- | --- | --- | --- | +| `TASK-home-warm-return-20260926.md` | — | **从其他页面回首页不再放加载动画**：首页按组件挂载计揭幕，客户端返回会重跑模型列表 / 后台状态 / 入口摘要 / 今日星语（3–5 次往返 + 最多 4 秒）。产品定：每次打开网页只揭幕一次；模块级暖快照按账户隔离、只存内存，暖返回首帧即就绪、后台静默刷新；缺项回落冷启动，不许半揭幕。**排在 BUG-1038 合入后**。BUG-1040 | 待领取 | — | | `TASK-new-chat-from-people-20260926.md` | — | **从星盘档案页点新建对话落回上一次生时校正**（产品 09-26 真机）：标题显示旧校正会话、输入框「正在打开生时校正…」，中间却是新对话开场；另有两套新建入口（`?new=1` 与 `?newChat=1`）违反 BUG-1015 一处解析红线。先复现写失败测试、定位跨页残留状态再修，合并入口。BUG-1038 | 待领取 | — | | `TASK-people-archive-p1-fix-20260925.md` | `PROGRESS-people-archive-p1-fix-20260925.md` | **P0修复**：worker按持久化人物解析、真实删除预留退款、本人历史OR is、切人/消息时序及P2/P3；BUG-1031/1032，关联1030/990/1024。永久定向54/54、独立前端5探针与退款r4六场景通过；必须最终Node22 Linux全量+DB逐条基线对照 | 已验收（Claude 09-25：两 P0、两 P1、七 P2 通过；新 P2 删后跳错人、人物接口故障连累聊天 → 收尾单） | `4d801e53`（已部署，health 核对一致） | | `TASK-home-page-split-20260925.md` | `PROGRESS-home-page-split-20260925.md` | **首页 page.tsx 拆分（只搬不改）**：启动流程约 285 行抽成 lib 纯函数 `runHomeBootstrap`、恢复轮询约 100 行抽出、错误 / 引导屏抽组件，目标 ≤1300 行并下调增长合同基线；两个按源码切片的测试改为直接调用函数；还原 824647f2 的 import 挤行。排在 chart-ephemeris 之后、people-archive P1 之前 | 已验收（行为逐行一致；1417 行达让步线、合同基线已下调；流程违规：未跑全量致门禁红 3 次） | `da35b3e4`（已部署） | diff --git a/docs/tasks/TASK-home-warm-return-20260926.md b/docs/tasks/TASK-home-warm-return-20260926.md new file mode 100644 index 00000000..e8500429 --- /dev/null +++ b/docs/tasks/TASK-home-warm-return-20260926.md @@ -0,0 +1,60 @@ +# TASK · 从其他页面回首页不再重放加载动画（2026-09-26） + +## 基线 + +- `origin/staging` 当前 head（线上 `e84d6eb8`）。分支 `codex/home-warm-return-20260926`。 +- **串行**：本单改 `frontend/src/app/(app)/page.tsx` 与 `frontend/src/lib/home-bootstrap-run.ts`，与 `TASK-new-chat-from-people-20260926.md`（BUG-1038，同样改新建意图与启动落点）冲突 → **BUG-1038 合入后开工**。与 `TASK-people-ephemeris-ui-20260926.md` 不交叉。 + +## 事故实证（产品 09-26 真机） + +第一次进首页有加载动画是预期；但从星盘 / 星历 / 我的报告 / 星盘档案点「新建对话」回首页，**每次都要再看一遍加载动画、等很久**。 + +代码链（`origin/staging` e84d6eb8）： + +- `page.tsx`：`const [hydrated, setHydrated] = useState(false)`、`const [bootstrapPhase, setBootstrapPhase] = useState("account")` —— 每次挂载都从"未就绪"开始，渲染 `AppLoadingIndicator`。 +- `home-bootstrap-run.ts` `runAccountPhase`：每次挂载都重新 `fetchModelCatalog`（`/api/models`）、`fetchActiveConsultationStatus`（`/api/consult/status`），`await sessionListReady`（共享外壳里已就绪，快），`resolveLanding` 中可能再 `fetchSessionDetail`。 +- 之后进入 prepare 阶段：`page.tsx` 拉 `/api/rectification/cases/entry-summary`，`daily-starlanguage-binder.tsx` `fetchDailyStarlanguage`，揭幕预算 `BOOTSTRAP_PREPARE_TIMEOUT_MS = 4000`。 +- 合计：回首页一次要 3–5 次网络往返 + 最多 4 秒揭幕等待。这些数据在本次打开里第一次进首页时已经拿过。 +- 先例：BUG-966 让星盘 / 星历 / 报告首屏数据进模块级缓存，"同一会话再次进入直接用模块缓存，不重放等待"（DESIGN §Secondary page shell）。首页没有同等机制。 + +## 根因 + +首页的"一次等待一次揭幕"是按**组件挂载**计的，不是按**这次打开网页**计的；客户端导航回首页会卸载重挂，于是每次重放完整启动。 + +## 决策记录（产品 2026-09-26） + +- **D1 加载动画每次打开网页只放一次**：整页加载（刷新、首次打开、登录后跳转）照旧有加载动画；同一次打开里从其他页面客户端导航回首页，**不出现加载动画**，首页立即可用。 +- **D2 模块级"首页暖快照"**（新文件 `frontend/src/lib/home-warm-snapshot.ts`，按账户 id 键，只存内存、不落 localStorage）：第一次启动成功后写入 —— `modelCatalog`、`account`、`profile`、`startGreeting` 所需信息、`onboardingStep`、校正入口摘要、今日星语（按当前人物 + 日期键）。 +- **D3 暖返回路径**：挂载时若有同账户快照 → `hydrated` / `bootstrapPhase` 的**初始值**直接取就绪态（用 `useState(() => …)` 初始化函数，不新增 hook），同步完成落点（含新建意图，沿用 BUG-1038 合并后的唯一解析）；随后**后台**刷新模型列表、后台任务状态（有进行中的咨询仍要恢复）、入口摘要、今日星语，结果到了再静默替换，不回到加载态、不出 spinner。 +- **D4 失效**：账户变化、登出、`/api/account` 401 → 清空快照；模型列表后台刷新发现当前所选模型已下线 → 沿用现有「此前选择的模型已下线，已切换为默认模型」提示；今日星语跨日或换人 → 该字段按新键重取（卡片区用现有静态句，不挡首页）。 +- **D5 打开历史会话**（从次级页侧栏点某条历史 `/?c=`）：同样不放加载动画；会话消息沿用首页内切换会话时的现有加载方式，不新造等待态。 + +## 硬红线 + +1. 整页加载的行为与文案不变（加载环、20 秒错误屏、局部重试、BUG-1021 的"不半揭幕"）。暖返回只在快照齐全时启用，缺任何一项就走原冷启动路径，**不得出现"揭幕了但模型 / 资料没填"的半状态**。 +2. 进行中的咨询恢复（`reservedConsultation` / pending）在暖返回时仍要执行，只是改为后台检查。 +3. `Home()` 不新增 `useState` / `useRef`（用初始化函数与模块快照）；`page.tsx` 不得增长超过增长合同；新逻辑放 `lib/`，内部不调用 React hook。 +4. 快照只在内存、按账户隔离，不落任何持久存储；不缓存消息正文以外的敏感数据到新位置（消息仍在现有会话状态里）。 +5. `/` 保持 `○ Static`，首屏 gzip ±2%；全量测试 Node 22 + Linux 与基线逐条一致、新增 0；改动断言写三栏（在测试文件里）。 +6. **必须在真实浏览器里测**：首页 → 星盘 → 点「新建对话」，录网络面板：暖返回时在首页可交互之前**没有任何被等待的网络请求**，也没有加载环；截图 / 数字写进 PROGRESS。 + +## 任务分解 + +- T1 `home-warm-snapshot.ts`（写入、读取、按账户失效、按人物 + 日期键的今日星语）。验收：纯函数单测覆盖写入 / 换账户清空 / 401 清空 / 跨日重取。 +- T2 冷启动成功后写快照；挂载时读快照走暖路径（D3），后台刷新与静默替换。验收：真实 React 生命周期测试——先冷启动一次 → 卸载 → 以 `/?new=1` 重挂：首帧即为就绪态（无 `AppLoadingIndicator`），新建空对话已激活，`fetchModelCatalog` 未被 await（后台调用可有）；快照缺一项时回落冷启动。 +- T3 后台刷新的各种结果：模型下线提示、进行中咨询恢复、今日星语换日 / 换人、入口摘要更新。 +- T4 记录：BUG-1040（回首页重放加载，关联 BUG-966 / 479 / 1021）；`frontend/DESIGN.md` §9 首页揭幕规则写明"每次打开网页只揭幕一次，客户端返回首页走暖快照"；CHANGELOG；PROGRESS（含网络面板记录）；`docs/testing/home-warm-return-20260926.md`（首页→星盘→新建对话无加载环；首页→报告→点历史会话无加载环；刷新首页仍有加载环；登出换账号后不串数据；跨日回首页今日星语更新）。 + +## 开工前置命令 + +```bash +git fetch origin --prune +git log --oneline origin/staging | grep -i "1038\|new chat" | head # 确认 BUG-1038 已合入 +node -v # 22.x +git worktree add -b codex/home-warm-return-20260926 .worktrees/home-warm-return-20260926 origin/staging +cd .worktrees/home-warm-return-20260926/frontend && npx tsx --test tests/home-bootstrap-run.test.ts tests/home-bootstrap-reveal.test.ts +``` + +## BUG 编号 + +写单时 BUG-1038 / 1039 已被同日两单预留；本单 **BUG-1040**，开工时核对。