feat: 新增备课模块并修复全模块 P0/P1/P2 缺陷

主要变更: - 新增 lesson-preparation 模块: 备课编辑器、节点编辑、AI 建议、知识点选择、版本历史、作业发布 - 新增 shared 通用组件: charts/question-bank-filters/schedule-list/ui (chip-nav/filter-bar/page-header/stat-card/stat-item) - 新增 student/admin 端 loading.tsx 与 error.tsx, 优化加载与错误态体验 - 新增 teacher/lesson-plans 页面 (列表/新建/编辑) - 新增 drizzle 迁移 0002_tiny_lionheart 及 snapshot - 新增 textbooks/schema.ts 与 exams/utils/normalize-structure.ts - 修复 Tiptap v3 SSR hydration 崩溃 (rich-text-block immediatelyRender: false) - 重构多模块 data-access/actions/组件, 修复权限校验与类型规范 - 同步架构文档 004/005 反映新增模块、导出、依赖关系 - 归档 bugs/* 测试报告与 e2e 测试脚本 (admin/parent/student/teacher web_test)
2026-06-22 01:06:16 +08:00
parent d8962aba96
commit 978d9a8309
327 changed files with 34070 additions and 5642 deletions
--- a/docs/feature/001_first_login_onboarding.md
+++ b/docs/feature/001_first_login_onboarding.md
@@ -0,0 +1,331 @@
+# 首次登录引导（Onboarding）重大问题讨论 · v2
+
+> 版本：**v2**（替代 v1，2026-06-18）
+> 状态：**讨论中，待决策**
+> 关联架构图：`docs/architecture/004_architecture_impact_map.md` §2.1 shared 层 / §3 已知问题 P2-4
+> 关联代码：
+> - [src/shared/components/onboarding-gate.tsx](file:///e:/Desktop/CICD/src/shared/components/onboarding-gate.tsx)（312 行，未变）
+> - [src/app/api/onboarding/status/route.ts](file:///e:/Desktop/CICD/src/app/api/onboarding/status/route.ts)（未变）
+> - [src/app/api/onboarding/complete/route.ts](file:///e:/Desktop/CICD/src/app/api/onboarding/complete/route.ts)（未变）
+> - [src/app/layout.tsx#L41](file:///e:/Desktop/CICD/src/app/layout.tsx#L41)（全局挂载点，未变）
+> - [src/auth.ts](file:///e:/Desktop/CICD/src/auth.ts)（jwt/session 回调，未注入 onboarded）
+> - [src/proxy.ts](file:///e:/Desktop/CICD/src/proxy.ts)（middleware，无 onboarding 拦截）
+
+---
+
+## 〇、v2 与 v1 的差异说明
+
+经 git 核实（`git log` + `git status` + `git diff`），onboarding 相关代码自 v1 审查以来**零改动**：
+- `onboarding-gate.tsx`、`api/onboarding/*/route.ts`、`layout.tsx`、`auth.ts` 均无修改
+- 工作区改动集中在 `proxy.ts`（权限常量替换）、`schema.ts`（新增 lesson_plans 表）等与 onboarding 无关的文件
+
+v2 在 v1 基础上**新增 9 项 v1 遗漏的问题**（标为「v2 新增」），其中含 2 项 P0 级越权漏洞。问题编号沿用 v1，新增项顺延。
+
+---
+
+## 一、背景与定位
+
+按项目规则"先图后码"，从架构影响地图定位 Onboarding 节点：
+
+- **shared 层**：`components/onboarding-gate.tsx`（312 行）已被架构图标记 ⚠️ P2-4「业务逻辑泄漏到 shared」
+- **app 层**：`/api/onboarding/status`、`/api/onboarding/complete` 两条路由
+- **数据层**：`users.onboardedAt`（[schema.ts:41](file:///e:/Desktop/CICD/src/shared/db/schema.ts#L41)）
+- **被调用模块**：`modules/classes/data-access.ts` 的 `enrollStudentByInvitationCode`（学生路径）；教师路径**绕过** `enrollTeacherByInvitationCode` 直接写表
+
+当前实现：全局 Dialog。`app/layout.tsx` 第 41 行无条件挂载 `<OnboardingGate />`，组件内 `useEffect` 拉取 `/api/onboarding/status`，`required === true` 时弹出不可关闭的 4 步 Dialog。
+
+---
+
+## 二、现状代码盘点
+
+### 2.1 组件层（onboarding-gate.tsx）
+
+| 步骤 | 标题 | 采集字段 | 备注 |
+|------|------|----------|------|
+| Step 0 | 角色选择 | role（student/teacher/parent） | admin 只读；其他角色用户可下拉**自选** |
+| Step 1 | 通用信息 | name / phone / address | 仅校验非空 |
+| Step 2 | 角色信息 | classCodes（学生/教师）、teacherSubjects（教师） | 可跳过；家长显示"暂不需要配置" |
+| Step 3 | 完成 | — | 调 `/api/onboarding/complete` 后跳 `/dashboard` |
+
+角色推断逻辑（[第 90-94 行](file:///e:/Desktop/CICD/src/shared/components/onboarding-gate.tsx#L90-L94)）用权限点反推角色。
+
+### 2.2 API 层
+
+- `GET /api/onboarding/status`：查 `users.onboardedAt` + 查 `usersToRoles` 推断角色
+- `POST /api/onboarding/complete`：update users → insert usersToRoles → 学生调 `enrollStudentByInvitationCode` → **教师直接 insert `classSubjectTeachers`** → 写 `onboardedAt`
+
+### 2.3 关键表结构（v2 补充）
+
+| 表 | 主键 | 影响 |
+|----|------|------|
+| `usersToRoles` | `(userId, roleId)` 联合主键（[schema.ts:118](file:///e:/Desktop/CICD/src/shared/db/schema.ts#L118)） | onDuplicateKeyUpdate 无法"替换"角色，只会新增行 → 追加角色 |
+| `classSubjectTeachers` | `(classId, subjectId)` 联合主键（[schema.ts:364](file:///e:/Desktop/CICD/src/shared/db/schema.ts#L364)） | 一个班级一个科目只有一位教师 → onDuplicateKeyUpdate 会**覆盖现有教师** |
+
+---
+
+## 三、重大问题清单（按风险分级）
+
+### 🔴 P0 级：安全/合规/越权
+
+#### P0-1 用户可自选角色（严重越权）
+- **位置**：[onboarding-gate.tsx:192-201](file:///e:/Desktop/CICD/src/shared/components/onboarding-gate.tsx#L192-L201)、[complete/route.ts:32-35](file:///e:/Desktop/CICD/src/app/api/onboarding/complete/route.ts#L32-L35)
+- **问题**：Step 0 允许任意登录用户自选 student/teacher/parent；`complete/route.ts` 直接信任前端 `body.role`。
+- **后果**：任何注册用户可自封 teacher 获得 `exam:create`、`homework:grade` 等权限。
+- **违反**：K12 行业铁律「角色由管理员预分配」、项目规则「Server Action 必须用 `requirePermission()`」。
+
+#### P0-2 教师可绑定任意班级+科目
+- **位置**：[complete/route.ts:95-130](file:///e:/Desktop/CICD/src/app/api/onboarding/complete/route.ts#L95-L130)
+- **问题**：教师通过 `classCodes`（6 位邀请码）可把自己写入任意班级的 `classSubjectTeachers`，`teacherSubjects` 由前端任意提交，服务端仅做"名称存在性"校验。
+- **后果**：教师可越权查看任意班级学生名单、成绩。
+
+#### P0-3 无权限校验、无 Zod、无事务
+- **位置**：[complete/route.ts](file:///e:/Desktop/CICD/src/app/api/onboarding/complete/route.ts) 整文件
+- **问题**：仅检查 `auth()` 登录态，无 `requirePermission()`；用 `String(body.role ?? "")` 手动解析无 Zod（架构图 005 声称"validation: Zod schema"与实际不符）；5 次独立 DB 写入无 `db.transaction()`；运行时 `db.insert(roles)` 创建角色记录（[第 66-68 行](file:///e:/Desktop/CICD/src/app/api/onboarding/complete/route.ts#L66-L68)）属异常路径。
+
+#### P0-4 教师可覆盖现有任课教师（v2 新增，严重破坏）
+- **位置**：[complete/route.ts:124-127](file:///e:/Desktop/CICD/src/app/api/onboarding/complete/route.ts#L124-L127)
+- **问题**：`classSubjectTeachers` 主键为 `(classId, subjectId)`（[schema.ts:364](file:///e:/Desktop/CICD/src/shared/db/schema.ts#L364)），一个班级一个科目只有一位教师。onboarding 用 `onDuplicateKeyUpdate({ set: { teacherId: userId, ... } })`，**会直接覆盖该班级该科目已有的任课教师**。
+- **对比**：`modules/classes/data-access.ts` 的 `enrollTeacherByInvitationCode`（[第 637 行](file:///e:/Desktop/CICD/src/modules/classes/data-access.ts#L637)）有完整校验 `if (mapping?.teacherId && mapping.teacherId !== tid) throw new Error("Subject already assigned")`，且只认领 `teacherId IS NULL` 的空缺位置（[第 657 行](file:///e:/Desktop/CICD/src/modules/classes/data-access.ts#L657)）。onboarding **绕过了该函数**，直接 insert。
+- **后果**：任何自封教师的人可抢占全校任意班级的任课位置，踢掉真实任课教师，篡改任课关系。
+- **违反**：项目规则「modules 之间通过对方 data-access 通信，不直接查询对方 DB 表」。
+
+#### P0-5 角色追加越权（v2 新增）
+- **位置**：[complete/route.ts:82-87](file:///e:/Desktop/CICD/src/app/api/onboarding/complete/route.ts#L82-L87)
+- **问题**：`usersToRoles` 主键为 `(userId, roleId)` 联合主键（[schema.ts:118](file:///e:/Desktop/CICD/src/shared/db/schema.ts#L118)）。`db.insert(usersToRoles).values({ userId, roleId }).onDuplicateKeyUpdate({ set: { roleId } })` 中，`set roleId` 无意义（roleId 已是要插入的值）。当用户已有其他 roleId 时，此操作**新增一行**而非替换——即**追加角色记录**。
+- **后果**：学生自选 teacher 角色后，给自己追加一条 teacher 角色行；`auth.ts` 的 `resolvePermissions(allRoles)` 会合并所有角色权限（[auth.ts:131](file:///e:/Desktop/CICD/src/auth.ts#L131)），学生因此获得 teacher 全部权限。结合 P0-1，这是完整的权限提升链。
+- **修复方向**：onboarding 不应写 `usersToRoles`，角色分配由管理员后台处理。
+
+### 🟠 P1 级：架构违规
+
+#### P1-1 shared 层反向承载领域逻辑
+- **位置**：[onboarding-gate.tsx](file:///e:/Desktop/CICD/src/shared/components/onboarding-gate.tsx) 整文件
+- **问题**：位于 `shared/components/`，含角色判断、班级代码、教师科目配置等强领域逻辑，通过 fetch 调用业务 API。
+- **违反**：项目规则「shared 不得反向依赖 @/auth、@/proxy 或任何 modules/*」。
+- **架构图标记**：004 文档 §2.1 已标记 P2-4。
+
+#### P1-2 app 层 API 直接跨模块写表
+- **位置**：[complete/route.ts:6](file:///e:/Desktop/CICD/src/app/api/onboarding/complete/route.ts#L6)
+- **问题**：直接 import 并写入 `classes`、`classSubjectTeachers`、`subjects` 表，绕过 `modules/classes` 的 data-access 与权限校验。
+- **违反**：项目规则「app 只能调用 modules 的 Server Actions 和 data-access」「modules 之间通过对方 data-access 通信」。
+
+#### P1-3 角色推断双源不一致
+- **位置**：[status/route.ts:29-41](file:///e:/Desktop/CICD/src/app/api/onboarding/status/route.ts#L29-L41) vs [onboarding-gate.tsx:90-94](file:///e:/Desktop/CICD/src/shared/components/onboarding-gate.tsx#L90-L94)
+- **问题**：status API 用 `roles.name` 推断（含 `grade_head/teaching_head → teacher` 归一化），组件用权限点重新推断，两套逻辑可能不一致。
+
+#### P1-4 auth.ts 未注入 onboarded 状态（v2 新增）
+- **位置**：[auth.ts:122-177](file:///e:/Desktop/CICD/src/auth.ts#L122-L177) jwt/session 回调
+- **问题**：jwt 回调每次刷新都查 `users.name` + `usersToRoles` + `roles` 三张表（[第 143-153 行](file:///e:/Desktop/CICD/src/auth.ts#L143-L153)），但**只读 `name`，未读 `onboardedAt`**，token 里永远没有 onboarding 状态。
+- **后果链**：
+  1. `proxy.ts`（middleware）用 `getToken` 读 token，无法判断 onboarded → 无法做重定向拦截
+  2. `status/route.ts` 必须每次查库判断 `required` → 性能损耗
+  3. 客户端无法从 `session.user` 读取 onboarded → 必须额外 fetch
+  4. `onFinish` 调 `update()` 后，token 刷新但 onboarded 仍未注入 → 即便有 middleware 也拦不住
+- **修复方向**：jwt 回调 `columns: { name: true, onboardedAt: true }`，注入 `token.onboarded = !!fresh.onboardedAt`；session 回调暴露 `session.user.onboarded`。
+
+#### P1-5 onboarding 绕过 classes 模块封装（v2 新增）
+- **位置**：[complete/route.ts:95-130](file:///e:/Desktop/CICD/src/app/api/onboarding/complete/route.ts#L95-L130)
+- **问题**：`modules/classes/data-access.ts` 已提供 `enrollTeacherByInvitationCode`（[第 589 行](file:///e:/Desktop/CICD/src/modules/classes/data-access.ts#L589)），含「教师身份校验」「科目已分配校验」「只认领空缺位置」等安全逻辑。onboarding **未调用它**，而是直接 insert `classSubjectTeachers`，绕过全部校验。
+- **后果**：与 P0-4 叠加，形成完整越权路径。
+- **违反**：项目规则「modules 之间通过对方 data-access 通信」。
+
+### 🟡 P2 级：用户体验与可访问性
+
+#### P2-1 全局 Dialog 模式缺陷
+- 不可关闭（`canClose = !required`）；刷新丢步；无独立 URL；首屏无骨架屏；`useEffect` 拉取期间闪烁。
+- **对比**：业界主流（Auth.js 官方、Clerk、Vercel 模板）均采用独立路由 `/onboarding` + middleware 重定向。
+
+#### P2-2 表单校验粗糙
+- 电话仅校验非空（无手机号格式）；姓名/地址无长度限制；班级代码无格式预校验。
+
+#### P2-3 国际化与可访问性
+- 中英文混合（"Role"、"Select role" 英文）；Dialog 缺 `aria-describedby`；进度条无 `aria-valuenow`。
+
+#### P2-4 进度条与步骤不一致
+- admin 跳过 Step 2，但进度条仍渲染 4 段，Step 2 永远亮起。
+
+#### P2-5 完成跳转硬编码 /dashboard（v2 新增）
+- **位置**：[onboarding-gate.tsx:154](file:///e:/Desktop/CICD/src/shared/components/onboarding-gate.tsx#L154)
+- **问题**：`router.push("/dashboard")` 硬编码，但 [proxy.ts:23-30](file:///e:/Desktop/CICD/src/proxy.ts#L23-L30) 的 `resolveDefaultPath` 按角色返回 `/admin/dashboard`、`/teacher/dashboard`、`/student/dashboard`、`/parent/dashboard`。
+- **后果**：非 admin 用户完成 onboarding 后跳 `/dashboard`（不存在），被 proxy 权限检查拦截后重定向，体验为"完成→闪跳→再跳"。
+
+#### P2-6 家长角色推断死锁（v2 新增）
+- **位置**：[onboarding-gate.tsx:90-94](file:///e:/Desktop/CICD/src/shared/components/onboarding-gate.tsx#L90-L94)
+- **问题**：
+  ```ts
+  const isTeacher = permissions.includes(EXAM_CREATE)
+  const isStudent = permissions.includes(HOMEWORK_SUBMIT) && !permissions.includes(EXAM_CREATE)
+  const isParent = !EXAM_CREATE && !HOMEWORK_SUBMIT && permissions.includes(EXAM_READ)
+  ```
+  - `isTeacher` 先判断且包含 `EXAM_READ`（teacher 有 EXAM_READ），家长条件 `!EXAM_CREATE && EXAM_READ` 与 teacher 重叠
+  - 实际角色权限映射中，parent 是否有 `EXAM_READ` 存疑；若 parent 无 `EXAM_READ`，则 `isParent` 永远为 false → 家长在 Step 2 看到"暂不需要配置"的分支永远不触发，可能落到空白页
+- **后果**：家长角色无法被正确识别，Step 2 渲染异常。
+
+#### P2-7 学生注册无错误处理（v2 新增）
+- **位置**：[complete/route.ts:89-93](file:///e:/Desktop/CICD/src/app/api/onboarding/complete/route.ts#L89-L93)
+- **问题**：`enrollStudentByInvitationCode` 会 throw（如无效邀请码），但无 try/catch。一个无效码导致整个请求 500，而前面的 `update users` 已执行（无事务）→ 用户 name/phone 已更新但 `onboardedAt` 仍为 null → 下次登录反复弹窗且数据不一致。
+
+#### P2-8 useEffect 依赖导致重复弹窗（v2 新增）
+- **位置**：[onboarding-gate.tsx:45-68](file:///e:/Desktop/CICD/src/shared/components/onboarding-gate.tsx#L45-L68)
+- **问题**：useEffect 依赖 `[status, session?.user?.name]`。`auth.ts` jwt 回调每次刷新会重读 `users.name` 并写入 token（[auth.ts:158](file:///e:/Desktop/CICD/src/auth.ts#L158)），若 name 变化（如管理员改了用户名），session.user.name 变化触发 useEffect 重新拉取 status → 可能重复弹窗。
+
+#### P2-9 不可关闭 Dialog 的冗余 effect（v2 新增）
+- **位置**：[onboarding-gate.tsx:70-74](file:///e:/Desktop/CICD/src/shared/components/onboarding-gate.tsx#L70-L74)
+- **问题**：
+  ```ts
+  useEffect(() => {
+    if (!open) return
+    if (!required) return
+    setOpen(true)  // 冗余：open 已为 true
+  }, [open, required])
+  ```
+  此 effect 在 open 被 Dialog 的 `onOpenChange` 关闭时强制重开，实现"不可关闭"。但逻辑脆弱：若 required 在异步中变化，可能产生状态竞态。应改为在 `onOpenChange` 中直接判断 `if (!canClose) return`。
+
+---
+
+## 四、业界大仓（Monorepo）解决方案引用
+
+### 4.1 Auth.js v5 官方推荐
+
+- **状态标记**：`users.onboardedAt` + `jwt`/`session` 回调注入；完成时调 `update()` 刷新 token。
+- **强制方式**：**middleware 重定向**到独立 `/onboarding` 路由。在 `proxy.ts`（Next.js 16 的 middleware）用 `getToken` 读取 `onboarded`，未完成且非白名单路径 → `NextResponse.redirect('/onboarding')`。
+- **结论**：客户端 Dialog 仅适合"非阻塞偏好补全"；强制 onboarding 应等同未登录处理。
+
+### 4.2 商业方案（Clerk / Supabase / Auth0）共性
+
+三段式：**metadata 标记 + 强制重定向独立路由 + 服务端 Action 校验**。
+- 角色等敏感字段放服务端可写的 metadata，**禁止前端自写**。
+- onboarding 完成回调必须由服务端 Action 写入，前端不能直接改。
+
+### 4.3 shadcn/ui 生态
+
+- 官方无内置 Stepper，但 `examples/forms` 与 `blocks` 范式明确：**独立路由页面 + `<Form>`（react-hook-form + zod）+ 父组件持 step state**。
+- 每步独立 zod schema 渐进式校验，最后一步汇总写入。
+
+### 4.4 企业级 K12 教务系统（PowerSchool / Veracross / 国内智慧校园）
+
+**铁律：角色由管理员预分配，用户不可自选。**
+
+| 角色 | 首次登录采集字段 | 角色来源 |
+|------|------------------|----------|
+| 学生 | 学号（预分配不可改）、姓名、性别、出生日期、家长联系方式、紧急联系人 | 管理员批量导入 |
+| 教师 | 工号（预分配）、姓名、所教科目、任教班级、办公室、联系电话、学历资质 | 教务处预分配 |
+| 家长 | 与学生关系、学生学号（通过 **Access ID + Access Password** 绑定）、本人姓名、电话、邮箱 | 学校发放凭证，家长绑定子女 |
+| 管理员 | 工号、姓名、职务、管理范围 | 学校 IT 创建 |
+
+### 4.5 Monorepo（turborepo / nx）惯例
+
+- 跨模块"流程型"功能（onboarding、setup-wizard）作为**独立 module**，而非塞进 shared。
+- nx feature-shell 模式：onboarding 作为 `feature-onboarding` library，依赖 `data-access-user`、`data-access-class`。
+- Vercel 自家项目：`app/(app)/onboarding/[[...step]]/page.tsx` 路由组 + `modules/onboarding/` 模块。
+
+---
+
+## 五、重构方案建议（待讨论）
+
+### 5.1 目标架构
+
+```
+app/
+├─ (auth)/login/                    # 登录页（proxy 白名单）
+├─ (onboarding)/onboarding/         # 新增独立路由
+│  └─ page.tsx                      # 服务端组件，读 session.onboarded 决定渲染
+└─ proxy.ts                         # 增强：未 onboarded 时重定向
+
+modules/onboarding/                 # 新建模块
+├─ actions.ts                       # completeOnboardingAction（Server Action + requirePermission）
+├─ data-access.ts                   # 仅操作 users.onboardedAt
+├─ schema.ts                        # Zod：name/phone/address/classCodes
+├─ types.ts
+└─ components/
+   ├─ OnboardingStepper.tsx
+   ├─ RoleConfirmStep.tsx           # 只读展示管理员分配的角色
+   ├─ ProfileStep.tsx               # 姓名/电话/住址
+   └─ BindingStep.tsx               # 学生：确认班级；教师：确认任课；家长：绑定子女
+
+shared/
+└─ components/onboarding-gate.tsx   # 删除
+```
+
+### 5.2 关键改动点
+
+1. **auth.ts 回调注入 onboarded**（P1-4）：jwt 回调 `columns: { name: true, onboardedAt: true }`，`token.onboarded = !!fresh.onboardedAt`；session 回调暴露 `session.user.onboarded`。
+2. **proxy.ts 增加 onboarding 拦截**：读 `token.onboarded`，未完成且路径不在白名单（`/login`、`/api/auth`、`/onboarding`、静态资源）→ 重定向 `/onboarding`。
+3. **删除 `shared/components/onboarding-gate.tsx`**，从 `app/layout.tsx` 移除挂载。
+4. **新建 `modules/onboarding/`**，承载所有领域逻辑。
+5. **新建 `app/(onboarding)/onboarding/page.tsx`** 独立路由。
+6. **删除 `app/api/onboarding/*/route.ts`**，改为 `modules/onboarding/actions.ts` 的 Server Action。
+7. **角色只读化**（P0-1/P0-5）：Step 0 改为"角色确认"——只读展示 `usersToRoles` 中的角色，用户不可改；**onboarding 不写 `usersToRoles`**。
+8. **班级绑定改造**（P0-2/P0-4/P1-5）：
+   - 学生：仅"确认"管理员预分配的班级，或输入邀请码（调 `enrollStudentByInvitationCode`）
+   - 教师：**必须调 `enrollTeacherByInvitationCode`**（含"Subject already assigned"校验），禁止直接 insert；理想方案是仅"确认"管理员预分配
+   - 家长：输入"子女学号 + 绑定码"绑定子女（参考 PowerSchool Access ID 模式）
+9. **事务化**（P0-3/P2-7）：`completeOnboardingAction` 用 `db.transaction()` 包裹所有写入，`onboardedAt` 在事务最后写入。
+10. **Zod 校验**（P0-3）：`onboardingSchema`，phone 用 `z.string().regex(/^1\d{10}$/)`，name `z.string().min(1).max(50)`，address `z.string().max(200).optional()`。
+11. **完成跳转修正**（P2-5）：用 `resolveDefaultPath(roles)` 替代硬编码 `/dashboard`。
+12. **角色推断统一**（P1-3/P2-6）：删除组件内的权限点反推逻辑，统一从 `session.user.roles`（auth.ts 已注入）读取。
+
+### 5.3 迁移兼容
+
+- 已 onboarded 用户（`onboardedAt` 非空）不受影响，proxy 直接放行。
+- 未 onboarded 用户下次登录被重定向到 `/onboarding`（而非弹 Dialog）。
+- 无需数据迁移，`users.onboardedAt` 字段保留。
+
+---
+
+## 六、待决策的开放问题
+
+### Q1：角色分配策略
+- **方案 A**（推荐，符合 K12 铁律）：onboarding 中角色完全只读，由管理员后台预分配；用户无法改变角色。
+- **方案 B**：保留角色选择，但服务端校验"用户已有该角色"才允许（即只能从已有角色中选主角色）。
+- **方案 C**：暂不改动角色选择，仅修复其他问题。
+
+### Q2：教师任课关系绑定
+- **方案 A**（推荐）：onboarding 中教师**仅确认**管理员预分配的任课关系，不自填班级代码。
+- **方案 B**：保留自填邀请码，但**必须调 `enrollTeacherByInvitationCode`**（含"Subject already assigned"校验），禁止直接 insert。
+- **方案 C**：完全移除 onboarding 中的班级绑定，统一由管理员后台处理。
+
+### Q3：家长绑定子女方式
+- **方案 A**（推荐，PowerSchool 模式）：家长输入"子女学号 + 学校发放的 6 位绑定码"。
+- **方案 B**：家长输入"子女学号 + 子女生日"作为验证。
+- **方案 C**：暂不实现家长绑定，由管理员后台预绑定。
+
+### Q4：onboarding 路由形态
+- **方案 A**（推荐）：单页 `/onboarding` + 客户端 stepper（步骤状态用 query param 持久化）。
+- **方案 B**：嵌套路由 `/onboarding/role`、`/onboarding/profile`、`/onboarding/binding`（每步独立 Server Action）。
+- **方案 C**：保留全局 Dialog，仅修复安全与架构问题。
+
+### Q5：实施范围
+- **方案 A**：一次性完成 P0 + P1 + P2 全部整改。
+- **方案 B**（推荐）：先做 P0（安全/越权）+ P1（架构），P2（UX）后续迭代。
+- **方案 C**：仅做 P0 紧急修复，P1/P2 列入 backlog。
+
+### Q6：auth.ts jwt 回调性能（v2 新增）
+jwt 回调每次刷新查 3 张表（[auth.ts:143-153](file:///e:/Desktop/CICD/src/auth.ts#L143-L153)）。注入 onboarded 可复用此次查库，但是否同步优化为「仅在登录时全量查、刷新时轻量查」？
+- **方案 A**：复用现有查库，只加 `onboardedAt` 字段（最小改动）。
+- **方案 B**：重构为登录时全量、刷新时只查 `onboardedAt`（优化性能）。
+
+---
+
+## 七、附录：问题与代码位置速查
+
+| 编号 | 问题 | 代码位置 | 风险 | v2 新增 |
+|------|------|----------|------|---------|
+| P0-1 | 用户自选角色 | [onboarding-gate.tsx:192-201](file:///e:/Desktop/CICD/src/shared/components/onboarding-gate.tsx#L192-L201) | 🔴 | |
+| P0-2 | 教师绑任意班级 | [complete/route.ts:95-130](file:///e:/Desktop/CICD/src/app/api/onboarding/complete/route.ts#L95-L130) | 🔴 | |
+| P0-3 | 无权限校验/Zod/事务 | [complete/route.ts](file:///e:/Desktop/CICD/src/app/api/onboarding/complete/route.ts) 整文件 | 🔴 | |
+| P0-4 | 教师覆盖现有任课教师 | [complete/route.ts:124-127](file:///e:/Desktop/CICD/src/app/api/onboarding/complete/route.ts#L124-L127) | 🔴 | ✅ |
+| P0-5 | 角色追加越权 | [complete/route.ts:82-87](file:///e:/Desktop/CICD/src/app/api/onboarding/complete/route.ts#L82-L87) | 🔴 | ✅ |
+| P1-1 | shared 反向承载领域逻辑 | [onboarding-gate.tsx](file:///e:/Desktop/CICD/src/shared/components/onboarding-gate.tsx) 整文件 | 🟠 | |
+| P1-2 | app 层跨模块写表 | [complete/route.ts:6](file:///e:/Desktop/CICD/src/app/api/onboarding/complete/route.ts#L6) | 🟠 | |
+| P1-3 | 角色推断双源不一致 | [status/route.ts:29-41](file:///e:/Desktop/CICD/src/app/api/onboarding/status/route.ts#L29-L41) vs [onboarding-gate.tsx:90-94](file:///e:/Desktop/CICD/src/shared/components/onboarding-gate.tsx#L90-L94) | 🟠 | |
+| P1-4 | auth 未注入 onboarded | [auth.ts:143-153](file:///e:/Desktop/CICD/src/auth.ts#L143-L153) | 🟠 | ✅ |
+| P1-5 | 绕过 classes 模块封装 | [complete/route.ts:95-130](file:///e:/Desktop/CICD/src/app/api/onboarding/complete/route.ts#L95-L130) | 🟠 | ✅ |
+| P2-1 | 全局 Dialog 缺陷 | [app/layout.tsx:41](file:///e:/Desktop/CICD/src/app/layout.tsx#L41) | 🟡 | |
+| P2-2 | 表单校验粗糙 | [onboarding-gate.tsx:88](file:///e:/Desktop/CICD/src/shared/components/onboarding-gate.tsx#L88) | 🟡 | |
+| P2-3 | i18n/a11y | [onboarding-gate.tsx:188-194](file:///e:/Desktop/CICD/src/shared/components/onboarding-gate.tsx#L188-L194) | 🟡 | |
+| P2-4 | 进度条与步骤不一致 | [onboarding-gate.tsx:179-184](file:///e:/Desktop/CICD/src/shared/components/onboarding-gate.tsx#L179-L184) | 🟡 | |
+| P2-5 | 完成跳转硬编码 /dashboard | [onboarding-gate.tsx:154](file:///e:/Desktop/CICD/src/shared/components/onboarding-gate.tsx#L154) | 🟡 | ✅ |
+| P2-6 | 家长角色推断死锁 | [onboarding-gate.tsx:90-94](file:///e:/Desktop/CICD/src/shared/components/onboarding-gate.tsx#L90-L94) | 🟡 | ✅ |
+| P2-7 | 学生注册无错误处理 | [complete/route.ts:89-93](file:///e:/Desktop/CICD/src/app/api/onboarding/complete/route.ts#L89-L93) | 🟡 | ✅ |
+| P2-8 | useEffect 重复弹窗 | [onboarding-gate.tsx:45-68](file:///e:/Desktop/CICD/src/shared/components/onboarding-gate.tsx#L45-L68) | 🟡 | ✅ |
+| P2-9 | 冗余不可关闭 effect | [onboarding-gate.tsx:70-74](file:///e:/Desktop/CICD/src/shared/components/onboarding-gate.tsx#L70-L74) | 🟡 | ✅ |
--- a/docs/feature/f_bk.md
+++ b/docs/feature/f_bk.md
@@ -0,0 +1,412 @@
+<!DOCTYPE html>
+
+<html class="light" lang="en"><head>
+<meta charset="utf-8"/>
+<meta content="width=device-width, initial-scale=1.0" name="viewport"/>
+<title>Chinese Education Suite - Text Study</title>
+<script src="https://cdn.tailwindcss.com?plugins=forms,container-queries"></script>
+<link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:wght,FILL@100..700,0..1&amp;display=swap" rel="stylesheet"/>
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;900&amp;family=JetBrains+Mono:wght@400&amp;display=swap" rel="stylesheet"/>
+<link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:wght,FILL@100..700,0..1&amp;display=swap" rel="stylesheet"/>
+<script id="tailwind-config">
+        tailwind.config = {
+            darkMode: "class",
+            theme: {
+                extend: {
+                    "colors": {
+                        "surface-container-highest": "#e4e2e2",
+                        "error-container": "#ffdad6",
+                        "primary-fixed": "#d4e3ff",
+                        "primary": "#005dac",
+                        "secondary-fixed-dim": "#ffb786",
+                        "primary-fixed-dim": "#a5c8ff",
+                        "secondary": "#964900",
+                        "primary-container": "#1976d2",
+                        "surface-container-low": "#f5f3f3",
+                        "on-tertiary-fixed": "#002204",
+                        "on-surface-variant": "#414752",
+                        "on-surface": "#1b1c1c",
+                        "tertiary": "#0d6c1e",
+                        "on-primary-fixed-variant": "#004786",
+                        "inverse-surface": "#303031",
+                        "secondary-container": "#fc820c",
+                        "on-secondary-fixed-variant": "#723600",
+                        "surface": "#fbf9f8",
+                        "error": "#ba1a1a",
+                        "background": "#fbf9f8",
+                        "on-primary-fixed": "#001c3a",
+                        "on-secondary-fixed": "#311300",
+                        "on-primary-container": "#fffdff",
+                        "outline-variant": "#c1c6d4",
+                        "on-tertiary": "#ffffff",
+                        "tertiary-fixed": "#9df898",
+                        "on-error-container": "#93000a",
+                        "surface-variant": "#e4e2e2",
+                        "tertiary-container": "#2f8635",
+                        "surface-container-lowest": "#ffffff",
+                        "on-tertiary-fixed-variant": "#005312",
+                        "surface-tint": "#005faf",
+                        "on-background": "#1b1c1c",
+                        "surface-bright": "#fbf9f8",
+                        "outline": "#717783",
+                        "on-tertiary-container": "#fdfff7",
+                        "inverse-primary": "#a5c8ff",
+                        "on-secondary-container": "#5e2c00",
+                        "on-secondary": "#ffffff",
+                        "surface-dim": "#dbdad9",
+                        "surface-container": "#efeded",
+                        "secondary-fixed": "#ffdcc6",
+                        "on-primary": "#ffffff",
+                        "on-error": "#ffffff",
+                        "tertiary-fixed-dim": "#82db7e",
+                        "surface-container-high": "#e9e8e7",
+                        "inverse-on-surface": "#f2f0f0"
+                    },
+                    "borderRadius": {
+                        "DEFAULT": "0.125rem",
+                        "lg": "0.25rem",
+                        "xl": "0.5rem",
+                        "full": "0.75rem"
+                    },
+                    "spacing": {
+                        "xl": "32px",
+                        "sidebar_width": "80px",
+                        "sidebar_width_hover": "280px",
+                        "grid_columns": "12",
+                        "gutter": "24px",
+                        "2xl": "48px",
+                        "xs": "8px",
+                        "md": "16px",
+                        "lg": "24px",
+                        "sm": "12px",
+                        "base": "4px"
+                    },
+                    "fontFamily": {
+                        "title-lg": ["Inter"],
+                        "display-lg": ["Inter"],
+                        "code-md": ["JetBrains Mono"],
+                        "body-lg": ["Inter"],
+                        "headline-lg-mobile": ["Inter"],
+                        "headline-md": ["Inter"],
+                        "label-md": ["Inter"],
+                        "headline-lg": ["Inter"],
+                        "title-md": ["Inter"],
+                        "body-md": ["Inter"]
+                    },
+                    "fontSize": {
+                        "title-lg": ["20px", { "lineHeight": "28px", "fontWeight": "600" }],
+                        "display-lg": ["48px", { "lineHeight": "56px", "letterSpacing": "-0.02em", "fontWeight": "700" }],
+                        "code-md": ["14px", { "lineHeight": "20px", "fontWeight": "400" }],
+                        "body-lg": ["16px", { "lineHeight": "26px", "fontWeight": "400" }],
+                        "headline-lg-mobile": ["24px", { "lineHeight": "32px", "fontWeight": "600" }],
+                        "headline-md": ["24px", { "lineHeight": "32px", "fontWeight": "600" }],
+                        "label-md": ["12px", { "lineHeight": "16px", "letterSpacing": "0.05em", "fontWeight": "500" }],
+                        "headline-lg": ["32px", { "lineHeight": "40px", "letterSpacing": "-0.01em", "fontWeight": "600" }],
+                        "title-md": ["16px", { "lineHeight": "24px", "fontWeight": "600" }],
+                        "body-md": ["14px", { "lineHeight": "22px", "fontWeight": "400" }]
+                    }
+                }
+            }
+        }
+    </script>
+<style>
+        .text-reading-chinese {
+            font-family: "KaiTi", "STKaiti", serif;
+            line-height: 2.2;
+            letter-spacing: 0.05em;
+        }
+        .annotation-highlight-yellow {
+            background-color: rgba(252, 130, 12, 0.2);
+            border-bottom: 2px dashed #fc820c;
+            transition: all 0.2s ease;
+        }
+        .annotation-highlight-yellow.active {
+            background-color: rgba(252, 130, 12, 0.4);
+            box-shadow: 0 0 0 2px rgba(252, 130, 12, 0.5);
+        }
+        .annotation-highlight-green {
+            background-color: rgba(47, 134, 53, 0.15);
+            border-bottom: 2px dashed #2f8635;
+            transition: all 0.2s ease;
+        }
+        .annotation-highlight-green.active {
+            background-color: rgba(47, 134, 53, 0.3);
+            box-shadow: 0 0 0 2px rgba(47, 134, 53, 0.5);
+        }
+        .floating-toolbar {
+            box-shadow: 0px 4px 12px rgba(0,0,0,0.08);
+            backdrop-filter: blur(8px);
+        }
+        .node-canvas-bg {
+            background-image: radial-gradient(var(--tw-colors-outline-variant) 1px, transparent 1px);
+            background-size: 24px 24px;
+            background-position: -12px -12px;
+        }
+        
+        .sidebar-collapsed {
+            width: 80px;
+            transition: width 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+        }
+        .sidebar-collapsed:hover {
+            width: 280px;
+        }
+        .sidebar-collapsed .sidebar-text {
+            opacity: 0;
+            transform: translateX(-10px);
+            transition: opacity 0.2s ease, transform 0.2s ease;
+            white-space: nowrap;
+        }
+        .sidebar-collapsed:hover .sidebar-text {
+            opacity: 1;
+            transform: translateX(0);
+            transition-delay: 0.1s;
+        }
+        .sidebar-collapsed .sidebar-header-compact {
+            display: flex;
+            transition: opacity 0.2s ease;
+        }
+        .sidebar-collapsed:hover .sidebar-header-compact {
+            display: none;
+            opacity: 0;
+        }
+        .sidebar-collapsed .sidebar-header-full {
+            display: none;
+            opacity: 0;
+            transition: opacity 0.2s ease;
+        }
+        .sidebar-collapsed:hover .sidebar-header-full {
+            display: flex;
+            opacity: 1;
+            transition-delay: 0.1s;
+        }
+
+        .connection-line {
+            stroke-dasharray: 6 6;
+            animation: dash 20s linear infinite;
+        }
+        @keyframes dash {
+            to {
+                stroke-dashoffset: -100;
+            }
+        }
+    </style>
+</head>
+<body class="bg-background text-on-background antialiased font-body-md overflow-hidden flex">
+<!-- SideNavBar (Shared Component) - Collapsed by Default -->
+<nav class="bg-surface-container-low border-r border-outline-variant fixed left-0 top-0 h-full sidebar-collapsed flex flex-col z-40 overflow-hidden shadow-[4px_0_12px_rgba(0,0,0,0.05)]">
+<!-- Header Profile/Brand Area -->
+<div class="p-lg border-b border-outline-variant min-h-[140px] flex flex-col justify-center">
+<!-- Compact Header (Icon only) -->
+<div class="sidebar-header-compact justify-center items-center h-full">
+<img class="w-10 h-10 rounded-full object-cover" data-alt="A small, professional portrait avatar of an elementary school teacher, wearing a neat blouse, softly lit with a friendly expression. The background is a clean, bright, out-of-focus classroom setting. Light, optimistic, modern educational aesthetic." src="https://lh3.googleusercontent.com/aida-public/AB6AXuCPm6ajyPls5KuN3NyxyIsYDJjwr4nGreE-xX_wJmhJXxEoloRJliDYKXVHc7pGX7V0JzgMspJ1gypOgUa9gsueX9F6-v1Nyq-yoOajjl5IkVUK-EcPVN1I_QOnZDkoyS-bKMM6bqTmwvjNT-Qeg3ZCLwAbQIVkGSlqmQcXG5XlZ3oHBtVYgcYOZpbEMegS75pxILeSysUPGRhfOxl3LerA0SoAsTgOTo6nIq7AcBzAmmGN_Qjst-6n5EeWdIni83vKOeYjHpOPyuc"/>
+</div>
+<!-- Full Header -->
+<div class="sidebar-header-full flex-col gap-sm">
+<div class="flex items-center gap-sm">
+<img class="w-10 h-10 rounded-full object-cover shrink-0" data-alt="A small, professional portrait avatar of an elementary school teacher, wearing a neat blouse, softly lit with a friendly expression. The background is a clean, bright, out-of-focus classroom setting. Light, optimistic, modern educational aesthetic." src="https://lh3.googleusercontent.com/aida-public/AB6AXuCPm6ajyPls5KuN3NyxyIsYDJjwr4nGreE-xX_wJmhJXxEoloRJliDYKXVHc7pGX7V0JzgMspJ1gypOgUa9gsueX9F6-v1Nyq-yoOajjl5IkVUK-EcPVN1I_QOnZDkoyS-bKMM6bqTmwvjNT-Qeg3ZCLwAbQIVkGSlqmQcXG5XlZ3oHBtVYgcYOZpbEMegS75pxILeSysUPGRhfOxl3LerA0SoAsTgOTo6nIq7AcBzAmmGN_Qjst-6n5EeWdIni83vKOeYjHpOPyuc"/>
+<div class="sidebar-text">
+<h2 class="font-headline-md text-headline-md font-bold text-primary">Lesson Planner</h2>
+<p class="font-body-md text-body-md text-on-surface-variant">Primary Chinese</p>
+</div>
+</div>
+<button class="mt-md bg-primary-container text-on-primary-container font-label-md text-label-md py-sm px-md rounded-lg flex items-center justify-center gap-xs hover:opacity-90 transition-opacity sidebar-text w-full">
+<span class="material-symbols-outlined text-[18px]">add</span>
+                New Lesson Plan
+            </button>
+</div>
+</div>
+<!-- Navigation Links -->
+<div class="flex-1 overflow-y-auto py-md">
+<ul class="flex flex-col gap-base px-sm">
+<!-- Text Study (ACTIVE) -->
+<li>
+<a class="flex items-center gap-sm px-md py-sm rounded-lg text-primary font-bold border-l-4 border-primary bg-primary-container/10 transition-transform duration-150" href="#">
+<span class="material-symbols-outlined shrink-0" style="font-variation-settings: 'FILL' 1;">book</span>
+<span class="font-title-md text-title-md sidebar-text">Text Study</span>
+</a>
+</li>
+<!-- Objectives (INACTIVE) -->
+<li>
+<a class="flex items-center gap-sm px-md py-sm rounded-lg text-on-surface-variant hover:bg-surface-container-highest transition-colors" href="#">
+<span class="material-symbols-outlined shrink-0">target</span>
+<span class="font-title-md text-title-md sidebar-text">Objectives</span>
+</a>
+</li>
+<!-- Teaching Process (INACTIVE) -->
+<li>
+<a class="flex items-center gap-sm px-md py-sm rounded-lg text-on-surface-variant hover:bg-surface-container-highest transition-colors" href="#">
+<span class="material-symbols-outlined shrink-0">school</span>
+<span class="font-title-md text-title-md sidebar-text">Teaching Process</span>
+</a>
+</li>
+<!-- Blackboard Design (INACTIVE) -->
+<li>
+<a class="flex items-center gap-sm px-md py-sm rounded-lg text-on-surface-variant hover:bg-surface-container-highest transition-colors" href="#">
+<span class="material-symbols-outlined shrink-0">draw</span>
+<span class="font-title-md text-title-md sidebar-text">Blackboard Design</span>
+</a>
+</li>
+<!-- Resources (INACTIVE) -->
+<li>
+<a class="flex items-center gap-sm px-md py-sm rounded-lg text-on-surface-variant hover:bg-surface-container-highest transition-colors" href="#">
+<span class="material-symbols-outlined shrink-0">folder_open</span>
+<span class="font-title-md text-title-md sidebar-text">Resources</span>
+</a>
+</li>
+<!-- Homework (INACTIVE) -->
+<li>
+<a class="flex items-center gap-sm px-md py-sm rounded-lg text-on-surface-variant hover:bg-surface-container-highest transition-colors" href="#">
+<span class="material-symbols-outlined shrink-0">assignment</span>
+<span class="font-title-md text-title-md sidebar-text">Homework</span>
+</a>
+</li>
+<!-- Preview (INACTIVE) -->
+<li>
+<a class="flex items-center gap-sm px-md py-sm rounded-lg text-on-surface-variant hover:bg-surface-container-highest transition-colors" href="#">
+<span class="material-symbols-outlined shrink-0">visibility</span>
+<span class="font-title-md text-title-md sidebar-text">Preview</span>
+</a>
+</li>
+</ul>
+</div>
+</nav>
+<!-- Main Content Wrapper -->
+<div class="ml-[80px] flex-1 flex flex-col h-screen overflow-hidden bg-background">
+<!-- TopNavBar (Shared Component) -->
+<header class="bg-surface border-b border-outline-variant flex justify-between items-center h-16 px-lg shrink-0 z-10 relative">
+<!-- Left: Brand/Context -->
+<div class="flex items-center gap-md">
+<h1 class="font-title-lg text-title-lg font-black text-primary">Chinese Education Suite</h1>
+<div class="h-6 w-px bg-outline-variant mx-sm"></div>
+<div class="flex items-center gap-xs">
+<span class="font-title-md text-title-md text-on-surface">《秋天》 (Autumn)</span>
+<span class="bg-surface-container-high text-on-surface-variant font-label-md text-label-md px-2 py-1 rounded">Grade 1</span>
+</div>
+</div>
+<!-- Center: Nav Links -->
+<nav class="hidden lg:flex gap-lg h-full absolute left-1/2 -translate-x-1/2">
+<a class="flex items-center h-full font-body-md text-body-md text-on-surface-variant hover:text-primary border-b-2 border-transparent transition-colors" href="#">Curriculum</a>
+<a class="flex items-center h-full font-body-md text-body-md text-on-surface-variant hover:text-primary border-b-2 border-transparent transition-colors" href="#">Standards</a>
+<a class="flex items-center h-full font-body-md text-body-md text-on-surface-variant hover:text-primary border-b-2 border-transparent transition-colors" href="#">Analytics</a>
+</nav>
+<!-- Right: Actions -->
+<div class="flex items-center gap-md ml-auto">
+<div class="relative">
+<span class="material-symbols-outlined absolute left-sm top-1/2 -translate-y-1/2 text-outline text-[20px]">search</span>
+<input class="pl-xl pr-sm py-1.5 bg-surface-container-low border border-outline-variant rounded-full font-body-md text-body-md focus:outline-none focus:border-primary focus:ring-2 focus:ring-primary/10 transition-all w-48" placeholder="Search..." type="text"/>
+</div>
+<button class="bg-secondary-container text-on-secondary-container font-label-md text-label-md py-1.5 px-md rounded-full border border-secondary-container hover:bg-transparent transition-colors flex items-center gap-xs">
+<span class="material-symbols-outlined text-[16px]">smart_toy</span>
+                    AI Assistant
+                </button>
+<button class="text-primary font-label-md text-label-md hover:opacity-80 transition-opacity">Export Plan</button>
+<div class="flex items-center gap-xs text-on-surface-variant">
+<button class="p-xs rounded-full hover:bg-surface-container-highest transition-colors"><span class="material-symbols-outlined text-[20px]">notifications</span></button>
+<button class="p-xs rounded-full hover:bg-surface-container-highest transition-colors"><span class="material-symbols-outlined text-[20px]">settings</span></button>
+</div>
+<img class="w-8 h-8 rounded-full border border-outline-variant" data-alt="A small circular avatar of a user, standard blank profile icon style, subtle grey tones on a white background." src="https://lh3.googleusercontent.com/aida-public/AB6AXuAoTWwwvka05iqtq0cMgF0dpJUpK_48qzYYStPnxDXFahYje8tyCmqaSyBF3jwLqLg6BmaRQJYOnQ40GhsX4wZWX5tHGYz7gRT_E_rPjuD9kzSG5A9wXmc1bbSwiuQ1GAGmL-C7lP5P3fuO5jGFNyQdLwxROqRD5LOpj0zGvcVpEKC7w8XAywqptBTED0cyde1nOpxiCtuap-NzXBMuj-smrxOzXEaGlY4Z98u_OqHKFk6xgSRW4BoqmDk5-tlmDuv-6qyz_4S-Vqc"/>
+</div>
+</header>
+<!-- Workspace Layout - Integrated Canvas -->
+<main class="flex-1 flex overflow-hidden relative bg-surface-container-low node-canvas-bg cursor-grab active:cursor-grabbing">
+<!-- Dynamic Connecting Lines (SVG Layer) -->
+<svg class="absolute inset-0 pointer-events-none w-full h-full" style="z-index: 10;">
+<path class="connection-line" d="M 580 320 C 650 320, 700 250, 750 250" fill="none" opacity="1" stroke="#fc820c" stroke-dasharray="6 6" stroke-width="2"></path>
+<path class="connection-line" d="M 520 450 C 600 450, 700 390, 750 390" fill="none" opacity="0.2" stroke="#2f8635" stroke-dasharray="6 6" stroke-width="2"></path>
+</svg>
+<!-- Integrated Document Container -->
+<div class="absolute left-12 top-12 bottom-12 w-[600px] bg-surface-container-lowest border border-outline-variant rounded-xl shadow-md overflow-y-auto z-20 cursor-text">
+<!-- Floating Toolbar (Attached to document) -->
+<div class="sticky top-6 left-1/2 -translate-x-1/2 w-max floating-toolbar bg-surface/95 border border-outline-variant rounded-full px-md py-sm flex items-center gap-sm z-30 mb-8 mt-6 mx-auto">
+<button class="p-xs text-primary rounded hover:bg-primary/10 transition-colors tooltip-trigger" title="Highlight">
+<span class="material-symbols-outlined text-[20px]">format_ink_highlighter</span>
+</button>
+<button class="p-xs text-on-surface-variant rounded hover:bg-surface-container-highest transition-colors tooltip-trigger" title="Underline">
+<span class="material-symbols-outlined text-[20px]">format_underlined</span>
+</button>
+<button class="p-xs text-on-surface-variant rounded hover:bg-surface-container-highest transition-colors tooltip-trigger" title="Add Note">
+<span class="material-symbols-outlined text-[20px]">add_comment</span>
+</button>
+<div class="w-px h-5 bg-outline-variant mx-xs"></div>
+<button class="w-5 h-5 rounded-full bg-secondary-container border border-outline-variant hover:scale-110 transition-transform ring-2 ring-offset-1 ring-secondary-container"></button>
+<button class="w-5 h-5 rounded-full bg-tertiary-container border border-outline-variant hover:scale-110 transition-transform"></button>
+<button class="w-5 h-5 rounded-full bg-primary border border-outline-variant hover:scale-110 transition-transform"></button>
+</div>
+<!-- Text Document -->
+<div class="px-2xl pb-2xl">
+<h2 class="text-center font-headline-lg text-headline-lg mb-xl text-on-surface">《秋天》</h2>
+<div class="text-reading-chinese text-[28px] text-on-surface">
+<p class="mb-lg indent-8">
+                            天气凉了，树叶黄了，一片片叶子从树上落下来。
+                            <span class="relative inline-block cursor-pointer group">
+<span class="annotation-highlight-yellow active px-1 rounded" id="highlight-1">天空那么蓝，那么高。</span>
+<!-- Connection Anchor -->
+</span></p><div class="absolute -right-2 top-1/2 w-2 h-2 rounded-full bg-secondary-container opacity-100"></div>
+<p></p>
+<p class="mb-lg indent-8">
+                            一群大雁往南飞，一会儿排成个“人”字，一会儿排成个“一”字。
+                            <span class="relative inline-block cursor-pointer group">
+<span class="annotation-highlight-green px-1 rounded" id="highlight-2">啊！秋天来了！</span>
+<!-- Connection Anchor -->
+</span></p><div class="absolute -right-2 top-1/2 w-2 h-2 rounded-full bg-tertiary-container opacity-0 group-hover:opacity-100 transition-opacity"></div>
+<p></p>
+</div>
+<!-- UI Hint for Interaction -->
+<div class="mt-2xl pt-lg border-t border-outline-variant/30 flex items-center justify-center gap-sm text-on-surface-variant/70 font-label-md text-sm">
+<span class="material-symbols-outlined text-[18px]">lightbulb</span>
+<span>Select text and hold <kbd class="bg-surface-container px-1.5 py-0.5 rounded border border-outline-variant font-code-md text-xs">Shift</kbd> to create a new node</span>
+</div>
+</div>
+</div>
+<!-- Nodes on Canvas (Positioned to the right) -->
+<div class="absolute top-[200px] left-[750px] w-[280px] bg-surface rounded-lg border-2 border-secondary-container shadow-md transition-shadow cursor-pointer group z-20" id="node-1">
+<div class="bg-secondary-fixed-dim/30 px-3 py-2 rounded-t-sm border-b border-secondary-container/50 flex justify-between items-center">
+<span class="text-on-secondary-fixed-variant font-label-md text-label-md font-bold">Language Feature</span>
+<button class="text-on-secondary-fixed-variant hover:text-on-surface transition-colors"><span class="material-symbols-outlined text-[16px]">more_horiz</span></button>
+</div>
+<div class="p-4 relative">
+<!-- Connection Anchor -->
+<div class="absolute -left-2 top-[30px] w-4 h-4 rounded-full bg-surface border-2 border-secondary-container"></div>
+<p class="font-body-md text-on-surface text-sm italic mb-3">"天空那么蓝，那么高。"</p>
+<div class="text-xs text-on-surface-variant border-t border-outline-variant/30 pt-2">
+<span class="font-bold text-on-surface">Note:</span> Focus on repetition of "那么".
+            </div>
+</div>
+</div>
+<div class="absolute top-[350px] left-[750px] w-[280px] bg-surface rounded-lg border border-tertiary-container/50 shadow-sm transition-all hover:shadow-md hover:border-tertiary-container cursor-pointer group z-20 opacity-80 hover:opacity-100" id="node-2">
+<div class="bg-tertiary-fixed-dim/20 px-3 py-2 rounded-t-sm border-b border-outline-variant flex justify-between items-center">
+<span class="text-on-tertiary-fixed-variant font-label-md text-label-md">Action Suggestion</span>
+<button class="text-outline hover:text-on-surface transition-colors"><span class="material-symbols-outlined text-[16px]">more_horiz</span></button>
+</div>
+<div class="p-4 relative">
+<!-- Connection Anchor -->
+<div class="absolute -left-2 top-[30px] w-4 h-4 rounded-full bg-surface border-2 border-outline-variant group-hover:border-tertiary-container transition-colors"></div>
+<p class="font-body-md text-on-surface text-sm italic">"啊！秋天来了！"</p>
+</div>
+</div>
+<!-- Floating Detail/Parameter Panel (Right side) -->
+<div class="absolute top-md right-md w-[320px] bg-surface/90 backdrop-blur-md rounded-2xl p-lg shadow-[0_8px_32px_rgba(0,0,0,0.08)] border border-outline-variant/50 flex flex-col gap-md z-30">
+<div class="flex justify-between items-start">
+<span class="bg-secondary-fixed-dim/40 text-on-secondary-fixed-variant font-label-md text-label-md px-2 py-1 rounded-sm border border-secondary-container/20">Language Feature</span>
+<button class="text-outline hover:text-on-surface transition-colors"><span class="material-symbols-outlined text-[18px]">close</span></button>
+</div>
+<div class="bg-surface-container-lowest p-3 rounded-lg border border-outline-variant/50">
+<p class="font-body-md text-body-md text-on-surface italic">"天空那么蓝，那么高。"</p>
+</div>
+<div class="flex flex-col gap-xs">
+<label class="font-label-md text-label-md text-on-surface-variant uppercase tracking-wider">Instructional Notes</label>
+<p class="font-body-md text-body-md text-on-surface">Focus on the repetition of "那么" (so) to emphasize the vastness of the autumn sky. Guide students to read with a prolonged, airy tone.</p>
+</div>
+<div class="flex flex-col gap-xs mt-auto pt-sm border-t border-outline-variant/30">
+<label class="font-label-md text-label-md text-on-surface-variant uppercase tracking-wider">Tags</label>
+<div class="flex gap-xs flex-wrap">
+<span class="bg-surface-container border border-outline-variant text-on-surface-variant font-label-md text-[10px] px-2 py-1 rounded-full">朗读指导</span>
+<button class="bg-transparent border border-dashed border-outline-variant text-on-surface-variant hover:text-primary hover:border-primary font-label-md text-[10px] px-2 py-1 rounded-full transition-colors flex items-center gap-1">
+<span class="material-symbols-outlined text-[12px]">add</span> Add Tag
+                    </button>
+</div>
+</div>
+</div>
+</main>
+</div>
+</body></html>
--- a/docs/feature/f_bk_design.md
+++ b/docs/feature/f_bk_design.md
@@ -0,0 +1,608 @@
+# 备课模块（lesson-preparation）设计文档
+
+> 配套原型：`docs/feature/f_bk.md`
+> 架构依据：`docs/architecture/004_architecture_impact_map.md`、`005_architecture_data.json`
+> 编写日期：2026-06-18
+> 范围：**P0 地基 + P1 联动**（P2 协作 / P3 AI 与学情回看留作后续 spec）
+
+---
+
+## 0. 关键决策摘要
+
+| 决策项 | 最终选择 | 理由 |
+|--------|----------|------|
+| 本次 spec 范围 | P0 + P1 | 构成"备课→出题→下发"最小可用闭环，体量适中 |
+| 编辑器形态 | Block 编辑器为主 | 与蓝图文字一致；设计稿的"课文+节点画布"作为 `text_study` block 的内部交互 |
+| Block 存储模型 | 方案 A：JSON 文档 + 版本快照表 | 与现有 `questions.content` / `homeworkAssignments.structure` 的 JSON 模式一致；为 P2 批注 / P3 AI 重写预留稳定 blockId 锚点；零跨模块 DB 访问 |
+| 知识点同步 | P1 仅"关联已有 + AI 推荐"，不回写教材树 | 避免 P1 引入审核流拖慢闭环；回写留作后续 spec |
+| 作业发布闭环 | 复用 exam 中转 | 课案练习块 → 打包成 exam 草稿 → 调用现有 `createHomeworkAssignmentAction` 下发；零 schema 侵入、溯源清晰（作业→exam→课案） |
+
+---
+
+## 1. 模块定位与边界
+
+### 1.1 模块名
+
+`lesson-preparation`（目录 `src/modules/lesson-preparation/`），中文"备课"。
+
+### 1.2 与 `course-plans` 的关系（互补，不合并）
+
+| 模块 | 粒度 | 回答的问题 |
+|------|------|-----------|
+| `course-plans` | 学期/周宏观排课（totalHours/weeklyHours/week/topic） | "这学期每周教什么" |
+| `lesson-preparation` | 具体一节课的教学设计（目标/重难点/导入/新授/练习/作业…） | "这节课怎么教" |
+
+软关联：课案可记录来源 `coursePlanItemId`（可空，无强外键），便于"周计划→具体课案"下钻。
+
+### 1.3 依赖关系（严格三层架构，零跨模块直查）
+
+- 依赖 `shared/*`、`@/auth`
+- 通过对方 data-access 通信（不直接查询对方表）：
+  - `textbooks` — 只读章节树 / 知识点树
+  - `questions` — 创建题目（含知识点关联）、查询题目
+  - `exams` — 创建 exam 草稿（用于发布中转）
+  - `homework` — 创建作业下发到班级
+  - `classes` — 查询教师班级（用于下发目标选择）
+  - `files` — 附件引用
+- 被依赖：P0/P1 阶段无被依赖方
+
+---
+
+## 2. 数据模型（新增 3 张表）
+
+### 2.1 `lesson_plans`（课案主表）
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| id | id | PK | CUID2 |
+| title | varchar(255) | notNull | 课案标题 |
+| textbookId | varchar(128) | FK→textbooks, nullable | 教材（允许非教材备课） |
+| chapterId | varchar(128) | FK→chapters, nullable | 章节 |
+| coursePlanItemId | varchar(128) | nullable, 无 FK | 软关联课程计划项 |
+| subjectId | varchar(128) | FK→subjects, nullable | 学科 |
+| gradeId | varchar(128) | FK→grades, nullable | 年级 |
+| templateId | varchar(128) | nullable | 使用的模板 ID |
+| templateName | varchar(100) | nullable | 模板名快照（防模板改名） |
+| content | json | notNull | block 文档 JSON（见 §3） |
+| status | varchar(50) | default 'draft' | `draft`/`published`/`archived` |
+| creatorId | varchar(128) | FK→users, notNull | 创建者 |
+| lastSavedAt | timestamp | nullable | 最后自动保存时间 |
+| createdAt | timestamp | defaultNow | |
+| updatedAt | timestamp | defaultNow onUpdateNow | |
+
+索引：`creatorIdx(creatorId)`、`statusIdx(status)`、`textbookChapterIdx(textbookId, chapterId)`、`subjectGradeIdx(subjectId, gradeId)`
+
+### 2.2 `lesson_plan_versions`（版本快照表）
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| id | id | PK | |
+| planId | varchar(128) | FK→lesson_plans, onDelete cascade | |
+| versionNo | int | notNull | 每 plan 内自增 |
+| label | varchar(100) | nullable | 手动保存时的标签 |
+| content | json | notNull | 该版本 content 快照 |
+| isAuto | boolean | default false | true=自动保存触发 |
+| creatorId | varchar(128) | FK→users, notNull | |
+| createdAt | timestamp | defaultNow | |
+
+索引：`planVersionIdx(planId, versionNo)`（唯一）、`planCreatedIdx(planId, createdAt desc)`
+
+### 2.3 `lesson_plan_templates`（模板表）
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| id | id | PK | |
+| name | varchar(100) | notNull | 模板名 |
+| type | varchar(50) | notNull | `system`/`personal` |
+| scope | varchar(50) | notNull | `regular`/`review`/`experiment`/`inquiry`/`blank`/`custom` |
+| blocks | json | notNull | 预置 block 骨架（blockType + 默认标题 + 提示语，无内容） |
+| creatorId | varchar(128) | FK→users, nullable | personal 模板拥有者；system 为 null |
+| createdAt | timestamp | defaultNow | |
+| updatedAt | timestamp | defaultNow onUpdateNow | |
+
+索引：`typeCreatorIdx(type, creatorId)`（personal 模板按创建者过滤）
+
+> 系统预设 4+1 套模板由 seed 脚本写入（type=system）。教师"另存为我的模板"写入 type=personal。
+
+---
+
+## 3. Block 文档 JSON 结构
+
+### 3.1 顶层结构
+
+```json
+{
+  "version": 1,
+  "blocks": [
+    {
+      "id": "blk_xxx",
+      "type": "objective",
+      "title": "教学目标",
+      "data": { },
+      "order": 0
+    }
+  ]
+}
+```
+
+- `id`：客户端生成的稳定 ID（CUID2），是 P2 批注锚点、P3 AI 单 block 重写的定位依据
+- `type`：见 §3.2 枚举
+- `title`：环节名（可改，模板提供默认值）
+- `data`：类型相关数据，见 §3.3
+- `order`：排序索引（整数，编辑器拖拽后重排）
+
+### 3.2 Block 类型枚举
+
+| type | 用途 | 出现模板 |
+|------|------|---------|
+| `objective` | 教学目标 | 常规/复习/实验 |
+| `key_point` | 教学重难点 | 常规 |
+| `import` | 导入 | 常规 |
+| `new_teaching` | 新授 | 常规 |
+| `consolidation` | 巩固 | 常规 |
+| `summary` | 小结 | 常规/复习/实验/探究 |
+| `homework` | 作业布置（文字描述型） | 常规 |
+| `blackboard` | 板书设计 | 常规 |
+| `text_study` | 文本研习（设计稿画布形态） | 语文/英语精读课自定义添加 |
+| `exercise` | 练习/作业块（P1 核心，关联题目） | 任意模板可添加 |
+| `rich_text` | 通用富文本（自定义环节） | 复习/实验/探究的自定义环节 |
+| `reflection` | 教学反思（P3 预留，P0/P1 不渲染特殊 UI） | 任意 |
+
+### 3.3 各 block.data 结构
+
+**富文本类**（`objective`/`key_point`/`import`/`new_teaching`/`consolidation`/`summary`/`homework`/`blackboard`/`rich_text`/`reflection`）：
+
+```json
+{
+  "html": "<p>...</p>",
+  "knowledgePointIds": ["kp_1", "kp_2"]
+}
+```
+
+**`text_study`**（设计稿画布形态的 block 化）：
+
+```json
+{
+  "sourceText": "天气凉了，树叶黄了...",
+  "annotations": [
+    {
+      "id": "ann_xxx",
+      "anchor": { "start": 12, "end": 20 },
+      "nodeType": "language_feature",
+      "title": "语言特色",
+      "note": "关注'那么'的反复",
+      "color": "yellow"
+    }
+  ],
+  "knowledgePointIds": ["kp_1"]
+}
+```
+
+**`exercise`**（P1 核心）：
+
+```json
+{
+  "items": [
+    {
+      "questionId": "q_xxx",
+      "source": "bank",
+      "score": 5,
+      "order": 0
+    },
+    {
+      "questionId": "inline_draft_xxx",
+      "source": "inline",
+      "inlineContent": {
+        "content": { },
+        "type": "single_choice",
+        "difficulty": 3,
+        "knowledgePointIds": ["kp_1"]
+      },
+      "score": 10,
+      "order": 1
+    }
+  ],
+  "purpose": "class_practice",
+  "knowledgePointIds": ["kp_1"]
+}
+```
+
+- `source`：`bank`=从题库拉取（questionId 已存在于 questions 表）；`inline`=课案内新建（编辑期 questionId 为占位 `inline_draft_${cuid}`，发布时入库后回填真实 ID）
+- `inlineContent`：仅 source=inline 时存在，结构与 `questions` 表字段对齐（content/type/difficulty/knowledgePointIds），发布时作为 `createQuestionWithRelations` 的入参
+- `purpose`：`class_practice`=课堂练习；`after_class_homework`=课后作业（发布闭环仅处理此类型）
+
+---
+
+## 4. 模板系统
+
+### 4.1 系统预设模板（4+1 套，由 seed 脚本写入）
+
+| 模板 | scope | block 序列 |
+|------|-------|-----------|
+| 常规课 | `regular` | objective → key_point → import → new_teaching → consolidation → summary → homework → blackboard |
+| 复习课 | `review` | objective → rich_text("知识网络梳理") → rich_text("典型例题精讲") → rich_text("变式训练") → exercise("当堂检测") → summary |
+| 实验课 | `experiment` | objective → rich_text("器材准备") → rich_text("实验步骤") → rich_text("观察记录表") → rich_text("交流讨论") → summary |
+| 探究课 | `inquiry` | rich_text("情境导入") → rich_text("问题驱动") → rich_text("小组探究") → rich_text("成果展示") → rich_text("归纳提升") |
+| 空白 | `blank` | （无预置 block） |
+
+模板 `blocks` JSON 仅定义骨架（type + 默认 title + 提示语），不含内容。教师选用后生成对应 block 序列，可自由增删、改序、改名、改内容。
+
+### 4.2 自定义模板
+
+- 教师在编辑器内"另存为我的模板"→ 写入 `lesson_plan_templates`（type=personal, creatorId=教师）
+- personal 模板仅创建者可见、可编辑、可删除
+- 创建课案时模板选择器并列展示 system + 我的 personal 模板
+
+---
+
+## 5. Block 编辑器与版本管理
+
+### 5.1 编辑器交互
+
+- 主体：可拖拽 block 列表（类 Notion/BlockNote 的块状编辑器）
+- 每个 block：标题栏（可改名）+ 内容区（按 type 渲染不同编辑组件）+ 拖拽手柄 + 删除/上移/下移/复制
+- block 增删：顶部"+"按钮选择 block 类型插入；可从模板侧栏拖入预置环节
+- 自动保存：编辑器 debounce 3s 无操作后触发自动保存（写 `lesson_plans.content` + `lastSavedAt`，不生成版本）
+- 手动保存：Ctrl+S 或按钮 → 生成新版本（写 `lesson_plan_versions`，isAuto=false）
+- 版本历史：侧栏抽屉展示版本列表（versionNo + label + 时间 + isAuto 标记），点击预览该版本 content，"回退到此版本"= 用该版本 content 覆盖当前 + 生成新版本
+
+### 5.2 版本策略
+
+- 自动保存：只更新 `lesson_plans.content` 与 `lastSavedAt`，**不**写 versions 表（避免版本爆炸）
+- 手动保存：写一条 versions 记录（isAuto=false）
+- 定时自动版本：每 30 分钟若有过改动，自动写一条 versions 记录（isAuto=true），防止教师长时间未手动保存丢失历史
+- 版本上限：每 plan 保留最近 50 条 versions，超出删除最旧的 isAuto=true 记录（手动版本永不被自动清理）
+
+### 5.3 我的课案库
+
+- 路由：`/teacher/lesson-plans`
+- 列表展示：卡片网格，显示 title / 教材章节 / 学科年级 / 模板 / status / 最后保存时间
+- 筛选：教材（级联章节）、学科、年级、状态、标签（标题关键词搜索）
+- 操作：编辑、复制（生成副本，title 加" - 副本"）、删除（软删除：status=archived）、发布（status=published）
+
+---
+
+## 6. P1：知识点标注与关联
+
+### 6.1 手动标注
+
+- 在富文本类 block 内选中文本 → 弹出知识点选择器（从 `textbooks` 模块的章节-知识点树勾选）
+- 选中的 knowledgePointId 写入该 block 的 `data.knowledgePointIds`
+- block 渲染时在关联的知识点旁显示标签 chip
+
+### 6.2 AI 推荐（轻量，P1 不做完整 AI 课案生成）
+
+- 编辑器顶部"AI 推荐知识点"按钮 → 读取当前课案所有 block 的纯文本 → 调用 `shared/lib/ai.createAiChatCompletion` → 返回推荐 knowledgePointId 列表
+- 教师在弹窗中勾选确认 → 合并到对应 block 的 `knowledgePointIds`
+- AI 仅做"推荐候选"，不自动写入；知识点池来自教材已有知识点（不创建新知识点）
+
+### 6.3 知识点-课案映射查询（data-access 暴露）
+
+- `getLessonPlansByKnowledgePoint(knowledgePointId)`：反查哪些课案重点讲解了某知识点（供后续学情分析/教材知识点树反查使用，P1 仅实现 data-access 函数，不做 UI）
+
+---
+
+## 7. P1：题目创建 / 拉取 / 同步题库
+
+### 7.1 从题库拉取（source=bank）
+
+- exercise block 侧栏：题库搜索器（按知识点 / 题型 / 难度筛选，调用 `questions/data-access.getQuestions`）
+- 选中题目 → 插入 exercise.items（source=bank, questionId=真实 ID）
+- 仅引用，不复制题目内容；渲染时按 questionId 查询展示
+
+### 7.2 课案内新建题目（source=inline）
+
+- exercise block 内"新建题目"按钮 → 弹出题目编辑器（复用 `questions/components/create-question-dialog` 的表单逻辑）
+- 编辑期：题目暂存为 inline draft，完整内容存入 `exercise.items[].inlineContent`（结构与 questions 表字段对齐），`questionId` 为占位 `inline_draft_${cuid}`
+- 保存课案时：inline 题目**不立即入库**，保持 draft 状态（inlineContent 随课案 content 一起持久化）
+- 发布作业时（见 §8）：inline 题目先入库（调用 `questions/data-access.createQuestionWithRelations`，入参取自 inlineContent），用真实 questionId 替换占位 ID，回写到课案 content
+
+### 7.3 题目-课案关联查询
+
+- `getLessonPlansByQuestion(questionId)`：反查某题在哪些课案的哪个 exercise block 被使用（data-access 函数，P1 仅实现，不做 UI）
+
+---
+
+## 8. P1：作业 / 考试发布打通（复用 exam 中转）
+
+### 8.1 发布流程
+
+```
+教师点击 exercise block（purpose=after_class_homework）的"发布作业"按钮
+  │
+  ▼
+[Action] publishLessonPlanHomeworkAction
+  │
+  ├─ requirePermission(LESSON_PLAN_PUBLISH)
+  │
+  ├─ 1. inline 题目入库
+  │     └─ 遍历 exercise.items，对 source=inline 的调用
+  │        questions/data-access.createQuestionWithRelations
+  │        （authorId=教师，关联 knowledgePointIds）
+  │     └─ 用真实 questionId 替换课案 content 中的占位 ID
+  │     └─ 更新 lesson_plans.content
+  │
+  ├─ 2. 打包成 exam 草稿
+  │     └─ 调用 exams/data-access.persistExamDraft
+  │        （title=课案标题+" - 作业"，creatorId=教师，
+  │         sourceLessonPlanId=课案ID，关联 textbookId/chapterId/subjectId/gradeId，
+  │         examQuestions = exercise.items 映射）
+  │     └─ 得到 examId
+  │
+  ├─ 3. 下发作业
+  │     └─ 调用 homework/data-access-write.createHomeworkAssignment
+  │        （sourceExamId=examId, title, targets=班级学生列表,
+  │         availableAt, dueAt）
+  │     └─ 得到 assignmentId
+  │
+  ├─ 4. 记录溯源
+  │     └─ 在课案 content 的 exercise block.data 写入
+  │        publishedAssignmentId + publishedExamId + publishedAt
+  │
+  └─ revalidatePath("/teacher/lesson-plans") + revalidatePath("/teacher/homework")
+```
+
+### 8.2 溯源标记
+
+- 课案 exercise block 渲染时：若 `data.publishedAssignmentId` 存在，显示"已发布为作业"徽章 + 跳转链接
+- 作业侧（P1 不改 homework 模块）：作业的 sourceExamId → exam → 可查到 sourceLessonPlanId（exam 草稿创建时记录），实现"作业→课案"反查链路
+- 学情报告（P3）：通过 assignmentId → exam → lessonPlanId 回链到课案
+
+### 8.3 发布前置校验
+
+- exercise block 至少有 1 道题
+- inline 题目必须填写完整（content/type/difficulty/knowledgePointIds）
+- 教师必须对目标班级有 `class_taught` DataScope 权限
+- 同一 exercise block 不可重复发布（已有 publishedAssignmentId 则禁用发布按钮，提供"重新发布为新作业"选项）
+
+---
+
+## 9. 模块文件结构
+
+```
+src/modules/lesson-preparation/
+├─ actions.ts                    # Server Actions（编排层）
+├─ data-access.ts                # 课案 CRUD + 版本查询
+├─ data-access-versions.ts       # 版本快照写入 + 查询 + 回退
+├─ data-access-templates.ts      # 模板 CRUD（system + personal）
+├─ data-access-knowledge.ts      # 知识点-课案映射查询（P1）
+├─ publish-service.ts            # 发布编排（inline 入库 → exam 草稿 → 作业下发）
+├─ ai-suggest.ts                 # AI 知识点推荐（P1 轻量）
+├─ schema.ts                     # Zod 验证
+├─ types.ts                      # 类型定义（含 Block 类型联合）
+├─ constants.ts                  # 模板预设、block 类型枚举、状态常量
+├─ seed.ts                       # 系统预设模板 seed 脚本
+├─ hooks/
+│  └─ use-lesson-plan-editor.ts  # 编辑器状态管理（自动保存/版本/拖拽）
+└─ components/
+   ├─ lesson-plan-list.tsx              # 我的课案库列表
+   ├─ lesson-plan-card.tsx              # 课案卡片
+   ├─ lesson-plan-filters.tsx           # 筛选器
+   ├─ lesson-plan-editor.tsx            # 编辑器主壳（block 列表容器）
+   ├─ block-renderer.tsx                # block 分发渲染
+   ├─ blocks/
+   │  ├─ rich-text-block.tsx            # 富文本类 block 编辑器
+   │  ├─ text-study-block.tsx           # 文本研习画布 block
+   │  ├─ exercise-block.tsx             # 练习/作业 block
+   │  └─ reflection-block.tsx           # 教学反思（P3 预留，P1 简单渲染）
+   ├─ template-picker.tsx               # 模板选择器
+   ├─ version-history-drawer.tsx        # 版本历史抽屉
+   ├─ knowledge-point-picker.tsx        # 知识点选择器（复用 textbooks 组件）
+   ├─ question-bank-picker.tsx          # 题库拉取侧栏（复用 questions 组件）
+   ├─ inline-question-editor.tsx        # 课案内新建题目（复用 questions 表单）
+   └─ publish-homework-dialog.tsx       # 发布作业弹窗（选班级/时间）
+```
+
+---
+
+## 10. Server Actions 清单
+
+所有 Action 遵循项目规范：`requirePermission()` → Zod 校验 → 调用 data-access → `revalidatePath` → 返回 `ActionState<T>`。
+
+| Action | 权限点 | 用途 |
+|--------|--------|------|
+| `getLessonPlansAction` | LESSON_PLAN_READ | 我的课案库列表（含筛选） |
+| `getLessonPlanByIdAction` | LESSON_PLAN_READ | 获取单个课案（含权限校验：creator 或 published） |
+| `createLessonPlanAction` | LESSON_PLAN_CREATE | 创建课案（选模板 → 生成初始 content） |
+| `updateLessonPlanAction` | LESSON_PLAN_UPDATE | 更新课案（自动保存，不生成版本） |
+| `saveLessonPlanVersionAction` | LESSON_PLAN_UPDATE | 手动保存生成版本 |
+| `revertLessonPlanVersionAction` | LESSON_PLAN_UPDATE | 回退到指定版本（生成新版本） |
+| `getLessonPlanVersionsAction` | LESSON_PLAN_READ | 获取版本列表 |
+| `deleteLessonPlanAction` | LESSON_PLAN_DELETE | 删除课案（软删除：status=archived） |
+| `duplicateLessonPlanAction` | LESSON_PLAN_CREATE | 复制课案 |
+| `getLessonPlanTemplatesAction` | LESSON_PLAN_READ | 获取模板列表（system + 我的 personal） |
+| `saveAsTemplateAction` | LESSON_PLAN_CREATE | 另存为我的模板 |
+| `deleteTemplateAction` | LESSON_PLAN_DELETE | 删除 personal 模板 |
+| `suggestKnowledgePointsAction` | LESSON_PLAN_READ + AI_CHAT | AI 推荐知识点（只读返回候选，不写入课案；教师确认后另调 updateLessonPlanAction） |
+| `publishLessonPlanHomeworkAction` | LESSON_PLAN_PUBLISH + HOMEWORK_CREATE | 发布作业（§8 编排） |
+
+---
+
+## 11. data-access 清单
+
+| 函数 | 用途 |
+|------|------|
+| `getLessonPlans(params & scope)` | 课案列表（DataScope 过滤） |
+| `getLessonPlanById(id, scope)` | 单课案详情 |
+| `createLessonPlan(input)` | 创建（含模板初始化 content） |
+| `updateLessonPlanContent(id, content, userId)` | 更新 content + lastSavedAt（自动保存） |
+| `softDeleteLessonPlan(id, userId)` | status=archived |
+| `duplicateLessonPlan(id, userId)` | 复制 |
+| `getLessonPlanVersions(planId)` | 版本列表 |
+| `createLessonPlanVersion(planId, content, userId, isAuto, label?)` | 写版本快照 |
+| `revertToVersion(planId, versionNo, userId)` | 用版本 content 覆盖当前 + 生成新版本 |
+| `pruneAutoVersions(planId, keep=50)` | 清理超出上限的自动版本 |
+| `getLessonPlanTemplates(userId)` | system + 该用户 personal |
+| `createPersonalTemplate(input, userId)` | 创建 personal 模板 |
+| `deletePersonalTemplate(id, userId)` | 删除（仅 owner） |
+| `getLessonPlansByKnowledgePoint(kpId)` | 知识点反查课案（P1 data-access only） |
+| `getLessonPlansByQuestion(questionId)` | 题目反查课案（P1 data-access only） |
+
+---
+
+## 12. 权限点（新增 5 个）
+
+在 `src/shared/types/permissions.ts` 新增：
+
+```typescript
+// Lesson Plan (备课)
+LESSON_PLAN_CREATE: "lesson_plan:create",
+LESSON_PLAN_READ: "lesson_plan:read",
+LESSON_PLAN_UPDATE: "lesson_plan:update",
+LESSON_PLAN_DELETE: "lesson_plan:delete",
+LESSON_PLAN_PUBLISH: "lesson_plan:publish",
+```
+
+在 `src/shared/lib/permissions.ts` 的 `ROLE_PERMISSIONS` 映射中：
+- `teacher`：全部 5 个
+- `admin`：全部 5 个
+- `student`/`parent`/其他：无
+
+---
+
+## 13. 路由
+
+| 路由 | 页面 | 权限 |
+|------|------|------|
+| `/teacher/lesson-plans` | 我的课案库列表 | LESSON_PLAN_READ |
+| `/teacher/lesson-plans/new` | 新建课案（选模板） | LESSON_PLAN_CREATE |
+| `/teacher/lesson-plans/[planId]/edit` | 课案编辑器 | LESSON_PLAN_UPDATE（creator）或 LESSON_PLAN_READ（published 只读） |
+
+侧边栏导航：在 `layout/config/navigation.ts` 的 teacher 角色菜单新增"备课"项。
+
+---
+
+## 14. DataScope 接入
+
+- `getLessonPlans` 接受 `scope` 参数：
+  - `teacher`/`admin`（type=all 或 class_taught）：返回自己创建的 + 公开 published 的
+  - 其他角色：仅 published 的
+- `getLessonPlanById`：creator 可看自己的 draft；非 creator 仅当 status=published 可看
+- 写操作（update/delete/publish）：仅 creator（DataScope 不适用，直接校验 `creatorId === userId`）
+
+---
+
+## 15. 架构图同步计划
+
+按项目规则"改码必同步图"，实现完成后需更新：
+
+### 15.1 `docs/architecture/004_architecture_impact_map.md`
+
+- §1.1 分层架构图：modules 行新增 `lesson-preparation`
+- §1.2 模块依赖关系图：新增 `lesson-preparation` 节点，标注对 textbooks/questions/exams/homework/classes/files 的合理依赖（───▶ data-access）
+- 第二部分新增 §2.27 lesson-preparation 模块清单（职责/导出函数/依赖/文件清单）
+- 附录 A 依赖矩阵新增一行一列
+
+### 15.2 `docs/architecture/005_architecture_data.json`
+
+- `modules.lesson_preparation`：完整模块节点
+- `dbTables`：新增 `lesson_plans` / `lesson_plan_versions` / `lesson_plan_templates`
+- `permissions`：新增 5 个权限点
+- `routes`：新增 3 个路由
+- `dependencyMatrix`：新增依赖关系
+
+### 15.3 `src/shared/db/schema.ts`
+
+新增 3 张表定义（按现有分节风格，加在合适 section）。schema.ts 当前 1111 行已超 1000 硬上限（P0 已知问题），新增 3 表会加剧；建议本次新增时一并按业务域拆分 schema.ts（但拆分属独立任务，不在本 spec 范围，仅在备注中提示）。
+
+---
+
+## 16. 实施分阶段计划
+
+### P0 地基（先做）
+
+1. 新增 3 张表 schema + 迁移
+2. 新增 5 个权限点 + 角色映射
+3. seed 系统预设模板（4+1 套）
+4. data-access + data-access-versions + data-access-templates
+5. 基础 CRUD Actions（create/get/update/delete/duplicate）
+6. 版本管理 Actions（save version / revert / list）
+7. 模板 Actions（list / save as / delete）
+8. 我的课案库列表页 + 筛选
+9. Block 编辑器主壳 + 富文本类 block + 拖拽排序 + 自动保存
+10. 版本历史抽屉
+11. 模板选择器（新建课案入口）
+12. 路由 + 侧边栏导航
+13. 同步架构图 004/005
+
+### P1 联动（P0 完成后）
+
+14. `text_study` block（设计稿画布形态）
+15. `exercise` block + 题库拉取侧栏（source=bank）
+16. `exercise` block + 课案内新建题目（source=inline，draft 暂存）
+17. 知识点选择器 + block 内 knowledgePointIds 标注
+18. AI 知识点推荐 Action + 编辑器入口
+19. publish-service（inline 入库 → exam 草稿 → 作业下发）
+20. 发布作业弹窗（选班级/时间）
+21. 溯源标记渲染（已发布徽章 + 跳转）
+22. data-access-knowledge（反查函数，无 UI）
+23. 同步架构图（若 P1 新增了导出函数）
+
+---
+
+## 17. 验收标准
+
+### P0 验收
+
+- [ ] 教师可创建课案（选教材/章节/模板）
+- [ ] 5 套系统预设模板可选，选用后生成对应 block 骨架
+- [ ] Block 编辑器：增删改 block、拖拽排序、富文本编辑
+- [ ] 自动保存（3s debounce）+ 手动保存生成版本
+- [ ] 版本历史：列表、预览、回退
+- [ ] 我的课案库：列表、筛选、复制、删除
+- [ ] 权限校验：非 creator 无法编辑 draft
+- [ ] `npm run lint` + `npx tsc --noEmit` 零错误
+- [ ] 架构图 004/005 已同步
+
+### P1 验收
+
+- [ ] exercise block 可从题库拉取题目并展示
+- [ ] exercise block 可课案内新建题目（draft 暂存）
+- [ ] 富文本 block 可标注知识点（选择器 + chip 展示）
+- [ ] AI 推荐知识点按钮可用，推荐结果可勾选确认
+- [ ] exercise block（purpose=after_class_homework）可发布为作业
+- [ ] 发布后 inline 题目已入库，课案 content 中占位 ID 已替换
+- [ ] 发布后作业可通过 sourceExamId → exam → sourceLessonPlanId 反查课案
+- [ ] 已发布 exercise block 显示溯源徽章
+- [ ] 重复发布被拦截（提供"重新发布为新作业"）
+- [ ] `npm run lint` + `npx tsc --noEmit` 零错误
+- [ ] 架构图已同步
+
+---
+
+## 18. 未覆盖范围（P2/P3 预告，本次不实现）
+
+以下功能在蓝图中提及，但**不在本 spec 范围**，留作后续独立 spec：
+
+### P2 协作
+- 分享链接（密码/有效期）
+- block 级批注线程（依赖本 spec 的稳定 blockId）
+- 采纳建议生成新版本
+
+### P3 智能与回看
+- AI 课案初稿生成（按模板结构填充）
+- 环节级 AI 重写（选中 block → 指令 → 替换该 block）
+- 一致性检查（目标-活动-评价对齐）
+- 系统内资源推荐（微课/课件/实验视频）
+- 外部资源对接（国家中小学智慧教育平台 API）
+- AI 生成资源草稿（课件大纲/微课脚本/学案）
+- 教学反思 block 完整 UI
+- 学情回看（班级知识点掌握率/高频错题内嵌）
+- AI 补救教学建议
+- 知识点回写教材树（含审核流）
+
+---
+
+## 19. 风险与备注
+
+| 风险 | 影响 | 缓解 |
+|------|------|------|
+| `schema.ts` 已 1111 行超 1000 硬上限，新增 3 表加剧 | 违反编码规范 | 本次新增时备注提示；schema.ts 按业务域拆分作为独立任务跟进 |
+| Block 编辑器复杂度高 | P0 工期风险 | 优先用成熟库（如 BlockNote/Plate）二次封装，不自研底层 |
+| inline 题目发布时入库失败 | 数据不一致 | publish-service 用事务包裹；失败则回滚 exam 草稿创建，课案 content 不替换占位 ID |
+| 自动保存频率高导致 versions 表膨胀 | 存储压力 | 自动保存不写 versions；定时自动版本 30min 一次；pruneAutoVersions 保留上限 50 |
+| AI 推荐知识点依赖 AI Provider 配置 | 功能可用性 | AI 不可用时按钮置灰 + 提示"未配置 AI Provider"；不阻塞主流程 |
+
+---
+
+> 本 spec 完成后，下一步进入 `writing-plans` skill 生成详细实施计划。