diff --git a/docs/architecture/004_architecture_impact_map.md b/docs/architecture/004_architecture_impact_map.md index 6c1cf57..2cf8c49 100644 --- a/docs/architecture/004_architecture_impact_map.md +++ b/docs/architecture/004_architecture_impact_map.md @@ -894,7 +894,7 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions" | `actions.ts` | 502 | 14 个 Server Action（写操作，含 Zod 校验 + 资源归属校验 + 知识图谱查询/前置依赖管理 + class-mastery 视图） | | `data-access.ts` | 593 | 教材/章节/知识点 CRUD + 跨模块查询接口 + 资源归属校验 + 数据范围过滤 + 前置依赖 CRUD（v3 P2：硬编码异常改为 NotFoundError） | | `data-access-graph.ts` | 188 | 知识图谱只读查询（✅ Task 5 新增：知识点关联聚合、学生/班级掌握度、前置后置知识点，标记 `server-only`；v2 修复：前置依赖双向 IN 过滤防跨教材污染） | -| `types.ts` | 94 | 类型定义（含知识图谱类型：GraphViewMode/MasteryInfo/KpWithRelations/GraphNodeData/GraphEdgeData/KnowledgeGraphData/MasteryLevel） | +| `types.ts` | 94 | 类型定义（含知识图谱类型：GraphViewMode/GraphLayoutMode/MasteryInfo/KpWithRelations/GraphNodeData/GraphEdgeData/KnowledgeGraphData/MasteryLevel） | | `schema.ts` | 56 | Zod 校验（含 CreatePrerequisiteSchema/DeletePrerequisiteSchema；v2 修复：refine 消息改为英文；v3 修复：移除死代码 ReorderChaptersSchema） | | `constants.ts` | 91 | 学科/年级常量与颜色映射（✅ 新增；v1 测试修复：新增 Chinese/Grade 1/Grade 2） | | `utils.ts` | 226 | 章节树构建/排序/查找等纯函数 + 循环检测（✅ 新增，含单测） | @@ -908,10 +908,11 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions" | `hooks/use-kp-update.ts` | 36 | 知识点更新 Hook（v3 P2 新增：从 use-kp-crud 拆分） | | `hooks/use-text-selection.ts` | 49 | 文本选区捕获 Hook | | `hooks/use-graph-data.ts` | 65 | 知识图谱数据加载 Hook（✅ Task 11 新增：派生值模式避免 effect 中 setState；v2 修复：区分 isLoading/isRefreshing 避免 UI 闪烁） | -| `components/knowledge-graph.tsx` | 356 | React Flow 知识图谱主组件（✅ Task 10/15 重写：全书视图 + 搜索高亮 + 关联节点高亮 + 章节着色；v2 新增：添加/删除前置依赖 Dialog） | +| `components/knowledge-graph.tsx` | 408 | 知识图谱主组件（✅ Task 10/15 重写：全书视图 + 搜索高亮 + 关联节点高亮 + 章节着色；v2 新增：添加/删除前置依赖 Dialog；v4 新增：hierarchical/force 布局模式切换，根据布局模式渲染分层 ReactFlow 或 Obsidian 风格力导向图，状态/详情面板/依赖增删对话框共享） | | `components/graph-kp-node.tsx` | 92 | React Flow 自定义节点（✅ Task 9 新增：知识点名称+题目数徽章+掌握度进度条；v2 修复：节点宽度常量化 NODE_WIDTH；v3 修复：类型守卫替代 as 断言） | | `components/graph-prerequisite-edge.tsx` | 43 | React Flow 自定义边（✅ Task 9 新增：虚线+箭头表示前置依赖；v2 修复：GraphEdgeData 类型安全转换） | -| `components/graph-toolbar.tsx` | 84 | 图谱工具栏（✅ Task 9 新增：视图模式切换 + 搜索 + 重置视图；v2 新增：isRefreshing 轻量指示器） | +| `components/graph-toolbar.tsx` | 121 | 图谱工具栏（✅ Task 9 新增：视图模式切换 + 搜索 + 重置视图；v2 新增：isRefreshing 轻量指示器；v4 新增：hierarchical/force 布局模式切换 Select） | +| `components/force-graph.tsx` | 451 | Obsidian 风格力导向图谱组件（v4 新增：基于 react-force-graph-2d + d3-force；v5 视觉对齐 Obsidian Graph View：小圆点节点+极细半透明边线+标签右侧带背景+hover/选中邻居高亮+紫色外圈焦点环；通过 next/dynamic ssr:false + import type 加载避免 SSR canvas/window 报错） | | `components/graph-node-detail-panel.tsx` | 171 | 节点详情侧边面板（✅ Task 13 新增：描述/掌握度/关联题目/前置后置列表；v2 修复：移除未使用 textbookId prop；v3 修复：aria-label） | | `components/chapter-sidebar-list.tsx` | 325 | 章节侧边栏列表（v2 修复：canEdit 默认 false + orderUpdateFailed i18n key；v3 修复：键盘导航） | | `components/section-error-boundary.tsx` | 53 | 章节内容错误边界（v2 修复：默认值改为空字符串 + 条件渲染；v3 修复：componentDidCatch + a11y） | @@ -919,7 +920,7 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions" | `components/textbook-content-panel.tsx` | 199 | 章节内容面板（v3 P2：17 props 按 chapter/editing/selection/highlight 四组重构） | | `components/textbook-form-dialog.tsx` | 68 | 教材创建对话框（v3 P2：复用 TextbookFormFields） | | `components/textbook-settings-dialog.tsx` | 136 | 教材设置对话框（v3 P2：复用 TextbookFormFields） | -| `components/textbook-reader.tsx` | 412 | 教材阅读器主组件（v3 P2：移除命令式 classList，高亮改为状态驱动） | +| `components/textbook-reader.tsx` | 458 | 教材阅读器主组件（v3 P2：移除命令式 classList，高亮改为状态驱动；v5 桌面端改用 ResizablePanel 可拖拽分栏，图谱 tab 时图谱初始占 60%，切换 tab 用 key 重置比例） | | `components/*` | 17 文件 | 教材编辑/知识图谱组件（新增 `textbook-form-fields.tsx`、5 个 graph-* 组件、3 个 use-kp-* 子 Hook；`teacher-textbook-reader.tsx` 已移至 app 层） | --- @@ -2758,6 +2759,34 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions" > - **权限扩展**：新增 STANDARD_READ/MANAGE/LINK + LESSON_PLAN_SUBMIT/REVIEW/ANALYTICS_READ/SUBSTITUTE_MANAGE > - **i18n 扩展**：zh-CN 新增 9 个命名空间；status 扩展为 6 状态 > - **数据库表**：新增 6 张表（lessonPlanComments/lessonPlanReviewRecords/lessonPlanFormativeItems/lessonPlanAttachments/lessonPlanAiEvaluations/lessonPlanSubstituteAssignments） +> +> 架构变更（2026-07-03，V5 场景缺口修复第一阶段）： +> - **V5-1 自动保存失败 UI 兜底**：version-slice.ts 新增 saveError/isOnline 状态；lesson-plan-editor.tsx 监听 online/offline 事件 + toast 提示 + 重试按钮 +> - **V5-2 撤销/重做**：新增 hooks/history-slice.ts（past/future 栈，50 步上限）；editor-slice.ts 所有 mutation 包装 pushHistory；编辑器顶部 Undo/Redo 按钮 + Ctrl/Cmd+Z/Shift+Z 快捷键 +> - **V5-3 发布前作业单预览**：publish-homework-dialog.tsx 改为 3 步流程（选班级 → 预览题目+总分+学生数 → 确认发布）；exercise-block.tsx 传入 items +> - **V5-4 导出/打印**：新增 lib/export.ts（文档扁平化，详细版/简洁版）+ components/print-view.tsx（打印视图）；编辑器顶部新增"导出"按钮 +> - **V5-5 多媒体嵌入 + 素材库**：types.ts RichTextBlockData 新增 attachments 字段；rich-text-block.tsx 集成 @tiptap/extension-image；新增 components/attachment-picker.tsx（复用 use-file-upload + M6 附件表 data-access）；LessonPlanDataService 接口新增 getLessonPlanAttachments/createLessonPlanAttachment/deleteLessonPlanAttachment 三个方法；新增依赖 @tiptap/extension-image；FileTargetType 新增 "lesson_plan" +> - **i18n 扩展**：zh-CN/en 同步新增 action.undo/redo、status.retrySave/saveFailed/recovered/offline、publish.step1-3/preview*/confirm*、questionBank.type 多题型、export.*、attachment.*、editor.textbookContent +> - **审计报告**：新增 docs/architecture/audit/lesson-preparation-audit-report-v5.md（场景缺口维度，对照 v4 架构合规维度） +> +> 架构变更（2026-07-03，V5 场景缺口修复第二阶段 V5-6~V5-21）： +> - **V5-6 W1 题库组卷预览**：exercise-block.tsx 增加组卷预览模式（题目列表 + 总分统计） +> - **V5-7 W3/W4 课案绑定课时**：新增 data-access-schedules.ts + actions-schedules.ts + components/schedule-dialog.tsx；编辑器新增「安排课时」按钮；数据库新增 lesson_plan_schedules 表 +> - **V5-8 U2 画布自动布局**：新增 lib/auto-layout.ts（@dagrejs/dagre DAG 自动布局，项目已安装依赖无需新增）；editor-slice.ts 新增 autoLayout action +> - **V5-9 F5 教材模糊搜索 + 最近使用**：template-picker.tsx 增加客户端模糊搜索（标题/学科/年级/出版社）+ localStorage 最近使用 5 个教材 +> - **V5-10 P1 画布性能优化**：node-editor.tsx ReactFlow 新增 onlyRenderVisibleElements 虚拟化 + minZoom={0.2}/maxZoom={2.5}/elevateNodesOnSelect={false} +> - **V5-12 R4 校内课案库**：新增 teacher/lesson-plans/library 路由 + loading.tsx + error.tsx；actions.ts 新增 duplicateLessonPlanFormAction（FormData wrapper 适配 form action） +> - **V5-13 P3 移动端只读视图**：新增 components/lesson-plan-mobile-view.tsx（按教学阶段分组线性卡片视图）；lesson-plan-readonly-view.tsx 集成 useMediaQuery("(max-width: 768px)") 小屏切换 +> - **V5-14 F4 板书可视化工具**：blackboard-block.tsx 增加轻量级可视化预览（不引入新库）——编辑/预览模式切换、structure 层级树、mindmap 中心+分支、text 等宽展示；新增 BlackboardPreview 子组件 + parseContent 纯函数（按缩进识别层级） +> - **V5-15 T1 教学阶段分组**：types.ts 新增 TeachingStage 类型 + TEACHING_STAGE_KEYS 常量；Block 接口新增 stage? 字段；node-edit-panel.tsx 添加教学阶段选择器 UI +> - **V5-16 T2 反思闭环（版本对比）**：新增 lib/version-diff.ts（纯函数 diffDocuments 对比两个 LessonPlanDocument 节点级差异，added/removed/modified/unchanged + changedFields）；新增 components/version-diff-view.tsx；version-history-drawer.tsx 集成版本对比（currentDoc prop + 对比按钮） +> - **V5-17 A1/A2 AI 反馈闭环**：新增 lib/ai-feedback.ts（generateLessonPlanFeedback 纯服务端函数，4 维度 strengths/improvements/alignment/differentiation，含解释性 reason 字段）；actions-ai.ts 新增 generateLessonPlanFeedbackAction；新增 components/ai-feedback-dialog.tsx；编辑器工具栏新增「AI 反馈」按钮 +> - **V5-18 W6 差异化教学标记**：types.ts 新增 DifferentiationLevel 类型 + DIFFERENTIATION_LEVEL_KEYS 常量；Block 接口新增 differentiation? 字段；node-edit-panel.tsx 添加差异化标记选择器 UI +> - **V5-19 T3 目标-评价一致性校验**：新增 lib/consistency-check.ts（纯函数 checkConsistency 输出 ConsistencyResult，校验规则：缺少 objective/exercise 警告、exercise 无知识点警告、objective 未被评价覆盖警告）；新增 components/consistency-check-dialog.tsx；编辑器工具栏新增「一致性校验」按钮 +> - **V5-20 T4 课标覆盖热力图**：新增 lib/curriculum-coverage.ts（纯函数 computeCurriculumCoverage 按 chapterId 分组统计覆盖率，识别 isBlindSpot 教学盲点；getHeatLevel 0-4 热力等级）；新增 components/curriculum-heatmap.tsx；新增 teacher/lesson-plans/heatmap 路由 + loading.tsx + error.tsx +> - **V5-21 A3/A4/A5 AI 差异化模块**：新增 lib/ai-differentiation.ts（3 个纯服务端函数：generateDifferentiationSuggestions/checkCurriculumAlignment/generateExplainableAssessment，复用 ai-feedback.ts 的 createAiChatCompletion + Zod + JSON 提取模式）；actions-ai.ts 新增 4 个 server actions（generateDifferentiationSuggestionsAction/checkCurriculumAlignmentAction/generateExplainableAssessmentAction/getKnowledgePointsForAlignmentAction）；新增 components/ai-differentiation-dialog.tsx（3 Tab 视图：差异化建议/课标核对/可解释评估，A4 按教材 ID 按需加载知识点）；编辑器工具栏新增「AI 差异化」按钮 +> - **i18n 扩展**：zh-CN/en 同步新增 editor.stage*/editor.differentiation*/editor.consistency*/consistency.*/diff.*/library.*/feedback.*/heatmap.*/aiDifferentiation.*/blackboard.editMode/previewMode/editHint/previewEmpty/untitled +> - **V5-11 R3 协同编辑**：需引入新依赖（Yjs/Liveblocks）或采用轻量协作方案（评论+@提醒+版本对比），暂标记为待规划，待用户决策 --- @@ -3893,7 +3922,7 @@ rateLimit(params: RateLimitParams): Promise // audit-P1-6： resetRateLimit(key: string): Promise // audit-P1-6：改为 Promise 返回 rateLimitKey(prefix: string, identifier: string): string // 同步纯函数 rateLimitHeaders(result: RateLimitResult): Record // 同步纯函数 -getRateLimiter(): RateLimiter // audit-P1-6 新增：返回当前进程的限流器实例 +getRateLimiter(): Promise // audit-P1-6 新增：返回当前进程的限流器实例；redis 驱动下动态 import redis-limiter 故为异步 RATE_LIMIT_RULES // 同步常量（含 LOGIN/API/UPLOAD/AI_CHAT/PASSWORD_CHANGE/ONBOARDING_BIND；audit-P1-8 新增 ONBOARDING_BIND: 5次/小时） // RateLimiter interface (audit-P1-6 新增) // limit(params: RateLimitParams): Promise diff --git a/docs/architecture/005_architecture_data.json b/docs/architecture/005_architecture_data.json index 17f5025..6d826fd 100644 --- a/docs/architecture/005_architecture_data.json +++ b/docs/architecture/005_architecture_data.json @@ -6443,11 +6443,21 @@ "name": "GraphViewMode", "type": "type", "definition": "\"structure\" | \"student-mastery\" | \"class-mastery\"", - "purpose": "Task 7 新增：图谱视图模式", + "purpose": "Task 7 新增：图谱数据视角（结构 / 学生掌握度 / 班级掌握度）", "usedBy": [ "getKnowledgeGraphDataAction" ] }, + { + "name": "GraphLayoutMode", + "type": "type", + "definition": "\"hierarchical\" | \"force\"", + "purpose": "v4 新增：图谱渲染布局（hierarchical=分层有向图 ReactFlow+dagre；force=Obsidian 风格力导向图 react-force-graph-2d）", + "usedBy": [ + "components/knowledge-graph.tsx", + "components/graph-toolbar.tsx" + ] + }, { "name": "MasteryInfo", "type": "interface", @@ -6648,7 +6658,17 @@ }, { "name": "KnowledgeGraph", - "purpose": "知识图谱可视化" + "purpose": "知识图谱可视化（v4 新增：支持 hierarchical/force 两种布局模式切换，hierarchical=ReactFlow+dagre 分层有向图，force=Obsidian 风格力导向图；外层共享状态/详情面板/前置依赖增删对话框）" + }, + { + "name": "ForceKnowledgeGraph", + "file": "components/force-graph.tsx", + "purpose": "v4 新增：Obsidian 风格力导向图谱组件，基于 react-force-graph-2d + d3-force；圆形节点+曲线连接+物理力导向+邻居高亮+拖拽联动；通过 next/dynamic ssr:false 加载避免 SSR canvas/window 报错" + }, + { + "name": "GraphToolbar", + "file": "components/graph-toolbar.tsx", + "purpose": "图谱工具栏（v4 新增 hierarchical/force 布局模式切换 Select；保留视图模式切换/搜索/重置视图）" }, { "name": "GraphNodeDetailPanel", @@ -6693,7 +6713,10 @@ ], "uiDeps": [], "uiDepsNote": "已通过 render prop 解耦，TeacherTextbookReader 已移至 app 层（src/app/(dashboard)/teacher/textbooks/[id]/_components/），textbooks 模块不再直接 import questions 模块组件", + "npmDeps": ["@xyflow/react", "@dagrejs/dagre", "react-force-graph-2d"], + "npmDepsNote": "v4 新增 react-force-graph-2d（基于 d3-force + Canvas）实现 Obsidian 风格力导向图谱；通过 next/dynamic ssr:false 加载避免 SSR canvas/window 报错；@xyflow/react + @dagrejs/dagre 用于分层有向图布局", "knownIssues": [ + "v4 新增（2026-07-03）：知识点图谱新增 Obsidian 风格力导向布局（force 模式），与原分层有向图（hierarchical 模式）共存，工具栏可切换；新增组件 force-graph.tsx，新增类型 GraphLayoutMode；保留全部现有功能（掌握度视图/搜索高亮/邻居高亮/前置依赖增删）", "i18n 覆盖率约 99%（v3 新增 notFound/noClassMasteryPermission/close/prerequisiteAddFailed/prerequisiteRemoveFailed 等键，data-access 层硬编码英文异常文案已改为 NotFoundError 错误码化）", "v3 审计修复（2026-06-24）：学生端两个页面添加 requirePermission(Permissions.TEXTBOOK_READ) 显式权限校验", "v3 审计修复（2026-06-24）：getKnowledgeGraphDataAction 添加学生/家长年级 scope 过滤，class-mastery 视图模式限制为 teacher/admin", @@ -6749,8 +6772,9 @@ "components/graph-kp-node.tsx": 92, "components/graph-node-detail-panel.tsx": 171, "components/graph-prerequisite-edge.tsx": 43, - "components/graph-toolbar.tsx": 84, - "components/knowledge-graph.tsx": 356, + "components/graph-toolbar.tsx": 121, + "components/force-graph.tsx": 454, + "components/knowledge-graph.tsx": 408, "components/knowledge-point-dialogs.tsx": 167, "components/knowledge-point-list.tsx": 117, "components/section-error-boundary.tsx": 53, @@ -20513,6 +20537,76 @@ "name": "suggestKnowledgePoints", "file": "ai-suggest.ts", "purpose": "AI 建议知识点（基于课案内容）" + }, + { + "name": "autoLayout", + "file": "lib/auto-layout.ts", + "purpose": "V5-8 U2 新增：基于 @dagrejs/dagre 的 DAG 自动布局算法，按 edges 拓扑排序计算 nodes 位置" + }, + { + "name": "diffDocuments", + "file": "lib/version-diff.ts", + "purpose": "V5-16 T2 新增：纯函数对比两个 LessonPlanDocument 节点级差异，返回 added/removed/modified/unchanged + changedFields" + }, + { + "name": "hasChanges", + "file": "lib/version-diff.ts", + "purpose": "V5-16 T2 新增：判断 VersionDiffResult 是否存在变更" + }, + { + "name": "checkConsistency", + "file": "lib/consistency-check.ts", + "purpose": "V5-19 T3 新增：纯函数目标-评价一致性校验，输出 ConsistencyResult（缺少 objective/exercise 警告、exercise 无知识点警告、objective 未被评价覆盖警告）" + }, + { + "name": "hasConsistencyWarnings", + "file": "lib/consistency-check.ts", + "purpose": "V5-19 T3 新增：判断 ConsistencyResult 是否存在警告" + }, + { + "name": "computeCurriculumCoverage", + "file": "lib/curriculum-coverage.ts", + "purpose": "V5-20 T4 新增：纯函数按 chapterId 分组统计教师所有课案对教材知识点的覆盖率，识别 isBlindSpot 教学盲点" + }, + { + "name": "getHeatLevel", + "file": "lib/curriculum-coverage.ts", + "purpose": "V5-20 T4 新增：根据覆盖率返回热力图颜色等级（0-4）" + }, + { + "name": "generateLessonPlanFeedback", + "file": "lib/ai-feedback.ts", + "purpose": "V5-17 A1/A2 新增：AI 反馈闭环，纯服务端函数，4 维度 strengths/improvements/alignment/differentiation，含解释性 reason 字段；AI 不可用时返回空结果" + }, + { + "name": "generateDifferentiationSuggestions", + "file": "lib/ai-differentiation.ts", + "purpose": "V5-21 A3 新增：AI 差异化教学建议生成，按 basic/intermediate/advanced 三层生成建议" + }, + { + "name": "checkCurriculumAlignment", + "file": "lib/ai-differentiation.ts", + "purpose": "V5-21 A4 新增：AI 课标实时核对，检查课案是否覆盖教材知识点" + }, + { + "name": "generateExplainableAssessment", + "file": "lib/ai-differentiation.ts", + "purpose": "V5-21 A5 新增：AI 可解释评估，对 exercise 节点给出 conclusion/rationale/suggestion" + }, + { + "name": "getLessonPlanSchedules", + "file": "data-access-schedules.ts", + "purpose": "V5-7 W3/W4 新增：查询课案绑定的课时列表" + }, + { + "name": "createLessonPlanSchedule", + "file": "data-access-schedules.ts", + "purpose": "V5-7 W3/W4 新增：课案绑定课时" + }, + { + "name": "deleteLessonPlanSchedule", + "file": "data-access-schedules.ts", + "purpose": "V5-7 W3/W4 新增：删除课时绑定" } ], "actions": [ @@ -20629,6 +20723,60 @@ "permission": "LESSON_PLAN_READ", "file": "actions.ts", "purpose": "按 textbookId 获取章节树（供 template-picker 选择章节）" + }, + { + "name": "duplicateLessonPlanFormAction", + "permission": "LESSON_PLAN_CREATE", + "file": "actions.ts", + "purpose": "V5-12 R4 新增：FormData wrapper 适配
，内部调用 duplicateLessonPlanAction 后 redirect 到新课案编辑页" + }, + { + "name": "getLessonPlanSchedulesAction", + "permission": "LESSON_PLAN_READ", + "file": "actions-schedules.ts", + "purpose": "V5-7 W3/W4 新增：查询课案绑定的课时列表" + }, + { + "name": "createLessonPlanScheduleAction", + "permission": "LESSON_PLAN_UPDATE", + "file": "actions-schedules.ts", + "purpose": "V5-7 W3/W4 新增：课案绑定课时" + }, + { + "name": "deleteLessonPlanScheduleAction", + "permission": "LESSON_PLAN_UPDATE", + "file": "actions-schedules.ts", + "purpose": "V5-7 W3/W4 新增：删除课时绑定" + }, + { + "name": "generateLessonPlanFeedbackAction", + "permission": "LESSON_PLAN_READ + AI_CHAT", + "file": "actions-ai.ts", + "purpose": "V5-17 A1/A2 新增：AI 反馈闭环，调用 generateLessonPlanFeedback 生成结构化反馈" + }, + { + "name": "generateDifferentiationSuggestionsAction", + "permission": "LESSON_PLAN_READ + AI_CHAT", + "file": "actions-ai.ts", + "purpose": "V5-21 A3 新增：AI 差异化教学建议生成" + }, + { + "name": "checkCurriculumAlignmentAction", + "permission": "LESSON_PLAN_READ + AI_CHAT", + "file": "actions-ai.ts", + "purpose": "V5-21 A4 新增：AI 课标实时核对" + }, + { + "name": "generateExplainableAssessmentAction", + "permission": "LESSON_PLAN_READ + AI_CHAT", + "file": "actions-ai.ts", + "purpose": "V5-21 A5 新增：AI 可解释评估" + }, + { + "name": "getKnowledgePointsForAlignmentAction", + "permission": "LESSON_PLAN_READ", + "file": "actions-ai.ts", + "purpose": "V5-21 A4 辅助新增：按 textbookId 获取知识点列表（仅 id+name），供课标核对 Tab 按需加载" } ], "schemas": [ @@ -20867,7 +21015,12 @@ "V4-11": "P2-4 废弃文件删除：components/block-renderer.tsx（@deprecated，无源码引用）删除", "V4-12": "P2-5 anchor-injector regex 一致性：markdownToPlainText 的 /^>\\s+/gm 改为 /^\\s*>\\s+/gm；skipPatterns 5 个 regex 统一添加 g 标志，与 markdownToPlainText 保持一致", "V4-13": "P2-6 Zustand store 拆 slice：hooks/use-lesson-plan-editor.ts 从 303 行单体 store 拆分为 3 个独立 slice——hooks/editor-slice.ts（文档结构+文档操作）/hooks/selection-slice.ts（选中状态）/hooks/version-slice.ts（版本与保存状态）；主文件重写为 25 行薄层，组合 3 个 slice 并导出 EditorState 类型", - "V4-14": "type-guards 导出补全：lib/type-guards.ts 的 VALID_QUESTION_TYPES 常量从模块私有改为 export（供 inline-question-editor.tsx 复用，消除重复定义）" + "V4-14": "type-guards 导出补全：lib/type-guards.ts 的 VALID_QUESTION_TYPES 常量从模块私有改为 export（供 inline-question-editor.tsx 复用，消除重复定义）", + "V5-1": "自动保存失败 UI 兜底：version-slice.ts 新增 saveError/isOnline 状态 + setSaveError/setOnline 方法；lesson-plan-editor.tsx 自动保存失败时 toast 提示 + 设置 saveError，断网时不触发保存请求，监听 window online/offline 事件 toast 提示，saveError 时显示重试按钮，恢复时提示已恢复", + "V5-2": "撤销/重做：新增 hooks/history-slice.ts（past/future 栈，50 步上限，canUndo/canRedo/pushHistory/undo/redo/clearHistory 方法）；editor-slice.ts 所有 mutation 方法（setTitle/addNode/updateNode/removeNode/updateTextbookContent/addAnchor/removeAnchor/updateAnchor/connect/disconnect/setEdges）包装 pushHistory，updateNodePosition 除外（拖拽过程中由调用方在 onDragStart 时推入）；version-slice hydrate/replaceDoc 调用 clearHistory；lesson-plan-editor.tsx 顶部新增 Undo/Redo 按钮 + Ctrl/Cmd+Z 撤销 + Ctrl/Cmd+Shift+Z 或 Ctrl/Cmd+Y 重做快捷键", + "V5-3": "发布前作业单预览：publish-homework-dialog.tsx 改为 3 步流程（step=select 选班级+时间 → step=preview 预览题目+总分+班级数 → step=confirm 确认发布），第二步显示题目列表（题型/来源/题干预览/分值）+汇总信息（班级数/题目数/总分），第三步显示最终确认信息+警告文案；exercise-block.tsx 调用 PublishHomeworkDialog 时传入 items={data.items}", + "V5-4": "导出/打印：新增 lib/export.ts（flattenLessonPlanForPrint 函数，将画布式 LessonPlanDocument 扁平化为 PrintableLessonPlan 线性结构，支持 detailed/concise 两种 variant，concise 仅含 objective/new_teaching/exercise/homework）+ components/print-view.tsx（打印视图组件，详细版/简洁版切换 + 调用 window.print() 通过浏览器原生能力保存为 PDF + print: CSS 媒体查询隐藏工具栏 + 页眉含教材/教师/班级/教学时长/最后保存时间 + break-inside-avoid 防止段落跨页）；lesson-plan-editor.tsx 新增 printablePlan useMemo 构造 + 导出按钮 + PrintView 渲染", + "V5-5": "多媒体嵌入 + 我的素材库：types.ts RichTextBlockData 新增 attachments?: RichTextAttachment[] 字段 + RichTextAttachment 类型（attachmentId/fileId/displayName/kind: image|audio|video|file/url/mimeType?）；rich-text-block.tsx 集成 @tiptap/extension-image（Image.configure inline:false allowBase64:false）+ 新增附件入口按钮 + 已嵌入附件列表渲染（非图片附件列表 + 图片附件缩略图，含删除按钮）+ 图片附件通过 editor.commands.setImage 直接插入富文本；新增 components/attachment-picker.tsx（素材库 picker，复用 use-file-upload hook 调用 /api/upload + 调用 service.createLessonPlanAttachment 落库到 M6 lessonPlanAttachments 表 + 列出 service.getLessonPlanAttachments + 删除 service.deleteLessonPlanAttachment + inferAttachmentKind 工具函数）；LessonPlanDataService 接口新增 getLessonPlanAttachments/createLessonPlanAttachment/deleteLessonPlanAttachment 三个方法 + LessonPlanAttachmentOption 导出类型；default-data-service.ts 实现三个方法（DB 层 Date 转 ISO string 以匹配接口类型）；BlockRenderProps 新增 planId? 字段；NodeEditPanel 新增 planId prop 透传；lesson-plan-editor.tsx NodeEditPanel 调用传入 planId；新增依赖 @tiptap/extension-image；files/types.ts FileTargetType 新增 'lesson_plan' 类型" } }, "error-book": { @@ -22029,6 +22182,13 @@ "columns": 6, "indexes": 2, "foreignKeys": 2 + }, + "lessonPlanSchedules": { + "owner": "lesson-preparation", + "description": "V5-7 W3/W4 课案绑定课时表(planId+classId+lessonDate 唯一约束，2026-07-03 新增)", + "columns": 6, + "indexes": 3, + "foreignKeys": 2 } } }, @@ -25438,11 +25598,45 @@ "duplicateLessonPlanAction", "saveAsTemplateAction", "suggestKnowledgePointsAction", - "publishLessonPlanHomeworkAction" + "publishLessonPlanHomeworkAction", + "getLessonPlanSchedulesAction", + "createLessonPlanScheduleAction", + "deleteLessonPlanScheduleAction", + "generateLessonPlanFeedbackAction", + "generateDifferentiationSuggestionsAction", + "checkCurriculumAlignmentAction", + "generateExplainableAssessmentAction", + "getKnowledgePointsForAlignmentAction" ], "permission": "lesson_plan:update", "permissionRead": "lesson_plan:read", - "description": "编辑课案页面（权限：requirePermission(LESSON_PLAN_UPDATE)；只读访问需 LESSON_PLAN_READ）" + "description": "编辑课案页面（权限：requirePermission(LESSON_PLAN_UPDATE)；只读访问需 LESSON_PLAN_READ；V5-7 新增课时绑定 actions；V5-17/V5-21 新增 AI 反馈/差异化 actions）" + }, + "/teacher/lesson-plans/library": { + "component": "LibraryPage", + "type": "server", + "module": "lesson-preparation", + "method": "GET", + "dataAccess": [ + "lesson-preparation/data-access.getLessonPlans" + ], + "actions": [ + "duplicateLessonPlanFormAction" + ], + "permission": "lesson_plan:read", + "description": "V5-12 R4 新增：校内课案库页面，展示其他教师发布的课案，支持一键复制（权限：requirePermission(LESSON_PLAN_READ)）" + }, + "/teacher/lesson-plans/heatmap": { + "component": "HeatmapPage", + "type": "server", + "module": "lesson-preparation", + "method": "GET", + "dataAccess": [ + "lesson-preparation/data-access.getLessonPlans", + "textbooks/data-access.getKnowledgePointsByTextbookId" + ], + "permission": "lesson_plan:read", + "description": "V5-20 T4 新增：课标覆盖热力图页面，统计教师所有课案对教材知识点的覆盖情况（权限：requirePermission(LESSON_PLAN_READ)）" }, "/teacher/error-book": { "component": "TeacherErrorBookPage + SubjectTabs + ClassFilter + AnalyticsStatsCards + ClassErrorBarChart + KnowledgePointWeaknessChart + ChapterWeaknessChart + GroupedStudentErrorTable + TopWrongQuestions", diff --git a/docs/architecture/audit/lesson-preparation-audit-report-v5.md b/docs/architecture/audit/lesson-preparation-audit-report-v5.md new file mode 100644 index 0000000..acdcd23 --- /dev/null +++ b/docs/architecture/audit/lesson-preparation-audit-report-v5.md @@ -0,0 +1,289 @@ +# 备课模块审计报告 v5 + +> 审计日期：2026-07-03 +> 审计范围：`src/modules/lesson-preparation/` 场景覆盖度维度（区别于 v4 的架构合规维度） +> 审计依据：用户实际备课工作流反馈 + v4 审计报告 + K12 行业产品对标（Planboard / Nearpod / Common Curriculum） +> 前序报告：`lesson-preparation-audit-report-v4.md`（2026-06-25，架构合规审计） +> 审计方法：场景驱动缺口分析 + 实际代码核对 + 高频备课工作流走查 + +--- + +## 一、审计背景 + +v4 审计聚焦**架构合规性**（权限/类型/解耦/a11y），30 项 P0/P1/P2 已全部修复。M1-M12 中长期计划已**部分实施**（M1 课标 / M2 评论 / M3 审核 / M4 课程地图 / M5 形成性 / M6 附件表 / M8 AI 评估 / M9 日历 / M10 分析 / M11 diff / M12 代课）。 + +但用户反馈显示：**M1-M12 虽建了数据层，UI 集成度不够**（M6 附件表无 UI、M9 日历不绑课表、M2 评论无协同编辑），且**完全遗漏了 4 项核心能力**（导出/打印、撤销/重做、多媒体嵌入、发布前预览）。 + +v5 审计聚焦"场景覆盖度"维度，对照教师日常备课工作流识别缺口。 + +--- + +## 二、教师备课工作流与模块覆盖度 + +### 2.1 标准备课工作流 + +| 阶段 | 教师动作 | 模块覆盖 | 缺口 | +|------|---------|---------|------| +| 课前 | 选教材/课文 → 选模板 → 创建课案 | ✅ 完整 | - | +| 课前 | 设计教学目标 / 重难点 / 导入 / 新授 / 总结 | ✅ 11 种 Block 完整 | - | +| 课前 | 关联知识点 / 课标 | ✅ 知识点 / M1 课标 | - | +| 课前 | 插入朗读音频 / 实验视频 / 图片素材 | ❌ rich_text 仅富文本 | F2 多媒体嵌入缺失 | +| 课前 | 重用历史素材 | ❌ 无素材库 | F3 我的素材库缺失 | +| 课前 | 设计板书（图文混排、分区） | ⚠️ blackboard 仅文本 | F4 板书可视化弱 | +| 课前 | 撤销/重做画布操作 | ❌ 无 history 栈 | U1 撤销/重做缺失 | +| 课前 | 自动保存失败提示 | ❌ 仅 console.error | S1 UI 兜底缺失 | +| 课前 | 题库选题 → 一键发布作业 | ⚠️ 无预览步骤 | W2 发布前预览缺失 | +| 课前 | 导出 PDF / 打印教案 | ❌ 完全缺失 | F1 导出/打印缺失 | +| 课中 | 学生查看发布课案 | ✅ 只读视图 | - | +| 课后 | 教学反思 + 二次备课 | ⚠️ reflection 节点存在，无锁定/diff | T2 反思闭环不完整 | + +### 2.2 工作流卡点分析 + +教师日常备课高频路径中存在 **5 个"卡点"**——遇到即停止使用，回退到 Word/PPT： + +| 卡点 | 频次 | 影响 | +|------|------|------| +| 画布误删节点无法撤销 | 极高 | 教师不敢操作画布 | +| 自动保存失败无提示，关闭页面数据丢失 | 高 | 信任崩塌 | +| 备课成果无法导出/打印交付教研组 | 高 | 系统外循环 | +| 无法插入多媒体素材 | 高 | 课"备不活" | +| 一键发布作业无预览 | 中 | 误发布风险 | + +--- + +## 三、场景缺口详细分析 + +### 3.1 S1 - 自动保存失败 UI 兜底（🔴 极紧急） + +- **位置**：[lesson-plan-editor.tsx](file:///e:/Desktop/CICD/src/modules/lesson-preparation/components/lesson-plan-editor.tsx) L97-116 +- **现状**：自动保存失败仅 `console.error("[LessonPlanEditor] auto-save failed", e)`，UI 无任何提示 +- **后果**： + - 教师关闭页面时数据丢失（beforeunload 仅检查 isDirty，不区分"保存失败"与"未触发保存"） + - 断网场景下教师继续编辑，所有改动静默丢失 +- **违反需求**：用户 §五"怕丢数据：必须要有强自动保存，以及断网恢复提示" + +### 3.2 U1 - 撤销/重做（🔴 极紧急） + +- **位置**：[editor-slice.ts](file:///e:/Desktop/CICD/src/modules/lesson-preparation/hooks/editor-slice.ts) 全文 +- **现状**：Zustand store 无 history 栈，所有 mutation 直接 set +- **后果**： + - 画布上误删一个节点，只能去版本抽屉回滚到 30 分钟前的状态 + - 教师不敢操作画布，回退到列表式备课 +- **违反需求**：用户 §三.5"撤销/重做：画布操作没有撤销，简直没法用。必须支持至少 50 步撤销" + +### 3.3 W2 - 发布前作业单预览（🔴 极紧急） + +- **位置**：[publish-homework-dialog.tsx](file:///e:/Desktop/CICD/src/modules/lesson-preparation/components/publish-homework-dialog.tsx) 全文 +- **现状**：对话框仅选班级 + 时间，点击"发布"直接调用 service.publishLessonPlanHomework +- **缺失**： + - 无题目列表预览（题干/选项/答案/分值） + - 无总分预览 + - 无班级学生数提示 + - 无"返回修改"步骤 +- **后果**：一键发布到学生/家长端，误发布无法收回 +- **违反需求**：用户 §五"怕误发布：发布前必须有预览" + +### 3.4 F1 - 导出/打印（🔴 极紧急） + +- **位置**：全模块无导出/打印相关代码 +- **现状**：画布做得再好，备课成果无法走出系统 +- **缺失**： + - 无 PDF 导出 + - 无打印视图 + - 无"详细版/简洁版"切换 +- **后果**：教研组检查无纸质交付，教师回退到 Word +- **违反需求**：用户 §二.1"没有导出，备课成果无法走出系统" + +### 3.5 F2/F3 - 多媒体嵌入 + 我的素材库（🔴 极紧急） + +- **位置**： + - [rich-text-block.tsx](file:///e:/Desktop/CICD/src/modules/lesson-preparation/components/blocks/rich-text-block.tsx) L29-45 仅用 Tiptap StarterKit + Placeholder + - [data-access-attachments.ts](file:///e:/Desktop/CICD/src/modules/lesson-preparation/data-access-attachments.ts) M6 数据层已建，**无 UI 集成** + - [actions-attachments.ts](file:///e:/Desktop/CICD/src/modules/lesson-preparation/actions-attachments.ts) Server Actions 已建，**无组件调用** +- **现状**：rich_text 节点不支持图片/音视频；M6 附件表与 UI 完全断链 +- **后果**： + - 教师无法插入朗读音频 / 实验视频 / PPT 截图 + - 每次都得从本地重新上传，无沉淀 +- **违反需求**：用户 §二.2"这决定了我能不能把课'备活'" + +--- + +## 四、改进方案与实施 + +### 4.1 第一阶段实施（v5 P0，本次完成） + +| ID | 缺口 | 实施方案 | 验收标准 | +|----|------|---------|---------| +| V5-1 | S1 自动保存失败 UI 兜底 | editor 添加 saveError 状态 + toast 提示 + 在线状态监听 + 重试按钮 | 断网时 toast 显示"保存失败"，恢复时 toast 显示"已恢复在线" | +| V5-2 | U1 撤销/重做 | 新增 `hooks/history-slice.ts`（past/future 栈，50 步上限）+ 编辑器顶部 Undo/Redo 按钮 + Cmd/Ctrl+Z / Cmd+Shift+Z 快捷键 | 误删节点后 Cmd+Z 可恢复 | +| V5-3 | W2 发布前作业单预览 | publish-homework-dialog 改为 3 步流程（选班级 → 预览题目+总分+学生数 → 确认发布） | 发布前可见所有题干、选项、答案、分值、班级学生数 | +| V5-4 | F1 导出/打印 | 新增 `lib/export.ts`（文档扁平化）+ `components/print-view.tsx`（打印视图）+ 编辑器"导出/打印"按钮 + 详细版/简洁版切换 | 浏览器打印对话框可保存为 PDF，含教材/教师/班级信息 | +| V5-5 | F2/F3 多媒体嵌入 + 素材库 | rich-text-block 集成 Tiptap Image 扩展 + 新增 `components/attachment-picker.tsx` 附件库 picker + 集成 M6 附件表 | 可在 rich_text 中插入图片，从素材库选择已有附件 | + +### 4.2 第二阶段计划（v5 P1，本次仅记录） + +| ID | 缺口 | 优先级 | +|----|------|--------| +| V5-6 | W1 题库组卷预览（题干展开） | 🟠 | +| V5-7 | W3/W4 课案绑定课时 | 🟠 | +| V5-8 | U2 画布自动布局 | 🟠 | +| V5-9 | F5 教材模糊搜索 + 最近使用 | 🟠 | +| V5-10 | P1 大课案画布性能压测 | 🟠 | + +### 4.3 第三阶段计划（v5 P2，本次仅记录） + +| ID | 缺口 | 优先级 | +|----|------|--------| +| V5-11 | R3 协同编辑（Yjs/Liveblocks 评估） | 🟡 | +| V5-12 | R4 校内课案库 | 🟡 | +| V5-13 | P3 移动端只读视图 | 🟡 | +| V5-14 | F4 板书可视化工具 | 🟡 | +| V5-15 | T1 教学阶段分组 | 🟡 | +| V5-16 | T2 反思闭环 | 🟡 | +| V5-17 | A1/A2 AI 反馈闭环 + 解释性 | 🟡 | + +### 4.4 第四阶段计划（v5 P3，本次仅记录） + +| ID | 缺口 | 优先级 | +|----|------|--------| +| V5-18 | W6 差异化教学标记 | 🟢 | +| V5-19 | T3 目标-评价一致性 | 🟢 | +| V5-20 | T4 教师端课标热力图 | 🟢 | +| V5-21 | A3/A4/A5 AI 差异化生成 + 课标实时核对 + 评估可解释 | 🟢 | + +--- + +## 五、架构影响 + +### 5.1 新增文件 + +| 文件 | 用途 | +|------|------| +| `hooks/history-slice.ts` | Zustand history slice（past/future 栈，50 步上限） | +| `lib/export.ts` | 文档扁平化导出工具（详细版/简洁版） | +| `components/print-view.tsx` | 打印视图组件（含教材/教师/班级信息） | +| `components/attachment-picker.tsx` | 附件库 picker（集成 M6 附件表） | + +### 5.2 修改文件 + +| 文件 | 修改内容 | +|------|---------| +| `hooks/use-lesson-plan-editor.ts` | 组合 history slice | +| `hooks/editor-slice.ts` | mutation 方法包装 history 推送 | +| `components/lesson-plan-editor.tsx` | 自动保存失败 UI 兜底 + Undo/Redo 按钮 + 快捷键 + 导出按钮 | +| `components/publish-homework-dialog.tsx` | 3 步发布流程（选班级 → 预览 → 确认） | +| `components/blocks/rich-text-block.tsx` | 集成 Tiptap Image 扩展 + 附件库入口 | +| `shared/i18n/messages/zh-CN/lesson-preparation.json` | 新增 undo/redo/export/print/saveError 等键 | +| `shared/i18n/messages/en/lesson-preparation.json` | 同步英文翻译 | + +### 5.3 架构图同步 + +修改 `docs/architecture/004_architecture_impact_map.md` §2.27 章节末尾追加"V5 场景缺口修复"小节。 +修改 `docs/architecture/005_architecture_data.json` modules.lesson_preparation.auditFixes 新增 V5-1 至 V5-5 条目。 + +--- + +## 六、验收标准 + +- ✅ `npm run lint` 零错误 +- ✅ `npx tsc --noEmit` 零错误 +- ✅ 单文件行数：组件 ≤ 500，hooks ≤ 80，工具函数 ≤ 40 +- ✅ 无 `any`、无 `as` 断言（除 unknown 收窄） +- ✅ 全量 i18n（zh-CN + en） +- ✅ 架构文档 004/005 已同步 +- ✅ `docs/troubleshooting/known-issues.md` 已记录 + +--- + +**v5 审计完成。本次实施第一阶段 V5-1 至 V5-5 共 5 项场景缺口修复。** + +--- + +## 七、V5 第二阶段实施结果（2026-07-03 续） + +### 7.1 已完成清单 + +| ID | 缺口 | 状态 | 实施摘要 | +|----|------|------|---------| +| V5-6 | W1 题库组卷预览 | ✅ | exercise-block.tsx 增加组卷预览模式 | +| V5-7 | W3/W4 课案绑定课时 | ✅ | 新增 data-access-schedules.ts + actions-schedules.ts + schedule-dialog.tsx + lesson_plan_schedules 表 | +| V5-8 | U2 画布自动布局 | ✅ | 新增 lib/auto-layout.ts（@dagrejs/dagre，复用已安装依赖） | +| V5-9 | F5 教材模糊搜索 + 最近使用 | ✅ | template-picker.tsx 增加客户端模糊搜索 + localStorage 最近使用 | +| V5-10 | P1 大画布性能优化 | ✅ | node-editor.tsx ReactFlow onlyRenderVisibleElements + zoom 限制 | +| V5-12 | R4 校内课案库 | ✅ | 新增 teacher/lesson-plans/library 路由 + duplicateLessonPlanFormAction | +| V5-13 | P3 移动端只读视图 | ✅ | 新增 lesson-plan-mobile-view.tsx + useMediaQuery 切换 | +| V5-14 | F4 板书可视化工具 | ✅ | blackboard-block.tsx 增加轻量级可视化预览（不引入新库，纯 CSS + 文本解析） | +| V5-15 | T1 教学阶段分组 | ✅ | types.ts TeachingStage 类型 + node-edit-panel 选择器 | +| V5-16 | T2 反思闭环 | ✅ | 新增 lib/version-diff.ts 纯函数 + version-diff-view 组件 + 抽屉集成 | +| V5-17 | A1/A2 AI 反馈闭环 | ✅ | 新增 lib/ai-feedback.ts 纯服务端函数 + ai-feedback-dialog + 工具栏集成 | +| V5-18 | W6 差异化教学标记 | ✅ | types.ts DifferentiationLevel 类型 + node-edit-panel 选择器 | +| V5-19 | T3 一致性校验 | ✅ | 新增 lib/consistency-check.ts 纯函数 + consistency-check-dialog + 工具栏集成 | +| V5-20 | T4 课标热力图 | ✅ | 新增 lib/curriculum-coverage.ts 纯函数 + curriculum-heatmap + teacher/lesson-plans/heatmap 路由 | +| V5-21 | A3/A4/A5 AI 差异化 | ✅ | 新增 lib/ai-differentiation.ts 3 个纯服务端函数 + ai-differentiation-dialog（3 Tab） + 4 个 server actions + 工具栏集成 | + +### 7.2 待规划 + +| ID | 缺口 | 状态 | 备注 | +|----|------|------|------| +| V5-11 | R3 协同编辑 | 🟡 长远计划 | 详见 §7.5 Yjs 方案评估（2026-07-03 评估，因架构改造复杂度高暂不实施） | + +### 7.3 i18n 修复 + +- 修复 zh-CN/en lesson-preparation.json 重复键问题（JSON 后者覆盖前者） +- 新增命名空间：`editor.stage*`/`editor.differentiation*`/`editor.consistency*`/`consistency.*`/`diff.*`/`library.*`/`feedback.*`/`heatmap.*`/`aiDifferentiation.*`/`blackboard.editMode/previewMode/editHint/previewEmpty/untitled` + +### 7.4 验证结果 + +- ✅ `npx tsc --noEmit` 零错误 +- ✅ 本次修改的 5 个文件（ai-differentiation-dialog/blackboard-block/actions-ai/lesson-plan-editor/ai-differentiation lib）`npx eslint` 零错误 +- ✅ 架构文档 004/005 已同步 V5-6~V5-21 +- ✅ `docs/troubleshooting/known-issues.md` 新增"V5 第二阶段 V5-6~V5-21 通用规则"小节 + +**V5 第二阶段完成 15 项（V5-6~V5-21 除 V5-11），V5-11 作为长远计划记录于 §7.5。** + +### 7.5 V5-11 R3 协同编辑长远规划（Yjs + y-websocket 方案） + +**决策**：2026-07-03 评估，因架构改造复杂度高，暂不实施，作为长远计划。 + +#### 7.5.1 Yjs 工作原理（澄清） + +Yjs 是 **CRDT（无冲突复制数据类型）** 库，**不是邮箱/消息系统**，而是**实时状态同步**机制。当 A 老师在编辑器输入"导入"，B 老师的屏幕上**立刻**出现"导入"——这是实时同步，不是发消息。 + +- **Yjs**：CRDT 数据结构库，保证多端最终一致性 +- **y-websocket**：传输层，需要独立的 WebSocket 服务器作为中转 +- **y-prosemirror**：Yjs 与 ProseMirror（Tiptap 底层）的绑定，让富文本编辑器支持多人光标 + +#### 7.5.2 与当前项目的关键冲突 + +| 冲突点 | 当前项目 | Yjs 要求 | +|--------|---------|---------| +| 服务器类型 | Next.js HTTP | 需独立 WebSocket 服务器进程 | +| 持久化 | Drizzle ORM + MySQL | Yjs document 状态需独立持久化（LevelDB 或自定义 adapter） | +| 权限校验 | Server Actions + requirePermission | WS 连接时需校验 JWT/session | +| 编辑器状态 | Zustand store（editor-slice） | Yjs document 作为真相源，Zustand 降级为视图层 | +| 数据结构 | LessonPlanDocument JSON | Yjs.XmlFragment（Tiptap 文档）或 Yjs.Map | + +#### 7.5.3 推荐架构（未来实施时） + +- **WS 服务器部署**：项目内独立进程（`server/ws-server.ts`，`npm run ws` 启动，生产环境用 PM2/Docker 管理） +- **协同范围**：仅 RichTextBlock（Tiptap）节点实现多人实时协同，其他节点保持单人编辑 +- **持久化策略**：双写——Yjs document 作为实时层，每隔 N 秒（或用户离开时）将状态序列化为 JSON 写入 `lessonPlans.content`，兼容现有数据结构 +- **权限校验**：WS 连接握手时校验 JWT，按 planId 校验 `LESSON_PLAN_UPDATE` 权限 + +#### 7.5.4 需要安装的依赖 + +| 依赖 | 用途 | 备注 | +|------|------|------| +| `yjs` | CRDT 核心库 | 必装 | +| `y-websocket` | WebSocket 传输层 | 必装 | +| `y-prosemirror` | Yjs ↔ ProseMirror 绑定 | 必装（Tiptap 集成） | +| `@hocuspocus/server` | WS 服务器框架（可选） | 提供权限/持久化/扩展插件，开箱即用 | +| `y-leveldb` | Yjs 持久化（可选） | LevelDB 存储，或自定义 MySQL adapter | + +#### 7.5.5 替代方案 + +若未来评估认为 Yjs 复杂度过高，可考虑**轻量协作方案**作为替代： +- 不引入实时协同库 +- 复用现有 messaging/notifications 模块 + V5-16 版本对比 +- 实现「Block 级评论 + @提醒 + 版本对比」 +- 无需新依赖，开发快，与项目现有架构契合 diff --git a/docs/troubleshooting/known-issues.md b/docs/troubleshooting/known-issues.md new file mode 100644 index 0000000..ce57fff --- /dev/null +++ b/docs/troubleshooting/known-issues.md @@ -0,0 +1,652 @@ +# 项目规则速查手册 + +> 一页式规则清单，指明正确做法。无需解释原因，遇到问题查表即可。 + +--- + +## 一、i18n 翻译文件规则 + +| 规则 | 正确写法 | 错误写法 | +|------|---------|---------| +| key 禁止包含 `.` | `"title": { "parent": "..." }` | `"title.parent": "..."` | +| 同字段多角色变体用嵌套对象 | `"title": { "default": "...", "parent": "...", "teacher": "..." }` | `"title": "..."`, `"title.parent": "..."` | +| 不同字段用驼峰命名 | `"createDesc": "..."` | `"create.desc": "..."` | +| 调用方 `t("title.parent")` 自动解析嵌套 | 无需改调用方代码 | — | +| 动态拼 key 需包含完整路径 | `t(\`type.${type}\`)`（type 在 type 对象下） | `t(type)`（漏掉 `type.` 前缀） | +| 嵌套 key 调用需带父级路径 | `t(\`difficulty.${level}\`)` | `t(level)` | + +### i18n 动态 key 调用规则 + +当 `t()` 参数为动态变量时，**必须包含完整嵌套路径**： + +```typescript +// JSON 结构: { "type": { "single_choice": "单选题", "multiple_choice": "多选题" } } + +// 正确：带父级路径 +const label = t(`type.${question.type}`) // t("type.single_choice") + +// 错误：漏掉父级路径，触发 MISSING_MESSAGE +const label = t(question.type) // t("single_choice") → 找不到 +``` +| ICU 参数用单花括号 | `"level": "难度 {level}"` | `"level": "难度 {{level}}"` | +| ICU 多参数直接并列 | `"summary": "{count} 题 · {subject}"` | `"summary": "{{count}} 题 · {{subject}}"` | + +--- + +## 二、"use server" 文件规则 + +| 规则 | 正确写法 | 错误写法 | +|------|---------|---------| +| 只能导出 `async function` | `export async function foo() {}` | `export const foo = ...` | +| 常量/对象放 `types.ts` 或 `constants.ts` | `types.ts: export const CONFIG = {...}` | `actions.ts: export const CONFIG = {...}` | +| 同步函数放 `lib/` 目录 | `lib/track-event.ts: export function track() {}` | `actions.ts: export function track() {}` | +| 禁止值 re-export | 调用方直接从源文件 import | `export { foo } from "./bar"` | +| 类型 re-export 允许 | `export type { Foo } from "./bar"` | — | + +--- + +## 三、Client Component 依赖隔离规则 + +| 规则 | 正确写法 | 错误写法 | +|------|---------|---------| +| 常量定义放 `types.ts` 或 `constants.ts` | `types.ts: export const MAX = 30` | `retention.ts: export const MAX = 30`（含 `import { db }`） | +| Client Component 不得 import server-only 文件 | `import { MAX } from "../types"` | `import { MAX } from "../retention"`（拉入 mysql2） | +| `import { db }` 或 `import "server-only"` 的文件不得被客户端 import | — | — | +| 纯类型文件不得 import db/mysql2 | `types.ts` 无 server-only import | `types.ts: import { db } from "@/shared/db"` | + +--- + +## 四、可选依赖处理规则 + +| 规则 | 正确写法 | 错误写法 | +|------|---------|---------| +| 可选依赖动态 import 加 `webpackIgnore` | `await import(/* webpackIgnore: true */ "@upstash/redis")` | `await import("@upstash/redis")` | +| 环境变量控制加载的模块用动态 import | `if (env.DRIVER === "redis") { const { Redis } = await import(...) }` | 顶层静态 import | +| 仅 redis 驱动加载的类用动态 import | `const { RedisRateLimiter } = await import("./redis-limiter")` | `import { RedisRateLimiter } from "./redis-limiter"` | + +--- + +## 五、Next.js 配置规则 + +| 规则 | 配置 | +|------|------| +| Node.js 服务端驱动标记为外部包 | `serverExternalPackages: ["mysql2"]` | +| 输出模式 | `output: "standalone"` | + +--- + +## 六、架构分层规则 + +| 层级 | 允许依赖 | 禁止依赖 | +|------|---------|---------| +| `app/` | `modules/` 的 actions + data-access | 直接访问 DB | +| `modules/` | 其他 `modules/` 的 data-access + `shared/` | 直接查询对方 DB 表 | +| `shared/` | 无 | `@/auth`、`@/proxy`、`modules/*` | + +--- + +## 七、模块文件职责规则 + +| 文件 | 职责 | 禁止 | +|------|------|------| +| `actions.ts` | Server Actions（async function + 权限校验） | 导出常量、同步函数、值 re-export | +| `data-access.ts` | 数据访问（可拆分 `data-access-*.ts`） | 业务逻辑、权限校验 | +| `types.ts` | 类型定义 + 常量 | `import { db }`、`import "server-only"` | +| `schema.ts` | Zod 验证 | — | +| `lib/` | 同步工具函数、业务逻辑 | "use server" 标记 | + +--- + +## 八、验证命令速查 + +| 场景 | 命令 | +|------|------| +| 类型检查 | `npx tsc --noEmit` | +| Lint | `npm run lint` | +| 开发服务器 | `npm run dev` | +| 生产构建 | `npm run build` | +| 检查 i18n key 是否含 `.` | Grep pattern: `^\s*"[a-zA-Z_]+\.[a-zA-Z_\.]+"\s*:`，glob: `**/messages/**/*.json` | +| 同步 schema 到数据库 | `npm run db:push` | +| 执行迁移文件 | `npm run db:migrate` | +| 检查表结构 | `SHOW COLUMNS FROM table_name` | + +--- + +## 十、数据库 Schema 同步规则 + +| 规则 | 正确做法 | 错误做法 | +|------|---------|---------| +| 修改 schema.ts 后必须同步数据库 | `npm run db:push` 或 `npm run db:migrate` | 仅改 schema.ts 不同步数据库 | +| 报错 `Unknown column` 时先查表结构 | `SHOW COLUMNS FROM xxx` | 仅看代码 schema 假设数据库已同步 | +| 迁移文件按编号顺序执行 | `drizzle/00XX_*.sql` 按序号递增 | 跳过编号或乱序执行 | +| `Failed query` 错误先排查数据库结构 | 用 mysql 客户端执行相同 SQL 确认 | 仅看代码假设查询逻辑错误 | +| 新增字段必须生成迁移文件 | `npm run db:generate` 后 commit `.sql` + `_journal.json` | 仅 ALTER 数据库不留迁移文件 | +| 修改 schema 后验证一致性 | `node scripts/verify-modules-schema.mjs` 或 `npm run db:push` | 仅看 dev server 不报错即认为成功 | + +### 数据库同步问题排查 + +当出现 `Unknown column 'xxx' in 'field list'` 或 `Failed query` 错误时： + +1. 用 `SHOW COLUMNS FROM 表名` 对比数据库实际结构与 `schema.ts` +2. 若字段缺失，执行 `npm run db:push` 同步，或手动执行对应迁移 SQL +3. 验证：用相同 SQL 在数据库客户端执行，确认不再报错 + +--- + +## 十一、Drizzle 迁移记录管理规则 + +| 规则 | 正确做法 | 错误做法 | +|------|---------|---------| +| 迁移文件必须录入 `_journal.json` | `npm run db:generate` 自动生成 entry | 手动创建 `.sql` 不更新 journal | +| `__drizzle_migrations` 表必须记录已应用迁移 | `npm run db:migrate` 自动写入 hash | 手动 ALTER 后不补 hash 记录 | +| 迁移文件编号唯一不可复用 | `0016_invitation_codes.sql` 与 `0016_message_reports.sql` 应改 `0022+` | 同前缀冲突 | +| 手动补 DDL 后必须同步 journal + migrations 表 | 见下方"手动补迁移"流程 | 仅 ALTER 数据库，留 journal 缺失 | +| 检查迁移状态 | `SELECT * FROM __drizzle_migrations` | 仅看 `_journal.json` 文件 | + +### 手动补迁移流程（数据库已 ALTER 但 journal/migrations 表缺失时） + +1. 在 `drizzle/` 创建 `00XX_*.sql` 文件（即使 DDL 已应用，仍需归档） +2. 在 `drizzle/meta/_journal.json` 添加对应 entry（`tag` = 文件名不含扩展名） +3. 计算文件 sha256 hash，插入 `__drizzle_migrations` 表： + ```sql + INSERT INTO __drizzle_migrations (hash, created_at) VALUES ('', ); + ``` +4. 验证：`npm run db:migrate` 应输出 "No new migrations to apply" + +### Drizzle 字段映射规则 + +| 场景 | 正确写法 | 错误写法 | +|------|---------|---------| +| TS 属性名与 DB 列名不同 | `status: mysqlEnum("report_status", [...])` | 假设 DB 列名是 `status` | +| 验证 SQL 用 DB 列名 | `SELECT report_status FROM learning_diagnostic_reports` | `SELECT status FROM learning_diagnostic_reports` | +| ORM 查询用 TS 属性名 | `db.select({ s: table.status })` | `db.select({ s: table.report_status })` | + +--- + +## 十二、V5 备课模块场景缺口修复规则 + +### Zustand store 拆 slice + history slice 模式 + +| 规则 | 正确写法 | 错误写法 | +|------|---------|---------| +| mutation 方法包装 history | `setTitle: (title) => { get().pushHistory(); set({ title, isDirty: true }); }` | `setTitle: (title) => set({ title, isDirty: true })` | +| 拖拽位置更新除外 | `updateNodePosition` 不推 history（调用方 onDragStart 时推） | 拖拽过程每次 move 都 pushHistory（栈瞬间爆满） | +| hydrate/replaceDoc 清空历史 | `hydrate: (...) => set({ ..., past: [], future: [] })` | 切换课案后旧 history 残留 | +| history 栈上限 | `past: [...s.past, snapshot].slice(-MAX_HISTORY)` | 无上限（内存爆炸） | + +### 撤销/重做快捷键 + +| 规则 | 正确写法 | 错误写法 | +|------|---------|---------| +| Cmd/Ctrl 区分 | `const isMod = e.metaKey \|\| e.ctrlKey` | 仅 `e.ctrlKey`（Mac 不工作） | +| Shift+Z 或 Y 重做 | `(key === "z" && e.shiftKey) \|\| key === "y"` | 仅 `key === "y"` | +| preventDefault | `e.preventDefault()` | 不阻止默认（浏览器原生撤销/重做冲突） | + +### 自动保存失败 UI 兜底 + +| 规则 | 正确写法 | 错误写法 | +|------|---------|---------| +| 保存失败显示 toast | `toast.error(t("status.saveFailed"), { description: ... })` | `console.error(e)`（用户无感知） | +| 断网时不触发保存 | `if (!editor.isOnline) return;` 在 debounce 内 | 网络请求堆积 | +| 监听 online/offline | `window.addEventListener("online", handleOnline)` | 不监听（永远显示离线） | +| saveError 显示重试按钮 | `{editor.saveError &&