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

@@ -44,7 +44,17 @@ import {
   EnrollStudentByEmailSchema,
 } from "./schema"
 
-const isClassSubject = (v: string): v is ClassSubject => DEFAULT_CLASS_SUBJECTS.includes(v as ClassSubject)
+const CLASS_SUBJECT_STRINGS: readonly string[] = DEFAULT_CLASS_SUBJECTS
+
+const isClassSubject = (v: string): v is ClassSubject => CLASS_SUBJECT_STRINGS.includes(v)
+
+const isWeekday = (n: number): n is 1 | 2 | 3 | 4 | 5 | 6 | 7 =>
+  n >= 1 && n <= 7 && Number.isInteger(n)
+
+const toWeekday = (n: number): 1 | 2 | 3 | 4 | 5 | 6 | 7 => {
+  if (!isWeekday(n)) throw new Error("Invalid weekday")
+  return n
+}
 
 export async function createTeacherClassAction(
   prevState: ActionState<string> | null,
@@ -517,8 +527,7 @@ export async function createClassScheduleItemAction(
     try {
       const id = await createClassScheduleItem({
         classId,
-        // weekday 已被 Zod 校验为 1-7 的整数，断言为 Weekday 联合类型
-        weekday: weekday as 1 | 2 | 3 | 4 | 5 | 6 | 7,
+        weekday: toWeekday(weekday),
         startTime,
         endTime,
         course,
@@ -561,8 +570,7 @@ export async function updateClassScheduleItemAction(
     try {
       await updateClassScheduleItem(validatedScheduleId, {
         classId: classId ?? undefined,
-        // weekday 已被 Zod 校验为 1-7 的整数或 null/undefined，断言为 Weekday 联合类型
-        weekday: (weekday ?? undefined) as 1 | 2 | 3 | 4 | 5 | 6 | 7 | undefined,
+        weekday: typeof weekday === "number" ? toWeekday(weekday) : undefined,
         startTime: startTime ?? undefined,
         endTime: endTime ?? undefined,
         course: course ?? undefined,

src/modules/classes/components/class-detail/class-overview-stats.tsx

@@ -1,7 +1,7 @@
 
 import { AlertCircle, BarChart3, CheckCircle2, PenTool } from "lucide-react"
 
-import { Card, CardContent } from "@/shared/components/ui/card"
+import { StatCard } from "@/shared/components/ui/stat-card"
 
 interface ClassOverviewStatsProps {
   averageScore: number | null
@@ -18,57 +18,30 @@ export function ClassOverviewStats({
 }: ClassOverviewStatsProps) {
   return (
     <div className="grid grid-cols-2 gap-4 lg:grid-cols-4">
-      <StatsCard
+      <StatCard
         title="Class Average"
         value={averageScore ? `${averageScore.toFixed(1)}%` : "-"}
-        subValue="Overall performance"
+        description="Overall performance"
         icon={BarChart3}
       />
-      <StatsCard
+      <StatCard
         title="Submission Rate"
         value={`${submissionRate.toFixed(0)}%`}
-        subValue="Average turn-in rate"
+        description="Average turn-in rate"
         icon={CheckCircle2}
       />
-      <StatsCard
+      <StatCard
         title="To Grade"
         value={papersToGrade.toString()}
-        subValue="Pending reviews"
+        description="Pending reviews"
         icon={PenTool}
       />
-      <StatsCard
+      <StatCard
         title="Missed Deadlines"
         value={overdueCount.toString()}
-        subValue="Active assignments past due"
+        description="Active assignments past due"
         icon={AlertCircle}
       />
     </div>
   )
 }
-
-function StatsCard({
-  title,
-  value,
-  subValue,
-  icon: Icon,
-}: {
-  title: string
-  value: string
-  subValue: string
-  icon: React.ElementType
-}) {
-  return (
-    <Card>
-      <CardContent className="p-6">
-        <div className="flex items-center justify-between space-y-0 pb-2">
-          <p className="text-sm font-medium text-muted-foreground">{title}</p>
-          <Icon className="h-4 w-4 text-muted-foreground" />
-        </div>
-        <div className="flex flex-col gap-1">
-          <div className="text-2xl font-bold">{value}</div>
-          <p className="text-xs text-muted-foreground">{subValue}</p>
-        </div>
-      </CardContent>
-    </Card>
-  )
-}

src/modules/classes/components/grade-classes-view.tsx

@@ -140,9 +140,9 @@ export function GradeClassesClient({
   const formatSubjectTeachers = (list: ClassSubjectTeacherAssignment[]) => {
     const pairs = list
       .filter((x) => x.teacher)
-      .map((x) => `${x.subject}:${x.teacher?.name ?? ""}`)
+      .map((x) => `${x.subject}: ${x.teacher?.name ?? ""}`)
       .filter((x) => x.length > 0)
-    return pairs.length > 0 ? pairs.join("，") : "-"
+    return pairs.length > 0 ? pairs.join(", ") : "-"
   }
 
   const selectedCreateGrade = managedGrades.find(g => g.id === createGradeId)
@@ -180,8 +180,8 @@ export function GradeClassesClient({
                   <TableHead>Grade</TableHead>
                   <TableHead>Homeroom</TableHead>
                   <TableHead>Room</TableHead>
-                  <TableHead>班主任</TableHead>
-                  <TableHead>任课老师</TableHead>
+                  <TableHead>Homeroom Teacher</TableHead>
+                  <TableHead>Subject Teachers</TableHead>
                   <TableHead className="text-right">Students</TableHead>
                   <TableHead>Updated</TableHead>
                   <TableHead className="w-[60px]" />
@@ -280,7 +280,7 @@ export function GradeClassesClient({
             </div>
 
             <div className="grid grid-cols-4 items-center gap-4">
-              <Label className="text-right">班主任</Label>
+              <Label className="text-right">Homeroom Teacher</Label>
               <div className="col-span-3">
                 <Select value={createTeacherId} onValueChange={setCreateTeacherId} disabled={teachers.length === 0}>
                   <SelectTrigger>
@@ -367,9 +367,9 @@ export function GradeClassesClient({
               </div>
 
               <div className="grid grid-cols-4 items-center gap-4">
-                <Label className="text-right">班主任</Label>
-                <div className="col-span-3">
-                  <Select value={editTeacherId} onValueChange={setEditTeacherId} disabled={teachers.length === 0}>
+              <Label className="text-right">Homeroom Teacher</Label>
+              <div className="col-span-3">
+                <Select value={editTeacherId} onValueChange={setEditTeacherId} disabled={teachers.length === 0}>
                     <SelectTrigger>
                       <SelectValue placeholder={teachers.length === 0 ? "No teachers" : "Select a teacher"} />
                     </SelectTrigger>
@@ -386,7 +386,7 @@ export function GradeClassesClient({
               </div>
 
               <div className="space-y-3 rounded-md border p-4">
-                <div className="text-sm font-medium">任课老师</div>
+                <div className="text-sm font-medium">Subject Teachers</div>
                 <div className="grid gap-3">
                   {DEFAULT_CLASS_SUBJECTS.map((subject) => {
                     const selected = editSubjectTeachers.find((x) => x.subject === subject)?.teacherId ?? null

src/modules/classes/components/students-table.tsx

@@ -8,7 +8,7 @@ import { toast } from "sonner"
 import { Button } from "@/shared/components/ui/button"
 import { Avatar, AvatarFallback, AvatarImage } from "@/shared/components/ui/avatar"
 import { Card, CardContent, CardFooter, CardHeader } from "@/shared/components/ui/card"
-import { cn } from "@/shared/lib/utils"
+import { cn, getInitials } from "@/shared/lib/utils"
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -52,15 +52,6 @@ export function StudentsTable({ students }: { students: ClassStudent[] }) {
     }
   }
 
-  const getInitials = (name: string) => {
-    return name
-      .split(" ")
-      .map((n) => n[0])
-      .join("")
-      .toUpperCase()
-      .slice(0, 2)
-  }
-
   return (
     <>
       <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">

src/modules/classes/data-access.ts

@@ -50,14 +50,14 @@ export const getSessionTeacherId = async (): Promise<string | null> => {
 
 // Strict subjectId-based mapping: no aliasing
 
-export const isDuplicateInvitationCodeError = (err: unknown) => {
+export const isDuplicateInvitationCodeError = (err: unknown): boolean => {
   if (!err) return false
   const msg = err instanceof Error ? err.message : String(err)
   const m = msg.toLowerCase()
   return m.includes("duplicate") && (m.includes("invitation") || m.includes("invitation_code"))
 }
 
-const generateInvitationCode = () => {
+const generateInvitationCode = (): string => {
   const n = randomInt(0, 1_000_000)
   return String(n).padStart(6, "0")
 }
@@ -90,14 +90,15 @@ export const getClassSubjects = async (): Promise<string[]> => {
   return Array.from(new Set(names))
 }
 
-const normalizeSortText = (v: string | null | undefined) => (typeof v === "string" ? v.trim().toLowerCase() : "")
+const normalizeSortText = (v: string | null | undefined): string =>
+  typeof v === "string" ? v.trim().toLowerCase() : ""
 
-const parseFirstInt = (v: string) => {
+const parseFirstInt = (v: string): number | null => {
   const m = v.match(/\d+/)
   return m ? Number(m[0]) : null
 }
 
-const compareGradeLabel = (a: string, b: string) => {
+const compareGradeLabel = (a: string, b: string): number => {
   const aNum = parseFirstInt(a)
   const bNum = parseFirstInt(b)
   if (typeof aNum === "number" && typeof bNum === "number" && aNum !== bNum) return aNum - bNum
@@ -107,7 +108,7 @@ const compareGradeLabel = (a: string, b: string) => {
 export const compareClassLike = (
   a: { schoolName?: string | null; grade: string; name: string; homeroom?: string | null; room?: string | null },
   b: { schoolName?: string | null; grade: string; name: string; homeroom?: string | null; room?: string | null }
-) => {
+): number => {
   const schoolCmp = normalizeSortText(a.schoolName).localeCompare(normalizeSortText(b.schoolName))
   if (schoolCmp !== 0) return schoolCmp
 
@@ -228,6 +229,32 @@ export const getTeacherSubjectIdsByClass = async (classId: string, teacherId: st
   return getTeacherSubjectIdsForClass(teacherId, classId)
 }
 
+/**
+ * 获取多个班级的所有教师 ID（班主任 + 任课教师）。
+ * 供跨模块调用使用，避免直接查询 classes / classSubjectTeachers 表。
+ */
+export const getTeacherIdsByClassIds = async (classIds: string[]): Promise<string[]> => {
+  if (classIds.length === 0) return []
+  const [homeroomRows, subjectRows] = await Promise.all([
+    db
+      .select({ teacherId: classes.teacherId })
+      .from(classes)
+      .where(inArray(classes.id, classIds)),
+    db
+      .select({ teacherId: classSubjectTeachers.teacherId })
+      .from(classSubjectTeachers)
+      .where(inArray(classSubjectTeachers.classId, classIds)),
+  ])
+  const set = new Set<string>()
+  for (const r of homeroomRows) {
+    if (r.teacherId) set.add(r.teacherId)
+  }
+  for (const r of subjectRows) {
+    if (r.teacherId) set.add(r.teacherId)
+  }
+  return Array.from(set)
+}
+
 /**
  * 获取学生当前活跃班级的 ID。
  * 供跨模块调用使用，避免直接查询 classEnrollments 表。
@@ -242,6 +269,23 @@ export const getStudentActiveClassId = async (studentId: string): Promise<string
   return row?.classId ?? null
 }
 
+/**
+ * 获取学生当前活跃班级的 ID 与名称（一次 JOIN 查询）。
+ * 供跨模块调用使用，避免分别查询 classEnrollments 与 classes 表。
+ */
+export const getStudentActiveClass = async (
+  studentId: string,
+): Promise<{ classId: string; className: string } | null> => {
+  const [row] = await db
+    .select({ classId: classes.id, className: classes.name })
+    .from(classEnrollments)
+    .innerJoin(classes, eq(classes.id, classEnrollments.classId))
+    .where(and(eq(classEnrollments.studentId, studentId), eq(classEnrollments.status, "active")))
+    .orderBy(asc(classEnrollments.createdAt))
+    .limit(1)
+  return row ?? null
+}
+
 /**
  * 获取学生当前活跃班级对应的年级 ID。
  * 供跨模块调用使用，避免直接查询 classEnrollments/classes 表。
@@ -368,7 +412,8 @@ export const getTeacherClasses = cache(async (params?: { teacherId?: string }):
         .where(inArray(classes.id, allIds))
         .groupBy(classes.id, classes.schoolName, classes.name, classes.grade, classes.homeroom, classes.room, classes.invitationCode)
         .orderBy(asc(classes.schoolName), asc(classes.grade), asc(classes.name), asc(classes.homeroom), asc(classes.room))
-    } catch {
+    } catch (error) {
+      console.error("getTeacherClasses query failed:", error)
       return []
     }
   })()
@@ -672,7 +717,9 @@ export async function enrollTeacherByInvitationCode(
 
     const preferred = DEFAULT_CLASS_SUBJECTS.find((s) => subjectRows.some((r) => r.name === s))
     if (!preferred) throw new Error("Class already has assigned teachers")
-    const sid = subjectRows.find((r) => r.name === preferred)!.id
+    const subjectRow = subjectRows.find((r) => r.name === preferred)
+    if (!subjectRow) throw new Error("Subject not found")
+    const sid = subjectRow.id
 
     await db
       .update(classSubjectTeachers)