xiner/NextEdu
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs(architecture): V4 纸感重构架构图同步

Browse Source 
004_architecture_impact_map.md: 更新 lesson-preparation 章节描述（V4 三栏布局）、新增 V4 纸感重构架构变更章节（H1/I1/J1/J2/J3/J4/J5 + 数据模型 v4）、更新文件清单（移除 9 个废弃文件，新增 paper-editor/structure-tree/detail-panel/interaction-block/anchor-migration-banner 等组件 + anchor-mark/export lib + history/expanded slices）。

005_architecture_data.json: 更新 lesson_preparation 节点——description 改为 V4 描述、dependencies 移除 @xyflow/react 改为 @tiptap/* 包、files 数组移除 9 个废弃文件并新增 V4 组件、auditFixes 新增 V4-PAPER-1~8 + V4-PAPER-DOC 条目。JSON 语法验证通过。
This commit is contained in:
SpecialX
2026-07-04 11:59:39 +08:00
parent 0e4eccec21
commit 5ca2a76e3a
2 changed files with 112 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

63
docs/architecture/005_architecture_data.json
View File

@@ -20330,7 +20330,7 @@
},
"lesson_preparation": {
"path": "src/modules/lesson-preparation",
"description": "教师备课模块（v3 锚点画布）：以课文正文为核心主体（textbook_content 节点置于画布中央，draggable=false 可缩放），教学目标/重难点等 11 种定制节点围绕正文组织。两种锚定机制：range（选择一段文本关联节点，未选中 opacity:0）+ point（插入带圈数字占位符，未选中 opacity:0.3）。锚点连线默认 10% 透明度，选中时完整显示。数据模型 v3：LessonPlanDocument 含 textbookContentNodeId、nodes、edges、anchors 数组。anchor-injector 实现 Markdown 纯文本偏移映射与占位符注入。实时拖动（onNodeDrag 替代 onNodeDragStop）。v1→v2→v3 链式迁移。强制选定教材+章节才能备课（template-picker 四步流程）。保留模板、版本管理、知识点标注、题目创建/拉取、作业发布能力",
"description": "教师备课模块（V4 纸感重构）：抛弃 React Flow 画布，改用三栏布局（260px 结构树 + 1fr 纸感编辑器 + 380px 详情面板）。正文采用 Tiptap 富文本编辑器，锚点从字符串偏移升级为 Tiptap Mark（AnchorMark 区间锚/AnchorPoint 点锚），v3 旧锚点通过 AnchorMigrationBanner 提示失效。doc.version=4，editor-slice 移除 updateNodePosition/connect/setEdges/autoLayout。新增 interaction block（师生交互对话回合，含 designIntent/turns[]/expectedAnswer）。结构树支持节点展开到正文流（expanded-slice）。PrintView 改为按 nodes.order 排序渲染，不再依赖画布。v1→v2→v3→v4 链式迁移。保留模板、版本管理、知识点标注、题目创建/拉取、作业发布、撤销/重做、AI 反馈/差异化、一致性校验、课时安排等能力",
"exports": {
"dataAccess": [
{
@@ -20862,7 +20862,10 @@
"classes",
"files",
"shared/lib/ai",
"@xyflow/react"
"@tiptap/react",
"@tiptap/starter-kit",
"@tiptap/pm",
"@tiptap/extension-image"
],
"files": [
"types.ts",
@@ -20871,13 +20874,17 @@
"lib/type-guards.ts",
"lib/i18n-errors.ts",
"lib/document-migration.ts",
"lib/anchor-injector.ts",
"lib/node-summary.ts",
"lib/rf-mappers.ts",
"lib/anchor-mark.ts",
"lib/export.ts",
"lib/scope-check.ts",
"lib/document-diff.ts",
"config/block-registry.tsx",
"providers/lesson-plan-provider.tsx",
"providers/lesson-plan-provider-setup.tsx",
"services/default-data-service.ts",
"services/default-question-service.ts",
"services/external-questions-bridge.ts",
"data-access.ts",
"data-access-versions.ts",
"data-access-templates.ts",
@@ -20886,6 +20893,7 @@
"actions-publish.ts",
"actions-ai.ts",
"actions-kp.ts",
"actions-questions.ts",
"publish-service.ts",
"ai-suggest.ts",
"seed-templates.ts",
@@ -20893,17 +20901,13 @@
"hooks/editor-slice.ts",
"hooks/selection-slice.ts",
"hooks/version-slice.ts",
"hooks/history-slice.ts",
"hooks/expanded-slice.ts",
"components/lesson-plan-list.tsx",
"components/lesson-plan-card.tsx",
"components/lesson-plan-filters.tsx",
"components/lesson-plan-editor.tsx",
"components/lesson-plan-readonly-view.tsx",
"components/node-editor.tsx",
"components/node-edit-panel.tsx",
"components/nodes/lesson-node.tsx",
"components/nodes/textbook-content-node.tsx",
"components/nodes/anchor-node-selector.tsx",
"components/nodes/textbook-segments.tsx",
"components/lesson-plan-error-boundary.tsx",
"components/lesson-plan-skeleton.tsx",
"components/template-picker.tsx",
@@ -20912,6 +20916,29 @@
"components/question-bank-picker.tsx",
"components/inline-question-editor.tsx",
"components/publish-homework-dialog.tsx",
"components/anchor-migration-banner.tsx",
"components/print-view.tsx",
"components/schedule-dialog.tsx",
"components/consistency-check-dialog.tsx",
"components/ai-feedback-dialog.tsx",
"components/ai-differentiation-dialog.tsx",
"components/curriculum-heatmap.tsx",
"components/version-diff-view.tsx",
"components/version-diff-viewer.tsx",
"components/lesson-plan-mobile-view.tsx",
"components/attachment-picker.tsx",
"components/paper-editor/paper-editor.tsx",
"components/paper-editor/paper-toolbar.tsx",
"components/paper-editor/paper-context-menu.tsx",
"components/paper-editor/textbook-tiptap-editor.tsx",
"components/paper-editor/inline-node.tsx",
"components/paper-editor/inline-qa-dialog.tsx",
"components/structure-tree/structure-tree.tsx",
"components/structure-tree/tree-node-row.tsx",
"components/detail-panel/detail-panel.tsx",
"components/detail-panel/detail-head.tsx",
"components/detail-panel/detail-props.tsx",
"components/detail-panel/qa-editor.tsx",
"components/blocks/rich-text-block.tsx",
"components/blocks/text-study-block.tsx",
"components/blocks/exercise-block.tsx",
@@ -20923,6 +20950,7 @@
"components/blocks/summary-block.tsx",
"components/blocks/homework-block.tsx",
"components/blocks/blackboard-block.tsx",
"components/blocks/interaction-block.tsx",
"components/calendar-view.tsx",
"components/curriculum-map-view.tsx",
"data-access-calendar.ts",
@@ -20933,6 +20961,7 @@
"data-access-substitutes.ts",
"data-access-ai-evaluation.ts",
"data-access-analytics.ts",
"data-access-schedules.ts",
"actions-calendar.ts",
"actions-review.ts",
"actions-comments.ts",
@@ -20940,7 +20969,8 @@
"actions-attachments.ts",
"actions-substitutes.ts",
"actions-ai-evaluation.ts",
"actions-analytics.ts"
"actions-analytics.ts",
"actions-schedules.ts"
],
"i18n": {
"namespace": "lessonPreparation",
@@ -21020,7 +21050,16 @@
"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' 类型"
"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' 类型",
"V4-PAPER-1": "H1 注册 interaction block：config/block-registry.tsx 新增 interaction case，导入 InteractionBlock 组件 + isInteractionBlockData 类型守卫；BLOCK_REGISTRY 支持 12 种 Block 类型（含 V4 interaction）",
"V4-PAPER-2": "H2 三栏布局重构：lesson-plan-editor.tsx 移除 NodeEditor/NodeEditPanel 导入与 JSX，改用 StructureTree + PaperEditor + DetailPanel 三栏布局（grid-template-columns: 260px 1fr 380px），保留顶部工具栏（标题/保存/撤销重做/发布/导出/安排课时/一致性校验/AI 反馈/AI 差异化）+ 5 个对话框（VersionHistoryDrawer/ConsistencyCheckDialog/AiFeedbackDialog/AiDifferentiationDialog/PrintView/ScheduleDialog）；删除 components/node-edit-panel.tsx + app/(dashboard)/teacher/lesson-plans/[planId]/edit/ai-content-generator-slot.tsx（依赖 NodeEditPanel 类型）",
"V4-PAPER-3": "I1 v3 锚点失效 banner：新增 components/anchor-migration-banner.tsx，检测 doc.anchors 中 invalid:true 或含 start 字段的旧锚点并提示用户；通过 key={planId} 实现 planId 变化时重新挂载内部组件，使用 lazy initial state 读取 localStorage（dismiss 状态按 planId 隔离），避免 useEffect 中 setState（符合 V4 react-hooks/set-state-in-effect lint 规则）",
"V4-PAPER-4": "J1 删除废弃文件：删除 8 个 React Flow 画布和字符串锚点相关文件——components/node-editor.tsx、components/nodes/lesson-node.tsx、components/nodes/textbook-content-node.tsx、components/nodes/textbook-segments.tsx、components/nodes/anchor-node-selector.tsx、lib/anchor-injector.ts、lib/rf-mappers.ts、lib/auto-layout.ts；lesson-plan-readonly-view.tsx 重写为委托 LessonPlanMobileView（线性卡片视图）渲染所有视口，移除 React Flow 依赖",
"V4-PAPER-5": "J2 PrintView 适配 V4：lib/export.ts 的 flattenBlockData switch 新增 interaction case + flattenInteraction 函数（输出设计意图 + 师生对话回合 + 预期回答）；export.ts 已使用 nodes.sort((a, b) => a.order - b.order) 按顺序扁平化，无画布依赖；docstring 更新为 12 种 Block（含 V4 interaction）",
"V4-PAPER-6": "J3 lint + tsc 零错误验证：tsc --noEmit 0 错误；lint 中 V4 引入的 react-hooks/set-state-in-effect 错误已通过 anchor-migration-banner.tsx 的 key-based remount + lazy initial state 模式修复；剩余 6 个 lint 错误为预存无关模块问题（exams/use-exam-preview-tasks react-hooks/refs 3 个、template-picker V5-9 set-state-in-effect 1 个），按计划要求记录不修复",
"V4-PAPER-7": "J4 架构图同步：004_architecture_impact_map.md 新增 V4 纸感重构章节；005_architecture_data.json 更新 lesson_preparation 节点——description 改为 V4 描述、dependencies 移除 @xyflow/react 改为 @tiptap/* 包、files 数组移除 9 个废弃文件并新增 V4 组件（paper-editor/structure-tree/detail-panel/interaction-block/anchor-migration-banner/print-view/schedule-dialog/consistency-check-dialog/ai-feedback-dialog/ai-differentiation-dialog/expanded-slice/history-slice/anchor-mark/export/scope-check/document-diff 等）、auditFixes 新增 V4-PAPER-1~7 条目",
"V4-PAPER-8": "J5 known-issues V4 规则：docs/troubleshooting/known-issues.md 新增 V4 纸感重构规则表，记录 8 条规则——React Flow 弃用、Tiptap Mark 锚点替代字符串偏移、setState in effect 禁用（用 key-based remount + lazy initial state 替代）、doc.version=4、editor-slice 移除画布相关方法、interaction block 注册、PrintView 按 order 排序、AnchorMigrationBanner 失效提示",
"V4-PAPER-DOC": "documentVersion 升级为 4：types.ts LessonPlanDocument.version = 4；lib/document-migration.ts normalizeDocument 兼容 v1/v2/v3/v4 链式迁移；editor-slice.ts 移除 updateNodePosition/connect/setEdges/autoLayout 画布相关方法；hooks/expanded-slice.ts 新增 expandedNodeIds/toggleExpand/setExpanded 状态（节点展开到正文流）；lib/anchor-mark.ts 新增 Tiptap AnchorMark + AnchorPoint 扩展（替代 v3 字符串偏移锚点）"
}
},
"error-book": {