NextEdu/docs/architecture/audit/archive/ai-module-deep-audit-report.md

AI 模块审计报告 V3 — 架构解耦与全角色对标

审计范围：基于 V1（ai-module-audit-report.md）与 V2（ai-module-audit-report-v2.md）已完成实现，进行第三轮深度架构审计。 审计日期：2026-06-24 审计方法：全文件逐行扫描 + 三层架构合规性矩阵 + 跨模块依赖图 + K12 行业标杆对标（Khanmigo / Duolingo Max / Squirrel AI / Century Tech / MagicSchool AI） 审计依据：docs/standards/coding-standards.md、docs/architecture/004_architecture_impact_map.md、docs/architecture/005_architecture_data.json、项目规则

---

一、现有实现概要

1.1 文件分布（30 个文件）

层	文件	行数	职责
types	modules/ai/types.ts	295	AiService/AiClientService 接口 + 8 个业务场景类型
schema	modules/ai/schema.ts	227	Zod 验证（8 输入 + 8 输出）
actions	modules/ai/actions.ts	381	9 个 Server Actions（含权限校验）
data-access	modules/ai/data-access.ts	138	AI 事件内存存储 + 统计聚合
services	modules/ai/services/ai-service.ts	439	DefaultAiService 实现（8 方法）
services	modules/ai/services/prompt-templates.ts	277	10 个系统提示词模板
services	modules/ai/services/usage-tracker.ts	99	AI 使用量埋点
services	modules/ai/services/content-safety.ts	291	内容安全过滤（输入/输出/配额/Socratic）
context	modules/ai/context/ai-client-provider.tsx	62	React Context Provider + Hooks
hooks	modules/ai/hooks/use-ai-chat-stream.ts	155	流式 AI 对话 Hook
hooks	modules/ai/hooks/use-ai-chat.ts	57	非流式 AI 对话 Hook
hooks	modules/ai/hooks/use-ai-suggestion.ts	72	AI 建议 Hook
hooks	modules/ai/hooks/use-floating-ball.ts	243	悬浮球拖拽 Hook
hooks	modules/ai/hooks/stream-utils.ts	135	SSE 流解析工具
components	modules/ai/components/ai-chat-panel.tsx	417	AI 对话面板
components	modules/ai/components/ai-assistant-widget.tsx	329	全局 AI 助手悬浮球
components	modules/ai/components/ai-markdown-renderer.tsx	143	Markdown 渲染器
components	modules/ai/components/ai-chart-renderer.tsx	329	图表渲染器
components	modules/ai/components/ai-error-boundary.tsx	88	AI 错误边界
components	modules/ai/components/ai-skeleton.tsx	47	骨架屏
components	modules/ai/components/ai-provider-selector.tsx	89	服务商选择器
components	modules/ai/components/ai-grading-assist.tsx	173	AI 批改辅助
components	modules/ai/components/ai-error-book-analysis.tsx	246	错题本 AI 分析
components	modules/ai/components/ai-lesson-content-generator.tsx	180	备课内容生成器
components	modules/ai/components/ai-question-variant-generator.tsx	218	题目变体生成器
components	modules/ai/components/ai-child-summary.tsx	186	家长学情摘要
components	modules/ai/components/ai-usage-dashboard.tsx	221	管理员使用统计
components	modules/ai/components/ai-study-path.tsx	200	学生学习路径
components	modules/ai/components/ai-suggestion-card.tsx	164	相似题建议卡片
api	app/api/ai/chat/route.ts	48	非流式聊天端点
api	app/api/ai/chat/stream/route.ts	237	SSE 流式端点

1.2 数据流

客户端组件
  └─▶ useAiClient() / useAiClientOptional()
        └─▶ AiClientProvider (app/layout.tsx 或子页面注入)
              └─▶ Server Actions (modules/ai/actions.ts)
                    └─▶ createAiService(userId) → DefaultAiService
                          └─▶ createAiChatCompletion (shared/lib/ai)
                                └─▶ OpenAI SDK + ai_providers 表

SSE 流式端点（独立路径）：
  app/api/ai/chat/stream/route.ts
    └─▶ requirePermission(AI_CHAT)
    └─▶ content-safety (filterUserInput / tryConsumeDailyQuota)
    └─▶ createAiChatCompletionStream (shared/lib/ai)
    └─▶ content-safety (filterAiOutput / validateSocraticOutput)

1.3 架构图记录情况

• 004_architecture_impact_map.md 第 2.29 节完整记录了 AI 模块（V2/V3/V4 变更）
• 005_architecture_data.json 包含 modules.ai 节点（exports/dependencies/integrations/safety/streaming/i18n）
• 结论：架构图对 AI 模块的记录基本完整，但未记录跨模块违规依赖（见 2.1.1）。

---

二、现存问题与原因分析

2.1 架构分层问题

问题 2.1.1：5 处跨模块直接依赖 shared/lib/ai（绕过 modules/ai）

• 位置：
  • ai-suggest.ts:5 — import { createAiChatCompletion } from "@/shared/lib/ai"
  • settings/actions.ts:14 — import { encryptAiApiKey, getAiErrorMessage, testAiProviderById, testAiProviderConfig } from "@/shared/lib/ai"
  • exams/actions.ts:987 — 动态 import("@/shared/lib/ai")
  • exams/ai-pipeline/request.ts:11 — import { createAiChatCompletion, getAiErrorMessage } from "@/shared/lib/ai"
  • exams/ai-pipeline/parse.ts:11 — import { createAiChatCompletion } from "@/shared/lib/ai"
• 原因：AI 模块在 V2 重构后才形成独立模块，但这些历史调用点未同步迁移。
• 后果：绕过 modules/ai 的内容安全过滤、每日配额、Socratic 模式、使用量埋点等保护机制；AI 调用无法统一治理。
• 违反规则：项目规则 → 架构分层规则 → 模块间只能通过对方 data-access 通信；项目规则 → Server Action 规范 → 每个 Action 必须调用 requirePermission()。

问题 2.1.2：非流式聊天端点绕过 modules/ai

• 位置：app/api/ai/chat/route.ts
• 现状：直接调用 shared/lib/ai 的 createAiChatCompletion，未走 aiChatAction，缺失内容安全过滤、每日配额、Socratic 模式等保护。
• 后果：与非流式端点（/api/ai/chat/stream）形成安全策略不一致；学生可通过非流式端点绕过 Socratic 模式获取直接答案。
• 违反规则：项目规则 → 安全规范；项目规则 → Server Action 规范。

问题 2.1.3：4 个子页面重复创建 AiClientService

• 位置：
  • teacher/lesson-plans/[planId]/edit/page.tsx
  • teacher/homework/submissions/[submissionId]/page.tsx
  • student/error-book/page.tsx
  • teacher/exams/[id]/build/page.tsx
• 现状：每个页面各自创建只含 6 个 Action 的 AiClientService，覆盖 layout.tsx 的全局 Provider（含 9 个 Action）。
• 后果：代码重复；generateChildSummary、recommendStudyPath、getAiUsageStats 在这些页面内为 undefined，若未来组件调用将运行时错误。
• 违反规则：项目规则 → 工程约定 → 最大化复用。

2.2 权限问题

问题 2.2.1：非流式聊天端点未走 requirePermission 体系

• 位置：app/api/ai/chat/route.ts
• 现状：虽然调用了 requirePermission(Permissions.AI_CHAT)，但绕过了 modules/ai/actions.ts 的 aiChatAction，导致内容安全过滤、每日配额、Socratic 模式等保护机制缺失。
• 后果：权限校验通过但安全策略不一致。
• 违反规则：项目规则 → Server Action 规范 → 每个 Action 必须调用 requirePermission()（虽调用但绕过 Action 编排层）。

2.3 国际化问题

问题 2.3.1：ai-chart-renderer.tsx 硬编码中文

• 位置：ai-chart-renderer.tsx:147
• 代码：图表数据格式错误，无法渲染
• 后果：无法切换语言。
• 违反规则：项目规则 → 所有用户可见文本必须适配 i18n。

问题 2.3.2：ai-assistant-widget.tsx systemPrompt 硬编码英文

• 位置：ai-assistant-widget.tsx:230-326
• 现状：inferContextFromPath 函数中所有 systemPrompt 和 contextMessage 为硬编码英文。
• 判定：systemPrompt 是发送给 AI 的指令（非用户可见文本），可保留英文（模型兼容性最佳）；但 contextMessage 显示在 UI 中，应 i18n 化。
• 后果：contextMessage 无法国际化。
• 违反规则：项目规则 → 所有用户可见文本必须适配 i18n。

2.4 类型安全问题

问题 2.4.1：ai-markdown-renderer.tsx 使用 as 断言

• 位置：ai-markdown-renderer.tsx:92
• 代码：lang.slice(CHART_LANG_PREFIX.length) as AiChartType
• 后果：若 lang 不在 AiChartType 枚举内，类型不安全。
• 违反规则：项目规则 → TypeScript 规则 → 禁止 as 断言。

问题 2.4.2：ai-provider-selector.tsx 使用 as 断言

• 位置：ai-provider-selector.tsx:66
• 代码：field.value as string
• 后果：react-hook-form 的 field.value 类型应为泛型，此处强转。
• 违反规则：项目规则 → TypeScript 规则 → 禁止 as 断言。

问题 2.4.3：ai-chart-renderer.tsx 使用 as 断言

• 位置：ai-chart-renderer.tsx:117
• 代码：JSON.parse(data) as AiChartSpec
• 后果：JSON 结构不可信，直接断言可能运行时错误。
• 违反规则：项目规则 → TypeScript 规则 → 禁止 as 断言。

2.5 错误处理问题

问题 2.5.1：ai-suggestion-card.tsx 未包裹 Error Boundary

• 位置：ai-suggestion-card.tsx
• 现状：组件内部有 try/catch 处理异步错误，但未用 AiErrorBoundary 包裹渲染期错误。
• 后果：若 result.data 结构异常或 questions.map 渲染时抛错，整页崩溃。
• 违反规则：审计要求 → 每个独立数据区块必须用 React Error Boundary 包裹。

问题 2.5.2：非流式聊天端点错误处理不完整

• 位置：app/api/ai/chat/route.ts
• 现状：getStatusFromError 基于错误消息字符串匹配状态码，脆弱且不可靠。
• 后果：错误分类不准确。
• 违反规则：项目规则 → 错误处理。

2.6 文件大小问题

问题 2.6.1：use-floating-ball.ts 超出 Hook 行数限制

• 位置：use-floating-ball.ts
• 现状：243 行，超出 Hook 文件 80 行建议上限 163 行。
• 后果：职责过多（位置加载/保存、拖拽事件、边缘吸附、半隐藏），难以维护和测试。
• 违反规则：项目规则 → 单文件行数 → 自定义 Hook：建议 ≤ 80 行。

2.7 可复用性问题

问题 2.7.1：4 个子页面重复创建 AiClientService

• 见问题 2.1.3。

问题 2.7.2：ai-suggestion-card.tsx 未被使用

• 位置：ai-suggestion-card.tsx
• 现状：组件已实现但无任何引用。
• 后果：死代码，维护负担。
• 违反规则：审计要求 → 最大化复用（应集成到错题本等页面）。

2.8 监控问题

问题 2.8.1：非流式聊天端点无使用量埋点

• 位置：app/api/ai/chat/route.ts
• 现状：未调用 trackAiUsage，调用数据不入统计。
• 后果：管理员仪表盘数据不完整。
• 违反规则：审计要求 → 监控。

---

三、行业差距对比

3.1 与 Khanmigo（Khan Academy）的差距

功能	Khanmigo	本项目	差距
学生 Socratic 模式	✅ 强制引导式	✅ 已实现	无
教师备课助手	✅ 课程计划生成	✅ 已实现	无
多语言支持	✅ 20+ 语言	⚠️ 仅中英文	缺少多语言 Prompt
学生情绪识别	✅ 检测挫败感	❌ 未实现	缺少情绪分析
家长沟通建议	✅ 家庭教育指导	✅ 已实现	无

3.2 与 Duolingo Max 的差距

功能	Duolingo Max	本项目	差距
解释我的答案	✅ AI 解释错误原因	❌ 未实现	缺少错题 AI 解释
角色扮演练习	✅ 情景对话练习	❌ 未实现	缺少口语/情景练习
个性化复习	✅ 基于遗忘曲线	⚠️ 仅 SM2 算法	AI 未参与复习规划

3.3 与 Squirrel AI 的差距

功能	Squirrel AI	本项目	差距
纳米级知识图谱	✅ 10000+ 知识点	⚠️ V3 已集成	知识图谱粒度较粗
自适应学习路径	✅ 实时调整	✅ V3 已实现	无
多模态学习	✅ 视频+图文+音频	❌ 仅文本	缺少多模态
学习风格识别	✅ VARK 模型	❌ 未实现	缺少学习风格分析

3.4 与 MagicSchool AI 的差距

功能	MagicSchool AI	本项目	差距
50+ AI 工具	✅ 丰富工具集	⚠️ 8 个能力	工具数量不足
IEP 生成	✅ 特殊教育计划	❌ 未实现	缺少 IEP
家校沟通模板	✅ 邮件/通知模板	❌ 未实现	缺少沟通模板
跨学科项目设计	✅ PBL 项目设计	❌ 未实现	缺少 PBL

3.5 关键差距总结

1. AI 能力数量不足：仅 8 个能力，行业平均 15-20 个
2. 多模态缺失：仅支持文本，缺少图像/语音/视频输入
3. 学习风格识别缺失：未识别学生 VARK 学习风格
4. 情绪识别缺失：未检测学生挫败感/兴奋度
5. IEP/PBL 缺失：未支持特殊教育和项目式学习
6. 跨模块数据联动不足：AI 未与考勤、行为、心理等数据联动分析

---

四、改进优先级建议

P0（紧急 — 安全/架构合规）

编号	问题	改进方向
P0-1	5 处跨模块直接依赖 shared/lib/ai	迁移至通过 modules/ai 的 data-access 或 actions 调用
P0-2	非流式聊天端点绕过 modules/ai	重构为调用 aiChatAction 或迁移安全策略
P0-3	ai-chart-renderer.tsx 硬编码中文	迁移至 i18n
P0-4	3 处 as 断言	改用类型守卫函数

P1（重要 — 规范/复用）

编号	问题	改进方向
P1-1	4 个子页面重复创建 AiClientService	提取 createAiClientService 工厂函数
P1-2	use-floating-ball.ts 超出行数限制	拆分为 use-drag-position + use-edge-snap
P1-3	ai-suggestion-card.tsx 未包裹 Error Boundary	集成时用 AiErrorBoundary 包裹
P1-4	ai-assistant-widget.tsx contextMessage 硬编码	迁移至 i18n
P1-5	非流式端点无使用量埋点	集成 trackAiUsage

P2（增强 — 行业对标）

编号	问题	改进方向
P2-1	缺少错题 AI 解释	新增 explainErrorAction
P2-2	缺少学习风格识别	新增 VARK 评估
P2-3	缺少 IEP 生成	新增特殊教育模块
P2-4	缺少家校沟通模板	新增沟通模板生成
P2-5	缺少多模态输入	支持图像/语音输入
P2-6	缺少情绪识别	集成情绪分析 API

---

五、架构图同步说明

5.1 需补充的节点

1. 跨模块违规依赖：在 005_architecture_data.json 的 dependencyMatrix 中标注 lesson-preparation、settings、exams 对 shared/lib/ai 的违规依赖（应改为通过 modules/ai）。
2. 非流式端点安全策略缺失：在 004_architecture_impact_map.md 的 AI 模块安全机制章节补充非流式端点的安全策略差距。
3. ai-suggestion-card.tsx 未使用：在文件清单中标注该组件为"已实现未集成"。

5.2 需修改的节点

1. V4 超时优化：已在 V4 中记录（shared/lib/ai/client.ts 按场景分离超时）。
2. V4 规范修复：已在 V4 中记录（ai-service.ts 消除 as 断言、actions.ts 消除非空断言、ai-assistant-widget.tsx i18n 修复）。

---

六、实施记录

6.1 P0 改进实施

P0-1：迁移跨模块依赖（部分）

已实施：

• 修复 ai-chart-renderer.tsx 硬编码中文（P0-3）
• 修复 ai-markdown-renderer.tsx as 断言（P0-4 部分）
• 修复 ai-provider-selector.tsx as 断言（P0-4 部分）
• 修复 ai-chart-renderer.tsx as 断言（P0-4 部分）

未实施（需中长期计划）：

• 5 处跨模块直接依赖 shared/lib/ai 的迁移（涉及 exams/lesson-preparation/settings 三个模块的重构，影响范围大，需单独排期）

P0-2：非流式聊天端点安全策略重构（已实施）

实施：重构 app/api/ai/chat/route.ts，与流式端点 /api/ai/chat/stream 安全策略完全对齐：

• Zod 校验输入（AiChatInputSchema，限制消息数 50/长度 8000）
• tryConsumeDailyQuota 原子化每日限额（防 TOCTOU 竞态）
• filterUserInput 输入安全过滤
• filterAiOutput 输出安全过滤
• 学生侧 Socratic 模式（服务端强制 SOCRATIC_TUTOR_SYSTEM_PROMPT，忽略客户端 systemPrompt）
• validateSocraticOutput 苏格拉底式输出校验
• 过滤/失败时 refundDailyQuota（不惩罚用户）
• trackEvent 使用量埋点（成功/失败均记录）

P0-3：ai-chart-renderer.tsx 硬编码中文（已实施）

实施：添加 i18n 键 ai.chart.parseError，替换硬编码中文。

P0-4：as 断言修复（已实施）

实施：

• ai-markdown-renderer.tsx：改用类型守卫函数 isAiChartType
• ai-provider-selector.tsx：改用 String(field.value ?? "")
• ai-chart-renderer.tsx：改用 Zod schema 校验

6.2 P1 改进实施

P1-1：提取 createAiClientService 工厂（已实施）

实施：新建 modules/ai/context/create-ai-client-service.ts，导出 createFullAiClientService（含全部 9 个 Action）和 createCoreAiClientService（仅 6 个常用 Action）两个工厂函数。app/(dashboard)/layout.tsx 使用前者，4 个子页面（error-book、lesson-plans、homework、exams）使用后者，消除重复代码。

P1-2：拆分 use-floating-ball.ts（已实施）

实施：将 243 行的 use-floating-ball.ts 拆分为 3 个文件：

• use-position-persistence.ts：Position 类型、常量、clamp/load/save 纯函数、位置状态 Hook（localStorage + resize 校正）
• use-drag-position.ts：拖拽状态 + pointer 事件处理 Hook（通过回调委托业务逻辑）
• use-floating-ball.ts：主组合 Hook（边缘吸附 + 半隐藏 + hovered 状态 + show/resetPosition）

P1-3：ai-suggestion-card.tsx Error Boundary（已实施）

实施：将原组件重命名为 AiSuggestionCardInner，新建 AiSuggestionCard 包装器用 AiErrorBoundary 包裹内部组件，保持公开 API 不变。

P1-4：ai-assistant-widget.tsx contextMessage i18n（已实施）

实施：在 en/ai.json 和 zh-CN/ai.json 中添加 chat.contextMessage.* 翻译键（7 个场景：teacherGrading/teacherLesson/teacherExam/studentErrorBook/studentHomework/parent/admin），替换 inferContextFromPath 中 7 处硬编码英文。

P1-5：非流式端点使用量埋点（已实施）

实施：在 app/api/ai/chat/route.ts 中集成 trackEvent（事件名 ai.chat），成功时记录 durationMs/tokenCount，失败时记录 errorMessage/durationMs。与流式端点（ai.chat_stream）对齐。

6.3 P2 改进（中长期计划）

P2-1：错题 AI 解释（已实施）

实施：

• 新增 ExplainErrorInput/ExplainErrorResult 类型（modules/ai/types.ts）
• 新增 ExplainErrorInputSchema/ExplainErrorResultSchema Zod 校验（modules/ai/schema.ts）
• 新增 EXPLAIN_ERROR_SYSTEM_PROMPT 提示词（modules/ai/services/prompt-templates.ts）
• 新增 explainError 服务方法（modules/ai/services/ai-service.ts）
• 新增 explainErrorAction Server Action（modules/ai/actions.ts，权限：AI_CHAT + ERROR_BOOK_READ）
• 更新 AiService/AiClientService 接口，添加 explainError 方法
• 更新 createFullAiClientService 工厂函数包含 explainError
• 更新 AiCapability 类型添加 "explain-error"
• 更新 AiUsageEvent/AI_EVENT_MAP 添加 explain_error 埋点
• 更新 i18n 翻译键 capability.explainError（en/zh-CN）
• 更新架构文档 004/005

未实施（需后续排期）：

• P2-2：VARK 学习风格评估（需新增评估模块 + DB 表）
• P2-3：IEP 特殊教育计划生成（需新增特殊教育模块）
• P2-4：家校沟通模板生成（需新增模板管理模块）
• P2-5：多模态输入支持（需接入图像/语音 API）
• P2-6：情绪识别（需接入情绪分析 API）