NextEdu/docs/superpowers/specs/2026-06-23-lesson-preparation-usage-fixes-design.md

备课模块使用问题修复设计

日期：2026-06-23 前置文档：2026-06-22-lesson-preparation-anchor-canvas-design.md 审计来源：深度分析备课模块现状后发现的使用问题

一、问题背景

备课模块 v3 锚点画布重构已完成，但实际使用中存在 15 个问题（3 个 P0 阻塞性 + 6 个 P1 严重 + 6 个 P2 一般），导致核心流程断裂、角色使用不完整。

核心闭环断裂

教师备课 → 发布课案 → 学生查看 → 家长查看
    ↑         ❌ P0-1     ❌ P0-2/3   ❌ P0-2/3
    无"发布"action   无权限/路由   无权限/路由

二、功能定位

备课模块核心闭环

1. 教师备课：选定教材+章节 → 锚点画布编辑 → 保存版本 → 发布
2. 学生查看：按班级可见 published 课案，只读画布视图
3. 家长查看：通过孩子关系自动可见 published 课案
4. 教研监督：教研组长/年级主任查看本年级教师备课（只读）
5. 管理员管理：全校课案列表 + 统计

三、角色使用矩阵

角色	权限	路由	视图
教师	CREATE/READ/UPDATE/DELETE/PUBLISH	/teacher/lesson-plans	完整编辑画布 + 发布按钮
学生	READ（仅 published）	/student/lesson-plans/[planId]/view	只读画布视图
家长	READ（仅孩子的 published）	/parent/lesson-plans/[planId]/view	只读画布视图
管理员	全部	/admin/lesson-plans	全校课案列表 + 统计
教研组长	READ（本年级教师）	/grade-head/lesson-plans	本年级教师课案列表（只读）
年级主任	READ（本年级教师）	/teaching-head/lesson-plans	同上

学生查看视图设计

只读画布视图：复用 React Flow，配置：

• nodesDraggable={false}
• nodesConnectable={false}
• elementsSelectable={true}（可点击查看节点详情）
• panOnDrag={true}、zoomOnScroll={true}（可缩放平移）

保留正文+节点+锚点的完整视觉关系，学生可缩放平移但不可编辑。

发布机制

• 发布到班级所有学生，家长通过孩子关系自动可见
• 状态流转：draft → published（发布）→ draft（撤回）或 archived（归档）
• 发布后学生/家长立即可见，撤回后立即不可见

四、修复范围（P0+P1 优先）

P0 阻塞性问题

编号	问题	修复方案
P0-1	无"发布课案"action	新增 publishLessonPlanAction / unpublishLessonPlanAction
P0-2	学生/家长无权限	给 student/parent 添加 LESSON_PLAN_READ 权限
P0-3	无学生/家长/管理员路由	新增路由 + 导航入口

P1 严重问题

编号	问题	修复方案
P1-1	锚点节点选择器占位	完善 AnchorNodeSelector，接收节点列表 + 实现"锚定到新节点"
P1-2	锚点偏移计算不可靠	改用 markdownToPlainText 搜索定位，支持跨段落
P1-3	边回写丢失 anchorId	anchorId 存入 edge.data，fromRfEdges 从 data 读取
P1-4	锚点边颜色无区分	使用 getNodeColor(anchor.nodeId)
P1-5	教研组长无权限	给 grade_head/teaching_head 添加 LESSON_PLAN_READ 权限
P1-6	个人模板不显示	TemplatePicker 调用 getLessonPlanTemplatesAction 合并显示

P2 一般问题（本次顺带修复）

编号	问题	修复方案
P2-1	正文节点侧边面板提示误导	改为"请在画布上直接操作正文"或显示锚点列表
P2-5	默认骨架节点位置重叠	增大列间距，避免与正文节点重叠

五、实施阶段

阶段 1：权限与路由基础（P0-2、P0-3、P1-5）

权限修改（shared/lib/permissions.ts）：

• student 数组添加 Permissions.LESSON_PLAN_READ
• parent 数组添加 Permissions.LESSON_PLAN_READ
• grade_head 数组添加 Permissions.LESSON_PLAN_READ
• teaching_head 数组添加 Permissions.LESSON_PLAN_READ

路由新增：

• app/(dashboard)/student/lesson-plans/page.tsx — 课案列表（按班级 published）
• app/(dashboard)/student/lesson-plans/[planId]/view/page.tsx — 只读画布
• app/(dashboard)/parent/lesson-plans/page.tsx — 课案列表（按孩子 published）
• app/(dashboard)/parent/lesson-plans/[planId]/view/page.tsx — 只读画布
• app/(dashboard)/admin/lesson-plans/page.tsx — 全校课案列表 + 统计
• app/(dashboard)/admin/lesson-plans/[planId]/view/page.tsx — 查看任意课案

导航入口（shared/lib/navigation.ts 或 modules/layout/config/navigation.ts）：

• student 导航添加"我的课案"
• parent 导航添加"孩子课案"
• admin 导航添加"课案管理"

只读画布组件：

• 新建 components/lesson-plan-readonly-view.tsx
• 复用 React Flow，配置只读模式
• 复用 toRfNodes / toRfEdges 渲染

阶段 2：发布机制（P0-1）

data-access 新增（data-access.ts）：

export async function publishLessonPlan(planId: string, userId: string): Promise<void>
export async function unpublishLessonPlan(planId: string, userId: string): Promise<void>

actions 新增（actions.ts）：

export async function publishLessonPlanAction(planId: string): Promise<ActionState<string>>
export async function unpublishLessonPlanAction(planId: string): Promise<ActionState<string>>

UI 修改：

• LessonPlanEditor 工具栏添加"发布"/"撤回发布"按钮
• LessonPlanCard 添加"发布"/"撤回"操作菜单项
• 发布时显示确认对话框

阶段 3：锚点交互完善（P1-1、P1-2、P1-3、P1-4）

P1-1 完善 AnchorNodeSelector：

• 接收 doc.nodes 列表（过滤掉 textbook_content）
• 渲染节点下拉选择器（显示节点标题 + 颜色标识）
• 实现"锚定到新节点"：弹出节点类型选择 → 创建节点 → 自动锚定

P1-2 修复锚点偏移计算：

• handleMouseUp 改用 Range.toString() 获取选中文本
• 在 markdownToPlainText(content) 中搜索定位 start/end 偏移
• 支持跨段落、跨行内元素的选择

P1-3 修复 fromRfEdges anchorId 丢失：

• toRfEdges 时将 anchorId 存入 edge.data.anchorId
• fromRfEdges 从 e.data?.anchorId 读取

P1-4 修复锚点边颜色：

• rf-mappers.ts 导入 getNodeColor
• toRfEdges 中 stroke: getNodeColor(anchor.nodeId)

阶段 4：模板与体验（P1-6 + P2）

P1-6 TemplatePicker 显示个人模板：

• 初始化时调用 getLessonPlanTemplatesAction()
• 合并系统模板和个人模板展示
• 个人模板标记"个人"徽章

P2-1 修复正文节点侧边面板：

• NodeEditPanel 选中 textbook_content 时显示锚点列表
• 或显示提示"请在画布上直接操作正文，点击正文选中文本可创建锚点"

P2-5 优化默认骨架节点位置：

• 增大列间距，左列 x=80，右列 x=900
• 正文节点居中 (500, 250)

六、数据模型变更

无数据模型变更。发布机制仅修改 lessonPlans.status 字段（已存在）。

七、i18n 键新增

zh-CN / en grades 命名空间（lesson-preparation.json）

• action.publish / action.unpublish
• action.publishConfirm / action.unpublishConfirm
• action.publishSuccess / action.unpublishSuccess
• status.published / status.draft / status.archived
• readonly.title / readonly.hint
• admin.title / admin.stats / admin.totalPlans / admin.publishedPlans
• gradeHead.title
• anchor.selectNode / anchor.createNode / anchor.nodeTypePrompt

八、架构文档同步

• 004_architecture_impact_map.md：补充路由、权限、新组件
• 005_architecture_data.json：补充 routes、permissions、exports

九、验证标准

• npx tsc --noEmit 零错误
• npm run lint 零错误
• 教师可发布课案，学生/家长可查看 published 课案
• 教研组长可查看本年级教师备课
• 锚点交互完整可用（选中文本 → 选择节点 → 创建锚点）
• 锚点边颜色与关联节点一致