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/app/(dashboard)/teacher/grades/analytics/page.tsx

@@ -1,14 +1,14 @@
+import type { JSX } from "react"
 import Link from "next/link"
 import { BarChart3, ArrowLeft } from "lucide-react"
-import { asc } from "drizzle-orm"
 
-import { db } from "@/shared/db"
-import { subjects } from "@/shared/db/schema"
 import { Button } from "@/shared/components/ui/button"
 import { EmptyState } from "@/shared/components/ui/empty-state"
 import { getAuthContext } from "@/shared/lib/auth-guard"
+import { getParam, type SearchParams } from "@/shared/lib/search-params"
 import { getTeacherClasses } from "@/modules/classes/data-access"
 import { getGrades } from "@/modules/school/data-access"
+import { getSubjectOptions } from "@/modules/school/data-access"
 
 import {
   getClassComparison,
@@ -20,21 +20,15 @@ import { GradeTrendChart } from "@/modules/grades/components/grade-trend-chart"
 import { ClassComparisonChart } from "@/modules/grades/components/class-comparison-chart"
 import { SubjectComparisonChart } from "@/modules/grades/components/subject-comparison-chart"
 import { GradeDistributionChart } from "@/modules/grades/components/grade-distribution-chart"
+import { AnalyticsFilters } from "@/modules/grades/components/analytics-filters"
 
 export const dynamic = "force-dynamic"
 
-type SearchParams = { [key: string]: string | string[] | undefined }
-
-const getParam = (params: SearchParams, key: string) => {
-  const v = params[key]
-  return Array.isArray(v) ? v[0] : v
-}
-
 export default async function GradeAnalyticsPage({
   searchParams,
 }: {
   searchParams: Promise<SearchParams>
-}) {
+}): Promise<JSX.Element> {
   const sp = await searchParams
   const ctx = await getAuthContext()
 
@@ -45,16 +39,14 @@ export default async function GradeAnalyticsPage({
   const [classes, allGrades, allSubjects] = await Promise.all([
     getTeacherClasses(),
     getGrades(),
-    db.query.subjects.findMany({
-      orderBy: [asc(subjects.order), asc(subjects.name)],
-    }),
+    getSubjectOptions(),
   ])
 
   if (classes.length === 0) {
     return (
       <div className="h-full flex-1 flex-col space-y-8 p-8 md:flex">
         <div>
-          <h2 className="text-2xl font-bold tracking-tight">Grade Analytics</h2>
+          <h1 className="text-2xl font-bold tracking-tight">Grade Analytics</h1>
           <p className="text-muted-foreground">
             Trend analysis, class comparisons, and score distributions.
           </p>
@@ -106,14 +98,14 @@ export default async function GradeAnalyticsPage({
     <div className="h-full flex-1 flex-col space-y-6 p-8 md:flex">
       <div className="flex flex-col justify-between gap-4 md:flex-row md:items-center">
         <div>
-          <h2 className="text-2xl font-bold tracking-tight">Grade Analytics</h2>
+          <h1 className="text-2xl font-bold tracking-tight">Grade Analytics</h1>
           <p className="text-muted-foreground">
             Trend analysis, class comparisons, and score distributions.
           </p>
         </div>
         <Button asChild variant="outline">
           <Link href="/teacher/grades">
-            <ArrowLeft className="mr-2 h-4 w-4" />
+            <ArrowLeft className="mr-2 h-4 w-4" aria-hidden="true" />
             Back to Grades
           </Link>
         </Button>
@@ -137,123 +129,3 @@ export default async function GradeAnalyticsPage({
     </div>
   )
 }
-
-interface AnalyticsFiltersProps {
-  classes: Array<{ id: string; name: string }>
-  grades: Array<{ id: string; name: string }>
-  subjects: Array<{ id: string; name: string }>
-  currentClassId: string
-  currentSubjectId: string
-  currentGradeId: string
-}
-
-function AnalyticsFilters({
-  classes,
-  grades,
-  subjects,
-  currentClassId,
-  currentSubjectId,
-  currentGradeId,
-}: AnalyticsFiltersProps) {
-  const buildHref = (overrides: {
-    classId?: string
-    subjectId?: string
-    gradeId?: string
-  }) => {
-    const params = new URLSearchParams()
-    params.set(
-      "classId",
-      overrides.classId !== undefined ? overrides.classId : currentClassId
-    )
-    params.set(
-      "subjectId",
-      overrides.subjectId !== undefined ? overrides.subjectId : currentSubjectId
-    )
-    if (
-      overrides.gradeId !== undefined
-        ? overrides.gradeId
-        : currentGradeId
-    ) {
-      params.set(
-        "gradeId",
-        overrides.gradeId !== undefined ? overrides.gradeId : currentGradeId
-      )
-    }
-    return `/teacher/grades/analytics?${params.toString()}`
-  }
-
-  return (
-    <div className="rounded-lg border bg-card p-4">
-      <div className="grid grid-cols-1 gap-4 md:grid-cols-3">
-        <div className="space-y-2">
-          <div className="text-xs font-medium text-muted-foreground">Class</div>
-          <div className="flex flex-wrap gap-1.5">
-            {classes.map((c) => (
-              <a
-                key={c.id}
-                href={buildHref({ classId: c.id })}
-                className={`rounded-md border px-2.5 py-1 text-xs transition-colors ${
-                  c.id === currentClassId
-                    ? "border-primary bg-primary text-primary-foreground"
-                    : "bg-background hover:bg-accent"
-                }`}
-              >
-                {c.name}
-              </a>
-            ))}
-          </div>
-        </div>
-
-        <div className="space-y-2">
-          <div className="text-xs font-medium text-muted-foreground">Subject</div>
-          <div className="flex flex-wrap gap-1.5">
-            <a
-              href={buildHref({ subjectId: "all" })}
-              className={`rounded-md border px-2.5 py-1 text-xs transition-colors ${
-                currentSubjectId === "all"
-                  ? "border-primary bg-primary text-primary-foreground"
-                  : "bg-background hover:bg-accent"
-              }`}
-            >
-              All
-            </a>
-            {subjects.map((s) => (
-              <a
-                key={s.id}
-                href={buildHref({ subjectId: s.id })}
-                className={`rounded-md border px-2.5 py-1 text-xs transition-colors ${
-                  s.id === currentSubjectId
-                    ? "border-primary bg-primary text-primary-foreground"
-                    : "bg-background hover:bg-accent"
-                }`}
-              >
-                {s.name}
-              </a>
-            ))}
-          </div>
-        </div>
-
-        <div className="space-y-2">
-          <div className="text-xs font-medium text-muted-foreground">
-            Grade (for class comparison)
-          </div>
-          <div className="flex flex-wrap gap-1.5">
-            {grades.map((g) => (
-              <a
-                key={g.id}
-                href={buildHref({ gradeId: g.id })}
-                className={`rounded-md border px-2.5 py-1 text-xs transition-colors ${
-                  g.id === currentGradeId
-                    ? "border-primary bg-primary text-primary-foreground"
-                    : "bg-background hover:bg-accent"
-                }`}
-              >
-                {g.name}
-              </a>
-            ))}
-          </div>
-        </div>
-      </div>
-    </div>
-  )
-}

src/app/(dashboard)/teacher/grades/entry/page.tsx

@@ -1,42 +1,37 @@
-import { db } from "@/shared/db"
-import { subjects } from "@/shared/db/schema"
-import { asc } from "drizzle-orm"
+import type { JSX } from "react"
 import { getTeacherClasses } from "@/modules/classes/data-access"
 import { getClassStudentsForEntry } from "@/modules/grades/data-access"
+import { getSubjectOptions } from "@/modules/school/data-access"
 import { BatchGradeEntry } from "@/modules/grades/components/batch-grade-entry"
+import { getParam, type SearchParams } from "@/shared/lib/search-params"
 
 export const dynamic = "force-dynamic"
 
-type SearchParams = { [key: string]: string | string[] | undefined }
-
-const getParam = (params: SearchParams, key: string) => {
-  const v = params[key]
-  return Array.isArray(v) ? v[0] : v
-}
-
-export default async function BatchEntryPage({ searchParams }: { searchParams: Promise<SearchParams> }) {
+export default async function BatchEntryPage({
+  searchParams,
+}: {
+  searchParams: Promise<SearchParams>
+}): Promise<JSX.Element> {
   const sp = await searchParams
 
   const defaultClassId = getParam(sp, "classId")
   const defaultSubjectId = getParam(sp, "subjectId")
 
-  const [classes, allSubjects] = await Promise.all([
+  const [classes, allSubjects, students] = await Promise.all([
     getTeacherClasses(),
-    db.query.subjects.findMany({ orderBy: [asc(subjects.order), asc(subjects.name)] }),
+    getSubjectOptions(),
+    defaultClassId
+      ? getClassStudentsForEntry(defaultClassId)
+      : Promise.resolve([] as Awaited<ReturnType<typeof getClassStudentsForEntry>>),
   ])
 
   const classOptions = classes.map((c) => ({ id: c.id, name: c.name }))
   const subjectOptions = allSubjects.map((s) => ({ id: s.id, name: s.name }))
 
-  let students: Array<{ id: string; name: string; email: string }> = []
-  if (defaultClassId) {
-    students = await getClassStudentsForEntry(defaultClassId)
-  }
-
   return (
     <div className="h-full flex-1 flex-col space-y-8 p-8 md:flex">
       <div>
-        <h2 className="text-2xl font-bold tracking-tight">Batch Grade Entry</h2>
+        <h1 className="text-2xl font-bold tracking-tight">Batch Grade Entry</h1>
         <p className="text-muted-foreground">Enter grades for all students in a class at once.</p>
       </div>
 

src/app/(dashboard)/teacher/grades/page.tsx

@@ -1,27 +1,36 @@
+import type { JSX } from "react"
 import Link from "next/link"
 import { PlusCircle, BarChart3, ClipboardList } from "lucide-react"
 import { Button } from "@/shared/components/ui/button"
 import { EmptyState } from "@/shared/components/ui/empty-state"
-import { db } from "@/shared/db"
-import { subjects } from "@/shared/db/schema"
-import { asc } from "drizzle-orm"
 import { getAuthContext } from "@/shared/lib/auth-guard"
+import { getParam, type SearchParams } from "@/shared/lib/search-params"
 import { getTeacherClasses } from "@/modules/classes/data-access"
 import { getGradeRecords } from "@/modules/grades/data-access"
+import { getSubjectOptions } from "@/modules/school/data-access"
 import { GradeQueryFilters } from "@/modules/grades/components/grade-query-filters"
 import { GradeRecordList } from "@/modules/grades/components/grade-record-list"
 import { ExportButton } from "@/modules/grades/components/export-button"
+import type { GradeRecordType, GradeRecordSemester } from "@/modules/grades/types"
 
 export const dynamic = "force-dynamic"
 
-type SearchParams = { [key: string]: string | string[] | undefined }
+const VALID_GRADE_TYPES: ReadonlySet<string> = new Set(["exam", "quiz", "homework", "other"])
+const VALID_SEMESTERS: ReadonlySet<string> = new Set(["1", "2"])
 
-const getParam = (params: SearchParams, key: string) => {
-  const v = params[key]
-  return Array.isArray(v) ? v[0] : v
+function parseGradeType(v?: string): GradeRecordType | undefined {
+  return v && VALID_GRADE_TYPES.has(v) ? (v as GradeRecordType) : undefined
 }
 
-export default async function TeacherGradesPage({ searchParams }: { searchParams: Promise<SearchParams> }) {
+function parseSemester(v?: string): GradeRecordSemester | undefined {
+  return v && VALID_SEMESTERS.has(v) ? (v as GradeRecordSemester) : undefined
+}
+
+export default async function TeacherGradesPage({
+  searchParams,
+}: {
+  searchParams: Promise<SearchParams>
+}): Promise<JSX.Element> {
   const sp = await searchParams
   const ctx = await getAuthContext()
 
@@ -30,20 +39,19 @@ export default async function TeacherGradesPage({ searchParams }: { searchParams
   const type = getParam(sp, "type")
   const semester = getParam(sp, "semester")
 
-  const [classes, allSubjects] = await Promise.all([
+  const [classes, allSubjects, records] = await Promise.all([
     getTeacherClasses(),
-    db.query.subjects.findMany({ orderBy: [asc(subjects.order), asc(subjects.name)] }),
+    getSubjectOptions(),
+    getGradeRecords({
+      scope: ctx.dataScope,
+      currentUserId: ctx.userId,
+      classId: classId && classId !== "all" ? classId : undefined,
+      subjectId: subjectId && subjectId !== "all" ? subjectId : undefined,
+      type: type && type !== "all" ? parseGradeType(type) : undefined,
+      semester: semester && semester !== "all" ? parseSemester(semester) : undefined,
+    }),
   ])
 
-  const records = await getGradeRecords({
-    scope: ctx.dataScope,
-    currentUserId: ctx.userId,
-    classId: classId && classId !== "all" ? classId : undefined,
-    subjectId: subjectId && subjectId !== "all" ? subjectId : undefined,
-    type: type && type !== "all" ? (type as "exam" | "quiz" | "homework" | "other") : undefined,
-    semester: semester && semester !== "all" ? (semester as "1" | "2") : undefined,
-  })
-
   const classOptions = classes.map((c) => ({ id: c.id, name: c.name }))
   const subjectOptions = allSubjects.map((s) => ({ id: s.id, name: s.name }))
 
@@ -51,19 +59,19 @@ export default async function TeacherGradesPage({ searchParams }: { searchParams
     <div className="h-full flex-1 flex-col space-y-8 p-8 md:flex">
       <div className="flex items-center justify-between space-y-2">
         <div>
-          <h2 className="text-2xl font-bold tracking-tight">Grades</h2>
+          <h1 className="text-2xl font-bold tracking-tight">Grades</h1>
           <p className="text-muted-foreground">Manage student grade records.</p>
         </div>
         <div className="flex items-center gap-2">
           <Button asChild variant="outline">
             <Link href="/teacher/grades/stats">
-              <BarChart3 className="mr-2 h-4 w-4" />
+              <BarChart3 className="mr-2 h-4 w-4" aria-hidden="true" />
               Statistics
             </Link>
           </Button>
           <Button asChild variant="outline">
             <Link href="/teacher/grades/entry">
-              <ClipboardList className="mr-2 h-4 w-4" />
+              <ClipboardList className="mr-2 h-4 w-4" aria-hidden="true" />
               Batch Entry
             </Link>
           </Button>
@@ -74,7 +82,7 @@ export default async function TeacherGradesPage({ searchParams }: { searchParams
           />
           <Button asChild>
             <Link href="/teacher/grades/entry">
-              <PlusCircle className="mr-2 h-4 w-4" />
+              <PlusCircle className="mr-2 h-4 w-4" aria-hidden="true" />
               Record Grades
             </Link>
           </Button>

src/app/(dashboard)/teacher/grades/stats/page.tsx

@@ -1,23 +1,21 @@
-import { db } from "@/shared/db"
-import { subjects } from "@/shared/db/schema"
-import { asc } from "drizzle-orm"
+import type { JSX } from "react"
 import { getTeacherClasses } from "@/modules/classes/data-access"
 import { getClassGradeStatsWithMeta, getClassRanking } from "@/modules/grades/data-access"
+import { getSubjectOptions } from "@/modules/school/data-access"
 import { ClassGradeReport } from "@/modules/grades/components/class-grade-report"
 import { ExportButton } from "@/modules/grades/components/export-button"
+import { StatsClassSelector } from "@/modules/grades/components/stats-class-selector"
 import { EmptyState } from "@/shared/components/ui/empty-state"
+import { getParam, type SearchParams } from "@/shared/lib/search-params"
 import { BarChart3 } from "lucide-react"
 
 export const dynamic = "force-dynamic"
 
-type SearchParams = { [key: string]: string | string[] | undefined }
-
-const getParam = (params: SearchParams, key: string) => {
-  const v = params[key]
-  return Array.isArray(v) ? v[0] : v
-}
-
-export default async function StatsPage({ searchParams }: { searchParams: Promise<SearchParams> }) {
+export default async function StatsPage({
+  searchParams,
+}: {
+  searchParams: Promise<SearchParams>
+}): Promise<JSX.Element> {
   const sp = await searchParams
 
   const classId = getParam(sp, "classId")
@@ -25,14 +23,14 @@ export default async function StatsPage({ searchParams }: { searchParams: Promis
 
   const [classes, allSubjects] = await Promise.all([
     getTeacherClasses(),
-    db.query.subjects.findMany({ orderBy: [asc(subjects.order), asc(subjects.name)] }),
+    getSubjectOptions(),
   ])
 
   if (classes.length === 0) {
     return (
       <div className="h-full flex-1 flex-col space-y-8 p-8 md:flex">
         <div>
-          <h2 className="text-2xl font-bold tracking-tight">Grade Statistics</h2>
+          <h1 className="text-2xl font-bold tracking-tight">Grade Statistics</h1>
           <p className="text-muted-foreground">View class grade statistics and rankings.</p>
         </div>
         <EmptyState
@@ -60,7 +58,7 @@ export default async function StatsPage({ searchParams }: { searchParams: Promis
     <div className="h-full flex-1 flex-col space-y-8 p-8 md:flex">
       <div className="flex items-center justify-between">
         <div>
-          <h2 className="text-2xl font-bold tracking-tight">Grade Statistics</h2>
+          <h1 className="text-2xl font-bold tracking-tight">Grade Statistics</h1>
           <p className="text-muted-foreground">View class grade statistics and rankings.</p>
         </div>
         <ExportButton
@@ -82,58 +80,3 @@ export default async function StatsPage({ searchParams }: { searchParams: Promis
     </div>
   )
 }
-
-function StatsClassSelector({
-  classes,
-  subjects,
-  currentClassId,
-  currentSubjectId,
-}: {
-  classes: Array<{ id: string; name: string }>
-  subjects: Array<{ id: string; name: string }>
-  currentClassId: string
-  currentSubjectId: string
-}) {
-  return (
-    <div className="flex flex-wrap gap-2">
-      {classes.map((c) => (
-        <a
-          key={c.id}
-          href={`/teacher/grades/stats?classId=${c.id}${currentSubjectId !== "all" ? `&subjectId=${currentSubjectId}` : ""}`}
-          className={`rounded-md border px-3 py-1.5 text-sm transition-colors ${
-            c.id === currentClassId
-              ? "border-primary bg-primary text-primary-foreground"
-              : "bg-card hover:bg-accent"
-          }`}
-        >
-          {c.name}
-        </a>
-      ))}
-      <div className="ml-auto flex flex-wrap gap-2">
-        <a
-          href={`/teacher/grades/stats?classId=${currentClassId}`}
-          className={`rounded-md border px-3 py-1.5 text-sm transition-colors ${
-            currentSubjectId === "all"
-              ? "border-primary bg-primary text-primary-foreground"
-              : "bg-card hover:bg-accent"
-          }`}
-        >
-          All Subjects
-        </a>
-        {subjects.map((s) => (
-          <a
-            key={s.id}
-            href={`/teacher/grades/stats?classId=${currentClassId}&subjectId=${s.id}`}
-            className={`rounded-md border px-3 py-1.5 text-sm transition-colors ${
-              s.id === currentSubjectId
-                ? "border-primary bg-primary text-primary-foreground"
-                : "bg-card hover:bg-accent"
-            }`}
-          >
-            {s.name}
-          </a>
-        ))}
-      </div>
-    </div>
-  )
-}