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/diagnostic/components/mastery-radar-chart.tsx

@@ -1,114 +1,69 @@
 "use client"
 
-import { RadarChart, PolarGrid, PolarAngleAxis, PolarRadiusAxis, Radar, Legend } from "recharts"
 import { Target } from "lucide-react"
 
-import {
-  Card,
-  CardContent,
-  CardDescription,
-  CardHeader,
-  CardTitle,
-} from "@/shared/components/ui/card"
-import {
-  ChartContainer,
-  ChartTooltip,
-  ChartTooltipContent,
-} from "@/shared/components/ui/chart"
-import { EmptyState } from "@/shared/components/ui/empty-state"
+import { ChartCardShell } from "@/shared/components/charts/chart-card-shell"
+import { ComparisonRadarChart } from "@/shared/components/charts/comparison-radar-chart"
 import type { MasteryRadarPoint } from "@/modules/diagnostic/types"
 
-const chartConfig = {
-  student: { label: "Student", color: "hsl(var(--primary))" },
-  classAverage: { label: "Class Avg", color: "hsl(var(--chart-2))" },
-}
-
 interface MasteryRadarChartProps {
   data: MasteryRadarPoint[]
 }
 
 export function MasteryRadarChart({ data }: MasteryRadarChartProps) {
-  if (!data || data.length === 0) {
-    return (
-      <Card>
-        <CardHeader>
-          <CardTitle className="flex items-center gap-2">
-            <Target className="h-4 w-4" />
-            Knowledge Point Mastery
-          </CardTitle>
-          <CardDescription>
-            Radar chart of mastery level (0-100) across knowledge points.
-          </CardDescription>
-        </CardHeader>
-        <CardContent>
-          <EmptyState
-            icon={Target}
-            title="No mastery data"
-            description="No knowledge point mastery records found for this student."
-            className="border-none h-60"
-          />
-        </CardContent>
-      </Card>
-    )
-  }
+  const isEmpty = !data || data.length === 0
 
-  // 知识点名称过长时截断显示
-  const chartData = data.map((d) => ({
-    ...d,
-    shortName: d.knowledgePoint.length > 8 ? `${d.knowledgePoint.slice(0, 8)}...` : d.knowledgePoint,
-  }))
+  const chartData = isEmpty
+    ? []
+    : data.map((d) => ({
+        ...d,
+        shortName:
+          d.knowledgePoint.length > 8
+            ? `${d.knowledgePoint.slice(0, 8)}...`
+            : d.knowledgePoint,
+      }))
 
-  const hasClassAverage = data.some((d) => d.classAverage !== undefined)
+  const hasClassAverage = !isEmpty && data.some((d) => d.classAverage !== undefined)
 
   return (
-    <Card>
-      <CardHeader>
-        <CardTitle className="flex items-center gap-2">
-          <Target className="h-4 w-4" />
-          Knowledge Point Mastery
-        </CardTitle>
-        <CardDescription>
-          Radar chart of mastery level (0-100) across knowledge points.
-        </CardDescription>
-      </CardHeader>
-      <CardContent>
-        <ChartContainer config={chartConfig} className="mx-auto h-[360px] w-full max-w-[520px]">
-          <RadarChart data={chartData} outerRadius="75%">
-            <PolarGrid strokeDasharray="4 4" strokeOpacity={0.4} />
-            <PolarAngleAxis
-              dataKey="shortName"
-              tick={{ fontSize: 11, fill: "hsl(var(--muted-foreground))" }}
-            />
-            <PolarRadiusAxis
-              domain={[0, 100]}
-              tickCount={5}
-              tick={{ fontSize: 10, fill: "hsl(var(--muted-foreground))" }}
-              axisLine={false}
-            />
-            <ChartTooltip content={<ChartTooltipContent className="w-[220px]" />} />
-            {hasClassAverage ? <Legend /> : null}
-            <Radar
-              name="Student"
-              dataKey="student"
-              stroke="var(--color-student)"
-              fill="var(--color-student)"
-              fillOpacity={0.35}
-              strokeWidth={2}
-            />
-            {hasClassAverage ? (
-              <Radar
-                name="Class Avg"
-                dataKey="classAverage"
-                stroke="var(--color-classAverage)"
-                fill="var(--color-classAverage)"
-                fillOpacity={0.15}
-                strokeWidth={2}
-                strokeDasharray="4 4"
-              />
-            ) : null}
-          </RadarChart>
-        </ChartContainer>
-      </CardContent>
-    </Card>
+    <ChartCardShell
+      title="Knowledge Point Mastery"
+      description="Radar chart of mastery level (0-100) across knowledge points."
+      icon={Target}
+      isEmpty={isEmpty}
+      emptyTitle="No mastery data"
+      emptyDescription="No knowledge point mastery records found for this student."
+      emptyClassName="h-60"
+    >
+      <ComparisonRadarChart
+        data={chartData}
+        angleKey="shortName"
+        angleTickFontSize={11}
+        domain={[0, 100]}
+        tickCount={5}
+        showLegend={hasClassAverage}
+        heightClassName="mx-auto h-[360px] w-full max-w-[520px]"
+        gridStrokeDasharray="4 4"
+        series={[
+          {
+            dataKey: "student",
+            name: "Student",
+            color: "hsl(var(--primary))",
+            fillOpacity: 0.35,
+            strokeWidth: 2,
+            show: true,
+          },
+          {
+            dataKey: "classAverage",
+            name: "Class Avg",
+            color: "hsl(var(--chart-2))",
+            fillOpacity: 0.15,
+            strokeWidth: 2,
+            strokeDasharray: "4 4",
+            show: hasClassAverage,
+          },
+        ]}
+      />
+    </ChartCardShell>
   )
 }

src/modules/diagnostic/data-access-reports.ts

@@ -1,7 +1,7 @@
 import "server-only"
 
 import { createId } from "@paralleldrive/cuid2"
-import { and, desc, eq, inArray } from "drizzle-orm"
+import { and, desc, eq, inArray, type SQL } from "drizzle-orm"
 import { cache } from "react"
 
 import { db } from "@/shared/db"
@@ -19,8 +19,6 @@ const toNumber = (v: unknown): number => {
   return Number.isFinite(n) ? n : 0
 }
 
-const round2 = (n: number): number => Math.round(n * 100) / 100
-
 const isStringArray = (v: unknown): v is string[] =>
   Array.isArray(v) && v.every((item) => typeof item === "string")
 
@@ -127,7 +125,7 @@ export async function generateClassDiagnosticReport(
 /** 查询诊断报告列表 */
 export const getDiagnosticReports = cache(
   async (filters: DiagnosticReportQueryParams): Promise<DiagnosticReportWithDetails[]> => {
-    const conditions = []
+    const conditions: SQL[] = []
     if (filters.studentId) conditions.push(eq(learningDiagnosticReports.studentId, filters.studentId))
     if (filters.reportType) conditions.push(eq(learningDiagnosticReports.reportType, filters.reportType))
     if (filters.status) conditions.push(eq(learningDiagnosticReports.status, filters.status))
@@ -203,6 +201,3 @@ export async function publishDiagnosticReport(id: string): Promise<void> {
 export async function deleteDiagnosticReport(id: string): Promise<void> {
   await db.delete(learningDiagnosticReports).where(eq(learningDiagnosticReports.id, id))
 }
-
-// 防止 round2 未使用警告（保留以备扩展）
-void round2

src/modules/diagnostic/data-access.ts

@@ -116,52 +116,62 @@ export async function updateMasteryFromSubmission(submissionId: string): Promise
   }
 
   const now = new Date()
-  for (const [kpId, stat] of kpStats.entries()) {
-    const masteryLevel = stat.total > 0 ? round2((stat.correct / stat.total) * 100) : 0
-    await db
-      .insert(knowledgePointMastery)
-      .values({
-        studentId: submission.studentId,
-        knowledgePointId: kpId,
-        masteryLevel: String(masteryLevel),
-        totalQuestions: stat.total,
-        correctQuestions: stat.correct,
-        lastAssessedAt: now,
-      })
-      .onDuplicateKeyUpdate({
-        set: {
+  await Promise.all(
+    Array.from(kpStats.entries()).map(async ([kpId, stat]) => {
+      const masteryLevel = stat.total > 0 ? round2((stat.correct / stat.total) * 100) : 0
+      await db
+        .insert(knowledgePointMastery)
+        .values({
+          studentId: submission.studentId,
+          knowledgePointId: kpId,
           masteryLevel: String(masteryLevel),
           totalQuestions: stat.total,
           correctQuestions: stat.correct,
           lastAssessedAt: now,
-          updatedAt: now,
-        },
-      })
-  }
+        })
+        .onDuplicateKeyUpdate({
+          set: {
+            masteryLevel: String(masteryLevel),
+            totalQuestions: stat.total,
+            correctQuestions: stat.correct,
+            lastAssessedAt: now,
+            updatedAt: now,
+          },
+        })
+    }),
+  )
 }
 
 /** 获取班级掌握度摘要 */
 export const getClassMasterySummary = cache(async (classId: string): Promise<ClassMasterySummary | null> => {
   const classExists = await getClassExists(classId)
   if (!classExists) return null
-  const className = (await getClassNameById(classId)) ?? "Unknown"
 
-  const studentIds = await getActiveStudentIdsByClassId(classId)
+  // 班级名称 与 学生列表 相互独立，并行拉取
+  const [classNameResult, studentIds] = await Promise.all([
+    getClassNameById(classId),
+    getActiveStudentIdsByClassId(classId),
+  ])
+  const className = classNameResult ?? "Unknown"
+
   if (studentIds.length === 0) {
     return { classId, className, studentCount: 0, averageMastery: 0, knowledgePointStats: [], studentsNeedingAttention: [] }
   }
 
-  const userMap = await getUserNamesByIds(studentIds)
+  // 学生姓名 与 掌握度记录 相互独立，并行拉取
+  const [userMap, masteryRows] = await Promise.all([
+    getUserNamesByIds(studentIds),
+    db
+      .select({ mastery: knowledgePointMastery, kpName: knowledgePoints.name })
+      .from(knowledgePointMastery)
+      .leftJoin(knowledgePoints, eq(knowledgePoints.id, knowledgePointMastery.knowledgePointId))
+      .where(inArray(knowledgePointMastery.studentId, studentIds)),
+  ])
+
   const students = studentIds
     .map((id) => ({ id, name: userMap.get(id)?.name ?? null }))
     .sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""))
 
-  const masteryRows = await db
-    .select({ mastery: knowledgePointMastery, kpName: knowledgePoints.name })
-    .from(knowledgePointMastery)
-    .leftJoin(knowledgePoints, eq(knowledgePoints.id, knowledgePointMastery.knowledgePointId))
-    .where(inArray(knowledgePointMastery.studentId, studentIds))
-
   const byKp = new Map<string, { name: string; levels: number[]; mastered: number; notMastered: number }>()
   const byStudent = new Map<string, { levels: number[]; weakCount: number }>()
   for (const s of students) byStudent.set(s.id, { levels: [], weakCount: 0 })