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)

src/modules/lesson-preparation/actions.ts

@@ -0,0 +1,284 @@
+"use server";
+
+import { revalidatePath } from "next/cache";
+import { requirePermission, PermissionDeniedError } from "@/shared/lib/auth-guard";
+import { Permissions } from "@/shared/types/permissions";
+import {
+  getLessonPlans,
+  getLessonPlanById,
+  createLessonPlan,
+  updateLessonPlanContent,
+  softDeleteLessonPlan,
+  duplicateLessonPlan,
+} from "./data-access";
+import {
+  getLessonPlanVersions,
+  createLessonPlanVersion,
+  revertToVersion,
+  pruneAutoVersions,
+} from "./data-access-versions";
+import {
+  getLessonPlanTemplates,
+  saveAsTemplate,
+  deletePersonalTemplate,
+} from "./data-access-templates";
+import {
+  createLessonPlanSchema,
+  updateLessonPlanContentSchema,
+  saveVersionSchema,
+  revertVersionSchema,
+  saveAsTemplateSchema,
+} from "./schema";
+import type { ActionState, LessonPlanDocument } from "./types";
+
+// ---- 课案列表 ----
+export async function getLessonPlansAction(params: {
+  query?: string;
+  textbookId?: string;
+  chapterId?: string;
+  subjectId?: string;
+  status?: string;
+}): Promise<
+  ActionState<{
+    items: Awaited<ReturnType<typeof getLessonPlans>>;
+  }>
+> {
+  try {
+    const ctx = await requirePermission(Permissions.LESSON_PLAN_READ);
+    const items = await getLessonPlans(params, ctx.dataScope, ctx.userId);
+    return { success: true, data: { items } };
+  } catch (e) {
+    if (e instanceof PermissionDeniedError)
+      return { success: false, message: e.message };
+    return { success: false, message: "获取课案列表失败" };
+  }
+}
+
+// ---- 单课案 ----
+export async function getLessonPlanByIdAction(
+  planId: string,
+): Promise<
+  ActionState<{ plan: Awaited<ReturnType<typeof getLessonPlanById>> }>
+> {
+  try {
+    const ctx = await requirePermission(Permissions.LESSON_PLAN_READ);
+    const plan = await getLessonPlanById(planId, ctx.userId);
+    if (!plan) return { success: false, message: "课案不存在或无权访问" };
+    return { success: true, data: { plan } };
+  } catch (e) {
+    if (e instanceof PermissionDeniedError)
+      return { success: false, message: e.message };
+    return { success: false, message: "获取课案失败" };
+  }
+}
+
+// ---- 创建 ----
+export async function createLessonPlanAction(
+  prevState: ActionState | null,
+  formData: FormData,
+): Promise<ActionState<{ planId: string }>> {
+  try {
+    const ctx = await requirePermission(Permissions.LESSON_PLAN_CREATE);
+    const parsed = createLessonPlanSchema.safeParse({
+      title: formData.get("title"),
+      textbookId: formData.get("textbookId") || undefined,
+      chapterId: formData.get("chapterId") || undefined,
+      subjectId: formData.get("subjectId") || undefined,
+      gradeId: formData.get("gradeId") || undefined,
+      templateId: formData.get("templateId"),
+    });
+    if (!parsed.success) {
+      return { success: false, errors: parsed.error.flatten().fieldErrors };
+    }
+    const { planId } = await createLessonPlan({
+      ...parsed.data,
+      creatorId: ctx.userId,
+    });
+    revalidatePath("/teacher/lesson-plans");
+    return { success: true, data: { planId } };
+  } catch (e) {
+    if (e instanceof PermissionDeniedError)
+      return { success: false, message: e.message };
+    return { success: false, message: "创建课案失败" };
+  }
+}
+
+// ---- 更新 content（自动保存）----
+export async function updateLessonPlanAction(input: {
+  planId: string;
+  title?: string;
+  content: LessonPlanDocument;
+}): Promise<ActionState> {
+  try {
+    const ctx = await requirePermission(Permissions.LESSON_PLAN_UPDATE);
+    const parsed = updateLessonPlanContentSchema.safeParse(input);
+    if (!parsed.success)
+      return { success: false, errors: parsed.error.flatten().fieldErrors };
+    await updateLessonPlanContent(parsed.data.planId, ctx.userId, {
+      ...(parsed.data.title ? { title: parsed.data.title } : {}),
+      content: parsed.data.content as LessonPlanDocument,
+    });
+    return { success: true };
+  } catch (e) {
+    if (e instanceof PermissionDeniedError)
+      return { success: false, message: e.message };
+    return { success: false, message: "保存失败" };
+  }
+}
+
+// ---- 手动保存版本 ----
+export async function saveLessonPlanVersionAction(input: {
+  planId: string;
+  content: LessonPlanDocument;
+  label?: string;
+}): Promise<ActionState<{ versionNo: number }>> {
+  try {
+    const ctx = await requirePermission(Permissions.LESSON_PLAN_UPDATE);
+    const parsed = saveVersionSchema.safeParse(input);
+    if (!parsed.success)
+      return { success: false, errors: parsed.error.flatten().fieldErrors };
+    const { versionNo } = await createLessonPlanVersion({
+      planId: parsed.data.planId,
+      content: input.content,
+      userId: ctx.userId,
+      isAuto: false,
+      label: parsed.data.label,
+    });
+    await pruneAutoVersions(parsed.data.planId);
+    return { success: true, data: { versionNo } };
+  } catch (e) {
+    if (e instanceof PermissionDeniedError)
+      return { success: false, message: e.message };
+    return { success: false, message: "保存版本失败" };
+  }
+}
+
+// ---- 版本列表 ----
+export async function getLessonPlanVersionsAction(
+  planId: string,
+): Promise<
+  ActionState<{
+    versions: Awaited<ReturnType<typeof getLessonPlanVersions>>;
+  }>
+> {
+  try {
+    const ctx = await requirePermission(Permissions.LESSON_PLAN_READ);
+    const versions = await getLessonPlanVersions(planId, ctx.userId);
+    return { success: true, data: { versions } };
+  } catch (e) {
+    if (e instanceof PermissionDeniedError)
+      return { success: false, message: e.message };
+    return { success: false, message: "获取版本失败" };
+  }
+}
+
+// ---- 回退版本 ----
+export async function revertLessonPlanVersionAction(input: {
+  planId: string;
+  versionNo: number;
+}): Promise<ActionState<{ newVersionNo: number }>> {
+  try {
+    const ctx = await requirePermission(Permissions.LESSON_PLAN_UPDATE);
+    const parsed = revertVersionSchema.safeParse(input);
+    if (!parsed.success)
+      return { success: false, errors: parsed.error.flatten().fieldErrors };
+    const result = await revertToVersion(
+      parsed.data.planId,
+      parsed.data.versionNo,
+      ctx.userId,
+    );
+    if (!result) return { success: false, message: "版本不存在或无权操作" };
+    revalidatePath(`/teacher/lesson-plans/${parsed.data.planId}/edit`);
+    return { success: true, data: { newVersionNo: result.newVersionNo } };
+  } catch (e) {
+    if (e instanceof PermissionDeniedError)
+      return { success: false, message: e.message };
+    return { success: false, message: "回退失败" };
+  }
+}
+
+// ---- 删除（软删除）----
+export async function deleteLessonPlanAction(
+  planId: string,
+): Promise<ActionState> {
+  try {
+    const ctx = await requirePermission(Permissions.LESSON_PLAN_DELETE);
+    await softDeleteLessonPlan(planId, ctx.userId);
+    revalidatePath("/teacher/lesson-plans");
+    return { success: true };
+  } catch (e) {
+    if (e instanceof PermissionDeniedError)
+      return { success: false, message: e.message };
+    return { success: false, message: "删除失败" };
+  }
+}
+
+// ---- 复制 ----
+export async function duplicateLessonPlanAction(
+  planId: string,
+): Promise<ActionState<{ newPlanId: string }>> {
+  try {
+    const ctx = await requirePermission(Permissions.LESSON_PLAN_CREATE);
+    const { newPlanId } = await duplicateLessonPlan(planId, ctx.userId);
+    revalidatePath("/teacher/lesson-plans");
+    return { success: true, data: { newPlanId } };
+  } catch (e) {
+    if (e instanceof PermissionDeniedError)
+      return { success: false, message: e.message };
+    return { success: false, message: "复制失败" };
+  }
+}
+
+// ---- 模板列表 ----
+export async function getLessonPlanTemplatesAction(): Promise<
+  ActionState<{
+    templates: Awaited<ReturnType<typeof getLessonPlanTemplates>>;
+  }>
+> {
+  try {
+    const ctx = await requirePermission(Permissions.LESSON_PLAN_READ);
+    const templates = await getLessonPlanTemplates(ctx.userId);
+    return { success: true, data: { templates } };
+  } catch (e) {
+    if (e instanceof PermissionDeniedError)
+      return { success: false, message: e.message };
+    return { success: false, message: "获取模板失败" };
+  }
+}
+
+// ---- 另存为模板 ----
+export async function saveAsTemplateAction(input: {
+  sourcePlanId: string;
+  name: string;
+}): Promise<ActionState<{ templateId: string }>> {
+  try {
+    const ctx = await requirePermission(Permissions.LESSON_PLAN_CREATE);
+    const parsed = saveAsTemplateSchema.safeParse(input);
+    if (!parsed.success)
+      return { success: false, errors: parsed.error.flatten().fieldErrors };
+    const { templateId } = await saveAsTemplate({
+      ...parsed.data,
+      userId: ctx.userId,
+    });
+    return { success: true, data: { templateId } };
+  } catch (e) {
+    if (e instanceof PermissionDeniedError)
+      return { success: false, message: e.message };
+    return { success: false, message: "保存模板失败" };
+  }
+}
+
+// ---- 删除模板 ----
+export async function deleteTemplateAction(
+  templateId: string,
+): Promise<ActionState> {
+  try {
+    const ctx = await requirePermission(Permissions.LESSON_PLAN_DELETE);
+    await deletePersonalTemplate(templateId, ctx.userId);
+    return { success: true };
+  } catch (e) {
+    if (e instanceof PermissionDeniedError)
+      return { success: false, message: e.message };
+    return { success: false, message: "删除模板失败" };
+  }
+}