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/school/actions.ts

@@ -30,15 +30,18 @@ export async function createDepartmentAction(
 ): Promise<ActionState<string>> {
   try {
     await requirePermission(Permissions.SCHOOL_MANAGE)
-    const parsed = UpsertDepartmentSchema.parse({
+    const parsed = UpsertDepartmentSchema.safeParse({
       name: formData.get("name"),
       description: formData.get("description"),
     })
+    if (!parsed.success) {
+      return { success: false, message: "Invalid form data", errors: parsed.error.flatten().fieldErrors }
+    }
 
     await createDepartment({
       id: createId(),
-      name: parsed.name,
-      description: parsed.description ?? null,
+      name: parsed.data.name,
+      description: parsed.data.description ?? null,
     })
 
     revalidatePath("/admin/school/departments")
@@ -57,14 +60,17 @@ export async function updateDepartmentAction(
 ): Promise<ActionState<string>> {
   try {
     await requirePermission(Permissions.SCHOOL_MANAGE)
-    const parsed = UpsertDepartmentSchema.parse({
+    const parsed = UpsertDepartmentSchema.safeParse({
       name: formData.get("name"),
       description: formData.get("description"),
     })
+    if (!parsed.success) {
+      return { success: false, message: "Invalid form data", errors: parsed.error.flatten().fieldErrors }
+    }
 
     await updateDepartment(departmentId, {
-      name: parsed.name,
-      description: parsed.description ?? null,
+      name: parsed.data.name,
+      description: parsed.data.description ?? null,
     })
 
     revalidatePath("/admin/school/departments")
@@ -95,19 +101,22 @@ export async function createAcademicYearAction(
 ): Promise<ActionState<string>> {
   try {
     await requirePermission(Permissions.SCHOOL_MANAGE)
-    const parsed = UpsertAcademicYearSchema.parse({
+    const parsed = UpsertAcademicYearSchema.safeParse({
       name: formData.get("name"),
       startDate: formData.get("startDate"),
       endDate: formData.get("endDate"),
       isActive: formData.get("isActive") ?? "false",
     })
+    if (!parsed.success) {
+      return { success: false, message: "Invalid form data", errors: parsed.error.flatten().fieldErrors }
+    }
 
     await createAcademicYear({
       id: createId(),
-      name: parsed.name,
-      startDate: new Date(parsed.startDate),
-      endDate: new Date(parsed.endDate),
-      isActive: parsed.isActive,
+      name: parsed.data.name,
+      startDate: new Date(parsed.data.startDate),
+      endDate: new Date(parsed.data.endDate),
+      isActive: parsed.data.isActive,
     })
 
     revalidatePath("/admin/school/academic-year")
@@ -126,18 +135,21 @@ export async function updateAcademicYearAction(
 ): Promise<ActionState<string>> {
   try {
     await requirePermission(Permissions.SCHOOL_MANAGE)
-    const parsed = UpsertAcademicYearSchema.parse({
+    const parsed = UpsertAcademicYearSchema.safeParse({
       name: formData.get("name"),
       startDate: formData.get("startDate"),
       endDate: formData.get("endDate"),
       isActive: formData.get("isActive") ?? "false",
     })
+    if (!parsed.success) {
+      return { success: false, message: "Invalid form data", errors: parsed.error.flatten().fieldErrors }
+    }
 
     await updateAcademicYear(academicYearId, {
-      name: parsed.name,
-      startDate: new Date(parsed.startDate),
-      endDate: new Date(parsed.endDate),
-      isActive: parsed.isActive,
+      name: parsed.data.name,
+      startDate: new Date(parsed.data.startDate),
+      endDate: new Date(parsed.data.endDate),
+      isActive: parsed.data.isActive,
     })
 
     revalidatePath("/admin/school/academic-year")
@@ -168,19 +180,22 @@ export async function createSchoolAction(
 ): Promise<ActionState<string>> {
   try {
     await requirePermission(Permissions.SCHOOL_MANAGE)
-    const parsed = UpsertSchoolSchema.parse({
+    const parsed = UpsertSchoolSchema.safeParse({
       name: formData.get("name"),
       code: formData.get("code"),
     })
+    if (!parsed.success) {
+      return { success: false, message: "Invalid form data", errors: parsed.error.flatten().fieldErrors }
+    }
 
     await createSchool({
       id: createId(),
-      name: parsed.name,
-      code: parsed.code?.trim() ? parsed.code.trim() : null,
+      name: parsed.data.name,
+      code: parsed.data.code?.trim() ? parsed.data.code.trim() : null,
     })
 
     after(() =>
-      logAudit({ action: "school.create", module: "school", targetType: "school", detail: { name: parsed.name } })
+      logAudit({ action: "school.create", module: "school", targetType: "school", detail: { name: parsed.data.name } })
     )
 
     revalidatePath("/admin/school/schools")
@@ -199,14 +214,17 @@ export async function updateSchoolAction(
 ): Promise<ActionState<string>> {
   try {
     await requirePermission(Permissions.SCHOOL_MANAGE)
-    const parsed = UpsertSchoolSchema.parse({
+    const parsed = UpsertSchoolSchema.safeParse({
       name: formData.get("name"),
       code: formData.get("code"),
     })
+    if (!parsed.success) {
+      return { success: false, message: "Invalid form data", errors: parsed.error.flatten().fieldErrors }
+    }
 
     await updateSchool(schoolId, {
-      name: parsed.name,
-      code: parsed.code?.trim() ? parsed.code.trim() : null,
+      name: parsed.data.name,
+      code: parsed.data.code?.trim() ? parsed.data.code.trim() : null,
     })
 
     after(() =>
@@ -215,7 +233,7 @@ export async function updateSchoolAction(
         module: "school",
         targetId: schoolId,
         targetType: "school",
-        detail: { name: parsed.name },
+        detail: { name: parsed.data.name },
       })
     )
 
@@ -253,21 +271,24 @@ export async function createGradeAction(
 ): Promise<ActionState<string>> {
   try {
     await requirePermission(Permissions.GRADE_MANAGE)
-    const parsed = UpsertGradeSchema.parse({
+    const parsed = UpsertGradeSchema.safeParse({
       schoolId: formData.get("schoolId"),
       name: formData.get("name"),
       order: formData.get("order"),
       gradeHeadId: formData.get("gradeHeadId"),
       teachingHeadId: formData.get("teachingHeadId"),
     })
+    if (!parsed.success) {
+      return { success: false, message: "Invalid form data", errors: parsed.error.flatten().fieldErrors }
+    }
 
     await createGrade({
       id: createId(),
-      schoolId: parsed.schoolId,
-      name: parsed.name,
-      order: parsed.order,
-      gradeHeadId: parsed.gradeHeadId,
-      teachingHeadId: parsed.teachingHeadId,
+      schoolId: parsed.data.schoolId,
+      name: parsed.data.name,
+      order: parsed.data.order,
+      gradeHeadId: parsed.data.gradeHeadId,
+      teachingHeadId: parsed.data.teachingHeadId,
     })
 
     revalidatePath("/admin/school/grades")
@@ -286,20 +307,23 @@ export async function updateGradeAction(
 ): Promise<ActionState<string>> {
   try {
     await requirePermission(Permissions.GRADE_MANAGE)
-    const parsed = UpsertGradeSchema.parse({
+    const parsed = UpsertGradeSchema.safeParse({
       schoolId: formData.get("schoolId"),
       name: formData.get("name"),
       order: formData.get("order"),
       gradeHeadId: formData.get("gradeHeadId"),
       teachingHeadId: formData.get("teachingHeadId"),
     })
+    if (!parsed.success) {
+      return { success: false, message: "Invalid form data", errors: parsed.error.flatten().fieldErrors }
+    }
 
     await updateGrade(gradeId, {
-      schoolId: parsed.schoolId,
-      name: parsed.name,
-      order: parsed.order,
-      gradeHeadId: parsed.gradeHeadId,
-      teachingHeadId: parsed.teachingHeadId,
+      schoolId: parsed.data.schoolId,
+      name: parsed.data.name,
+      order: parsed.data.order,
+      gradeHeadId: parsed.data.gradeHeadId,
+      teachingHeadId: parsed.data.teachingHeadId,
     })
 
     revalidatePath("/admin/school/grades")

src/modules/school/data-access.ts

@@ -21,7 +21,7 @@ import type {
   StaffOption,
 } from "./types"
 
-const toIso = (d: Date) => d.toISOString()
+const toIso = (d: Date): string => d.toISOString()
 
 export const getDepartments = cache(async (): Promise<DepartmentListItem[]> => {
   try {
@@ -395,6 +395,40 @@ export const getGradeOptions = cache(async (): Promise<GradeOption[]> => {
   }
 })
 
+/**
+ * 按 ID 获取单个年级名称。
+ * 供跨模块调用使用，避免为单个年级拉取全量年级选项。
+ */
+export const getGradeNameById = cache(
+  async (gradeId: string): Promise<string | null> => {
+    const id = gradeId.trim()
+    if (!id) return null
+    const [row] = await db
+      .select({ name: grades.name })
+      .from(grades)
+      .where(eq(grades.id, id))
+      .limit(1)
+    return row?.name ?? null
+  },
+)
+
+/**
+ * 按 ID 获取单个科目名称。
+ * 供跨模块调用使用，避免为单个科目拉取全量科目选项或直接查询 subjects 表。
+ */
+export const getSubjectNameById = cache(
+  async (subjectId: string): Promise<string | null> => {
+    const id = subjectId.trim()
+    if (!id) return null
+    const [row] = await db
+      .select({ name: subjects.name })
+      .from(subjects)
+      .where(eq(subjects.id, id))
+      .limit(1)
+    return row?.name ?? null
+  },
+)
+
 // ---------------------------------------------------------------------------
 // Cross-module query interfaces — grade head/teaching head verification
 // ---------------------------------------------------------------------------
@@ -403,7 +437,7 @@ export const getGradeOptions = cache(async (): Promise<GradeOption[]> => {
  * 校验用户是否为指定年级的年级主任。
  * 供 classes 模块跨模块调用使用，避免直接查询 grades 表。
  */
-export const isGradeHead = async (
+export const isGradeHead = cache(async (
   gradeId: string,
   userId: string
 ): Promise<boolean> => {
@@ -417,13 +451,13 @@ export const isGradeHead = async (
     .where(and(eq(grades.id, trimmedGradeId), eq(grades.gradeHeadId, trimmedUserId)))
     .limit(1)
   return Boolean(row)
-}
+})
 
 /**
  * 校验用户是否为指定年级的年级主任或教学主任。
  * 供 classes 模块跨模块调用使用，避免直接查询 grades 表。
  */
-export const isGradeManager = async (
+export const isGradeManager = cache(async (
   gradeId: string,
   userId: string
 ): Promise<boolean> => {
@@ -442,13 +476,13 @@ export const isGradeManager = async (
     )
     .limit(1)
   return Boolean(row)
-}
+})
 
 /**
  * 根据年级名称（大小写不敏感）查找用户担任年级主任的年级 ID。
  * 供 classes 模块跨模块调用使用，避免直接查询 grades 表。
  */
-export const findGradeIdByHeadAndName = async (
+export const findGradeIdByHeadAndName = cache(async (
   userId: string,
   gradeName: string
 ): Promise<string | null> => {
@@ -467,4 +501,4 @@ export const findGradeIdByHeadAndName = async (
     )
     .limit(1)
   return row?.id ?? null
-}
+})