niuniu/gaokao-volunteer-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
61ba0ca9878d9060427f70c8b9cdf4d2fbf3d3f8
gaokao-volunteer-system/SPRINT_4_S4_PERF_OPS.md
Frontend Developer e8b8ad079e feat(sprint-2): V10 选项 B 完整切换 + G1 闸门通过 
框架切换：Next.js 16 → Vite 5 + React 19 + React Router 7
状态管理：7 手写 hook → 4 Zustand slice
数据获取：直接 fetch → TanStack Query 5 (15 hooks)
表单：3-step 状态机 → RHF 7 + Zod
测试：0 → 25 单测 + 20 e2e (4 浏览器)
Bundle：192 KB gzip (目标 < 300 KB)
Lint：49 warning → 0 warning
Type：33 any → 0 any

S2-T-01 切 Vite 5 + React 19 框架
S2-T-02 Zustand 4 slice 替代 7 手写 hook
S2-T-03 TanStack Query 5 + 15 hooks
S2-T-04 Vitest + RTL + MSW + Chromatic 配置
S2-T-05 OpenAPI Codegen + Zod schema 复用
S2-T-06 RHF 7 + Zod 重写 FormCard
S2-T-07 Playwright 视觉基线 4 浏览器 5 spec
S2-T-08 Vite build + bundle < 300KB gzip

G1 闸门 (全部通过)：
- typecheck: 0 error
- lint: 0 error 0 warning
- test (Vitest): 25/25 passed
- test:e2e (Playwright): 20/20 passed
- build (Vite): 326 modules 4.14s
- codegen:check: OpenAPI types 非占位

Sprint 2 收口报告：SPRINT_2_CLOSEOUT_2026-07-03.md
2026-07-03 15:51:03 +08:00

277 lines
8.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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）
```bash
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 完成后立即启动
Reference in New Issue View Git Blame Copy Permalink