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/ui/chip-nav.tsx

@@ -0,0 +1,78 @@
+import Link from "next/link"
+
+import { cn } from "@/shared/lib/utils"
+
+/**
+ * Chip 导航组：用于通过 URL search params 切换筛选维度的 chip/button 组。
+ *
+ * 覆盖以下重复模式：
+ * - stats-class-selector（班级 + 学科 chip 组）
+ * - attendance-stats-class-selector（班级 chip 组）
+ * - analytics-filters（班级 + 学科 + 年级 chip 组）
+ *
+ * 每个 chip 是一个 Link，点击后通过 buildHref 构造的 URL 跳转。
+ */
+interface ChipNavOption {
+  id: string
+  name: string
+}
+
+interface ChipNavProps {
+  /** 可选项列表 */
+  options: ChipNavOption[]
+  /** 当前选中项 id */
+  currentId: string
+  /** 根据选项 id 构造跳转 href */
+  buildHref: (id: string) => string
+  /** chip 尺寸："sm"（默认）或 "xs"（更紧凑） */
+  size?: "sm" | "xs"
+  /** 可选的 "全部" 选项，放在最前 */
+  allOption?: { id: string; label: string }
+  /** 额外类名 */
+  className?: string
+}
+
+export function ChipNav({
+  options,
+  currentId,
+  buildHref,
+  size = "sm",
+  allOption,
+  className,
+}: ChipNavProps) {
+  const sizeClass =
+    size === "xs" ? "px-2.5 py-1 text-xs" : "px-3 py-1.5 text-sm"
+
+  const chipClass = (active: boolean): string =>
+    cn(
+      "rounded-md border transition-colors",
+      "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+      sizeClass,
+      active
+        ? "border-primary bg-primary text-primary-foreground"
+        : "bg-card hover:bg-accent"
+    )
+
+  return (
+    <div className={cn("flex flex-wrap gap-2", className)}>
+      {allOption ? (
+        <Link
+          key={allOption.id}
+          href={buildHref(allOption.id)}
+          className={chipClass(currentId === allOption.id)}
+        >
+          {allOption.label}
+        </Link>
+      ) : null}
+      {options.map((option) => (
+        <Link
+          key={option.id}
+          href={buildHref(option.id)}
+          className={chipClass(currentId === option.id)}
+        >
+          {option.name}
+        </Link>
+      ))}
+    </div>
+  )
+}

src/shared/components/ui/filter-bar.tsx

@@ -0,0 +1,124 @@
+"use client"
+
+import type { ReactNode } from "react"
+import { Search, X } from "lucide-react"
+
+import { Button } from "@/shared/components/ui/button"
+import { Input } from "@/shared/components/ui/input"
+import { cn } from "@/shared/lib/utils"
+
+/**
+ * 筛选栏容器：统一的筛选控件布局壳。
+ *
+ * 覆盖以下重复模式（6+ 个文件共享相同布局）：
+ * - ExamFilters: 搜索 + Select + Reset
+ * - TextbookFilters: 搜索 + Select + Reset
+ * - QuestionFilters: 搜索 + Select + Select + Reset
+ * - AuditLogFilters: Select + Input + Select + date + date + Reset
+ * - LoginLogFilters: Select + Select + date + date + Reset
+ *
+ * 布局：移动端纵向排列，桌面端横向排列（可选 wrap/justify-between）。
+ * 注意：URL 状态管理方式（nuqs/router/callback）由各模块自行处理，
+ * 本组件只负责布局壳和 Reset 按钮的视觉统一。
+ */
+interface FilterBarProps {
+  /** 筛选控件（搜索框、Select、日期等） */
+  children: ReactNode
+  /** 是否有激活的筛选条件（控制 Reset 按钮显示） */
+  hasFilters?: boolean
+  /** 重置回调 */
+  onReset?: () => void
+  /** 布局变体：默认=横向, wrap=允许换行, between=两端对齐 */
+  layout?: "default" | "wrap" | "between"
+  /** 容器间距类名（默认 "gap-3"） */
+  gapClassName?: string
+  /** 容器额外类名 */
+  className?: string
+  /** Reset 按钮额外类名（如 h-8 px-2） */
+  resetClassName?: string
+}
+
+export function FilterBar({
+  children,
+  hasFilters = false,
+  onReset,
+  layout = "default",
+  gapClassName = "gap-3",
+  className,
+  resetClassName,
+}: FilterBarProps) {
+  const layoutClass =
+    layout === "wrap"
+      ? "md:flex-wrap"
+      : layout === "between"
+        ? "md:justify-between"
+        : ""
+
+  return (
+    <div
+      className={cn(
+        "flex flex-col",
+        gapClassName,
+        "md:flex-row md:items-center",
+        layoutClass,
+        className,
+      )}
+    >
+      {children}
+      {hasFilters && onReset ? (
+        <FilterResetButton onClick={onReset} className={resetClassName} />
+      ) : null}
+    </div>
+  )
+}
+
+/**
+ * 筛选栏搜索框：带 Search 图标的 Input。
+ *
+ * 覆盖 exam-filters/textbook-filters/question-filters 中重复的搜索框模式。
+ */
+interface FilterSearchInputProps {
+  value: string
+  onChange: (value: string) => void
+  placeholder?: string
+  className?: string
+  inputClassName?: string
+}
+
+export function FilterSearchInput({
+  value,
+  onChange,
+  placeholder = "Search...",
+  className,
+  inputClassName,
+}: FilterSearchInputProps) {
+  return (
+    <div className={cn("relative w-full md:w-80", className)}>
+      <Search className="absolute left-2.5 top-2.5 h-4 w-4 text-muted-foreground/50" />
+      <Input
+        placeholder={placeholder}
+        className={cn("pl-9 bg-background border-muted-foreground/20", inputClassName)}
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+      />
+    </div>
+  )
+}
+
+interface FilterResetButtonProps {
+  onClick: () => void
+  className?: string
+}
+
+export function FilterResetButton({ onClick, className }: FilterResetButtonProps) {
+  return (
+    <Button
+      variant="ghost"
+      onClick={onClick}
+      className={cn("h-10 px-3", className)}
+    >
+      Reset
+      <X className="ml-2 h-4 w-4" />
+    </Button>
+  )
+}

src/shared/components/ui/page-header.tsx

@@ -0,0 +1,44 @@
+import type { ComponentType, ReactNode } from "react"
+
+import { cn } from "@/shared/lib/utils"
+
+/**
+ * 页面头部：统一的标题 + 描述 + 操作区域布局。
+ *
+ * 覆盖以下重复模式：
+ * - AdminDashboardView 内联头部
+ * - Profile 页面内联头部
+ * - SettingsView 内联头部
+ * - Security 页面内联头部（带图标）
+ *
+ * 结构：左侧标题 + 描述，右侧操作区域（响应式：移动端纵向，桌面端横向）。
+ */
+interface PageHeaderProps {
+  /** 页面标题 */
+  title: string
+  /** 标题下方描述文本 */
+  description?: string
+  /** 标题左侧图标组件（lucide-react 图标等） */
+  icon?: ComponentType<{ className?: string }>
+  /** 右侧操作区域（按钮、徽章等） */
+  actions?: ReactNode
+  /** 额外类名 */
+  className?: string
+}
+
+export function PageHeader({ title, description, icon: Icon, actions, className }: PageHeaderProps) {
+  return (
+    <div className={cn("flex flex-col justify-between gap-4 md:flex-row md:items-center", className)}>
+      <div className="space-y-1">
+        <div className="flex items-center gap-2">
+          {Icon ? <Icon className="h-7 w-7 text-muted-foreground" /> : null}
+          <h1 className="text-3xl font-bold tracking-tight">{title}</h1>
+        </div>
+        {description ? (
+          <div className="text-sm text-muted-foreground">{description}</div>
+        ) : null}
+      </div>
+      {actions ? <div className="flex items-center gap-2">{actions}</div> : null}
+    </div>
+  )
+}

src/shared/components/ui/stat-card.tsx

@@ -0,0 +1,95 @@
+import * as React from "react"
+import Link from "next/link"
+
+import { cn } from "@/shared/lib/utils"
+import { Card, CardContent, CardHeader, CardTitle } from "@/shared/components/ui/card"
+import { Skeleton } from "@/shared/components/ui/skeleton"
+
+/**
+ * 统计卡片：用于仪表盘、洞察页等场景的单张统计卡片。
+ *
+ * 覆盖以下重复模式：
+ * - TeacherStats / StudentStatsGrid（带图标 + 描述 + 跳转）
+ * - AdminDashboardView KpiCard（带图标，无描述）
+ * - insights / diagnostic / student-summary 页面内联卡片（无图标，带描述）
+ */
+interface StatCardProps {
+  /** 卡片标题（统计项名称） */
+  title: string
+  /** 统计数值 */
+  value: string | number
+  /** 图标组件（Lucide 图标），传入组件类型而非实例 */
+  icon?: React.ComponentType<{ className?: string }>
+  /** 数值下方描述文本 */
+  description?: string
+  /** 图标颜色类名（如 "text-amber-500"） */
+  color?: string
+  /** 是否高亮（amber 边框 + 背景） */
+  highlight?: boolean
+  /** 点击跳转链接，传入则包裹 Link */
+  href?: string
+  /** 加载态，显示骨架屏 */
+  isLoading?: boolean
+  /** 数值自定义类名（如 "text-red-500"） */
+  valueClassName?: string
+}
+
+function StatCardSkeleton() {
+  return (
+    <Card>
+      <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
+        <Skeleton className="h-4 w-[100px]" />
+        <Skeleton className="h-4 w-4 rounded-full" />
+      </CardHeader>
+      <CardContent>
+        <Skeleton className="mb-2 h-8 w-[60px]" />
+        <Skeleton className="h-3 w-[140px]" />
+      </CardContent>
+    </Card>
+  )
+}
+
+export function StatCard({
+  title,
+  value,
+  icon: Icon,
+  description,
+  color,
+  highlight = false,
+  href,
+  isLoading = false,
+  valueClassName,
+}: StatCardProps) {
+  if (isLoading) {
+    return <StatCardSkeleton />
+  }
+
+  const card = (
+    <Card
+      className={cn(
+        highlight && "border-amber-200 bg-amber-50/50 dark:border-amber-900 dark:bg-amber-950/20"
+      )}
+    >
+      <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
+        <CardTitle className="text-sm font-medium">{title}</CardTitle>
+        {Icon ? <Icon className={cn("h-4 w-4 text-muted-foreground", color)} /> : null}
+      </CardHeader>
+      <CardContent>
+        <div className={cn("text-2xl font-bold", valueClassName)}>{value}</div>
+        {description ? (
+          <p className="text-xs text-muted-foreground">{description}</p>
+        ) : null}
+      </CardContent>
+    </Card>
+  )
+
+  if (href) {
+    return (
+      <Link href={href} className="block transition-transform hover:-translate-y-1">
+        {card}
+      </Link>
+    )
+  }
+
+  return card
+}

src/shared/components/ui/stat-item.tsx

@@ -0,0 +1,38 @@
+import * as React from "react"
+
+import { cn } from "@/shared/lib/utils"
+
+/**
+ * 统计项：用于统计面板内部网格中的紧凑统计单元。
+ *
+ * 覆盖以下重复模式：
+ * - AttendanceStatsCard 内部 StatItem
+ * - GradeStatsCard 内部 StatItem
+ *
+ * 结构：rounded-lg border bg-card 容器，含 label + icon + value + hint
+ */
+interface StatItemProps {
+  /** 统计项标签 */
+  label: string
+  /** 统计数值 */
+  value: string | number
+  /** 图标节点（如 <Users className="h-4 w-4" />） */
+  icon?: React.ReactNode
+  /** 底部提示文本 */
+  hint?: string
+  /** 数值自定义类名（如 "text-red-500"） */
+  valueClassName?: string
+}
+
+export function StatItem({ label, value, icon, hint, valueClassName }: StatItemProps) {
+  return (
+    <div className="flex flex-col gap-1 rounded-lg border bg-card p-4">
+      <div className="flex items-center justify-between">
+        <span className="text-xs font-medium text-muted-foreground">{label}</span>
+        {icon ? <span className="text-muted-foreground">{icon}</span> : null}
+      </div>
+      <span className={cn("text-2xl font-bold", valueClassName)}>{value}</span>
+      {hint ? <span className="text-xs text-muted-foreground">{hint}</span> : null}
+    </div>
+  )
+}