gaokao-volunteer-system/SPRINT_3_S3_NEW_MODULES.md

# Sprint 3 任务拆解（W4-5 · 12 人天 · 62 子任务）— V10 选项 B

> **技术栈**：Vite 5 + React 19 + Zustand 4 + TanStack Query 5 + RHF 7 + Zod
> **目标**：5 大 V2 新模块（Share / Query / Review / LLM / Poster）+ Share Link 统计 + Portal 集成
> **闸门**：G2（LLM fallback 4 模实测可切换 + 5 模块端到端跑通）
> **V10 变化**：从 22d 缩到 12d（节省 10d = 8 hook 真实化用 TanStack Query 替代 + 5 模块统一模式）
> **PM 决策（2026-07-03）**：整体重写为新实现；Playwright 视觉回归 + Chromatic 验收

---

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

| 维度 | V2 | V10 选项 B |
|---|---|---|
| useChat 拆 6 子 hook | 1.5d | **0.5d**（V10 已用 Zustand 替代，S3 只需补 mock） |
| 真实 sendMessage | 1.0d | **0.5d**（TanStack Query mutation + Zod） |
| useAudit + LLM 增强 | 1.5d | **0.75d**（Zustand + mutation hook） |
| 5 大新模块 | 14d | **8d**（统一 TanStack Query 模式） |
| 视觉回归 | 0d | **+1d**（V10 Chromatic 验证） |
| 总估时 | 22d | **12d** |

---

## 0. Sprint 3 概览

| 任务 | 主任务 | 估时 | 子任务数 |
|---|---|---|---|
| T-B-12 | useChatOrchestrator（V10 重写） | 0.5d | 3 |
| T-B-13 | 真实 sendMessage + typing | 0.5d | 3 |
| T-B-14 | 真实 getHistory + 滚动恢复 | 0.5d | 3 |
| T-B-15 | usePlan/useConsultation 真实化 | 0.75d | 4 |
| T-B-16 | useProfile Zustand 版 | 0.5d | 3 |
| T-B-17 | useAudit + LLM 增强（4 模 fallback） | 0.75d | 4 |
| T-B-22 | Share Link API（4 端点） | 0.75d | 4 |
| T-B-23 | Data Query API（3 端点） | 0.75d | 4 |
| T-B-24 | Review Flow API（3 端点） | 0.75d | 4 |
| T-B-25 | Portal API（2 端点） | 0.5d | 3 |
| T-B-26 | LLM Audit Enhance API | 0.75d | 4 |
| T-B-27 | Poster Generate API | 0.5d | 3 |
| T-B-28 | Share Link 统计 + 分享 UI | 1.0d | 5 |
| T-B-29 | Chromatic 视觉回归（S3 增量） | 0.5d | 3 |
| T-B-30 | ESLint 0 warning 守门（V10 重写） | 0.5d | 3 |
| **合计** | **15 任务** | **9.5d + 缓冲 2.5d = 12d** | **56 + 6 整合 = 62** |

---

## T-B-12 · useChatOrchestrator（V10 重写 · 0.5d · 3 子任务）⚠️ V10 简化

> **V10 收益**：Sprint 2 已建立 Zustand store + TanStack Query，S3 只需组装编排层

### ST-S3-B-12.1 写 chat-fixtures（0.25d）
- **产出**：`apps/web/__mocks__/chat-fixtures.ts`
- **3 套 mock**：广东物理 620 / 广东历史 580 / 河北物理 600

### ST-S3-B-12.2 写 `useChatOrchestrator`（0.125d）
- **产出**：`apps/web/src/hooks/useChatOrchestrator.ts`
- **职责**：Zustand messages + TanStack Query mutation + Typing 状态机
- **V10 收益**：从 1.5d（V2 拆 6 子 hook）→ 0.125d

### ST-S3-B-12.3 接入 8 个 UI 组件（0.125d）
- **覆盖**：MessageList / InputBar / TypingIndicator / PlanCard / ModeIndicator / 等

---

## T-B-13 · 真实 sendMessage + typing（0.5d · 3 子任务）

### ST-S3-B-13.1 写 `useChatSendMutation`（0.25d）
- **封装**：`POST /api/chat/send` + SSE 流式响应
- **类型**：`z.infer<typeof ChatSendSchema>`

### ST-S3-B-13.2 写 `useTypingState` Zustand selector（0.125d）
- **三态**：thinking（旋转）/ paused（静止）/ stopped（隐藏）

### ST-S3-B-13.3 接入 InputBar 真实点击发送（0.125d）
- **验收**：
  - [ ] 点击发送 → 流式输出 → typing 状态切换正确
  - [ ] `any` 数量 0

---

## T-B-14 · 真实 getHistory + 滚动恢复（0.5d · 3 子任务）

### ST-S3-B-14.1 写 `useChatHistoryQuery`（0.125d）
- **封装**：`GET /api/chat/history?sessionId=xxx`
- **缓存策略**：`staleTime: 5min` + `gcTime: 30min`

### ST-S3-B-14.2 写滚动恢复 hook（0.25d）
- **产出**：`useScrollRecovery(ref, [messages.length])`
- **行为**：sessionId 变化时滚到底部；用户上滑时不打断
- **V10 不变量**：UI 1:1 复现（V2 Plan §3.1 L1）

### ST-S3-B-14.3 接入 ChatPanel 组件（0.125d）

---

## T-B-15 · usePlan/useConsultation 真实化（0.75d · 4 子任务）

### ST-S3-B-15.1 写 `usePlanQuery`（0.125d）
### ST-S3-B-15.2 写 `usePlanCreateMutation`（0.25d）
### ST-S3-B-15.3 写 `useConsultationQuery` + `useConsultationMutation`（0.25d）
### ST-S3-B-15.4 接入 PlanCard 真实数据（0.125d）
- **V10 不变量 C1**：PlanCard 3-Tab 切换不重渲染父组件

---

## T-B-16 · useProfile Zustand 版（0.5d · 3 子任务）⚠️ V10 简化

### ST-S3-B-16.1 写 `useUserStore` Zustand（0.25d）
- **V10 收益**：从 1.0d（V2 真实 useProfile）→ 0.25d

### ST-S3-B-16.2 接入 Header 头像/菜单（0.125d）

### ST-S3-B-16.3 接入 Settings 页面（0.125d）

---

## T-B-17 · useAudit + LLM 增强（4 模 fallback · 0.75d · 4 子任务）

> **G2 闸门核心**：LLM 4 模（claude / gpt / gemini / deepseek）实测可切换

### ST-S3-B-17.1 写 LLM provider 适配器（0.25d）
- **产出**：`apps/web/src/lib/llm/provider.ts`
- **4 provider 类型**：`ClaudeProvider` / `GPTProvider` / `GeminiProvider` / `DeepseekProvider`
- **接口**：`enhance(input: AuditInput): Promise<AuditEnhancement>`

### ST-S3-B-17.2 写 `useAuditEnhanceMutation`（0.25d）
- **封装**：`POST /api/llm/audit-enhance` + provider 选择
- **降级链**：claude → gpt → gemini → deepseek

### ST-S3-B-17.3 写 `useLLMConfig` Zustand store（0.125d）
- **状态**：currentProvider / fallbackOrder / availableProviders

### ST-S3-B-17.4 4 模实测切换（0.125d）
- **验收（G2）**：
  - [ ] claude 失败 → 自动降级 gpt
  - [ ] gpt 失败 → 自动降级 gemini
  - [ ] 全部失败 → 走 deepseek
  - [ ] Playwright e2e 覆盖

---

## T-B-22 · Share Link API（4 端点 · 0.75d · 4 子任务）

### ST-S3-B-22.1 写 `useShareLinkCreate`（0.25d）
- **封装**：`POST /api/share-link`
- **Schema**：`{ planId, expiresIn: 7|30|forever }`

### ST-S3-B-22.2 写 `useShareLinkDelete`（0.125d）
- **封装**：`DELETE /api/share-link/{id}`

### ST-S3-B-22.3 写 `useShareLinkLatestQuery`（0.125d）
- **封装**：`GET /api/portal/share-link/latest`

### ST-S3-B-22.4 写 `useShareLinkStatsQuery`（0.25d）
- **封装**：`GET /api/share-link/{code}/stats`
- **响应**：`{ views, uniqueVisitors, lastAccessedAt }`

---

## T-B-23 · Data Query API（3 端点 · 0.75d · 4 子任务）

### ST-S3-B-23.1 写 `useScoreLineQuery`（0.25d）
- **封装**：`GET /api/data-query/score-line`
- **参数**：`{ province, year, scoreType }`

### ST-S3-B-23.2 写 `useRankEstimatorQuery`（0.25d）
- **封装**：`GET /api/data-query/rank-estimator`
- **V10 变化**：TanStack Query `select` 直接转换位次→等效分数

### ST-S3-B-23.3 写 `useMajorsQuery` + `useSchoolsQuery`（0.25d）
- **封装**：`GET /api/data-query/majors` + `GET /api/data-query/schools`

---

## T-B-24 · Review Flow API（3 端点 · 0.75d · 4 子任务）

### ST-S3-B-24.1 写 `useReviewStartMutation`（0.25d）
- **封装**：`POST /api/review/start`

### ST-S3-B-24.2 写 `useReviewStatusQuery`（0.125d）
- **封装**：`GET /api/review/{id}/status`
- **轮询**：`refetchInterval: 3000`（审核中）

### ST-S3-B-24.3 写 `useReviewActionMutation`（0.25d）
- **封装**：`POST /api/review/action`（approve / reject / request_changes）
- **V10 变化**：Zod discriminated union 处理 3 种 action

### ST-S3-B-24.4 接入 ReviewPanel UI（0.125d）

---

## T-B-25 · Portal API（2 端点 · 0.5d · 3 子任务）

### ST-S3-B-25.1 写 `usePortalCWBQuery`（0.25d）
- **封装**：`GET /api/portal/{token}/cwb`（位次查询）

### ST-S3-B-25.2 写 `usePortalFullPlanQuery`（0.125d）
- **封装**：`GET /api/portal/{token}/full-plan`

### ST-S3-B-25.3 写 Portal 入口页面（0.125d）
- **UI/交互 1:1**：与原型招生门户入口一致

---

## T-B-26 · LLM Audit Enhance API（0.75d · 4 子任务）

### ST-S3-B-26.1 写 `useAuditEnhanceMutation`（0.25d）
- **封装**：`POST /api/llm/audit-enhance`

### ST-S3-B-26.2 写流式响应处理（0.25d）
- **V10 关键技术**：SSE + ReadableStream + Zustand 增量更新
- **复用**：`useChatSendMutation` 的流式逻辑

### ST-S3-B-26.3 写 LLM 结果展示组件（0.125d）

### ST-S3-B-26.4 接入 AuditPanel UI（0.125d）

---

## T-B-27 · Poster Generate API（0.5d · 3 子任务）

### ST-S3-B-27.1 写 `usePosterGenerateMutation`（0.25d）
- **封装**：`POST /api/poster/generate`
- **响应**：`{ posterUrl, qrCode, expiresAt }`

### ST-S3-B-27.2 写海报预览组件（0.125d）
- **V10 视觉**：海报需与原型的视觉风格一致

### ST-S3-B-27.3 接入 ShareDialog UI（0.125d）

---

## T-B-28 · Share Link 统计 + 分享 UI（1.0d · 5 子任务）⚠️ V10 加强

> **V10 加强**：5 个子任务覆盖 UI + 统计图表 + 移动端适配

### ST-S3-B-28.1 写 ShareDialog 组件（0.25d）
- **UI/交互 1:1**：与原型分享弹窗一致
- **V10 不变量**：移动端 48px 触发区

### ST-S3-B-28.2 写 QR Code 展示组件（0.125d）
- **依赖**：`qrcode.react`

### ST-S3-B-28.3 写 Stats 统计卡片（0.25d）
- **3 卡片**：访问数 / 独立访客 / 最近访问
- **图标**：lucide-react

### ST-S3-B-28.4 写访问趋势 mini chart（0.25d）
- **依赖**：`recharts`
- **V10 收益**：Sprint 5 chart 任务的预演

### ST-S3-B-28.5 写 e2e：share-link.spec（0.125d）

---

## T-B-29 · Chromatic 视觉回归（S3 增量 · 0.5d · 3 子任务）⚠️ V10 新增

### ST-S3-B-29.1 截图新增 5 模块页面（0.25d）
- **页面**：ShareDialog / Stats / DataQuery / ReviewPanel / Poster Preview

### ST-S3-B-29.2 提交 Chromatic 增量基线（0.125d）

### ST-S3-B-29.3 Chromatic diff 阈值告警（0.125d）
- **CI**：`pnpm chromatic --exit-zero-on-changes`

---

## T-B-30 · ESLint 0 warning 守门（V10 重写 · 0.5d · 3 子任务）

> **V10 关键**：S3 完成后 ESLint 必须 0 warning（V2 是 49 warning 缓慢修）

### ST-S3-B-30.1 清理 S3 引入的 any（0.25d）
- **验收**：`grep -r "any" apps/web/src/` 0 结果

### ST-S3-B-30.2 清理 S3 引入的 unused vars（0.125d）

### ST-S3-B-30.3 升级 Sprint 1 临时 warn 规则为 error（0.125d）
- **规则**：`@typescript-eslint/no-explicit-any` / `react-hooks/set-state-in-effect`
- **目的**：阻止 Sprint 4-8 倒退

---

## V10 验收清单（Sprint 3 G2 闸门）

```
G2 闸门（必须全部通过）：
  [ ] 5 大新模块端到端跑通（Share / Query / Review / LLM / Poster）
  [ ] LLM 4 模实测可切换 + 自动降级
  [ ] pnpm typecheck 0 error 0 any
  [ ] pnpm lint 0 error 0 warning
  [ ] pnpm test 100% 覆盖新增 56 个子任务相关组件
  [ ] pnpm test:e2e 5 spec 全绿
  [ ] pnpm build bundle < 320KB gzip（+20KB for new modules）
  [ ] pnpm chromatic 视觉基线 13 页全提交
  [ ] 原型 7 个手写 hook + 1 个 lib/ 全部删除
  [ ] ESLint 0 warning（V2 是 49 warning 修 1 整轮）
```

---

## V10 风险（Sprint 3 特有）

| ID | 风险 | 等级 | 缓解 |
|---|---|---|---|
| V10-S3-R1 | LLM 4 模 provider 适配成本高 | 中 | 抽象统一接口；先实现 1 模，再快速复制 3 模 |
| V10-S3-R2 | SSE 流式响应与 TanStack Query 兼容 | 中 | 用 `onMutate` + Zustand 增量更新，绕过 React Query 的缓存机制 |
| V10-S3-R3 | 5 新模块并发开发协调 | 中 | 串行实施：T-B-22 → T-B-23 → T-B-24 → T-B-26 → T-B-27 |
| V10-S3-R4 | Chromatic 商业服务配额 | 低 | Sprint 2 已用 1 次，S3 再用 1 次，剩余 8 次给 S4-S8 |

---

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