feat(ai): V2 深度增强 — SSE 流式/全局助手/内容安全/多角色覆盖

对标 Khanmigo/Duolingo Max/Squirrel AI/Century Tech 实现： - SSE 流式响应：createAiChatCompletionStream AsyncGenerator + /api/ai/chat/stream SSE 端点 + useAiChatStream hook（AbortController 停止生成 + localStorage 持久化） - Markdown 渲染：AiMarkdownRenderer（react-markdown + remark-gfm + 代码块/表格/列表 + hover 复制按钮） - 全局 AI 助手：AiAssistantWidget 浮动按钮 + Sheet 侧抽屉 + usePathname 路由推断上下文（7 类场景系统提示）+ dashboard layout 全局注入 AiClientProvider - 内容安全：content-safety.ts 多层过滤（输入/输出安全过滤 + 每日限制 student 50/teacher 200/parent 30/admin 500 + 学生苏格拉底模式），COPPA/FERPA K12 合规 - 多角色 AI 覆盖：家长端 AiChildSummary（学情摘要）+ 管理员端 AiUsageDashboard（使用监控）+ 学生端 AiStudyPath（个性化学习路径） - i18n 修复：8 处错误键引用 + zh-CN/en ai.json 全面扩展 - 架构文档 004/005 同步更新
2026-06-23 01:34:37 +08:00
parent a60105455e
commit 4da9194a5e
27 changed files with 3522 additions and 172 deletions
--- a/docs/architecture/004_architecture_impact_map.md
+++ b/docs/architecture/004_architecture_impact_map.md
@@ -430,6 +430,8 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 - `cn()` / `formatDate()` / `formatFileSize()` — 通用工具
 - `getInitials(name)` / `formatDateForFile(d?)` — 通用工具（P1-c / P1-a 重构新增：从 parent/lib/utils.ts、grades/export-button.tsx 等多处重复实现抽取）
 - `downloadBase64File(base64, filename, mimeType?)` / `downloadBlob(blob, filename)` — 客户端文件下载（P1-c 重构新增：从 grades/export-button、users/user-import-dialog、audit/audit-log-export-button 三处重复实现抽取，位于 `lib/download.ts`）
+- `handleActionError(e)` / `safeActionCall(action, options?)` / `safeJsonParse(json, msg)` / `safeParseDate(v, field)` / `safeParseNumber(v, field)` / `escapeLikePattern(input)` — Server Action 错误处理与客户端调用包装（2026-06-23 审计修复新增：位于 `lib/action-utils.ts`，统一所有 Server Action catch 块错误处理，避免内部错误消息暴露给客户端）
+- `BusinessError` / `NotFoundError` / `ValidationError` — 错误类（2026-06-23 审计修复新增：位于 `lib/action-utils.ts`，已知业务错误基类，message 可安全返回客户端）

 **共享组件导出**（P0-b / P1-a / P1-b / P1-c / P2-a / P2-b / P3-a / P3-b / P3-c / P3-d / 第二轮 P0-1/P0-2/P0-3/P1-1/P1-2/P1-3/P1-4 重构新增，按类别组织）：

@@ -601,6 +603,7 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 - ✅ V3-8：新增 `getHomeworkAssignmentsByExamId` + `getGradedSubmissionsByExamId`，供 exams 模块跨模块调用
 - ✅ V3-9：新增 `getStudentSubmissionResult` + `HomeworkSubmissionResult` + 路由 `/student/learning/assignments/[assignmentId]/result`，`homework-take-view.tsx` 提交后跳转结果页
 - ✅ V3-12：`homework-take-view.tsx` 移动端触摸目标尺寸优化
+- ✅ 2026-06-23 审计修复：data-access 层 4 个查询函数新增 `scope?: DataScope` 参数（`getHomeworkAssignments`/`getHomeworkAssignmentById`/`getHomeworkSubmissions`/`getHomeworkAssignmentReviewList`），教师仅查看自己创建的作业，学生/家长仅查看相关作业；Server Action catch 块改用 `handleActionError` 统一错误处理

 **文件清单**：
 | 文件 | 行数 | 职责 |
@@ -717,11 +720,12 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 **职责**：成绩分析（录入/查询/统计/导出/趋势对比分析）。

 **导出函数**：
- Actions：`getGradeRecordsAction` / `createGradeRecordAction` / `updateGradeRecordAction` / `deleteGradeRecordAction` / `exportGradesAction` / `getGradeTrendAction` / `getClassComparisonAction` / `getSubjectComparisonAction` / `getGradeDistributionAction` / `getClassRankingAction` / `getRankingTrendAction` / `getGradeRecordByIdAction` / `getClassGradeStatsAction` / `getStudentGradeSummaryAction` / `batchCreateGradeRecordsAction` / `assertClassInScope`（✅ P3 新增导出：班级 scope 校验工具，供 actions-analytics 复用）
- Data-access：`getGradeRecords` / `getStudentGradeSummary` / `getClassRanking` / `getClassStudentsForEntry` / `getClassGradeStats` / `getClassGradeStatsWithMeta` / `getGradeTrend` / `getClassComparison` / `getSubjectComparison` / `getGradeDistribution` / `getRankingTrend` / `PaginatedGradeRecords`（✅ P3 新增：分页结果接口 `{ records, total }`）
+- Actions：`getGradeRecordsAction` / `createGradeRecordAction` / `updateGradeRecordAction` / `deleteGradeRecordAction` / `exportGradesAction` / `getGradeTrendAction` / `getClassComparisonAction` / `getSubjectComparisonAction` / `getGradeDistributionAction` / `getClassRankingAction` / `getRankingTrendAction` / `getGradeRecordByIdAction` / `getClassGradeStatsAction` / `getStudentGradeSummaryAction` / `batchCreateGradeRecordsAction` / `assertClassInScope`（✅ P3 新增导出：班级 scope 校验工具，供 actions-analytics 复用）/ `saveGradeDraftAction` / `getGradeDraftAction` / `deleteGradeDraftAction`（✅ v3-P2 新增：成绩录入草稿 Server Actions，分别使用 GRADE_RECORD_MANAGE/GRADE_RECORD_READ/GRADE_RECORD_MANAGE 权限）
+- Data-access：`getGradeRecords` / `getStudentGradeSummary` / `getClassRanking` / `getClassStudentsForEntry` / `getClassGradeStats` / `getClassGradeStatsWithMeta` / `getGradeTrend` / `getClassComparison` / `getSubjectComparison` / `getGradeDistribution` / `getRankingTrend` / `PaginatedGradeRecords`（✅ P3 新增：分页结果接口 `{ records, total }`）/ `saveGradeDraft` / `getGradeDraft` / `deleteGradeDraft`（✅ v3-P2 新增：成绩录入草稿 CRUD，upsert + 24 小时过期）/ `getExamOptionsForGrades` / `getSchoolWideGradeSummary`（✅ v3-P2 新增：考试选项查询 + 全校各年级成绩汇总，管理员视图按年级聚合平均分/及格率/优秀率/学生数/班级数，加权平均计算全校汇总）
+- Types（✅ v3-P2 新增）：`SchoolWideGradeSummaryItem`（全校汇总按年级聚合项：gradeId/gradeName/schoolName/classCount/studentCount/averageScore/passRate/excellentRate/recordCount）/ `SchoolWideGradeSummary`（全校汇总：grades 数组 + totals 汇总对象）/ `GradeDraftData`（草稿数据接口：{ scores: Record<string, string>, timestamp: number }，位于 data-access.ts）
 - Lib（✅ P1-2 新增，✅ P3 更新签名）：`toNumber` / `normalize` / `buildScopeClassFilter(scope, currentUserId?)`（P3 修复：`class_members` scope 内置 studentId 过滤，需传入 currentUserId 参数）
 - Stats-service（✅ P1-1 新增）：`computeGradeStats` / `computeAverageScore` / `buildGradeTrendPoints` / `computeTrendAverage` / `computeClassComparisonStats` / `computeSubjectComparisonStats` / `computeGradeDistribution` / `buildRankingTrendPoints`（从 3 个 data-access 文件抽取的纯函数，使数据层专注 DB I/O，统计逻辑可独立测试）
- Components（✅ P1-5 新增）：`WidgetBoundary`（Error Boundary + Suspense + Skeleton 组合，含 a11y 属性）
+- Components（✅ P1-5 新增）：`WidgetBoundary`（Error Boundary + Suspense + Skeleton 组合，含 a11y 属性）/ `SchoolWideSummaryCard`（✅ v3-P2 新增：管理员全校成绩汇总卡片，4 个统计卡片 + 各年级对比表格）

 **依赖关系**：
 - 依赖：`shared/*`、`@/auth`、`classes`（✅ P1-1 已修复：通过 classes data-access.getClassExists/getClassNameById/getClassNamesByIds/getActiveStudentIdsByClassId/getStudentActiveClassId/getClassesByGradeId）、`school`（✅ P1-1 已修复：通过 school data-access.getSubjectOptions/getGradeOptions）、`users`（✅ P1-1 已修复：通过 users data-access.getUserNamesByIds）
@@ -754,20 +758,27 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 - ✅ P3 修复（2026-06-22）：~~组件直接 try/catch 调用 Server Action~~ 改用 `safeActionCall` 包装器（onError/onFinally 回调）；`batch-grade-entry.tsx` localStorage 访问包裹 `typeof window !== "undefined"` 检查；区分"未录入"与"录入 0"
 - ✅ P3 修复（2026-06-22）：~~`grade-trend-card.tsx` 排序未处理 NaN 日期、除法未检查 fullScore > 0~~ 新增日期有效性检查与 `fullScore > 0` 守卫
 - ✅ P3 修复（2026-06-22）：~~页面文件缺少 scope 传递~~ teacher/grades/page.tsx 使用 DB 层分页；analytics/page.tsx 添加 EmptyState；entry/page.tsx 与 stats/page.tsx 过滤 class_taught scope 班级；student/grades/page.tsx 与 parent/grades/page.tsx 传递 `ctx.dataScope` 到 data-access
+- ✅ v3-P2 改进（2026-06-23）：新增 `grade_drafts` 表（成绩录入草稿，userId+classId+subjectId+type 唯一键，content JSON 存储 scores，24 小时过期，schema.ts 第 1444-1469 行）；新增 `saveGradeDraft`/`getGradeDraft`/`deleteGradeDraft` data-access 函数 + 对应 3 个 Server Actions，支持成绩批量录入草稿服务端持久化
+- ✅ v3-P2 改进（2026-06-23）：新增 `getExamOptionsForGrades` data-access 函数，获取指定班级/科目下有成绩记录的考试列表；`AnalyticsFilters` 组件新增 `exams`/`currentExamId`/`currentSemester` props，添加学期和考试筛选 ChipNav；teacher/grades/analytics/page.tsx 新增 semester/examId 搜索参数解析
+- ✅ v3-P2 改进（2026-06-23）：`getGradeTrend`/`getGradeDistribution`/`getSubjectComparison`/`getClassComparison` 均新增 `semester` 和 `examId` 可选参数，支持按学期和考试筛选分析
+- ✅ v3-P2 改进（2026-06-23）：新增 `getSchoolWideGradeSummary` data-access 函数 + `SchoolWideSummaryCard` 组件 + `SchoolWideGradeSummary`/`SchoolWideGradeSummaryItem` 类型，管理员全校成绩汇总视图（按年级聚合平均分/及格率/优秀率/学生数/班级数，加权平均计算全校汇总）；admin/school/grades/insights/page.tsx 顶部新增 SchoolWideSummaryCard
+- ✅ v3-P2 改进（2026-06-23）：parent/grades/page.tsx 为每个子女并行查询 `getClassAverageTrend`，渲染 GradeTrendCard

 **文件清单**：
 | 文件 | 行数 | 职责 |
 |------|------|------|
-| `actions.ts` | 396 | 15 个 Server Action（含 Zod 校验，含 v2-P1-5 安全修复：assertClassInScope + 行级 scope 校验；P3 修复：handleActionError + safeJsonParse + scope 传递 + DB 层分页） |
+| `actions.ts` | 396+ | 18 个 Server Action（含 Zod 校验，含 v2-P1-5 安全修复：assertClassInScope + 行级 scope 校验；P3 修复：handleActionError + safeJsonParse + scope 传递 + DB 层分页；v3-P2 新增：saveGradeDraftAction/getGradeDraftAction/deleteGradeDraftAction） |
 | `actions-analytics.ts` | 170 | 5 个分析 Action（含 Zod 校验，P3 修复：handleActionError + assertClassInScope 校验） |
-| `data-access.ts` | 428 | 成绩 CRUD + 统计（含 v2-P2-9 修复：recorderName 批量查询；P3 修复：PaginatedGradeRecords 接口 + DB 层分页 + 事务 + 存在性检查 + scope 过滤 + 并列排名） |
-| `data-access-analytics.ts` | 200 | 趋势/对比分析（P3 修复：getClassComparison 应用 buildScopeClassFilter） |
+| `data-access.ts` | 428+ | 成绩 CRUD + 统计 + 草稿（含 v2-P2-9 修复：recorderName 批量查询；P3 修复：PaginatedGradeRecords 接口 + DB 层分页 + 事务 + 存在性检查 + scope 过滤 + 并列排名；v3-P2 新增：saveGradeDraft/getGradeDraft/deleteGradeDraft + GradeDraftData 接口） |
+| `data-access-analytics.ts` | 200+ | 趋势/对比分析（P3 修复：getClassComparison 应用 buildScopeClassFilter；v3-P2 新增：getExamOptionsForGrades/getSchoolWideGradeSummary；getGradeTrend/getClassComparison/getSubjectComparison/getGradeDistribution 新增 semester/examId 可选参数） |
 | `data-access-ranking.ts` | 83 | 排名查询（P3 修复：getRankingTrend 接受 scope 参数 + class_taught 校验） |
 | `stats-service.ts` | 279 | 统计计算纯函数（P1-1 新增：8 个纯函数 + 2 个常量 + 2 个接口） |
 | `export.ts` | 189 | Excel 导出（v2-P1-5 修复：传递 currentUserId 到 data-access；P3 修复：适配 PaginatedGradeRecords 结构 + 传递 scope） |
-| `schema.ts` | 113 | Zod 校验（含 12 个查询 schema；P3 修复：score .max(1000) + records .max(500) + 补全查询字段） |
+| `schema.ts` | 113+ | Zod 校验（含 12 个查询 schema；P3 修复：score .max(1000) + records .max(500) + 补全查询字段；v3-P2 新增：grade_drafts 表定义第 1444-1469 行） |
 | `lib/grade-utils.ts` | 66 | 公共工具函数（toNumber/normalize/buildScopeClassFilter，v2-P2-2 修复：改用 classes data-access 子查询；P3 修复：buildScopeClassFilter 新增 currentUserId 参数） |
+| `types.ts` | 168+ | 类型定义（v3-P2 新增：SchoolWideGradeSummaryItem/SchoolWideGradeSummary） |
 | `components/widget-boundary.tsx` | 136 | Widget 边界组件（P1-5 新增，v2-P1-1 已在 3 个页面应用） |
+| `components/school-wide-summary-card.tsx` | - | v3-P2 新增：管理员全校成绩汇总卡片（4 个统计卡片 + 各年级对比表格） |
 | `components/grade-trend-card.tsx` | 69 | 趋势卡片（v2-P2-9 修复：a11y；v2-P1-4：i18n；P3 修复：NaN 日期检查 + fullScore > 0 守卫） |
 | `components/grade-record-list.tsx` | 125 | 成绩记录列表（v2-P1-4：i18n；P3 修复：safeActionCall 包装删除操作） |
 | `components/grade-distribution-chart.tsx` | 100 | 分数分布图（v2-P1-4：i18n） |
@@ -775,16 +786,15 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 | `components/class-comparison-chart.tsx` | 58 | 班级对比图（v2-P1-4：i18n） |
 | `components/grade-trend-chart.tsx` | 59 | 趋势图（v2-P1-4：i18n） |
 | `components/grade-record-form.tsx` | 177 | 录入表单（v2-P2-7 修复：Label htmlFor；v2-P1-4：i18n；P3 修复：safeActionCall 包装提交） |
-| `components/batch-grade-entry.tsx` | 435 | 批量录入（v2-P2-7 修复：Label htmlFor；v2-P1-4：i18n；P3 修复：safeActionCall + localStorage 安全检查 + 区分未录入与录入 0） |
+| `components/batch-grade-entry.tsx` | 435+ | 批量录入（v2-P2-7 修复：Label htmlFor；v2-P1-4：i18n；P3 修复：safeActionCall + localStorage 安全检查 + 区分未录入与录入 0；v3-P2 新增：接入服务端草稿 saveGradeDraftAction/getGradeDraftAction/deleteGradeDraftAction） |
 | `components/grade-filters.tsx` | 76 | 过滤器（v2-P1-4：i18n） |
 | `components/student-grade-summary.tsx` | 107 | 学生成绩摘要（v2-P1-4：i18n） |
 | `components/export-button.tsx` | 79 | 导出按钮（v2-P1-4：i18n；P3 修复：safeActionCall 包装导出操作） |
-| `components/analytics-filters.tsx` | 86 | 分析过滤器（v2-P1-4：i18n） |
+| `components/analytics-filters.tsx` | 86+ | 分析过滤器（v2-P1-4：i18n；v3-P2 新增：exams/currentExamId/currentSemester props，添加学期和考试筛选 ChipNav） |
 | `components/stats-class-selector.tsx` | 40 | 统计班级选择器（v2-P1-4：i18n） |
 | `components/grade-stats-card.tsx` | 74 | 统计卡片（v2-P1-4：i18n） |
 | `components/class-grade-report.tsx` | 90 | 班级成绩报告（v2-P1-4：i18n） |
 | `components/grade-query-filters.tsx` | 96 | 查询过滤器（v2-P2-7 修复：Label htmlFor；v2-P1-4：i18n） |
-| `types.ts` | 168 | 类型定义 |

 ---

@@ -1362,6 +1372,7 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 - ⚠️ v4 保留：`/parent/leave` 为占位页，待后端实现请假审批流后接入
 - ⚠️ v4 保留：`ParentExportButton` 为占位，待后端实现成绩导出 Server Action 后接入
 - ⚠️ v4 保留：详情页 Attendance/Diagnostic Tab 为占位提示，待对应功能实现后填充
+- ✅ v3-P2 改进（2026-06-23）：parent/grades/page.tsx 为每个子女并行查询 `getClassAverageTrend`，渲染 GradeTrendCard；parent/diagnostic/page.tsx 传入 `practiceHrefBase={null}` 隐藏练习按钮
 - ✅ 职责单一，正确复用其他模块 data-access

 **文件清单**：
@@ -1390,8 +1401,8 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 | 路由 | 文件 | 说明 |
 |------|------|------|
 | `/parent/dashboard` | `dashboard/page.tsx` + `loading.tsx` | 家长仪表盘 |
-| `/parent/grades` | `grades/page.tsx` + `loading.tsx` | 多子女成绩聚合 |
-| `/parent/diagnostic` | `diagnostic/page.tsx` + `loading.tsx` + `error.tsx` | P2-5 新增：多子女学情诊断聚合 |
+| `/parent/grades` | `grades/page.tsx` + `loading.tsx` | 多子女成绩聚合（v3-P2：并行查询 getClassAverageTrend + GradeTrendCard） |
+| `/parent/diagnostic` | `diagnostic/page.tsx` + `loading.tsx` + `error.tsx` | P2-5 新增：多子女学情诊断聚合（v3-P2：practiceHrefBase={null} 隐藏练习按钮） |
 | `/parent/attendance` | `attendance/page.tsx` + `loading.tsx` | 多子女考勤聚合（v4 新增预警横幅） |
 | `/parent/leave` | `leave/page.tsx` + `loading.tsx` | v4 新增：请假申请（占位） |
 | `/parent/children/[studentId]` | `children/[studentId]/page.tsx` + `loading.tsx` | 子女详情页（v4 重构：Tab 布局 + 多子女切换） |
@@ -1513,6 +1524,7 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 - ✅ v2-P1-4 已修复：~~4 个组件 i18n 完全未接入~~ 全部接入 `useTranslations("diagnostic")`
 - ✅ v2-P2-7 已修复：~~`report-list.tsx` 过滤器 Label 缺少 `htmlFor`~~ 添加 `htmlFor` 和 `id`
 - ✅ 与 grades 模块无职责重叠
+- ✅ v3-P2 改进（2026-06-23）：`StudentDiagnosticView` 新增 `practiceHrefBase` prop（string | null），null 时隐藏练习按钮；teacher/diagnostic/student/[studentId] 传入 `practiceHrefBase="/teacher/questions"`，parent/diagnostic 传入 `practiceHrefBase={null}` 隐藏练习按钮

 **文件清单**：
 | 文件 | 行数 | 职责 |
@@ -1524,7 +1536,7 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 | `schema.ts` | 23 | Zod 校验（4 个 schema，v2-P2-3 删除 2 个死代码 schema） |
 | `types.ts` | 87 | 类型定义 |
 | `components/class-diagnostic-view.tsx` | 266 | 班级诊断视图（v2-P1-6 热力图 a11y；v2-P1-4 i18n） |
-| `components/student-diagnostic-view.tsx` | 225 | 学生诊断视图（v2-P1-4 i18n） |
+| `components/student-diagnostic-view.tsx` | 225+ | 学生诊断视图（v2-P1-4 i18n；v3-P2 新增：practiceHrefBase prop，null 时隐藏练习按钮） |
 | `components/mastery-radar-chart.tsx` | 72 | 雷达图（v2-P1-4 i18n） |
 | `components/report-list.tsx` | 265 | 报告列表（v2-P2-7 Label htmlFor；v2-P1-4 i18n） |

@@ -1758,6 +1770,12 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 > - **P2-1 a11y 修复**：5 个组件（question-bank-picker/publish-homework-dialog/knowledge-point-picker/exercise-block/text-study-block）添加 `role="dialog"`/`aria-modal`/`aria-label`；inline-question-editor 添加 `role="dialog"`/`aria-modal`/`aria-label`
 > - **P2-4 监控埋点预留**：`providers/lesson-plan-provider.tsx` 定义 `LessonPlanTracker` 接口 + `noopTracker` 默认空实现，生产环境可替换为真实埋点

+> 架构变更（2026-06-23，本次审计修复）：
+> - **Zod schema 补全**：`schema.ts` 新增 `publishLessonPlanHomeworkSchema`（planId/blockId 必填，classIds 至少 1 个，availableAt/dueAt 日期格式校验），导出类型 `PublishLessonPlanHomeworkInput`；3 个 action 文件（actions/actions-publish/actions-ai）补全 Zod 校验
+> - **data-access-versions.ts 事务修复**：`revertToVersion` 包裹 `db.transaction` 确保原子性（回滚版本时同步更新 lessonPlans.content 与版本记录）
+> - **统一错误处理**：所有 Server Action catch 块改用 `handleActionError`；`JSON.parse` 改用 `safeJsonParse`
+> - **block-renderer 拖拽 BUG 修复**：修复拖拽时节点位置计算错误
+
 **文件清单**：
 | 文件 | 职责 |
 |------|------|
@@ -1896,14 +1914,15 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"

 ---

-## 2.29 ai（AI 模块）— ✅ 新增
+## 2.29 ai（AI 模块）— ✅ 新增 / V2 增强

-**职责**：统一 AI 能力封装，为备课、错题集、试卷、改题等业务模块提供 AI 服务。
+**职责**：统一 AI 能力封装，为备课、错题集、试卷、改题等业务模块提供 AI 服务。V2 增加流式响应、Markdown 渲染、全局助手、内容安全过滤、家长学情摘要、管理员使用统计、学生学习路径推荐。

 **架构定位**：
 - 位于 `modules/` 层，通过 `shared/lib/ai` 调用底层 AI SDK
 - 通过 `AiClientProvider`（React Context）向客户端组件注入 Server Action 引用
 - 业务模块不直接 import `ai/actions`，仅通过 Context 消费
+- V2：在 dashboard layout 全局注入 `AiClientProvider`，所有页面均可使用 AI 助手

 **核心导出**：

@@ -1915,19 +1934,34 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 | **Server Actions** | `generateLessonContentAction` | `modules/ai/actions.ts` | 备课内容生成（权限：AI_CHAT + LESSON_PLAN_READ） |
 | **Server Actions** | `generateQuestionVariantAction` | `modules/ai/actions.ts` | 题目变体生成（权限：AI_CHAT + EXAM_AI_GENERATE） |
 | **Server Actions** | `analyzeWeaknessAction` | `modules/ai/actions.ts` | 薄弱点分析（权限：AI_CHAT + ERROR_BOOK_READ） |
-| **Service** | `AiService` | `modules/ai/types.ts` | 服务端 AI 服务接口（chat/suggestSimilarQuestions/suggestGrading/generateLessonContent/generateQuestionVariant/analyzeWeakness） |
+| **Server Actions** | `generateChildSummaryAction` | `modules/ai/actions.ts` | 家长学情摘要（权限：AI_CHAT）— V2 新增 |
+| **Server Actions** | `recommendStudyPathAction` | `modules/ai/actions.ts` | 学习路径推荐（权限：AI_CHAT）— V2 新增 |
+| **Server Actions** | `getAiUsageStatsAction` | `modules/ai/actions.ts` | AI 使用统计（权限：AI_CONFIGURE）— V2 新增 |
+| **SSE Route** | `POST /api/ai/chat/stream` | `app/api/ai/chat/stream/route.ts` | 流式 AI 对话（SSE）— V2 新增 |
+| **Service** | `AiService` | `modules/ai/types.ts` | 服务端 AI 服务接口（含 8 个方法） |
 | **Service** | `AiClientService` | `modules/ai/types.ts` | 客户端 AI 服务接口（Server Action 引用集合） |
 | **Provider** | `AiClientProvider` | `modules/ai/context/ai-client-provider.tsx` | React Context Provider，注入 AiClientService |
 | **Hook** | `useAiClient` | `modules/ai/context/ai-client-provider.tsx` | 消费 AiClientService（必须在 Provider 内使用） |
 | **Hook** | `useAiClientOptional` | `modules/ai/context/ai-client-provider.tsx` | 可选消费 AiClientService（未注入返回 null） |
+| **Hook** | `useAiChatStream` | `modules/ai/hooks/use-ai-chat-stream.ts` | 流式 AI 对话 Hook（SSE + AbortController）— V2 新增 |
+| **Hook** | `useAiChat` | `modules/ai/hooks/use-ai-chat.ts` | 非流式 AI 对话 Hook |
+| **Hook** | `useAiSuggestion` | `modules/ai/hooks/use-ai-suggestion.ts` | AI 建议 Hook |
+| **Component** | `AiAssistantWidget` | `modules/ai/components/ai-assistant-widget.tsx` | 全局 AI 助手悬浮按钮（上下文感知）— V2 新增 |
+| **Component** | `AiChatPanel` | `modules/ai/components/ai-chat-panel.tsx` | AI 对话面板（流式 + Markdown + 复制 + 停止 + 建议）— V2 增强 |
+| **Component** | `AiMarkdownRenderer` | `modules/ai/components/ai-markdown-renderer.tsx` | Markdown 渲染器（GFM + 复制按钮）— V2 新增 |
 | **Component** | `AiGradingAssist` | `modules/ai/components/ai-grading-assist.tsx` | AI 批改辅助（主观题预评分 + 反馈建议） |
 | **Component** | `AiErrorBookAnalysis` | `modules/ai/components/ai-error-book-analysis.tsx` | 错题本 AI 分析（相似题 + 薄弱点） |
 | **Component** | `AiLessonContentGenerator` | `modules/ai/components/ai-lesson-content-generator.tsx` | 备课内容生成器（活动/评估/讨论题/素材） |
 | **Component** | `AiQuestionVariantGenerator` | `modules/ai/components/ai-question-variant-generator.tsx` | 题目变体生成器（同知识点/不同难度/不同题型） |
-| **Component** | `AiChatPanel` | `modules/ai/components/ai-chat-panel.tsx` | AI 对话面板 |
+| **Component** | `AiChildSummary` | `modules/ai/components/ai-child-summary.tsx` | 家长 AI 学情摘要 — V2 新增 |
+| **Component** | `AiUsageDashboard` | `modules/ai/components/ai-usage-dashboard.tsx` | 管理员 AI 使用统计仪表盘 — V2 新增 |
+| **Component** | `AiStudyPath` | `modules/ai/components/ai-study-path.tsx` | 学生学习路径推荐 — V2 新增 |
 | **Component** | `AiErrorBoundary` | `modules/ai/components/ai-error-boundary.tsx` | AI 功能错误边界 |
 | **Component** | `AiSuggestionSkeleton` | `modules/ai/components/ai-skeleton.tsx` | AI 建议加载骨架屏 |
 | **Component** | `AiProviderSelector` | `modules/ai/components/ai-provider-selector.tsx` | AI 服务商选择器 |
+| **Safety** | `filterUserInput` | `modules/ai/services/content-safety.ts` | 输入安全过滤 — V2 新增 |
+| **Safety** | `filterAiOutput` | `modules/ai/services/content-safety.ts` | 输出安全过滤 — V2 新增 |
+| **Safety** | `checkDailyLimit` | `modules/ai/services/content-safety.ts` | 每日交互限制 — V2 新增 |

 **集成点**：

@@ -1937,41 +1971,62 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 | error-book | `AiErrorBookAnalysis` | `student/error-book` | 相似题推荐 + 薄弱点分析 |
 | lesson-preparation | `AiLessonContentGenerator` | `teacher/lesson-plans/[planId]/edit` | 备课内容生成 |
 | exams | `AiQuestionVariantGenerator` | `teacher/exams/[id]/build` | 题目变体生成 |
+| **全局** | `AiAssistantWidget` | `app/(dashboard)/layout.tsx` | 全局 AI 助手悬浮按钮（所有页面）— V2 新增 |
+| **parent** | `AiChildSummary` | `parent/*` | 家长学情 AI 摘要 — V2 新增 |
+| **admin** | `AiUsageDashboard` | `admin/*` | AI 使用统计仪表盘 — V2 新增 |
+| **student** | `AiStudyPath` | `student/*` | 学习路径推荐 — V2 新增 |

 **依赖关系**：
- `modules/ai` → `shared/lib/ai`（AI SDK 封装）
+- `modules/ai` → `shared/lib/ai`（AI SDK 封装，含流式 `createAiChatCompletionStream`）
 - `modules/ai` → `shared/lib/auth-guard`（权限校验）
+- `modules/ai` → `shared/lib/track-event`（使用量埋点）
 - `modules/ai` → `shared/types/permissions`（权限常量）
 - `modules/ai` → `shared/types/action-state`（返回值类型）
+- `app/(dashboard)/layout` → `modules/ai`（全局 Provider + Widget）— V2 新增
 - 业务模块 → `modules/ai/context/ai-client-provider`（通过 Context 注入）
 - 业务模块 → `modules/ai/components/*`（组合 AI 组件）

+**安全机制（V2 新增）**：
+- 输入过滤：`filterUserInput` 拦截暴力/自残/色情/PII
+- 输出过滤：`filterAiOutput` 扫描 AI 回复
+- 每日限制：学生 50 次/天，教师 200 次/天，家长 30 次/天
+- 学生 Socratic 模式：system prompt 强制不直接给答案
+- SSE 端点权限校验：`requirePermission(AI_CHAT)`
+
 **文件清单**：

 | 文件 | 行数 | 职责 |
 |------|------|------|
-| `modules/ai/types.ts` | 194 | 类型定义（AiService/AiClientService/业务场景类型） |
-| `modules/ai/schema.ts` | - | Zod 验证 schema |
-| `modules/ai/actions.ts` | 244 | 6 个 Server Actions（含权限校验） |
-| `modules/ai/services/ai-service.ts` | - | DefaultAiService 实现 |
-| `modules/ai/services/prompt-templates.ts` | - | 6 个系统提示词模板 |
-| `modules/ai/services/usage-tracker.ts` | - | AI 使用量埋点 |
-| `modules/ai/context/ai-client-provider.tsx` | 59 | React Context Provider + Hooks |
+| `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/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 增强 |
+| `modules/ai/components/ai-markdown-renderer.tsx` | ~100 | Markdown 渲染器 — V2 新增 |
+| `modules/ai/components/ai-child-summary.tsx` | ~170 | 家长学情摘要 — V2 新增 |
+| `modules/ai/components/ai-usage-dashboard.tsx` | ~180 | 管理员使用统计 — V2 新增 |
+| `modules/ai/components/ai-study-path.tsx` | ~170 | 学生学习路径 — V2 新增 |
 | `modules/ai/components/ai-grading-assist.tsx` | 173 | AI 批改辅助组件 |
 | `modules/ai/components/ai-error-book-analysis.tsx` | 246 | 错题本 AI 分析组件 |
-| `modules/ai/components/ai-lesson-content-generator.tsx` | - | 备课内容生成器 |
-| `modules/ai/components/ai-question-variant-generator.tsx` | - | 题目变体生成器 |
-| `modules/ai/components/ai-chat-panel.tsx` | - | AI 对话面板 |
-| `modules/ai/components/ai-error-boundary.tsx` | - | AI 错误边界 |
-| `modules/ai/components/ai-skeleton.tsx` | - | AI 骨架屏 |
-| `modules/ai/components/ai-provider-selector.tsx` | - | 服务商选择器 |
-| `modules/ai/hooks/use-ai-chat.ts` | - | AI 对话 Hook |
-| `modules/ai/hooks/use-ai-suggestion.ts` | - | AI 建议 Hook |
+| `modules/ai/components/ai-lesson-content-generator.tsx` | ~187 | 备课内容生成器 |
+| `modules/ai/components/ai-question-variant-generator.tsx` | ~208 | 题目变体生成器 |
+| `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.ts` | ~57 | 非流式 AI 对话 Hook |
+| `modules/ai/hooks/use-ai-suggestion.ts` | ~72 | AI 建议 Hook |
+| `app/api/ai/chat/stream/route.ts` | ~160 | SSE 流式端点 — V2 新增 |

 **i18n**：
 - 翻译文件：`shared/i18n/messages/{locale}/ai.json`
 - 命名空间：`ai`
- 包含：chat/provider/suggestion/grading/errorBook/lessonPrep/exam/error/capability
+- V2 新增键：`chat.streaming/stopGeneration/copy/clearConfirm/suggestedPrompts`、`grading.description/batch*`、`lessonPrep.description/additionalContext/insertContent`、`exam.variantType.*/targetDifficulty/addVariant`、`parent.*`、`admin.*`、`studyPath.*`、`widget.*`、`safety.*`

 ---

@@ -2240,6 +2295,82 @@ shared/lib/{audit-logger, change-logger, auth-guard} → @/auth → shared/lib/*

 ---

+## 3.6 教师端全模块审计修复（2026-06-23）
+
+> 本次审计修复覆盖教师端 13 个模块组、约 80+ 个文件，聚焦越权访问漏洞、错误处理一致性、类型安全与 React 性能。以下仅记录涉及架构图同步的变更（函数签名/导出/新增文件），其余纯实现修复（如 try/catch 补齐、useMemo/useCallback、key prop、as 断言清理）不在此列出。
+
+### 3.6.1 新增共享文件 `src/shared/lib/action-utils.ts`
+
+统一 Server Action 错误处理与客户端 Action 调用模式，避免内部错误消息暴露给客户端。
+
+| 导出 | 类型 | 签名 | 用途 |
+|------|------|------|------|
+| `handleActionError` | function | `(e: unknown) => ActionState<never>` | 统一 Server Action catch 块错误处理：PermissionDeniedError/BusinessError 返回其 message，其他 Error 返回通用消息并 console.error 记录 |
+| `safeActionCall` | function | `<T>(action: () => Promise<ActionState<T>>, options?: { onError?, onFinally? }) => Promise<ActionState<T> \| null>` | 客户端调用 Server Action 的 try/catch/finally 包装器，防止 UI 永久卡 loading |
+| `safeJsonParse` | function | `<T>(json: string, errorMessage: string) => T` | 安全 JSON.parse，失败抛 ValidationError（替代裸 JSON.parse） |
+| `safeParseDate` | function | `(value: string, fieldName: string) => Date` | 校验日期字符串有效性，无效抛 ValidationError |
+| `safeParseNumber` | function | `(value: string, fieldName: string) => number` | 校验数字字符串，无效抛 ValidationError |
+| `escapeLikePattern` | function | `(input: string) => string` | 转义 SQL LIKE 通配符（% _ \\），防止用户输入干扰模糊查询 |
+| `BusinessError` | class | `extends Error` | 已知业务错误基类，message 可安全返回客户端（含可选 code） |
+| `NotFoundError` | class | `extends BusinessError` | 资源不存在错误（自动生成 `${resource} 不存在` 消息，code: not_found） |
+| `ValidationError` | class | `extends BusinessError` | 输入校验错误（code: validation_error） |
+
+### 3.6.2 grades 模块签名变更
+
+**data-access 层新增 scope 参数**（P3 修复：所有查询函数应用 `buildScopeClassFilter` 进行行级 scope 过滤）：
+
+| 函数 | 文件 | 旧签名 | 新签名 |
+|------|------|--------|--------|
+| `getGradeRecords` | `data-access.ts` | `(params: GradeQueryParams) => Promise<GradeRecordListItem[]>` | `(params: GradeQueryParams & { scope: DataScope; currentUserId?: string; limit?: number; offset?: number }) => Promise<PaginatedGradeRecords>` |
+| `getClassGradeStats` | `data-access.ts` | `(classId, subjectId?, examId?) => Promise<GradeStats>` | `(classId, subjectId?, examId?, scope?: DataScope, currentUserId?: string) => Promise<GradeStats \| null>` |
+| `getStudentGradeSummary` | `data-access.ts` | `(studentId) => Promise<StudentGradeSummary>` | `(studentId, scope?: DataScope) => Promise<StudentGradeSummary \| null>`（class_taught scope 校验学生归属） |
+| `getClassRanking` | `data-access.ts` | `(classId, subjectId?, examId?) => Promise<ClassRankingItem[]>` | `(classId, subjectId?, examId?, scope?: DataScope, currentUserId?: string) => Promise<ClassRankingItem[]>`（含并列排名处理） |
+| `getClassStudentsForEntry` | `data-access.ts` | `(classId) => Promise<{id,name}[]>` | `(classId, scope?: DataScope) => Promise<{id,name,email}[]>`（class_taught scope 校验 classId） |
+| `getRankingTrend` | `data-access-ranking.ts` | `(studentId, subjectId?, semester?) => Promise<RankingTrendResult \| null>` | `(studentId, subjectId?, semester?, scope?: DataScope) => Promise<RankingTrendResult \| null>`（class_taught scope 校验） |
+
+**lib 层签名变更**：
+- `buildScopeClassFilter(scope: DataScope, currentUserId?: string): SQL | null`（新增 `currentUserId` 参数，`class_members` scope 内置 `eq(gradeRecords.studentId, currentUserId)` 过滤）
+
+**新增导出**：
+- `assertClassInScope(scope: DataScope, classId: string): string | null`（`actions.ts`，校验 classId 是否在 scope 允许范围内，供 actions.ts 与 actions-analytics.ts 复用）
+- `PaginatedGradeRecords` 接口（`data-access.ts`，`{ records: GradeRecordListItem[]; total: number }`，配合 DB 层分页）
+
+### 3.6.3 homework 模块签名变更
+
+**data-access 层新增 scope 参数**（P3 修复：教师仅查看自己创建的作业，学生/家长仅查看相关作业）：
+
+| 函数 | 文件 | 新签名 |
+|------|------|--------|
+| `getHomeworkAssignments` | `data-access.ts` | `(params?: { creatorId?, ids?, classId?, scope?: DataScope }) => Promise<HomeworkAssignmentListItem[]>` |
+| `getHomeworkAssignmentById` | `data-access.ts` | `(id: string, scope?: DataScope) => Promise<HomeworkAssignmentListItem \| null>` |
+| `getHomeworkSubmissions` | `data-access.ts` | `(params?: { assignmentId?, classId?, creatorId?, scope?: DataScope }) => Promise<HomeworkSubmissionListItem[]>` |
+| `getHomeworkAssignmentReviewList` | `data-access.ts` | `(params: { creatorId: string; scope?: DataScope }) => Promise<HomeworkReviewListItem[]>` |
+
+### 3.6.4 lesson-preparation 模块变更
+
+**新增 Zod schema**（`schema.ts`）：
+- `publishLessonPlanHomeworkSchema`：发布作业输入校验（planId/blockId 必填，classIds 至少 1 个，availableAt/dueAt 日期格式校验）
+- 导出类型 `PublishLessonPlanHomeworkInput = z.infer<typeof publishLessonPlanHomeworkSchema>`
+
+**data-access-versions.ts 事务变更**：
+- `revertToVersion` 包裹 `db.transaction` 确保原子性（回滚版本时同步更新 lessonPlans.content 与版本记录）
+- `createLessonPlanVersion` 已使用 `db.transaction`（版本号自增 + 插入版本记录原子化）
+
+### 3.6.5 其他修复（不涉及签名变更，仅记录范围）
+
+- 越权访问修复：15+ 处页面添加 `requirePermission`，data-access 层添加 scope 过滤
+- 功能性 BUG 修复：question-actions 删除字段名、question-columns 时间显示、textbook-card 删除按钮、block-renderer 拖拽
+- 统一错误处理：所有 Server Action catch 块改用 `handleActionError`
+- 客户端 Action 调用添加 try/catch/finally（20+ 处，使用 `safeActionCall`）
+- `JSON.parse` 改用 `safeJsonParse`（8+ 处）
+- Date 解析添加校验（15+ 处，使用 `safeParseDate`）
+- 数据库事务添加：`batchCreateGradeRecords`、`deleteChapter`、`revertToVersion`
+- 性能优化：`Promise.all` 并行化、DB 层分页（grades `getGradeRecords`）
+- TypeScript `as` 断言清理（30+ 处，改用类型守卫）
+- React 性能修复：`useMemo`、`useCallback`、`key` prop、渲染期间副作用移除
+
+---
+
 # 附录 A：模块间依赖矩阵

 > 行表示使用方，列表示被使用方。`✅` 合理依赖，`❌` 违规直查，`⟳` 循环依赖。
--- a/docs/architecture/005_architecture_data.json
+++ b/docs/architecture/005_architecture_data.json
--- a/docs/architecture/audit/ai-module-audit-report-v2.md
+++ b/docs/architecture/audit/ai-module-audit-report-v2.md
@@ -0,0 +1,508 @@
+# AI 模块审计报告 V2 — 深度可用性分析与行业对标
+
+> 审计范围：基于 V1 审计报告（`ai-module-audit-report.md`）已完成的实现，进行第二轮深度审计。
+> 审计日期：2026-06-23
+> 审计方法：逐组件可用性走查 + 行业标杆对标（Khanmigo / Duolingo Max / Squirrel AI / Century Tech）+ 多角色用户旅程分析
+> 审计依据：`docs/standards/coding-standards.md`、`docs/architecture/004_architecture_impact_map.md`、行业研究
+
+---
+
+## 一、V1 完成度回顾
+
+### 1.1 已完成项
+
+| 编号 | V1 改进项 | 状态 | 实现位置 |
+|------|----------|------|---------|
+| P0-1 | AI 聊天端点权限校验 | ✅ | [actions.ts](file:///e:/Desktop/CICD/src/modules/ai/actions.ts) `aiChatAction` |
+| P0-2 | AI 独立模块 | ✅ | `src/modules/ai/` 完整结构 |
+| P0-3 | exam-ai-generator i18n | ✅ | [exam-ai-generator.tsx](file:///e:/Desktop/CICD/src/modules/exams/components/exam-ai-generator.tsx) |
+| P0-4 | AI 管线错误消息 i18n | ✅ | [request.ts](file:///e:/Desktop/CICD/src/modules/exams/ai-pipeline/request.ts) |
+| P0-5 | ai-suggest.ts 类型安全 | ✅ | [ai-suggest.ts](file:///e:/Desktop/CICD/src/modules/lesson-preparation/ai-suggest.ts) |
+| P1-1 | AiService 接口抽象 | ✅ | [types.ts](file:///e:/Desktop/CICD/src/modules/ai/types.ts) |
+| P1-2 | 可复用 AI 组件 | ✅ | 9 个组件 |
+| P1-3 | AI Error Boundary | ✅ | [ai-error-boundary.tsx](file:///e:/Desktop/CICD/src/modules/ai/components/ai-error-boundary.tsx) |
+| P1-4 | 错题集 AI 集成 | ✅ | [ai-error-book-analysis.tsx](file:///e:/Desktop/CICD/src/modules/ai/components/ai-error-book-analysis.tsx) |
+| P1-5 | 改题 AI 集成 | ✅ | [ai-grading-assist.tsx](file:///e:/Desktop/CICD/src/modules/ai/components/ai-grading-assist.tsx) |
+| P1-6 | AI 使用监控 | ✅ | [usage-tracker.ts](file:///e:/Desktop/CICD/src/modules/ai/services/usage-tracker.ts) |
+| P1-7 | 备课 AI 内容生成 | ✅ | [ai-lesson-content-generator.tsx](file:///e:/Desktop/CICD/src/modules/ai/components/ai-lesson-content-generator.tsx) |
+| P2-4 | 题目变体生成 | ✅ | [ai-question-variant-generator.tsx](file:///e:/Desktop/CICD/src/modules/ai/components/ai-question-variant-generator.tsx) |
+| P2-7 | 架构图同步 | ✅ | 004/005 文档 |
+
+### 1.2 未完成项（V2 重点）
+
+| 编号 | V1 改进项 | 状态 | 原因 |
+|------|----------|------|------|
+| P2-1 | 流式响应 | ❌ | V1 仅实现非流式 |
+| P2-2 | AI 对话历史 | ❌ | 未持久化 |
+| P2-3 | Prompt 可配置化 | ⚠️ | 模板已抽取但仍硬编码在 TS 文件中 |
+| P2-5 | 多 Provider 对比 | ❌ | 未实现 |
+| P2-6 | 内容安全过滤 | ❌ | 未实现 |
+
+---
+
+## 二、深度可用性走查（逐组件）
+
+### 2.1 AiChatPanel — 通用聊天面板
+
+**文件**：[ai-chat-panel.tsx](file:///e:/Desktop/CICD/src/modules/ai/components/ai-chat-panel.tsx)
+
+| 编号 | 问题 | 严重度 | 位置 | 行业对标 | 用户影响 |
+|------|------|--------|------|---------|---------|
+| U2.1.1 | **无流式响应** — 用户等待完整 AI 回复才看到内容 | P0 | L77-96 | Khanmigo/Duolingo 均使用 SSE 流式输出，逐 token 渲染 | 长文本（>500 字）等待 10-30 秒，用户以为卡死 |
+| U2.1.2 | **无 Markdown 渲染** — AI 回复以纯文本显示 | P0 | L139 | 所有主流 AI 产品均渲染 Markdown（代码块、列表、表格） | AI 生成的代码、表格、列表无法正确显示，可读性极差 |
+| U2.1.3 | **无复制按钮** — 用户无法复制 AI 回复 | P1 | L132-141 | ChatGPT/Claude 均提供 hover 复制按钮 | 教师想复用 AI 生成的内容需手动选择文本 |
+| U2.1.4 | **无停止生成按钮** — 流式时无法中断 | P1 | — | Khanmigo 明确将 stop-generation 列为 K12 必备 | AI 生成不当内容时无法及时止损 |
+| U2.1.5 | **无建议提示词** — 空状态无引导 | P1 | L119 | Khanmigo 首屏展示"试试问我..."建议 | 新用户不知道能问什么，首次使用门槛高 |
+| U2.1.6 | **无清除对话按钮** — i18n 键 `chat.clear` 存在但无 UI | P1 | — | 所有聊天产品均有清空按钮 | 对话越来越长，上下文窗口爆满后 AI 回复质量下降 |
+| U2.1.7 | **无对话历史持久化** — 刷新页面对话丢失 | P1 | L44 | Khanmigo 提供 chat history 面板 | 教师备课时生成的 AI 内容刷新即丢失 |
+| U2.1.8 | **无 token/模型指示器** — 用户不知道用了哪个模型 | P2 | — | OpenAI PlayGround 显示模型与 token 用量 | 无法评估 AI 调用成本 |
+| U2.1.9 | **aria-live 缺失** — 屏幕阅读器无法感知新消息 | P1 | L121 | WCAG 2.1 AA 要求 | 视障用户无法使用 |
+
+### 2.2 AiGradingAssist — 批改辅助
+
+**文件**：[ai-grading-assist.tsx](file:///e:/Desktop/CICD/src/modules/ai/components/ai-grading-assist.tsx)
+
+| 编号 | 问题 | 严重度 | 位置 | 行业对标 | 用户影响 |
+|------|------|--------|------|---------|---------|
+| U2.2.1 | **CardDescription 与 CardTitle 使用相同 i18n 键** | P0 | L97 `t("grading.title")` | — | 描述区域显示重复文字，UI 不专业 |
+| U2.2.2 | **无批量批改** — 一次只能批改一题 | P1 | — | Khanmigo 的 student work summary 支持批量 | 教师批改 30 人 × 5 道主观题 = 150 次点击 |
+| U2.2.3 | **无分数对比** — 不显示教师已给分数 vs AI 建议 | P1 | — | — | 教师无法快速判断 AI 建议是否合理 |
+| U2.2.4 | **无置信度阈值配置** — 低置信度建议也直接展示 | P2 | L87 | — | confidence < 0.5 的建议可能误导教师 |
+| U2.2.5 | **无 Socratic 模式** — 直接给分而非引导思考 | P2 | — | Khanmigo 的 Socratic 方法不直接给答案 | 教师过度依赖 AI，丧失独立判断 |
+
+### 2.3 AiErrorBookAnalysis — 错题本分析
+
+**文件**：[ai-error-book-analysis.tsx](file:///e:/Desktop/CICD/src/modules/ai/components/ai-error-book-analysis.tsx)
+
+| 编号 | 问题 | 严重度 | 位置 | 行业对标 | 用户影响 |
+|------|------|--------|------|---------|---------|
+| U2.3.1 | **无"立即练习"按钮** — 相似题生成后只能"选择" | P0 | L150-159 | Duolingo Max 的 "Explain My Answer" 后直接进入练习 | 学生看到相似题但无法直接作答，流程断裂 |
+| U2.3.2 | **薄弱点分析不持久化** — 刷新即丢失 | P1 | L59 | Squirrel AI 持续追踪薄弱点变化趋势 | 无法追踪薄弱点改善进度 |
+| U2.3.3 | **无 SM2 算法集成** — AI 相似题不进入复习队列 | P1 | — | Squirrel AI 的闭环：诊断→练习→复习→再诊断 | AI 生成的相似题是一次性的，无法形成学习闭环 |
+| U2.3.4 | **无趋势可视化** — 薄弱点无历史趋势图 | P2 | — | Century Tech 的 dashboard 展示 mastery 进展 | 学生/家长无法看到进步 |
+| U2.3.5 | **无难度递进** — 相似题难度不随掌握度调整 | P2 | L69 `count: 3` | Squirrel AI 的自适应难度 | 掌握度高的学生仍收到简单题，浪费时间 |
+
+### 2.4 AiLessonContentGenerator — 备课内容生成
+
+**文件**：[ai-lesson-content-generator.tsx](file:///e:/Desktop/CICD/src/modules/ai/components/ai-lesson-content-generator.tsx)
+
+| 编号 | 问题 | 严重度 | 位置 | 行业对标 | 用户影响 |
+|------|------|--------|------|---------|---------|
+| U2.4.1 | **CardDescription 与 CardTitle 使用相同 i18n 键** | P0 | L108 `t("lessonPrep.generateContent")` | — | 描述区域重复 |
+| U2.4.2 | **附加上下文 label 使用错误键** | P0 | L131 `t("lessonPrep.generateContent")` | — | 标签显示"生成内容"而非"附加上下文" |
+| U2.4.3 | **placeholder 使用错误键** | P0 | L137 `t("lessonPrep.generateContent")` | — | 占位符显示"生成内容" |
+| U2.4.4 | **插入按钮使用错误键** | P0 | L178 `t("lessonPrep.generateContent")` | — | 按钮显示"生成内容"而非"插入内容" |
+| U2.4.5 | **无内容预览/编辑** — 生成后直接插入 | P1 | L168-180 | Khanmigo 生成的内容可编辑后再插入 | 教师无法微调 AI 生成的内容 |
+| U2.4.6 | **无生成历史** — 无法回看之前生成的内容 | P1 | — | Khanmigo 的 chat history | 教师生成了 5 段内容，只能保留最后 1 段 |
+| U2.4.7 | **无课程标准对齐** — 生成内容不关联课标 | P2 | — | Khanmigo 与课程标准对齐 | 生成内容可能偏离教学大纲 |
+
+### 2.5 AiQuestionVariantGenerator — 题目变体生成
+
+**文件**：[ai-question-variant-generator.tsx](file:///e:/Desktop/CICD/src/modules/ai/components/ai-question-variant-generator.tsx)
+
+| 编号 | 问题 | 严重度 | 位置 | 行业对标 | 用户影响 |
+|------|------|--------|------|---------|---------|
+| U2.5.1 | **所有变体类型标签使用相同 i18n 键** | P0 | L87-89 全部 `t("exam.generate")` | — | 三个选项显示相同文字"生成"，无法区分 |
+| U2.5.2 | **无批量生成** — 一次只生成 1 个变体 | P1 | — | — | 教师需要 5 个变体需点击 5 次 |
+| U2.5.3 | **无难度滑块** — different_difficulty 无法指定目标难度 | P1 | — | — | 教师无法控制变简单还是变难 |
+| U2.5.4 | **无知识点映射展示** — 不显示变体覆盖的知识点 | P2 | — | Squirrel AI 的知识图谱可视化 | 教师无法验证变体是否覆盖目标知识点 |
+
+### 2.6 AiSuggestionCard — 相似题建议卡片
+
+**文件**：[ai-suggestion-card.tsx](file:///e:/Desktop/CICD/src/modules/ai/components/ai-suggestion-card.tsx)
+
+| 编号 | 问题 | 严重度 | 位置 | 行业对标 | 用户影响 |
+|------|------|--------|------|---------|---------|
+| U2.6.1 | **无难度筛选** — 所有难度混合展示 | P2 | — | — | 学生只想练习中等难度题时无法筛选 |
+| U2.6.2 | **无"全部添加"按钮** — 需逐题选择 | P2 | — | — | 批量添加效率低 |
+
+### 2.7 全局架构层面
+
+| 编号 | 问题 | 严重度 | 行业对标 | 用户影响 |
+|------|------|--------|---------|---------|
+| U2.7.1 | **无全局 AI 助手入口** | P0 | Khanmigo 嵌入式助手 / Duolingo 角色触发 | 用户在非集成页面无法获取 AI 帮助 |
+| U2.7.2 | **无上下文感知** | P0 | Khanmigo 自动感知当前学习内容 | AI 不知道用户当前在做什么，建议不精准 |
+| U2.7.3 | **无内容安全过滤** | P0 | Khanmigo 多层 moderation + Duolingo 人工审核 | 学生可能接触不当内容，违反 COPPA/FERPA |
+| U2.7.4 | **无家长 AI 功能** | P1 | Khanmigo 家长可见聊天记录 / Squirrel AI 24/7 家长面板 | 家长无法获取子女学情 AI 摘要 |
+| U2.7.5 | **无管理员 AI 仪表盘** | P1 | Khanmigo district dashboard / Century Tech 全校视图 | 管理员无法监控 AI 使用量与成本 |
+| U2.7.6 | **无学生学习路径** | P1 | Squirrel AI 纳米级知识图谱 / Century Tech nuggets | 学生缺少个性化学习引导 |
+| U2.7.7 | **无每日交互限制** | P1 | Khanmigo 每日上限防止滥用 | 学生可能过度使用 AI 聊天偏离学习 |
+
+---
+
+## 三、行业标杆对标
+
+### 3.1 竞品功能矩阵
+
+| 能力 | Khanmigo | Duolingo Max | Squirrel AI | Century Tech | 本系统 V1 | 本系统 V2 目标 |
+|------|----------|-------------|-------------|-------------|----------|--------------|
+| **流式输出** | ✅ SSE | ✅ SSE | ✅ | ✅ | ❌ | ✅ |
+| **Markdown 渲染** | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ |
+| **Socratic 模式** | ✅ 不直接给答案 | — | — | — | ❌ | ✅ |
+| **内容安全过滤** | ✅ 多层 moderation | ✅ 人工+AI | ✅ 物理中心 | ✅ 教师监督 | ❌ | ✅ |
+| **对话历史** | ✅ 可查看 | ✅ | ✅ | ✅ | ❌ | ✅ |
+| **全局助手入口** | ✅ 嵌入式 | ✅ 角色触发 | ✅ 平台级 | ✅ Dashboard | ❌ | ✅ |
+| **上下文感知** | ✅ 内容库集成 | ✅ 课程对齐 | ✅ 诊断驱动 | ✅ 自适应 | ❌ | ✅ |
+| **学习路径推荐** | — | — | ✅ 纳米级 | ✅ nuggets | ❌ | ✅ |
+| **家长面板** | ✅ 聊天记录可见 | — | ✅ 24/7 分析 | — | ❌ | ✅ |
+| **管理员仪表盘** | ✅ district | — | ✅ | ✅ 全校 | ❌ | ✅ |
+| **每日限制** | ✅ | — | — | — | ❌ | ✅ |
+| **停止生成** | ✅ | ✅ | — | — | ❌ | ✅ |
+| **批量批改** | ✅ student summary | — | — | ✅ 自标记 | ❌ | ✅ |
+| **自适应难度** | — | ✅ | ✅ 核心 | ✅ | ❌ | ✅ |
+
+### 3.2 关键差距分析
+
+#### 差距 1：无流式响应（影响所有 AI 交互）
+
+**行业做法**：
+- Khanmigo 和 Duolingo Max 均使用 SSE 流式输出
+- 逐 token 渲染模拟"打字效果"，降低感知延迟
+- 配合"停止生成"按钮，让用户可控
+
+**我们的差距**：
+- 所有 AI 调用等待完整响应才返回
+- 长文本生成时用户看到的是空白 + loading spinner
+- 无法中断不当内容生成
+
+**影响**：用户体验差，长文本等待 10-30 秒，学生误以为系统卡死
+
+#### 差距 2：无内容安全过滤（影响学生侧）
+
+**行业做法**（Khanmigo 多层防护）：
+1. **输入过滤**：Moderation API 分类用户输入，拦截暴力/自残/色情/PII
+2. **输出过滤**：AI 回复展示前扫描
+3. **行为限制**：每日交互上限
+4. **透明审计**：所有聊天记录对家长/教师可见
+5. **自动告警**：moderation 触发时邮件通知成人
+6. **访问控制**：未成年人仅通过家长/学区订阅
+
+**我们的差距**：
+- 学生可直接调用 AI 聊天，无任何过滤
+- 无每日限制
+- 无聊天记录审计
+- 无不当内容告警
+
+**影响**：违反 COPPA/FERPA 合规要求；学生可能接触不当内容；学校无法审计 AI 使用
+
+#### 差距 3：无全局 AI 助手入口
+
+**行业做法**：
+- Khanmigo：嵌入式聊天集成在教师/学生 dashboard 中
+- Duolingo Max：角色图标触发（Lin, Eddy 等角色）
+- 通用模式：右下角悬浮按钮 → 侧边抽屉
+
+**我们的差距**：
+- AI 仅嵌入在 4 个特定页面（备课/错题/试卷/批改）
+- 用户在其他页面无法获取 AI 帮助
+- 无上下文感知（AI 不知道用户当前页面）
+
+**影响**：AI 使用率低；用户在需要时找不到 AI 入口
+
+#### 差距 4：无学习路径推荐
+
+**行业做法**：
+- Squirrel AI：纳米级知识分解（10,000+ 节点），诊断驱动路径
+- Century Tech：nuggets 微内容 + 自适应路径
+- 共同点：诊断 → 路径 → 练习 → 复习 → 再诊断的闭环
+
+**我们的差距**：
+- 错题本 AI 分析是一次性的，不持久化
+- AI 生成的相似题不进入 SM2 复习队列
+- 无知识图谱可视化
+- 无自适应难度
+
+**影响**：AI 价值未形成闭环；学生缺少个性化学习引导
+
+#### 差距 5：无家长/管理员 AI 功能
+
+**行业做法**：
+- Khanmigo：家长可查看子女聊天记录；学区管理员有 dashboard
+- Squirrel AI：24/7 家长分析面板
+- Century Tech：全校课程覆盖视图
+
+**我们的差距**：
+- 家长端无任何 AI 功能
+- 管理员无 AI 使用统计
+- 无成本监控
+
+**影响**：家长无法获取子女学情 AI 摘要；管理员无法优化 AI 使用策略
+
+---
+
+## 四、V2 改进优先级
+
+### P0（紧急 — 影响安全与核心体验）
+
+| 编号 | 改进项 | 对标 | 实现方向 |
+|------|--------|------|---------|
+| V2-P0-1 | **流式响应（SSE）** | Khanmigo/Duolingo | 新增 `aiChatStreamAction` + EventSource API + 停止生成按钮 |
+| V2-P0-2 | **Markdown 渲染** | 所有竞品 | 引入 `react-markdown` + `remark-gfm`，AI 回复渲染为富文本 |
+| V2-P0-3 | **内容安全过滤** | Khanmigo 多层防护 | 输入/输出双层过滤 + 每日限制 + 学生侧 Socratic 模式 |
+| V2-P0-4 | **全局 AI 助手悬浮按钮** | Khanmigo 嵌入式 | 右下角悬浮按钮 → 侧边抽屉，上下文感知 |
+| V2-P0-5 | **修复 i18n 键错误** | — | 修复 AiGradingAssist/AiLessonContentGenerator/AiQuestionVariantGenerator 中重复/错误键 |
+| V2-P0-6 | **复制按钮 + 清除对话** | ChatGPT/Claude | AiChatPanel 增加 hover 复制 + 清除对话按钮 |
+| V2-P0-7 | **建议提示词** | Khanmigo | 空状态展示角色相关的建议问题 |
+| V2-P0-8 | **aria-live 无障碍** | WCAG 2.1 AA | 消息列表添加 `aria-live="polite"` |
+
+### P1（重要 — 影响功能完整性）
+
+| 编号 | 改进项 | 对标 | 实现方向 |
+|------|--------|------|---------|
+| V2-P1-1 | **AI 对话历史持久化** | Khanmigo | localStorage 存储最近 20 条对话 + 历史面板 |
+| V2-P1-2 | **家长 AI 学情摘要** | Khanmigo 家长面板 / Squirrel AI | 新增 `AiChildSummary` 组件 + `generateChildSummaryAction` |
+| V2-P1-3 | **管理员 AI 使用统计** | Khanmigo district / Century Tech | 新增 `AiUsageDashboard` 组件 + `getAiUsageStatsAction` |
+| V2-P1-4 | **学生学习路径推荐** | Squirrel AI / Century Tech | 新增 `AiStudyPath` 组件 + `recommendStudyPathAction` |
+| V2-P1-5 | **错题相似题"立即练习"** | Duolingo Max | AiErrorBookAnalysis 增加"练习"按钮，进入答题流程 |
+| V2-P1-6 | **备课内容预览/编辑** | Khanmigo | AiLessonContentGenerator 生成后可编辑再插入 |
+| V2-P1-7 | **批量 AI 批改** | Khanmigo student summary | 新增 `AiBatchGradingAssist` 组件 |
+| V2-P1-8 | **每日交互限制** | Khanmigo | Server Action 层按用户+日期计数，超限返回 429 |
+
+### P2（优化 — 提升体验与扩展性）
+
+| 编号 | 改进项 | 对标 | 实现方向 |
+|------|--------|------|---------|
+| V2-P2-1 | **自适应难度** | Squirrel AI | 相似题难度根据 masteryLevel 动态调整 |
+| V2-P2-2 | **薄弱点趋势可视化** | Century Tech | 薄弱点历史趋势图 |
+| V2-P2-3 | **知识点映射展示** | Squirrel AI 知识图谱 | 变体生成后展示覆盖的知识点 |
+| V2-P2-4 | **多 Provider 对比** | — | 同一 Prompt 并行调用多 Provider |
+| V2-P2-5 | **Prompt 可配置化** | — | Prompt 模板存入数据库，支持版本管理 |
+| V2-P2-6 | **token/模型指示器** | OpenAI PlayGround | AiChatPanel 显示模型与 token 用量 |
+| V2-P2-7 | **Socratic 模式** | Khanmigo | 学生侧 AI 不直接给答案，引导思考 |
+
+---
+
+## 五、用户旅程分析（多角色）
+
+### 5.1 教师旅程
+
+**场景**：张老师要批改 30 名学生的语文主观题作业
+
+**当前流程（V1）**：
+1. 进入作业批改页 → 看到学生列表
+2. 点击学生 A → 看到主观题答案
+3. 点击"AI 批改建议" → 等待 5 秒 → 看到 AI 建议
+4. 点击"应用分数" → 点击"应用反馈"
+5. 点击下一个学生 → 重复 2-4
+6. **总计**：30 学生 × 3 题 × 4 次点击 = 360 次点击
+
+**行业最佳实践（Khanmigo）**：
+1. 进入批改页 → AI 自动扫描所有学生答案
+2. AI 批量生成评分建议（student work summary）
+3. 教师查看汇总，快速确认/调整
+4. **总计**：1 次批量生成 + 30 次确认 = 31 次点击
+
+**差距**：缺少批量批改能力，效率差 10 倍
+
+### 5.2 学生旅程
+
+**场景**：李同学做错了一道数学题，想针对性练习
+
+**当前流程（V1）**：
+1. 进入错题本 → 看到错题列表
+2. 点击错题 → 打开详情对话框
+3. 点击"AI 智能分析" → 等待 → 看到相似题
+4. 点击"选择" → 相似题... 然后呢？**流程断裂**
+5. 无法直接练习相似题
+
+**行业最佳实践（Duolingo Max）**：
+1. 做错题 → "Explain My Answer" 按钮
+2. AI 解释为什么错 → 直接进入"再练一题"
+3. 相似题难度自适应 → 形成学习闭环
+
+**差距**：相似题生成后无法直接练习，无自适应难度，无学习闭环
+
+### 5.3 家长旅程
+
+**场景**：王家长想了解子女近期学习情况
+
+**当前流程（V1）**：
+1. 进入家长 dashboard → 看到成绩/考勤
+2. **无任何 AI 功能**
+3. 需手动翻阅各科成绩自行分析
+
+**行业最佳实践（Squirrel AI）**：
+1. 家长面板 → AI 自动生成子女学情摘要
+2. AI 识别薄弱点 → 给出家庭辅导建议
+3. 24/7 可查看详细分析
+
+**差距**：家长端完全无 AI 能力
+
+### 5.4 管理员旅程
+
+**场景**：赵校长想了解全校 AI 使用情况
+
+**当前流程（V1）**：
+1. **无任何 AI 管理功能**
+2. 无法知道哪些教师在用 AI
+3. 无法知道 AI 成本
+4. 无法知道 AI 效果
+
+**行业最佳实践（Khanmigo district）**：
+1. 管理员 dashboard → AI 使用量趋势
+2. 按教师/学科/班级分解
+3. 成本统计 + 异常告警
+
+**差距**：管理员完全无 AI 可见性
+
+---
+
+## 六、V2 实现方案
+
+### 6.1 流式响应架构
+
+```
+客户端 (EventSource)
+  └─▶ POST /api/ai/chat/stream (SSE Route)
+        └─▶ aiChatStreamAction (Server Action)
+              └─▶ AiService.chatStream() (返回 AsyncGenerator)
+                    └─▶ createAiChatCompletionStream() (OpenAI SDK stream: true)
+```
+
+**关键设计**：
+- 使用 Server-Sent Events（SSE）而非 WebSocket（单向足够，更简单）
+- 客户端用 `fetch` + `ReadableStream` 消费（EventSource 不支持 POST）
+- 支持 `AbortController` 中断生成
+- 流式完成后 `withAiTracking` 记录完整 token 用量
+
+### 6.2 全局 AI 助手架构
+
+```
+app/(dashboard)/layout.tsx
+  └─▶ <AiAssistantWidget /> (全局悬浮按钮)
+        ├─▶ usePathname() 感知当前页面
+        ├─▶ 根据路由推断上下文（如 /teacher/homework → 批改上下文）
+        └─▶ 侧边抽屉 <AiChatPanel>
+              ├─▶ systemPrompt 根据上下文动态生成
+              └─▶ contextMessage 注入当前页面信息
+```
+
+**上下文感知规则**：
+| 路由模式 | 上下文 | systemPrompt |
+|---------|--------|-------------|
+| `/teacher/homework/*` | 作业批改 | "You are a grading assistant..." |
+| `/teacher/lesson-plans/*` | 备课 | "You are a lesson planning assistant..." |
+| `/teacher/exams/*` | 试卷 | "You are an exam design assistant..." |
+| `/student/error-book/*` | 错题本 | "You are a study tutor. Use Socratic method..." |
+| `/student/homework/*` | 做作业 | "You are a homework helper. Don't give direct answers..." |
+| `/parent/*` | 家长面板 | "You are a family education advisor..." |
+
+### 6.3 内容安全过滤架构
+
+```
+aiChatAction (Server Action)
+  ├─▶ 1. 输入过滤：filterUserInput(messages)
+  │      └─▶ 检查关键词/PII/不当内容 → 拦截返回错误
+  ├─▶ 2. 每日限制：checkDailyLimit(userId)
+  │      └─▶ 超限返回 429
+  ├─▶ 3. 调用 AI：service.chat()
+  ├─▶ 4. 输出过滤：filterAiOutput(content)
+  │      └─▶ 扫描不当内容 → 替换/拦截
+  └─▶ 5. 记录审计：logAiInteraction(userId, messages, response)
+```
+
+**学生侧额外限制**：
+- Socratic 模式：system prompt 强制不直接给答案
+- 每日上限：50 条消息（可配置）
+- 关键词过滤：暴力、自残、色情、PII
+
+### 6.4 i18n 新增键结构
+
+```json
+{
+  "chat": {
+    "streaming": "AI is typing...",
+    "stopGeneration": "Stop generating",
+    "copy": "Copy",
+    "copied": "Copied!",
+    "clearConfirm": "Clear all messages?",
+    "suggestedPrompts": {
+      "teacher": ["Help me grade this", "Generate a lesson activity", "Create a quiz question"],
+      "student": ["Explain this concept", "Give me a practice question", "Help me study"],
+      "parent": ["How is my child doing?", "What should I focus on at home?"],
+      "admin": ["Show AI usage stats", "Which teachers use AI most?"]
+    }
+  },
+  "safety": {
+    "blocked": "Your message was blocked by safety filter",
+    "dailyLimit": "Daily AI usage limit reached. Please try again tomorrow.",
+    "studentMode": "AI is in student mode. It will guide you to find the answer."
+  },
+  "parent": {
+    "summary": "AI Learning Summary",
+    "generateSummary": "Generate Summary",
+    "weaknessHint": "Areas to focus on",
+    "suggestion": "Family tutoring suggestion"
+  },
+  "admin": {
+    "usageDashboard": "AI Usage Dashboard",
+    "totalCalls": "Total AI Calls",
+    "activeUsers": "Active Users",
+    "costEstimate": "Estimated Cost",
+    "topUsers": "Top Users",
+    "byCapability": "By Capability"
+  },
+  "studyPath": {
+    "title": "Your Learning Path",
+    "nextSteps": "Recommended Next Steps",
+    "mastered": "Mastered",
+    "inProgress": "In Progress",
+    "needsWork": "Needs Work"
+  },
+  "lessonPrep": {
+    "additionalContext": "Additional context",
+    "additionalContextPlaceholder": "Add any specific requirements...",
+    "insertContent": "Insert Content",
+    "editBeforeInsert": "Edit before insert"
+  },
+  "exam": {
+    "variantType": {
+      "same_knowledge_point": "Same knowledge point, different context",
+      "different_difficulty": "Different difficulty",
+      "different_format": "Different format"
+    }
+  }
+}
+```
+
+---
+
+## 七、架构图同步说明
+
+V2 实现后需在 004/005 文档中新增以下节点：
+
+### 7.1 新增导出
+
+| 文档 | 节点 | 内容 |
+|------|------|------|
+| 005 | `modules.ai.exports.functions` | 新增 `aiChatStreamAction`、`generateChildSummaryAction`、`getAiUsageStatsAction`、`recommendStudyPathAction` |
+| 005 | `modules.ai.exports.components` | 新增 `AiAssistantWidget`、`AiMarkdownRenderer`、`AiChildSummary`、`AiUsageDashboard`、`AiStudyPath`、`AiBatchGradingAssist` |
+| 005 | `modules.ai.exports.services` | 新增 `filterUserInput`、`filterAiOutput`、`checkDailyLimit`、`logAiInteraction` |
+| 004 | AI 模块章节 | 新增 V2 组件清单与安全过滤说明 |
+
+### 7.2 新增路由
+
+| 文档 | 节点 | 内容 |
+|------|------|------|
+| 005 | `routes` | 新增 `/api/ai/chat/stream`（SSE 端点） |
+
+### 7.3 新增依赖
+
+| 文档 | 节点 | 内容 |
+|------|------|------|
+| 005 | `dependencyMatrix` | `parent → ai`、`dashboard → ai`（全局 widget） |
+
+---
+
+## 八、总结
+
+V1 完成了 AI 模块的基础架构与四大业务场景集成，但在**用户体验深度**、**安全合规**、**多角色覆盖**三个方面与行业标杆存在显著差距。
+
+V2 的核心目标是：
+1. **补齐流式 + Markdown + 安全过滤**三大基础体验
+2. **新增全局助手 + 上下文感知**提升 AI 可达性
+3. **覆盖家长 + 管理员**两个缺失角色
+4. **实现学习路径推荐**形成学习闭环
+5. **修复 i18n 键错误**消除 UI 缺陷
+
+实现后，AI 模块将达到 Khanmigo 级别的功能完整度，满足 K12 教育场景的安全合规要求。