NextEdu/docs/architecture/audit/archive/lesson-preparation-audit-report-v3.md

备课模块审计报告 v3

审计日期：2026-06-24 审计范围：src/modules/lesson-preparation/ 全部文件 + src/app/(dashboard)/{teacher,admin,student,parent}/lesson-plans/ 全部页面 审计依据：e:\Desktop\CICD\.trae\rules\project_rules.md、docs/architecture/004_architecture_impact_map.md §2.27、docs/architecture/005_architecture_data.json modules.lesson_preparation 前序报告：lesson-preparation-audit-report-v2.md

---

一、现有实现概要

1.1 文件分布

备课模块共 45 个文件，分布如下：

层级	文件数	主要文件
types/schema/constants	3	types.ts(345行)、schema.ts(63行)、constants.ts(117行)
data-access	4	data-access.ts(593行)、data-access-versions.ts(181行)、data-access-templates.ts(129行)、data-access-knowledge.ts(95行)
actions	4	actions.ts(391行)、actions-publish.ts(82行)、actions-ai.ts(46行)、actions-kp.ts(47行)
services	2	publish-service.ts(198行)、ai-suggest.ts(82行)
lib	6	type-guards.ts(213行)、i18n-errors.ts(50行)、document-migration.ts(330行)、anchor-injector.ts(304行)、node-summary.ts(133行)、rf-mappers.ts(172行)
config	1	block-registry.tsx(194行)
providers	2	lesson-plan-provider.tsx(336行)、lesson-plan-provider-setup.tsx(29行)
services	1	default-data-service.ts(165行)
hooks	1	use-lesson-plan-editor.ts(303行)
components	18	含 11 个 block 组件 + 4 个 node 组件 + 7 个业务组件
seed	1	seed-templates.ts(9行)
页面	13	teacher(3) + admin(2) + student(2) + parent(2) + loading/error(4)

1.2 数据流

页面(Server Component) → getAuthContext() → data-access → DB
                       ↓
                       LessonPlanProviderSetup → LessonPlanProvider
                       ↓
                       LessonPlanEditor(LessonPlanList) → useLessonPlanContextSafe()
                       ↓
                       default-data-service → Server Actions → requirePermission → data-access → DB

1.3 架构图完整性

架构影响地图 §2.27 记录的导出函数、文件清单、依赖关系与实际代码基本一致，但存在以下遗漏：

• providers/lesson-plan-provider-setup.tsx 已在 V3 续审计中补充
• components/nodes/anchor-node-selector.tsx 和 textbook-segments.tsx 已在 V3 续审计中补充
• node-edit-panel.tsx 对 @/modules/ai 的直接依赖未在架构图依赖关系中记录

---

二、现存问题与原因分析

2.1 安全与权限问题（P0）

问题 1：Parent/Student 路由未校验孩子/班级归属 — 信息泄露漏洞

• 位置：data-access.ts 第 197-204 行 buildScopeCondition
• 问题：children 和 class_members 类型的 DataScope 仅过滤 status = 'published'，完全未使用 scope.childrenIds/scope.classIds/scope.gradeIds 进行归属过滤
• 违反规则：项目规则 "Parent routes must include permission checks with both parentId and studentId to prevent information leakage"
• 后果：任何家长可查看全校所有已发布课案；任何学生可查看全校所有已发布课案，构成信息泄露

问题 2：createLessonPlanVersion 未校验 planId 归属

• 位置：data-access-versions.ts 第 56-82 行
• 问题：函数接收 planId 和 userId，但事务内只查询 lessonPlanVersions 表的 max(versionNo)，未校验该 planId 是否属于 userId
• 违反规则：项目规则 "All Server Actions must call requirePermission() for permission verification" + "软删除/权限过滤在 data-access 层结合 userId 过滤"
• 后果：调用方传入任意 planId 即可为他人课案创建版本记录，越权写入

问题 3：pruneAutoVersions 完全无权限校验

• 位置：data-access-versions.ts 第 152-181 行
• 问题：函数签名 pruneAutoVersions(planId, keep = 50) 没有 userId 参数，任何调用方传入 planId 即可删除该课案的自动版本记录
• 违反规则：同问题 2
• 后果：越权删除他人课案的版本历史

问题 4：getLessonPlansByKnowledgePoint/getLessonPlansByQuestion 无权限过滤

• 位置：data-access-knowledge.ts 第 11-95 行
• 问题：两个函数直接 db.select().from(lessonPlans) 查询全表，未过滤 creatorId，也未过滤 status（archived 课案也会被查出）
• 违反规则：同问题 2
• 后果：任意调用方可获取所有课案（含他人 draft、archived 状态）的列表，严重越权

问题 5：saveLessonPlanVersionAction 的 schema 不包含 content 字段

• 位置：actions.ts 第 154-178 行、schema.ts 第 26-28 行
• 问题：saveVersionSchema 仅校验 planId 和 label，完全不包含 content 字段，input.content（类型为 LessonPlanDocument）未经任何运行时校验直接持久化
• 违反规则：项目规则 "输入使用 Zod 验证，验证失败返回结构化错误"
• 后果：恶意或畸形文档结构可被写入数据库

问题 6：publishLessonPlanHomeworkAction 中 homeworkTitle 传入 planId

• 位置：actions-publish.ts 第 35 行
• 问题：homeworkTitle = t("publish.homeworkTitle", { title: parsed.data.planId }) — title 参数传入的是 planId（UUID），而非课案标题
• 违反规则：业务逻辑正确性
• 后果：作业标题将包含 UUID 而非有意义的课案名称

问题 7：getLessonPlansAction 的 params 未经验证

• 位置：actions.ts 第 43-53 行
• 问题：params（含 query/textbookId/chapterId/subjectId/status）未经过 Zod 验证直接传入 getLessonPlans()
• 违反规则：项目规则 "输入使用 Zod 验证"
• 后果：若 query 用于 SQL LIKE 查询且未调用 escapeLikePattern()，存在 LIKE 通配符注入风险

2.2 架构违规问题（P0/P1）

问题 8：node-edit-panel.tsx 直接 import @/modules/ai

• 位置：node-edit-panel.tsx 第 11-12 行
• 问题：直接 import AiLessonContentGenerator 和 useAiClientOptional，形成模块间紧耦合
• 违反规则：项目规则 "模块内部组件绝不直接 import 其他业务模块的 actions 或 data-access（只能通过注入的接口调用）"
• 后果：模块间紧耦合，无法独立测试，AI 模块变更影响备课模块

问题 9：admin/student/parent 列表页未包裹 LessonPlanProviderSetup

• 位置：admin/lesson-plans/page.tsx、student/lesson-plans/page.tsx、parent/lesson-plans/page.tsx
• 问题：LessonPlanList 调用 useLessonPlanContextSafe() 获取 service，当未在 Provider 内使用时 service 为 null，导致 handleFilter 静默返回 — 筛选功能在 admin/student/parent 页面完全失效
• 违反规则：项目规则 "Provider 是否正确注入数据服务"
• 后果：筛选 UI 仍可见但点击无反应，用户体验差

问题 10：publish-service.ts 多步写操作未包裹事务

• 位置：publish-service.ts 第 56-197 行
• 问题：publishLessonPlanHomework 包含 5 个写操作步骤（创建题目、创建 exam 草稿、插入 exam 题目关联、下发作业、回写溯源标记），均未包裹在 db.transaction 中
• 违反规则：项目规则 "需要原子性的操作必须包裹在 db.transaction 中"
• 后果：任一步骤失败将导致数据不一致（孤儿题目、草稿残留、溯源断裂）

2.3 类型安全问题（P1）

问题 11：rf-mappers.ts 颜色映射 Bug

• 位置：rf-mappers.ts 第 113 行
• 问题：getNodeColor(anchor.nodeId) 传入 nodeId 而非 node type，getNodeColor 期望接收节点类型（如 "objective"），传入 nodeId 必然找不到匹配项
• 违反规则：功能性 Bug
• 后果：锚点边始终使用默认灰色 #9e9e9e，注释声称的"P1-4 修复"实际未生效

问题 12：富文本类型配置三处不一致

• 位置：constants.ts 第 25-36 行、block-registry.tsx 第 50、56-69 行
• 问题：RICH_TEXT_BLOCK_TYPES（10项）vs RICH_TEXT_TYPES（2项）vs BLOCK_REGISTRY.isRichText（2项）三处定义语义冲突
• 违反规则：配置一致性
• 后果：isRichTextBlock() 与 RICH_TEXT_BLOCK_TYPES 行为完全相反，调用方混用会产生矛盾结果

问题 13：多处 as 断言违规

• 位置：
  • node-summary.ts 第 28-55 行：as { html?: string; ... } 将联合类型转为内联接口
  • rf-mappers.ts 第 81、95 行：as Record<string, unknown>
  • block-renderer.tsx 第 107、115、121、125 行：4 处 as XxxBlockData
  • lesson-plan-readonly-view.tsx 第 91 行：as Edge[]
  • inline-question-editor.tsx 第 34 行：as typeof QUESTION_TYPES[number]
  • data-access-knowledge.ts 第 24、39、67、82 行：4 处 as 断言
  • use-lesson-plan-editor.ts 第 137、138、154、155 行：4 处 as 断言
  • 4 个页面文件中 findChapter 的 as typeof chapters（冗余断言）
  • actions.ts 第 144 行：as unknown as LessonPlanDocument 双重断言
• 违反规则：项目规则 "禁止 as 断言（除类型收窄外）"
• 后果：类型安全被绕过，潜在运行时错误

问题 14：actions-ai.ts/actions-kp.ts 隐式 any

• 位置：actions-ai.ts 第 34 行 Array.isArray(doc.nodes) 收窄为 any[]；actions-kp.ts 第 30 行 let kps; 隐式 any
• 违反规则：项目规则 "禁止 any"
• 后果：类型安全缺失

2.4 i18n 与错误处理问题（P1）

问题 15：actions-ai.ts/actions-kp.ts 未使用 handleActionError 和 translateFieldErrors

• 位置：actions-ai.ts 第 23、41-45 行；actions-kp.ts 第 23、42-46 行
• 问题：Zod 错误未调用 translateFieldErrors() 翻译；catch 块未使用 handleActionError()，非权限错误被静默吞掉，无日志
• 违反规则：项目规则 "所有 Server Action catch 块改用 handleActionError"
• 后果：错误不可观测，用户看到未翻译的 i18n 键

问题 16：block-renderer.tsx 硬编码中文

• 位置：block-renderer.tsx 第 130 行
• 问题："未知 block 类型" 直接硬编码为中文，整个文件未 import useTranslations
• 违反规则：项目规则 "所有用户可见文本必须适配 i18n"
• 后果：多语言环境下显示中文

问题 17：schema.ts 多个 schema 缺少 i18n 错误消息

• 位置：schema.ts 第 14-32 行
• 问题：仅 createLessonPlanSchema 和 publishLessonPlanHomeworkSchema 部分字段使用 i18n 键，其他 6 个 schema 均未使用
• 违反规则：项目规则 "Zod schema 错误消息应使用 i18n 键"
• 后果：Zod 校验错误返回英文默认消息

2.5 a11y 与 UX 问题（P1/P2）

问题 18：inline-question-editor.tsx Modal 缺少焦点陷阱

• 位置：inline-question-editor.tsx 第 72-227 行
• 问题：模态框设置了 role="dialog" 和 aria-modal="true"，但未实现焦点陷阱、Escape 关闭、焦点管理
• 违反规则：a11y 键盘导航
• 后果：键盘用户无法正常使用模态框

问题 19：多处缺少 aria-label

• 位置：lesson-plan-editor.tsx 第 239-243 行（标题输入框）、第 330-335 行（添加节点按钮）；block-renderer.tsx 第 71-102 行（4 个图标按钮）；lesson-plan-readonly-view.tsx 第 89-103 行（画布缺少 aria）
• 违反规则：a11y 语义化标签
• 后果：屏幕阅读器无法识别元素用途

问题 20：getLessonPlanStats 的 archived 恒为 0

• 位置：data-access.ts 第 553-566 行、admin/lesson-plans/page.tsx 第 63-72 行
• 问题：WHERE 子句排除 archived 后硬编码返回 archived: 0，但 admin 页面仍渲染"已归档"统计卡片
• 违反规则：数据准确性
• 后果：统计卡片永远显示 0，具有误导性

2.6 性能与代码质量问题（P2）

问题 21：use-lesson-plan-editor.ts 303 行超标

• 位置：hooks/use-lesson-plan-editor.ts
• 问题：文件 303 行，远超 Hook 80 行建议上限
• 违反规则：项目规则 "自定义 Hook：建议 ≤ 80 行"
• 后果：可维护性差

问题 22：findChapter 在 4 个页面重复

• 位置：teacher edit、admin view、student view、parent view
• 问题：4 个页面文件中存在完全相同的 findChapter 递归函数实现
• 违反规则：DRY 原则
• 后果：代码重复，维护成本高

问题 23：lesson-plan-card.tsx 4 个异步函数未使用 useCallback

• 位置：lesson-plan-card.tsx 第 72、89、105、122 行
• 问题：handleArchive/handleDuplicate/handlePublish/handleUnpublish 每次渲染重新创建
• 违反规则：性能最佳实践
• 后果：不必要渲染

问题 24：多处 Tailwind 任意值

• 位置：lesson-plan-editor.tsx（4处）、node-edit-panel.tsx（2处）、inline-question-editor.tsx（3处）
• 违反规则：项目规则 "禁止使用任意值（w-[137px]），除非有充分理由并注释"

---

三、行业差距对比

3.1 与优秀 K12 产品的差距

维度	优秀实践	当前实现	差距影响
权限隔离	家长仅能查看自己孩子班级的课案，学生仅能查看自己班级课案	家长/学生可查看全校已发布课案	信息泄露风险，违反 FERPA/GDPR 等隐私法规
数据一致性	发布作业等关键操作使用事务保证原子性	多步写操作无事务	部分失败导致数据不一致，需要人工修复
版本管理	版本创建/删除有严格的归属校验	版本创建/删除可越权操作	用户可篡改他人课案历史
a11y	模态框实现完整焦点管理，所有交互元素有 aria-label	Modal 无焦点陷阱，多处缺少 aria-label	残障用户无法使用
错误可观测性	所有异常记录日志，有统一错误处理	部分Action 静默吞掉错误	生产问题无法排查
配置一致性	单一数据源定义 Block 类型属性	三处富文本配置冲突	运行时行为不可预测
模块解耦	通过接口抽象依赖，支持独立测试	直接 import AI 模块组件	无法独立测试，变更影响扩散

3.2 缺失的功能

• 课案协作：优秀产品支持多位教师协作编辑同一课案，当前仅支持单教师
• 课案评课：教研组长可对课案添加评课意见，当前缺失
• 课案资源库：跨学期/学年的课案资源库检索，当前仅按教材章节组织
• AI 智能备课：基于课标自动生成教学目标/重难点，当前仅有知识点推荐

---

四、改进优先级建议

P0（严重 — 安全/正确性，必须立即修复）

#	问题	改进方向
P0-1	Parent/Student 路由未校验归属关系	修复 buildScopeCondition 的 children/class_members 分支，使用 scope.classIds/scope.gradeIds/scope.childrenIds 过滤；修复 getLessonPlanById 增加归属校验
P0-2	createLessonPlanVersion 未校验 planId 归属	事务开头增加 lessonPlans.creatorId = userId 校验
P0-3	pruneAutoVersions 无 userId 参数	增加 userId 参数，删除前校验 planId 归属
P0-4	getLessonPlansByKnowledgePoint/getLessonPlansByQuestion 无权限过滤	增加 userId 参数，过滤 status != 'archived'，按 creatorId/DataScope 限制
P0-5	saveLessonPlanVersionAction schema 不含 content	定义 lessonPlanDocumentSchema 递归校验文档结构
P0-6	publishLessonPlanHomeworkAction homeworkTitle 传入 planId	先查询课案标题再传入
P0-7	getLessonPlansAction params 未验证	定义 Zod schema，data-access 使用 escapeLikePattern
P0-8	rf-mappers.ts 颜色映射 Bug	传入节点 type 而非 nodeId
P0-9	富文本配置三处不一致	统一为单一数据源，删除冗余定义
P0-10	block-renderer.tsx 硬编码中文 + as 断言	使用 i18n + 类型守卫
P0-11	node-edit-panel.tsx 直接 import @/modules/ai	通过 props 注入 AI 组件
P0-12	publish-service.ts 多步写操作无事务	包裹 db.transaction
P0-13	admin/student/parent 列表页未包裹 Provider	包裹 LessonPlanProviderSetup

P1（高 — 类型安全/规范一致性）

#	问题	改进方向
P1-1	多处 as 断言（node-summary/rf-mappers/block-renderer/readonly-view/inline-question-editor/data-access-knowledge/use-lesson-plan-editor/4页面）	使用类型守卫替代
P1-2	actions-ai.ts/actions-kp.ts 隐式 any	显式类型标注
P1-3	actions-ai.ts/actions-kp.ts 未用 handleActionError/translateFieldErrors	统一错误处理
P1-4	schema.ts 多个 schema 缺 i18n 错误消息	补全 i18n 键
P1-5	getLessonPlanStats archived 恒为 0	修复统计逻辑
P1-6	findChapter 4 处重复	提取为 textbooks 共享工具
P1-7	inline-question-editor.tsx Modal 缺焦点陷阱	实现焦点管理
P1-8	多处缺少 aria-label	补全 a11y 属性
P1-9	data-access-knowledge.ts LIKE 未用 escapeLikePattern	统一转义
P1-10	actions-publish.ts 重复 requirePermission	复用 AuthContext

P2（中 — 性能/代码质量）

#	问题	改进方向
P2-1	use-lesson-plan-editor.ts 303 行超标	拆分为多个 slice
P2-2	lesson-plan-card.tsx 4 函数未 useCallback	包裹 useCallback
P2-3	多处 Tailwind 任意值	提取设计令牌
P2-4	lesson-plan-list.tsx 缺筛选加载状态	增加 isLoading
P2-5	block-renderer.tsx 废弃文件	评估是否可删除
P2-6	ai-suggest.ts prompt 硬编码中文	参数化注入

---

五、架构图同步说明

本次审计发现架构图需补充以下内容：

1. 依赖关系补充：node-edit-panel.tsx 对 @/modules/ai 的直接依赖需在 005_architecture_data.json 的 lesson_preparation.dependsOn 中记录
2. auditFixes 补充：本次 V3 续续审计的修复记录（V3-23 ~ V3-35）需添加到 005_architecture_data.json 的 auditFixes 对象
3. 文件清单更新：若 use-lesson-plan-editor.ts 拆分为多个 slice，需更新 004 文件清单和 005 files 数组
4. 配置冲突修复：constants.ts 与 block-registry.tsx 的富文本配置统一后，需更新 004 中两者的描述

---

六、实施计划

本报告所有问题将按 P0 → P1 → P2 顺序完整实施，实施过程中同步更新架构图 004/005。