docs(home): record slow-network acceptance
Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
jesse-ux
@@ -13560,6 +13560,34 @@
|
||||
- 复发自：BUG-715/723 的失败分档未覆盖按需层投影与组件出口；旧测试仅验主盘错误和端点不可用说明，未串联真实 busy 层响应到 hook。
|
||||
- 修复版本：`1420471a`（staging 已部署、health 核对一致）
|
||||
|
||||
## BUG-1021 | 慢网首页半揭幕，模型与账户状态脱节
|
||||
|
||||
- 状态：resolved（本地 Windows/Node 20 定向合同与 TypeScript 验证通过；浏览器 Slow 3G、staging health 与部署证据待产品/协调方完成）
|
||||
- 首次发现 / 最近更新：2026-09-24。
|
||||
- 影响面：首页账户、会话、模型目录、咨询状态 bootstrap 与重试。
|
||||
- 现象 / 触发：Slow 3G 强刷首页，原 8 秒串行预算先显示云端超时；SessionListProvider 后到仍写账户/会话，页面可能揭幕为模型不可用、发送禁用并重新询问称呼的半成品。
|
||||
- 根因：Home 自有 8 秒 AbortController 与 SessionListProvider 独立请求脱节；模型目录失败只写 composer 提示却仍允许账户提交；渲染门未要求模型目录存在。
|
||||
- 修复：引入 20 秒 `HOME_BOOTSTRAP_SLOW_MS`；模型、咨询状态与 provider 并行启动；必要数据齐全前统一等待，模型/必要请求失败保持全屏错误；重试取消旧请求、reload provider 并局部重跑；provider 使用可重入读取和旧 generation/controller 防护；首屏 ES5 fallback 调为 25 秒。
|
||||
- 验证：`tsc --noEmit` 通过；首页与 fallback 定向合同通过；完整 lint 有 0 error、既有 warnings；浏览器与部署验收未在本地宣称通过。
|
||||
- 防复发：保留一次等待一次揭幕、错误屏要求 `account` 与 `modelCatalog`，禁止 React 错误屏使用 `location.reload()`；provider 旧请求不得提交状态。
|
||||
- 相关记录：BUG-479、BUG-927、BUG-936；`TASK-home-slow-network-20260924.md`。
|
||||
- 复发自：无；BUG-927 引入的 provider/Home 时序脱节首次在本单补齐门控。
|
||||
- 修复版本：`659bd9600`（待 staging 推送与部署核对）。
|
||||
|
||||
## BUG-1022 | 账户与点数首次打开慢且离线预取会误触发刷新
|
||||
|
||||
- 状态：resolved（本地 Node 20 定向合同通过；浏览器与 staging 验收待完成）
|
||||
- 首次发现 / 最近更新：2026-09-24。
|
||||
- 影响面：账户菜单、BillingPanel 动态分包、套餐接口与支付/兑换余额同步。
|
||||
- 现象 / 触发：首次打开账户与点数需等待懒加载 chunk 和套餐请求；面板挂载还会重复请求完整 `/api/account`；指针悬停离线时动态 import reject 可能被全局 stale-client recovery 当作 ChunkLoadError 并整页刷新。
|
||||
- 根因：账单 chunk 无预取/静态占位；套餐零缓存；挂载账户请求结果被 Home 传入账户覆盖；prefetch reject 未隔离。
|
||||
- 修复：账户菜单 pointer enter/down 预取 chunk 和套餐；chunk 未到时显示静态占位；套餐结果模块缓存 60 秒并后台刷新；独立 route 查询并行；删除挂载 `/api/account`，兑换和支付直接用响应 `credits` 通过既有共享事件同步；prefetch 显式 catch 隔离失败。
|
||||
- 验证：账单、membership、epay、首页 bootstrap/fallback 定向合同共 65/65；TypeScript 通过；定向 lint 通过；完整 lint 0 error、既有 warnings；浏览器/部署验收待完成。
|
||||
- 防复发：合同锁定无 `/api/account`、响应 credits 同步和 prefetch catch；动态 import 预取失败不得冒泡到全局刷新逻辑。
|
||||
- 相关记录：BUG-479、BUG-1021、`TASK-home-slow-network-20260924.md`。
|
||||
- 复发自：BUG-554（账户与点数离开首页的旧入口已修复）；本单是性能与慢网回归，不改变设置弹窗入口。
|
||||
- 修复版本：`1fbe14995`、`6a097b6a3`（待 staging 推送与部署核对）。
|
||||
|
||||
## BUG-1020 | CRLF 普通报告下载保留图盘 JSON 围栏
|
||||
|
||||
- 状态：investigating（产品 2026-09-24 批准 D5 有限例外 D14，修复单待领取；未修复前不得标 resolved）
|
||||
|
||||
@@ -0,0 +1,66 @@
|
||||
# PROGRESS · 慢网首页半揭幕 + 账户与点数打开慢（2026-09-24）
|
||||
|
||||
## 当前状态
|
||||
|
||||
- 实际 worktree：`G:\Ferti\Jyotisha\.claude\worktrees\agent-aa9a862be5b171b9b`
|
||||
- 分支：`codex/home-slow-network-20260924`
|
||||
- 基线：`origin/staging` `edc9c22c3`
|
||||
- 当前实现提交：`1fbe14995`、`659bd9600`、`6a097b6a3`；本记录及最终验收修订尚未提交。
|
||||
- 第二单、第三单未开始，按任务书串行依赖暂停。
|
||||
|
||||
## 实施
|
||||
|
||||
### T1 首页启动
|
||||
|
||||
- 新增 `HOME_BOOTSTRAP_SLOW_MS = 20_000`；删除原 8 秒硬超时语义。
|
||||
- `/api/models`、咨询状态和 SessionListProvider 启动读取并行；模型或必要 bootstrap 请求失败时在 commit 前进入全屏错误状态，不揭幕半成品首页。
|
||||
- React 错误屏「重试」取消上一轮、reload provider 读取并局部重跑，不调用 `location.reload()`。
|
||||
- SessionListProvider 增加可重入 reload、AbortController 替换和旧请求提交保护。
|
||||
- 首屏 ES5 fallback 调为 25 秒，仍保留六类失败分类；只有 bundle 没运行的首屏 fallback 按钮才允许用户点击整页 reload。
|
||||
|
||||
### T2 账户与点数
|
||||
|
||||
- BillingPanel 动态分包使用静态占位「账户信息还没拿到。」；账户菜单 pointer enter/down 预取 chunk 和套餐。
|
||||
- 移除 `use-billing-panel` 挂载时完整 `/api/account` 请求；兑换成功使用兑换响应 `credits`，支付成功使用 status 响应 `credits`，均通过既有共享余额事件同步，不新增账户请求。
|
||||
- 套餐结果模块级缓存 60 秒，过期返回旧值并后台刷新；套餐 route 的 feature flags 与商品读取并行，权益仍在 product IDs 就绪后读取。
|
||||
- 预取动态 chunk 的失败显式 catch 隔离，不让离线 hover 预取触发全局 stale-client recovery reload。
|
||||
|
||||
## 三栏断言调整
|
||||
|
||||
| 文件 | 原值 | 新值 | 原因 |
|
||||
| --- | --- | --- | --- |
|
||||
| `frontend/tests/membership-navigation-contract.test.ts` | 挂载断言 `Promise.allSettled([fetchAccountData(), fetchPackages()])`，认证跳转计数 4 | 仅断言套餐加载、无 `fetchAccountData`/`/api/account`；认证跳转计数 3 | T2 删除无用挂载账户请求，保留订单、兑换、支付状态的 401 硬跳转 |
|
||||
| `frontend/tests/epay-settings.test.ts` | 直接断言 hook fetch `/api/payment/packages`、`payload.enabled` 和旧 `setPaymentEnabled(true)` | 断言 hook 使用 `fetchPaymentPackages`，缓存模块发起请求并规范化 enabled | 网络请求迁移到 60 秒共享缓存，支付开关行为不变 |
|
||||
| `frontend/tests/billing-panel.test.ts` | 兑换/支付后再次 `fetchAccountData()`；预取无失败处理 | 断言使用响应 credits 广播余额，预取 promise catch 隔离 | 删除重复账户查询但保留成功后的余额同步，避免离线预取未处理 rejection |
|
||||
| `frontend/tests/first-paint-fallback-contract.test.ts` | 兜底晚于 8 秒 + 4 秒 prepare | 兜底晚于 20 秒慢网阈值并留余量 | 新首页 slow-network budget 为 20 秒 |
|
||||
|
||||
## 验证结果
|
||||
|
||||
已通过：
|
||||
|
||||
```text
|
||||
./node_modules/.bin/tsc --noEmit exit 0
|
||||
./node_modules/.bin/eslint src/hooks/use-billing-panel.ts \
|
||||
src/lib/session-list-context.tsx tests/epay-settings.test.ts exit 0
|
||||
./node_modules/.bin/tsx --test \
|
||||
tests/membership-navigation-contract.test.ts \
|
||||
tests/billing-panel.test.ts tests/epay-settings.test.ts \
|
||||
tests/home-bootstrap-reveal.test.ts \
|
||||
tests/first-paint-fallback-contract.test.ts 65 pass / 0 fail
|
||||
```
|
||||
|
||||
全量 `npm run lint` 已执行：0 error、121 warnings；warnings 为仓库既有问题，本轮新增的 `epay-settings` 未使用变量 warning 已移除。全量 `npm test`、`npm run build`、浏览器 Slow 3G / Offline 真人验收仍需最终执行/记录。
|
||||
|
||||
## 环境缺口
|
||||
|
||||
- 本轮未读取或提交任何真实隐私资料、凭据、Cookie、JWT 或模型密钥。
|
||||
- 本地 Windows worktree 可完成 TypeScript、定向合同和定向 lint；尚未有 Chrome 登录态，真人 Slow 3G / Offline、动态 chunk 网络行为无法在本地声明通过。
|
||||
- 尚未执行 build、Static/gzip 对比、Docker/Linux volume 保真路径和 staging health；不能据此声称部署或 staging 已验收。
|
||||
- 未 push；Gitea 认证 token 当前不可用，需协调方恢复既定认证后再按 `status → fetch --prune → 同步 origin/staging → push` 流程交付。
|
||||
|
||||
## 后续
|
||||
|
||||
1. 独立复核本记录、BUG_HISTORY 和定向测试。
|
||||
2. 完成全量前端测试、build 与可用的静态/gzip 对比；将失败名单与基线逐项记录。
|
||||
3. 协调推送前先 `git status -sb`、`git fetch origin --prune`，同步最新 `origin/staging`，确认无共享工作树改动后再推送本单。
|
||||
4. staging 验收通过后才领取 `TASK-chart-ephemeris-fixes-20260924.md`。
|
||||
@@ -0,0 +1,41 @@
|
||||
# 慢网首页与账户点数真人验收清单（2026-09-24）
|
||||
|
||||
> 仅使用受控测试账号和虚构资料；不要记录姓名、出生资料、邮箱、Cookie、JWT 或完整会话内容。
|
||||
|
||||
## 自动化前置
|
||||
|
||||
- [ ] `tsc --noEmit` 通过。
|
||||
- [ ] `npm run lint` 结果与进度记录一致；warnings 不得新增。
|
||||
- [ ] 定向合同测试 65/65 通过。
|
||||
- [ ] `npm test`、`npm run build`、`/` Static 与首屏 gzip 对比完成。
|
||||
|
||||
## Chrome Slow 3G 首页
|
||||
|
||||
1. 打开 Chrome DevTools Network，选择 Slow 3G，清空缓存并强刷 `/`。
|
||||
2. 确认揭幕后只发生一次等待：未到齐前只有既有首页轨道环；账户、会话、模型和必要 bootstrap 数据齐后一次揭幕。
|
||||
3. 确认揭幕后没有 spinner、骨架或「正在加载」；模型可选择，发送按钮可用，页面不再次询问已存在的称呼。
|
||||
4. 在 provider 较慢、模型先到和模型较慢两种顺序各重复一次；确认没有首页+错误条的半揭幕。
|
||||
|
||||
## 模型失败与慢网错误屏
|
||||
|
||||
1. 用受控网络规则让 `/api/models` 失败、但账户/会话成功。
|
||||
2. 确认首页不揭幕，显示「暂时无法进入 Jyotisha」错误屏，不出现模型不可用的半成品。
|
||||
3. 让请求持续超过 20 秒；确认显示现有全屏错误屏。
|
||||
4. 恢复网络后点击「重试」，确认只重跑请求并进入首页；在 DevTools 断点或脚本中确认没有调用 `location.reload()`。
|
||||
|
||||
## 账户与点数
|
||||
|
||||
1. 正常打开账户菜单，将指针移到「账户与点数」，观察动态 chunk 和 `/api/payment/packages` 预取。
|
||||
2. 首次打开确认 chunk 未到时显示静态句「账户信息还没拿到。」，不显示 spinner；套餐接口只请求一次。
|
||||
3. 关闭后第二次打开，确认 60 秒内套餐立即显示，网络请求为 0 或后台刷新一次。
|
||||
4. 兑换成功后确认余额通过共享事件更新；支付成功轮询后确认余额更新；Network 中不出现由面板挂载触发的额外 `/api/account`。
|
||||
5. 在离线状态把指针移到「账户与点数」，确认预取失败不触发整页自动刷新；恢复网络后由用户重新打开或重试。
|
||||
|
||||
## 结果记录
|
||||
|
||||
- 浏览器 / 版本：
|
||||
- 账号类型（不要写账号标识）：
|
||||
- 测试时间：
|
||||
- 通过项：
|
||||
- 未通过项与脱敏截图路径：
|
||||
- 环境缺口：无 Chrome、无受控账号或无法模拟网络时填写，不得写成通过。
|
||||
Reference in New Issue
Block a user