gaokao-volunteer-system/SPRINT_4_S4_PERF_OPS.md

Sprint 4 任务拆解（W6-7 · 10 人天 · 46 子任务）— V10 选项 B

技术栈：Vite 5 + React 19 + Zustand 4 + TanStack Query 5 + RHF 7 + Zod 目标：错误/兜底/离线/防重 + 性能优化 + 监控收口 + 真实后端回归 闸门：G3（Lighthouse P75 ≥ 90 P/A/B/S）+ G4（Poster CLI Docker 镜像跑通） V10 变化：从 14d 缩到 10d（节省 4d = Vite SSR 简化 + e2e 用 Playwright 1.55 加速） PM 决策（2026-07-03）：整体重写为新实现；Playwright 视觉回归 + Chromatic 验收

---

⚠️ V10 关键变化（与 V2 对比）

维度	V2	V10 选项 B
Lighthouse 目标	90 P75	90 P75（保持）
e2e 真实化（8 路径）	3.0d	2.0d（Playwright trace + Vite preview 加速）
Bundle 优化	1.0d	0.5d（Vite 已分块）
i18n 错误码映射	0.5d	0.5d（不变）
总估时	14d	10d

---

0. Sprint 4 概览

任务	主任务	估时	子任务数
T-B-18	错误码 → 用户文案映射	0.5d	3
T-B-19	ErrorBoundary 兜底页	0.5d	3
T-B-20	离线检测 + 提示	1.0d	4
T-B-21	表单提交防重复（RHF 版）	0.5d	3
T-B-22	TanStack Query 持久化	0.5d	3
T-B-23	e2e 真实化（8 路径，Playwright 加速）	2.0d	8
T-B-24	Lighthouse CI 集成	1.5d	4
T-B-25	Bundle 优化（Vite 版）	0.5d	3
T-B-26	路由级 prefetch	0.5d	2
T-B-27	真实后端回归	0.5d	2
T-B-40	Share Link 状态面板数据	0.5d	3
T-B-41	ShareLink 失败降级	0.5d	3
T-B-42	LLM 增强进度轮询	0.5d	3
T-B-43	Poster 异步生成 + 轮询	0.5d	3
T-C-44	Poster CLI 部署集成（Docker）	1.0d	4
T-C-45	集成测试套件	0d	2
合计	16 任务	10d	53

---

T-B-18 · 错误码 → 用户文案映射（0.5d · 3 子任务）

ST-S4-B-18.1 写 packages/i18n/zh-CN/errors.json（0.25d）

• 内容：15 个错误码全覆盖
  • E03001 / E03002 / E03003
  • E04001 / E04002
  • E05001
  • +8 V2 错误码
• 约束：沿用 admin/errors/registry.py 5 字段结构

ST-S4-B-18.2 写 api-client 拦截器（0.125d）

• 验收：
  • 拦截响应 → 查表 → 返回 i18n 文案

ST-S4-B-18.3 写单测（0.125d）

• 覆盖：15 错误码各 1 用例

---

T-B-19 · ErrorBoundary 兜底页（0.5d · 3 子任务）

ST-S4-B-19.1 写 ErrorBoundary 组件（0.25d）

• V10 变化：用 react-error-boundary 库，避免手写 class 组件

ST-S4-B-19.2 写兜底页（0.125d）

• UI/交互 1:1：与原型 ErrorPage 一致

ST-S4-B-19.3 接入根路由（0.125d）

---

T-B-20 · 离线检测 + 提示（1.0d · 4 子任务）

ST-S4-B-20.1 写 useOnlineStatus hook（0.25d）

• 封装：navigator.onLine + online/offline 事件

ST-S4-B-20.2 写 OfflineBanner 组件（0.25d）

• V10 不变量 L2：移动端 48px 高度

ST-S4-B-20.3 写离线降级策略（0.25d）

• 行为：写操作排队 + 恢复后自动重试

ST-S4-B-20.4 写 e2e：offline.spec（0.25d）

---

T-B-21 · 表单提交防重复（RHF 版 · 0.5d · 3 子任务）⚠️ V10 简化

V10 收益：RHF formState.isSubmitting 内置

ST-S4-B-21.1 接入 RHF isSubmitting（0.125d）

ST-S4-B-21.2 写通用 SubmitButton 组件（0.25d）

ST-S4-B-21.3 写单测（0.125d）

---

T-B-22 · TanStack Query 持久化（0.5d · 3 子任务）⚠️ V10 简化

V10 收益：@tanstack/query-async-storage-persister 内置支持

ST-S4-B-22.1 安装 persister（0.125d）

pnpm --filter web add @tanstack/query-async-storage-persister

ST-S4-B-22.2 写 queryClient.ts 持久化配置（0.25d）

• maxAge：24h
• storage：localStorage

ST-S4-B-22.3 验证 5 模块刷新恢复（0.125d）

---

T-B-23 · e2e 真实化（8 路径 · 2.0d · 8 子任务）⚠️ V10 加速

V10 加速：用 Playwright test.step + Vite preview server

ST-S4-B-23.1 e2e: theme-switch（0.25d）

ST-S4-B-23.2 e2e: chat-send-receive（0.25d）

ST-S4-B-23.3 e2e: form-submit-validation（0.25d）

ST-S4-B-23.4 e2e: plan-create-view（0.25d）

ST-S4-B-23.5 e2e: share-link-create-scan（0.25d）

ST-S4-B-23.6 e2e: data-query-search（0.25d）

ST-S4-B-23.7 e2e: review-flow-approve（0.25d）

ST-S4-B-23.8 e2e: poster-generate-download（0.25d）

---

T-B-24 · Lighthouse CI 集成（1.5d · 4 子任务）

ST-S4-B-24.1 安装 @lhci/cli（0.25d）

ST-S4-B-24.2 写 lighthouserc.json（0.5d）

• 目标：P ≥ 90 / A ≥ 95 / B ≥ 90 / S ≥ 90
• V10 收益：Vite 产物比 Next.js 小，Lighthouse 分数天然更高

ST-S4-B-24.3 接入 GitHub Action（0.5d）

• 验收：
  • PR 触发 LHCI
  • 分数 < 90 阻止合并

ST-S4-B-24.4 调优未达标项（0.25d）

---

T-B-25 · Bundle 优化（Vite 版 · 0.5d · 3 子任务）⚠️ V10 简化

V10 收益：Sprint 2 已分块，S4 只做微调

ST-S4-B-25.1 配置 manualChunks 精细化（0.125d）

• 目标：recharts 单独 chunk（懒加载）

ST-S4-B-25.2 配置资源内联阈值（0.125d）

• 4KB 以下内联

ST-S4-B-25.3 验证 bundle < 300KB gzip（0.25d）

---

T-B-26 · 路由级 prefetch（0.5d · 2 子任务）

ST-S4-B-26.1 写 <PrefetchLink> 组件（0.25d）

• 行为：hover 200ms 后预取目标 chunk

ST-S4-B-26.2 接入 Header / Sidebar（0.25d）

• 验收：
  • hover → 预取 → 点击 0 等待

---

T-B-27 · 真实后端回归（0.5d · 2 子任务）

ST-S4-B-27.1 启动后端服务（0.25d）

• 命令：docker compose up backend postgres

ST-S4-B-27.2 跑 5 模块端到端（0.25d）

• 验收：
  • Share / Query / Review / LLM / Poster 全部 200

---

T-B-40 · Share Link 状态面板数据（0.5d · 3 子任务）

ST-S4-B-40.1 写 useShareLinkStatsQuery（0.125d）

• 封装：GET /api/share-link/{code}/stats

ST-S4-B-40.2 写 Stats 组件（0.25d）

• V10 收益：Sprint 3 已实现，此处优化

ST-S4-B-40.3 接入 Dashboard（0.125d）

---

T-B-41 · ShareLink 失败降级（0.5d · 3 子任务）

ST-S4-B-41.1 写重试机制（0.25d）

• V10 收益：TanStack Query retry: 3 内置

ST-B-41.2 写降级 UI（0.125d）

ST-S4-B-41.3 写 e2e：share-link-fallback.spec（0.125d）

---

T-B-42 · LLM 增强进度轮询（0.5d · 3 子任务）⚠️ V10 简化

V10 收益：TanStack Query refetchInterval 内置

ST-S4-B-42.1 写 useAuditEnhanceStatusQuery（0.125d）

ST-S4-B-42.2 写进度条组件（0.25d）

ST-S4-B-42.3 接入 AuditPanel（0.125d）

---

T-B-43 · Poster 异步生成 + 轮询（0.5d · 3 子任务）

ST-S4-B-43.1 写 usePosterStatusQuery（0.125d）

ST-S4-B-43.2 写状态机组件（0.25d）

• 三态：generating / ready / failed

ST-S4-B-43.3 接入 PosterDialog（0.125d）

---

T-C-44 · Poster CLI 部署集成（Docker · 1.0d · 4 子任务）

ST-C-44.1 写 Dockerfile.poster（0.25d）

ST-C-44.2 写 docker-compose.yml 添加 poster 服务（0.25d）

ST-C-44.3 本地构建 + 启动验证（0.25d）

ST-C-44.4 CI 集成（0.25d）

---

T-C-45 · 集成测试套件（0d · 2 子任务）

ST-C-45.1 写 tests/integration/ 骨架（0d）

ST-C-45.2 跑通 3 个集成测试（0d）

---

V10 验收清单（Sprint 4 G3 + G4 闸门）

G3 闸门（必须全部通过）：
  [ ] Lighthouse P75 ≥ 90（P/A/B/S 四项）
  [ ] pnpm build bundle < 300KB gzip
  [ ] 8 e2e spec 全绿
  [ ] 真实后端 5 模块 200

G4 闸门：
  [ ] Poster CLI Docker 镜像本地构建 < 60s
  [ ] docker compose up 启动成功
  [ ] Poster 异步生成端到端跑通

---

V10 风险（Sprint 4 特有）

ID	风险	等级	缓解
V10-S4-R1	Lighthouse 分数不达标	中	Vite 产物天然高分；重点优化 LCP 图
V10-S4-R2	真实后端回归失败	中	用 docker compose 隔离环境；失败可回退 mock
V10-S4-R3	Poster CLI Docker 镜像构建慢	低	多阶段构建 + 缓存

---

Sprint 4 文档状态：V10 选项 B 重写完成 总工时：10 人天（V2 是 14 人天，节省 4d） 总子任务：53 个（V2 是 50 个） 下一步：Sprint 3 完成后立即启动