fix(ai): V3 长期问题修复+规则合规+竞品对标

## P1 安全加固
- 原子化每日限额（tryConsumeDailyQuota）解决 TOCTOU 竞态
- 流式端点补齐 Zod 校验 + rate limit + 服务端强制 systemPrompt
- 配额回退机制（refundDailyQuota）：过滤/失败不扣配额
- PII 最小化：移除 AI prompt 中的学生姓名

## P1 数据一致性
- 修复 capability 埋点缺失 child_summary/study_path 类型
- 创建 data-access.ts：真实统计聚合替代硬编码零
- 修复 generateChildSummary/recommendStudyPath 的 capability 标记

## P2 可靠性
- AI 调用重试机制（withRetry 指数退避，429/5xx，2 次重试）
- 30s 超时配置
- 流式 controller 安全 enqueue（防已关闭抛错）
- localStorage 防抖持久化（500ms，流式过程中跳过）

## P2 TypeScript/规则合规
- 移除 as 断言（VariantType 类型守卫、Permission 类型、StreamErrorKey）
- 补齐返回类型标注（POST/getStatusFromError/DashboardLayout）
- 拆分 use-ai-chat-stream hook（190→107 行，函数体≤80 行）
- 抽取 stream-utils.ts（SSE 解析/错误映射/消息工具）
- Tailwind 任意值添加注释说明（max-w-[80%] 聊天气泡）

## P3 竞品对标
- 苏格拉底式辅导强化（对标 Khanmigo）：
  - SOCRATIC_TUTOR_SYSTEM_PROMPT 3 级提示升级
  - 强化 STUDENT_BLOCKED_PATTERNS 正则（中英文答案拦截）
  - validateSocraticOutput 服务端校验（问号结尾+连续陈述句限制）
  - socratic_warning SSE 事件类型
- 知识图谱集成（对标 Squirrel AI）：
  - StudyPathInput 新增 knowledgeGraph/textbookId 字段
  - recommendStudyPathAction 自动从 textbooks 模块获取图谱+掌握度
  - STUDY_PATH_SYSTEM_PROMPT 增加前置依赖链规则
  - WEAKNESS_ANALYSIS_SYSTEM_PROMPT 增加 rootCause 字段

## 架构文档同步
- 004 更新 AI 模块章节（V3 标记/新导出/依赖关系/安全机制/文件清单）
- 005 更新 modules.ai 节点（dependsOn/exports/dataAccess/streamUtils/dependencyMatrix）

docs/architecture/004_architecture_impact_map.md

@@ -2056,33 +2056,41 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 | **student** | `AiStudyPath` | `student/*` | 学习路径推荐 — V2 新增 |
 
 **依赖关系**：
-- `modules/ai` → `shared/lib/ai`（AI SDK 封装，含流式 `createAiChatCompletionStream`）
+- `modules/ai` → `shared/lib/ai`（AI SDK 封装，含流式 `createAiChatCompletionStream`，V3 增加 `withRetry` 重试机制）
 - `modules/ai` → `shared/lib/auth-guard`（权限校验）
 - `modules/ai` → `shared/lib/track-event`（使用量埋点）
 - `modules/ai` → `shared/types/permissions`（权限常量）
 - `modules/ai` → `shared/types/action-state`（返回值类型）
+- `modules/ai` → `modules/textbooks/data-access-graph`（知识图谱+掌握度查询）— V3 新增
 - `app/(dashboard)/layout` → `modules/ai`（全局 Provider + Widget）— V2 新增
+- `app/api/ai/chat/stream` → `modules/ai/services/content-safety`（SSE 端点安全过滤）— V3 加固
 - 业务模块 → `modules/ai/context/ai-client-provider`（通过 Context 注入）
 - 业务模块 → `modules/ai/components/*`（组合 AI 组件）
 
-**安全机制（V2 新增）**：
+**安全机制（V2 新增 / V3 加固）**：
 - 输入过滤：`filterUserInput` 拦截暴力/自残/色情/PII
 - 输出过滤：`filterAiOutput` 扫描 AI 回复
 - 每日限制：学生 50 次/天，教师 200 次/天，家长 30 次/天
 - 学生 Socratic 模式：system prompt 强制不直接给答案
 - SSE 端点权限校验：`requirePermission(AI_CHAT)`
+- V3 原子配额：`tryConsumeDailyQuota` 解决 TOCTOU 竞态，`refundDailyQuota` 过滤/失败时回退
+- V3 苏格拉底校验：`validateSocraticOutput` 检查问号结尾+连续陈述句限制，`SOCRATIC_TUTOR_SYSTEM_PROMPT` 3 级提示升级
+- V3 SSE 端点加固：Zod 校验 + rate limit + 服务端强制 systemPrompt（忽略客户端）
+- V3 重试机制：`withRetry` 指数退避（429/5xx，2 次重试，1s/2s/4s 延迟）
+- V3 知识图谱集成：`recommendStudyPathAction` 自动从 textbooks 模块获取图谱+掌握度注入 prompt
 
 **文件清单**：
 
 | 文件 | 行数 | 职责 |
 |------|------|------|
-| `modules/ai/types.ts` | ~270 | 类型定义（8 个业务场景类型 + AiService/AiClientService） |
-| `modules/ai/schema.ts` | ~205 | Zod 验证 schema（8 个输入 + 8 个输出） |
-| `modules/ai/actions.ts` | ~340 | 9 个 Server Actions（含权限校验） |
-| `modules/ai/services/ai-service.ts` | ~400 | DefaultAiService 实现（8 个方法） |
-| `modules/ai/services/prompt-templates.ts` | ~210 | 8 个系统提示词模板 |
-| `modules/ai/services/usage-tracker.ts` | ~83 | AI 使用量埋点 |
-| `modules/ai/services/content-safety.ts` | ~130 | 内容安全过滤（输入/输出/每日限制）— V2 新增 |
+| `modules/ai/types.ts` | ~290 | 类型定义（8 个业务场景类型 + AiService/AiClientService，V3 新增 knowledgeGraph/textbookId） |
+| `modules/ai/schema.ts` | ~230 | Zod 验证 schema（8 个输入 + 8 个输出，V3 新增 knowledgeGraph/textbookId） |
+| `modules/ai/actions.ts` | ~400 | 9 个 Server Actions（含权限校验，V3 新增知识图谱获取） |
+| `modules/ai/data-access.ts` | ~138 | AI 事件存储+统计聚合 — V3 新增 |
+| `modules/ai/services/ai-service.ts` | ~430 | DefaultAiService 实现（8 个方法，V3 新增知识图谱上下文注入） |
+| `modules/ai/services/prompt-templates.ts` | ~250 | 9 个系统提示词模板（V3 新增 SOCRATIC_TUTOR_SYSTEM_PROMPT） |
+| `modules/ai/services/usage-tracker.ts` | ~90 | AI 使用量埋点（V3 新增 child_summary/study_path 能力） |
+| `modules/ai/services/content-safety.ts` | ~290 | 内容安全过滤（输入/输出/每日限制/原子配额/苏格拉底校验）— V2 新增 / V3 加固 |
 | `modules/ai/context/ai-client-provider.tsx` | ~62 | React Context Provider + Hooks |
 | `modules/ai/components/ai-assistant-widget.tsx` | ~170 | 全局 AI 助手悬浮按钮 — V2 新增 |
 | `modules/ai/components/ai-chat-panel.tsx` | ~305 | AI 对话面板（流式 + Markdown）— V2 增强 |
@@ -2097,7 +2105,8 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 | `modules/ai/components/ai-error-boundary.tsx` | ~88 | AI 错误边界 |
 | `modules/ai/components/ai-skeleton.tsx` | ~47 | AI 骨架屏 |
 | `modules/ai/components/ai-provider-selector.tsx` | ~129 | 服务商选择器 |
-| `modules/ai/hooks/use-ai-chat-stream.ts` | ~170 | 流式 AI 对话 Hook — V2 新增 |
+| `modules/ai/hooks/use-ai-chat-stream.ts` | ~107 | 流式 AI 对话 Hook（V3 拆分至 ≤80 行函数体）— V2 新增 / V3 重构 |
+| `modules/ai/hooks/stream-utils.ts` | ~120 | SSE 流解析工具（consumeSseStream/getStreamErrorKey 等）— V3 新增 |
 | `modules/ai/hooks/use-ai-chat.ts` | ~57 | 非流式 AI 对话 Hook |
 | `modules/ai/hooks/use-ai-suggestion.ts` | ~72 | AI 建议 Hook |
 | `app/api/ai/chat/stream/route.ts` | ~160 | SSE 流式端点 — V2 新增 |