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/shared/components/charts/chart-card-shell.tsx

@@ -0,0 +1,90 @@
+"use client"
+
+import type { ComponentType, ReactNode } from "react"
+
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/shared/components/ui/card"
+import { EmptyState } from "@/shared/components/ui/empty-state"
+import { cn } from "@/shared/lib/utils"
+
+/**
+ * 图表卡片外壳：统一的 Card + CardHeader + EmptyState + CardContent 结构。
+ *
+ * 覆盖以下重复模式：
+ * - GradeTrendChart 的 Card + EmptyState 包装
+ * - TeacherGradeTrends 的 Card + EmptyState 包装
+ * - StudentGradesCard 的 Card + EmptyState 包装
+ * - ChildGradeSummary 的 Card + EmptyState 包装
+ * - GradeDistributionChart / ClassComparisonChart 等 BarChart 卡片
+ * - SubjectComparisonChart / MasteryRadarChart 等 RadarChart 卡片
+ *
+ * 结构：Card > CardHeader (icon + title + description) > CardContent (EmptyState | children)。
+ */
+interface ChartCardShellProps {
+  /** 卡片标题 */
+  title: string
+  /** 标题下方描述（可为字符串或 ReactNode，例如含动态数值） */
+  description?: ReactNode
+  /** 标题左侧图标（lucide-react 图标等） */
+  icon?: ComponentType<{ className?: string }>
+  /** 图标额外类名（如 text-primary、text-muted-foreground） */
+  iconClassName?: string
+  /** 标题额外类名（如 text-base font-medium） */
+  titleClassName?: string
+  /** 是否为空状态（为 true 时渲染 EmptyState，否则渲染 children） */
+  isEmpty?: boolean
+  /** 空状态标题 */
+  emptyTitle?: string
+  /** 空状态描述 */
+  emptyDescription?: string
+  /** 空状态图标（默认使用 icon） */
+  emptyIcon?: ComponentType<{ className?: string }>
+  /** 空状态额外类名（如 h-60、h-72） */
+  emptyClassName?: string
+  /** 卡片内容 */
+  children: ReactNode
+  /** Card 额外类名 */
+  className?: string
+  /** CardContent 额外类名 */
+  contentClassName?: string
+}
+
+export function ChartCardShell({
+  title,
+  description,
+  icon: Icon,
+  iconClassName,
+  titleClassName,
+  isEmpty = false,
+  emptyTitle,
+  emptyDescription,
+  emptyIcon,
+  emptyClassName,
+  children,
+  className,
+  contentClassName,
+}: ChartCardShellProps) {
+  const EmptyIcon = emptyIcon ?? Icon
+  return (
+    <Card className={className}>
+      <CardHeader>
+        <CardTitle className={cn("flex items-center gap-2", titleClassName)}>
+          {Icon ? <Icon className={cn("h-4 w-4", iconClassName)} /> : null}
+          {title}
+        </CardTitle>
+        {description ? <CardDescription>{description}</CardDescription> : null}
+      </CardHeader>
+      <CardContent className={contentClassName}>
+        {isEmpty ? (
+          <EmptyState
+            icon={EmptyIcon}
+            title={emptyTitle ?? "No data available"}
+            description={emptyDescription ?? "No data to display."}
+            className={cn("border-none", emptyClassName)}
+          />
+        ) : (
+          children
+        )}
+      </CardContent>
+    </Card>
+  )
+}

src/shared/components/charts/comparison-radar-chart.tsx

@@ -0,0 +1,143 @@
+"use client"
+
+import {
+  PolarAngleAxis,
+  PolarGrid,
+  PolarRadiusAxis,
+  Radar,
+  RadarChart,
+  Legend,
+} from "recharts"
+
+import {
+  ChartContainer,
+  ChartTooltip,
+  ChartTooltipContent,
+  type ChartConfig,
+} from "@/shared/components/ui/chart"
+import { cn } from "@/shared/lib/utils"
+
+/**
+ * 对比雷达图：统一的 RadarChart 配置（PolarGrid + PolarAngleAxis + PolarRadiusAxis + ChartTooltip + Radar）。
+ *
+ * 覆盖以下重复模式：
+ * - SubjectComparisonChart（双 Radar：averageScore + passRate）
+ * - MasteryRadarChart（双 Radar：student + classAverage，含条件 Legend）
+ *
+ * 默认配置：
+ * - PolarGrid: strokeOpacity=0.4
+ * - PolarAngleAxis: tick fontSize=12
+ * - PolarRadiusAxis: domain=[0,100], tickFormatter=百分比
+ * - Radar: stroke/fill 来自 config，fillOpacity 可配置
+ */
+export interface RadarSeries {
+  /** 数据字段名 */
+  dataKey: string
+  /** 图例名称 */
+  name: string
+  /** 颜色（CSS 变量或 hsl 值） */
+  color: string
+  /** 填充透明度（默认 0.3） */
+  fillOpacity?: number
+  /** 线宽（默认不设置） */
+  strokeWidth?: number
+  /** 虚线样式（如 "4 4"） */
+  strokeDasharray?: string
+  /** 是否条件渲染（为 false 时不渲染该系列） */
+  show?: boolean
+}
+
+interface ComparisonRadarChartProps {
+  /** 图表数据 */
+  data: Array<Record<string, string | number>>
+  /** 雷达系列配置 */
+  series: RadarSeries[]
+  /** 角度轴数据字段名 */
+  angleKey: string
+  /** 角度轴刻度格式化（默认不格式化） */
+  angleTickFormatter?: (value: string) => string
+  /** 角度轴字体大小（默认 12） */
+  angleTickFontSize?: number
+  /** 半径轴定义域（默认 [0, 100]） */
+  domain?: [number, number]
+  /** 半径轴刻度数量 */
+  tickCount?: number
+  /** 是否显示 Legend */
+  showLegend?: boolean
+  /** 图表高度类名（默认 "h-[300px]"） */
+  heightClassName?: string
+  /** Tooltip 宽度类名（默认 "w-[220px]"） */
+  tooltipClassName?: string
+  /** 容器额外类名 */
+  className?: string
+  /** PolarGrid 虚线样式（如 "4 4"） */
+  gridStrokeDasharray?: string
+  /** PolarGrid 透明度（默认 0.4） */
+  gridStrokeOpacity?: number
+}
+
+export function ComparisonRadarChart({
+  data,
+  series,
+  angleKey,
+  angleTickFormatter,
+  angleTickFontSize = 12,
+  domain = [0, 100],
+  tickCount,
+  showLegend = false,
+  heightClassName = "h-[300px]",
+  tooltipClassName = "w-[220px]",
+  className,
+  gridStrokeDasharray,
+  gridStrokeOpacity = 0.4,
+}: ComparisonRadarChartProps) {
+  const chartConfig: ChartConfig = {}
+  for (const s of series) {
+    chartConfig[s.dataKey] = {
+      label: s.name,
+      color: s.color,
+    }
+  }
+
+  const visibleSeries = series.filter((s) => s.show !== false)
+
+  return (
+    <ChartContainer
+      config={chartConfig}
+      className={cn(heightClassName, "w-full", className)}
+    >
+      <RadarChart data={data} outerRadius="75%">
+        <PolarGrid
+          strokeDasharray={gridStrokeDasharray}
+          strokeOpacity={gridStrokeOpacity}
+        />
+        <PolarAngleAxis
+          dataKey={angleKey}
+          tick={{ fontSize: angleTickFontSize }}
+          tickFormatter={angleTickFormatter}
+        />
+        <PolarRadiusAxis
+          domain={domain}
+          tickCount={tickCount}
+          tickFormatter={(value: number) => `${value}%`}
+          tick={{ fontSize: 10 }}
+          axisLine={false}
+        />
+        <ChartTooltip content={<ChartTooltipContent className={tooltipClassName} />} />
+        {showLegend ? <Legend /> : null}
+        {visibleSeries.map((s) => (
+          <Radar
+            key={s.dataKey}
+            name={s.name}
+            dataKey={s.dataKey}
+            stroke={`var(--color-${s.dataKey})`}
+            fill={`var(--color-${s.dataKey})`}
+            fillOpacity={s.fillOpacity ?? 0.3}
+            strokeWidth={s.strokeWidth}
+            strokeDasharray={s.strokeDasharray}
+          />
+        ))}
+      </RadarChart>
+    </ChartContainer>
+  )
+}

src/shared/components/charts/simple-bar-chart.tsx

@@ -0,0 +1,162 @@
+"use client"
+
+import type { ReactNode } from "react"
+import { Bar, BarChart, CartesianGrid, Legend, XAxis, YAxis, Cell } from "recharts"
+
+import {
+  ChartContainer,
+  ChartTooltip,
+  ChartTooltipContent,
+  type ChartConfig,
+} from "@/shared/components/ui/chart"
+import { cn } from "@/shared/lib/utils"
+
+/**
+ * 柱状图：统一的 BarChart 配置（CartesianGrid + XAxis + YAxis + ChartTooltip + Bar）。
+ *
+ * 覆盖以下重复模式：
+ * - GradeDistributionChart（单 Bar + Cell 分桶着色）
+ * - ClassComparisonChart（多 Bar + Legend）
+ *
+ * 默认配置：
+ * - CartesianGrid: vertical=false, strokeDasharray="4 4", strokeOpacity=0.4
+ * - XAxis: tickLine=false, axisLine=false, tickMargin=8, 默认截断到 8 字符
+ * - YAxis: tickLine=false, axisLine=false
+ * - Bar: radius=[4,4,0,0]
+ */
+export interface BarSeries {
+  /** 数据字段名 */
+  dataKey: string
+  /** 图例名称 */
+  name: string
+  /** 颜色（CSS 变量或 hsl 值） */
+  color: string
+  /** 圆角（默认 [4, 4, 0, 0]） */
+  radius?: [number, number, number, number]
+}
+
+interface SimpleBarChartProps {
+  /** 图表数据 */
+  data: Array<Record<string, string | number>>
+  /** 柱系列配置（单条或多条） */
+  bars: BarSeries[]
+  /** X 轴数据字段名 */
+  xKey: string
+  /** Y 轴定义域（如 [0, 100]；不传则不设置 domain） */
+  yDomain?: [number, number]
+  /** Y 轴是否允许小数（默认 true） */
+  yAllowDecimals?: boolean
+  /** Y 轴刻度格式化（如百分比） */
+  yTickFormatter?: (value: number) => string
+  /** X 轴刻度格式化（默认 "default"=截断到 8 字符；设为 null 则不格式化；传函数则自定义） */
+  xTickFormatter?: ((value: string) => string) | "default" | null
+  /** X 轴截断长度（默认 8） */
+  xTruncateLength?: number
+  /** Y 轴宽度（默认 36） */
+  yWidth?: number
+  /** 图表高度类名（默认 "h-[280px]"） */
+  heightClassName?: string
+  /** 图表 margin */
+  margin?: { left: number; right: number; top: number; bottom: number }
+  /** 是否显示 Legend（多 Bar 时建议 true） */
+  showLegend?: boolean
+  /** Tooltip 宽度类名（默认 "w-[200px]"） */
+  tooltipClassName?: string
+  /** 自定义 Tooltip formatter（用于自定义 tooltip 内容） */
+  tooltipFormatter?: (payload: unknown) => ReactNode
+  /** 按数据项着色的映射（key = xKey 值, value = 颜色）；用于单 Bar 分桶着色 */
+  cellColors?: Record<string, string>
+  /** 容器额外类名 */
+  className?: string
+}
+
+const DEFAULT_X_TRUNCATE_LENGTH = 8
+
+function makeXTickFormatter(truncateLength: number) {
+  return (value: string): string =>
+    value.length > truncateLength ? `${value.slice(0, truncateLength)}...` : value
+}
+
+export function SimpleBarChart({
+  data,
+  bars,
+  xKey,
+  yDomain,
+  yAllowDecimals = true,
+  yTickFormatter,
+  xTickFormatter = "default",
+  xTruncateLength = DEFAULT_X_TRUNCATE_LENGTH,
+  yWidth = 36,
+  heightClassName = "h-[280px]",
+  margin = { left: 8, right: 8, top: 8, bottom: 8 },
+  showLegend = false,
+  tooltipClassName = "w-[200px]",
+  tooltipFormatter,
+  cellColors,
+  className,
+}: SimpleBarChartProps) {
+  const chartConfig: ChartConfig = {}
+  for (const b of bars) {
+    chartConfig[b.dataKey] = {
+      label: b.name,
+      color: b.color,
+    }
+  }
+
+  const resolvedXTickFormatter =
+    xTickFormatter === null
+      ? undefined
+      : xTickFormatter === "default"
+        ? makeXTickFormatter(xTruncateLength)
+        : xTickFormatter
+
+  const hasCellColors = !!cellColors && bars.length === 1
+
+  return (
+    <ChartContainer config={chartConfig} className={cn(heightClassName, "w-full", className)}>
+      <BarChart data={data} margin={margin}>
+        <CartesianGrid vertical={false} strokeDasharray="4 4" strokeOpacity={0.4} />
+        <XAxis
+          dataKey={xKey}
+          tickLine={false}
+          axisLine={false}
+          tickMargin={8}
+          tickFormatter={resolvedXTickFormatter}
+        />
+        <YAxis
+          domain={yDomain}
+          allowDecimals={yAllowDecimals}
+          tickLine={false}
+          axisLine={false}
+          tickFormatter={yTickFormatter}
+          width={yWidth}
+        />
+        <ChartTooltip
+          content={
+            tooltipFormatter ? (
+              <ChartTooltipContent className={tooltipClassName} formatter={tooltipFormatter} />
+            ) : (
+              <ChartTooltipContent className={tooltipClassName} />
+            )
+          }
+        />
+        {showLegend ? <Legend /> : null}
+        {bars.map((b) => (
+          <Bar
+            key={b.dataKey}
+            dataKey={b.dataKey}
+            fill={`var(--color-${b.dataKey})`}
+            radius={b.radius ?? [4, 4, 0, 0]}
+          >
+            {hasCellColors && cellColors
+              ? data.map((entry) => {
+                  const cellKey = String(entry[xKey])
+                  return <Cell key={cellKey} fill={cellColors[cellKey]} />
+                })
+              : null}
+          </Bar>
+        ))}
+      </BarChart>
+    </ChartContainer>
+  )
+}

src/shared/components/charts/trend-line-chart.tsx

@@ -0,0 +1,153 @@
+"use client"
+
+import { CartesianGrid, Line, LineChart, XAxis, YAxis } from "recharts"
+
+import {
+  ChartContainer,
+  ChartTooltip,
+  ChartTooltipContent,
+  type ChartConfig,
+} from "@/shared/components/ui/chart"
+import { cn } from "@/shared/lib/utils"
+
+/**
+ * 趋势折线图：统一的 LineChart 配置（CartesianGrid + XAxis + YAxis + ChartTooltip + Line）。
+ *
+ * 覆盖以下重复模式（4 个文件几乎逐行相同）：
+ * - GradeTrendChart（dataKey=normalizedScore, height=h-[280px]）
+ * - TeacherGradeTrends（dataKey=score, height=h-[200px]）
+ * - StudentGradesCard（dataKey=score, height=h-[200px]）
+ * - ChildGradeSummary（dataKey=score, xKey=date, height=h-[160px]）
+ *
+ * 默认配置：
+ * - CartesianGrid: vertical=false, strokeDasharray="4 4", strokeOpacity=0.4
+ * - XAxis: tickLine=false, axisLine=false, tickMargin=8, 默认截断到 10 字符
+ * - YAxis: domain=[0,100], tickLine=false, axisLine=false, 默认百分比格式化, width=36
+ * - ChartTooltip: cursor 虚线, content=ChartTooltipContent indicator="line" labelKey="fullTitle"
+ * - Line: type="monotone", strokeWidth=2
+ */
+export interface TrendLineSeries {
+  /** 数据字段名（对应 data 中的 key） */
+  dataKey: string
+  /** 图例名称 */
+  name: string
+  /** 颜色（CSS 变量或 hsl 值，如 "hsl(var(--primary))"） */
+  color: string
+  /** 数据点半径（默认 3） */
+  dotRadius?: number
+  /** 激活数据点半径（默认 5） */
+  activeDotRadius?: number
+}
+
+interface TrendLineChartProps {
+  /** 图表数据 */
+  data: Array<Record<string, string | number>>
+  /** 折线系列配置（支持单条或多条） */
+  series: TrendLineSeries[]
+  /** X 轴数据字段名（默认 "title"） */
+  xKey?: string
+  /** Y 轴定义域（默认 [0, 100]） */
+  yDomain?: [number, number]
+  /** Y 轴刻度格式化（默认百分比 `${value}%`） */
+  yTickFormatter?: (value: number) => string
+  /** X 轴刻度格式化（默认截断到 10 字符；设为 null 则不格式化） */
+  xTickFormatter?: ((value: string) => string) | null
+  /** 图表高度类名（默认 "h-[280px]"） */
+  heightClassName?: string
+  /** 图表 margin（默认 { left: 8, right: 8, top: 8, bottom: 8 }） */
+  margin?: { left: number; right: number; top: number; bottom: number }
+  /** Y 轴宽度（默认 36） */
+  yWidth?: number
+  /** Tooltip 内容宽度类名（默认 "w-[220px]"） */
+  tooltipClassName?: string
+  /** Tooltip labelKey（默认 "fullTitle"） */
+  tooltipLabelKey?: string
+  /** 容器额外类名 */
+  className?: string
+}
+
+const DEFAULT_X_TICK_TRUNCATE_LENGTH = 10
+
+function defaultXTickFormatter(value: string): string {
+  return value.length > DEFAULT_X_TICK_TRUNCATE_LENGTH
+    ? `${value.slice(0, DEFAULT_X_TICK_TRUNCATE_LENGTH)}...`
+    : value
+}
+
+function defaultYTickFormatter(value: number): string {
+  return `${value}%`
+}
+
+export function TrendLineChart({
+  data,
+  series,
+  xKey = "title",
+  yDomain = [0, 100],
+  yTickFormatter = defaultYTickFormatter,
+  xTickFormatter = defaultXTickFormatter,
+  heightClassName = "h-[280px]",
+  margin = { left: 8, right: 8, top: 8, bottom: 8 },
+  yWidth = 36,
+  tooltipClassName = "w-[220px]",
+  tooltipLabelKey = "fullTitle",
+  className,
+}: TrendLineChartProps) {
+  const chartConfig: ChartConfig = {}
+  for (const s of series) {
+    chartConfig[s.dataKey] = {
+      label: s.name,
+      color: s.color,
+    }
+  }
+
+  return (
+    <ChartContainer config={chartConfig} className={cn(heightClassName, "w-full", className)}>
+      <LineChart data={data} margin={margin}>
+        <CartesianGrid vertical={false} strokeDasharray="4 4" strokeOpacity={0.4} />
+        <XAxis
+          dataKey={xKey}
+          tickLine={false}
+          axisLine={false}
+          tickMargin={8}
+          tickFormatter={xTickFormatter ?? undefined}
+        />
+        <YAxis
+          domain={yDomain}
+          tickLine={false}
+          axisLine={false}
+          tickFormatter={yTickFormatter}
+          width={yWidth}
+        />
+        <ChartTooltip
+          cursor={{
+            stroke: "hsl(var(--muted-foreground))",
+            strokeWidth: 1,
+            strokeDasharray: "4 4",
+          }}
+          content={
+            <ChartTooltipContent
+              indicator="line"
+              labelKey={tooltipLabelKey}
+              className={tooltipClassName}
+            />
+          }
+        />
+        {series.map((s) => (
+          <Line
+            key={s.dataKey}
+            dataKey={s.dataKey}
+            type="monotone"
+            stroke={`var(--color-${s.dataKey})`}
+            strokeWidth={2}
+            dot={{
+              fill: `var(--color-${s.dataKey})`,
+              r: s.dotRadius ?? 3,
+              strokeWidth: 2,
+            }}
+            activeDot={{ r: s.activeDotRadius ?? 5, strokeWidth: 0 }}
+          />
+        ))}
+      </LineChart>
+    </ChartContainer>
+  )
+}