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

@@ -17,23 +17,23 @@ import {
   createMessage,
   markMessageAsRead,
   deleteMessage,
-  getNotifications,
-  markNotificationAsRead,
-  markAllNotificationsAsRead,
   getRecipients,
 } from "./data-access"
+import {
+  getNotifications,
+  markNotificationAsRead,
+  markAllNotificationsAsRead,
+} from "@/modules/notifications/data-access"
 import {
   getNotificationPreferences,
   upsertNotificationPreferences,
-} from "./notification-preferences"
+} from "@/modules/notifications/preferences"
+import type { Message, MessageType, RecipientOption } from "./types"
 import type {
-  Message,
   Notification,
-  MessageType,
   NotificationPreferences,
-  RecipientOption,
   UpdateNotificationPreferencesInput,
-} from "./types"
+} from "@/modules/notifications/types"
 
 export async function sendMessageAction(
   prevState: ActionState<string> | null,

src/modules/messaging/components/message-compose.tsx

@@ -1,6 +1,7 @@
 "use client"
 
 import { useState } from "react"
+import Link from "next/link"
 import { useRouter } from "next/navigation"
 import { toast } from "sonner"
 import { ArrowLeft, Send } from "lucide-react"
@@ -70,9 +71,9 @@ export function MessageCompose({
       <CardHeader>
         <div className="flex items-center gap-2">
           <Button asChild variant="ghost" size="icon">
-            <a href={backHref}>
+            <Link href={backHref}>
               <ArrowLeft className="h-4 w-4" />
-            </a>
+            </Link>
           </Button>
           <CardTitle>{parentMessageId ? "Reply" : "New Message"}</CardTitle>
         </div>

src/modules/messaging/components/message-detail.tsx

@@ -76,9 +76,9 @@ export function MessageDetail({
       <div className="flex items-center justify-between gap-2">
         <div className="flex items-center gap-2">
           <Button asChild variant="ghost" size="icon">
-            <a href={backHref}>
+            <Link href={backHref}>
               <ArrowLeft className="h-4 w-4" />
-            </a>
+            </Link>
           </Button>
           <h2 className="text-2xl font-bold tracking-tight">Message</h2>
         </div>

src/modules/messaging/components/message-list.tsx

@@ -9,7 +9,7 @@ import { Button } from "@/shared/components/ui/button"
 import { Card, CardContent, CardHeader } from "@/shared/components/ui/card"
 import { EmptyState } from "@/shared/components/ui/empty-state"
 import { Tabs, TabsList, TabsTrigger } from "@/shared/components/ui/tabs"
-import { formatDate } from "@/shared/lib/utils"
+import { cn, formatDate } from "@/shared/lib/utils"
 import { usePermission } from "@/shared/hooks/use-permission"
 import { Permissions } from "@/shared/types/permissions"
 
@@ -79,7 +79,7 @@ export function MessageList({
             const unread = isReceived && !m.isRead
             return (
               <Link key={m.id} href={`/messages/${m.id}`} className="block">
-                <Card className={`transition-colors hover:bg-accent/50 ${unread ? "border-primary/40" : ""}`}>
+                <Card className={cn("transition-colors hover:bg-accent/50", unread && "border-primary/40")}>
                   <CardHeader className="flex flex-row items-start justify-between gap-2 space-y-0 pb-3">
                     <div className="space-y-1">
                       <div className="flex items-center gap-2">
@@ -88,7 +88,7 @@ export function MessageList({
                         ) : (
                           <MailOpen className="text-muted-foreground h-4 w-4" />
                         )}
-                        <span className={`text-sm font-medium ${unread ? "text-primary" : ""}`}>
+                        <span className={cn("text-sm font-medium", unread && "text-primary")}>
                           {m.subject ?? "(no subject)"}
                         </span>
                         {unread ? <Badge variant="default" className="text-xs">New</Badge> : null}

src/modules/messaging/components/notification-dropdown.tsx

@@ -16,14 +16,14 @@ import {
   DropdownMenuTrigger,
 } from "@/shared/components/ui/dropdown-menu"
 import { ScrollArea } from "@/shared/components/ui/scroll-area"
-import { formatDate } from "@/shared/lib/utils"
+import { cn, formatDate } from "@/shared/lib/utils"
 
 import {
   getNotificationsAction,
   markAllNotificationsAsReadAction,
   markNotificationAsReadAction,
 } from "../actions"
-import type { Notification, NotificationType } from "../types"
+import type { Notification, NotificationType } from "@/modules/notifications/types"
 
 const TYPE_ICON: Record<NotificationType, typeof Bell> = {
   message: MessageSquare,
@@ -131,7 +131,7 @@ export function NotificationDropdown() {
                       {!n.isRead ? (
                         <span className="bg-primary size-1.5 shrink-0 rounded-full" />
                       ) : null}
-                      <span className={`text-xs ${!n.isRead ? "font-semibold" : "font-medium"}`}>
+                      <span className={cn("text-xs", !n.isRead ? "font-semibold" : "font-medium")}>
                         {n.title}
                       </span>
                     </div>

src/modules/messaging/components/notification-list.tsx

@@ -10,10 +10,10 @@ import { Badge } from "@/shared/components/ui/badge"
 import { Button } from "@/shared/components/ui/button"
 import { Card, CardContent } from "@/shared/components/ui/card"
 import { EmptyState } from "@/shared/components/ui/empty-state"
-import { formatDate } from "@/shared/lib/utils"
+import { cn, formatDate } from "@/shared/lib/utils"
 
 import { markAllNotificationsAsReadAction, markNotificationAsReadAction } from "../actions"
-import type { Notification, NotificationType } from "../types"
+import type { Notification, NotificationType } from "@/modules/notifications/types"
 
 const TYPE_ICON: Record<NotificationType, typeof Bell> = {
   message: MessageSquare,
@@ -91,7 +91,7 @@ export function NotificationList({ notifications }: { notifications: Notificatio
             return (
               <Card
                 key={n.id}
-                className={`transition-colors ${!n.isRead ? "border-primary/40 bg-primary/5" : ""}`}
+                className={cn("transition-colors", !n.isRead && "border-primary/40 bg-primary/5")}
               >
                 <CardContent className="flex items-start gap-3 py-4">
                   <div className="bg-muted flex size-9 shrink-0 items-center justify-center rounded-full">
@@ -99,7 +99,7 @@ export function NotificationList({ notifications }: { notifications: Notificatio
                   </div>
                   <div className="min-w-0 flex-1 space-y-1">
                     <div className="flex items-center gap-2">
-                      <span className={`text-sm ${!n.isRead ? "font-semibold" : "font-medium"}`}>
+                      <span className={cn("text-sm", !n.isRead ? "font-semibold" : "font-medium")}>
                         {n.title}
                       </span>
                       {!n.isRead ? <Badge variant="default" className="text-xs">New</Badge> : null}

src/modules/messaging/data-access.ts

@@ -9,31 +9,35 @@ import "server-only"
  * - getUnreadMessageCount: 未读私信计数
  * - getRecipients: 获取收件人列表（按 DataScope 过滤）
  *
- * 注意: 通知相关函数（createNotification / getNotifications /
+ * 通知相关函数（createNotification / getNotifications /
  * markNotificationAsRead / markAllNotificationsAsRead / getUnreadNotificationCount）
- * 已迁移到 notifications/data-access.ts（P0-4 / P1-5 修复）。
- * 本文件通过 re-export 保持向后兼容，现有调用方无需修改 import 路径。
+ * 已迁移到 notifications/data-access.ts，请直接从该模块导入。
  */
 
 import { cache } from "react"
 import { createId } from "@paralleldrive/cuid2"
-import { and, count, desc, eq, inArray, or } from "drizzle-orm"
+import { and, count, desc, eq, inArray, or, type SQL } from "drizzle-orm"
 
 import { db } from "@/shared/db"
 import {
   messages,
   users,
-  classEnrollments,
-  classes,
 } from "@/shared/db/schema"
+import {
+  getClassesByGradeId,
+  getStudentIdsByClassIds,
+  getTeacherIdsByClassIds,
+  getStudentActiveClassId,
+} from "@/modules/classes/data-access"
+import { getUserNamesByIds } from "@/modules/users/data-access"
 import type { DataScope } from "@/shared/types/permissions"
 import type {
   Message,
   GetMessagesParams,
   CreateMessageInput,
-  PaginatedResult,
   RecipientOption,
 } from "./types"
+import type { PaginatedResult } from "@/modules/notifications/types"
 
 const toIso = (d: Date | null | undefined): string | null => (d ? d.toISOString() : null)
 
@@ -81,7 +85,7 @@ export const getMessages = cache(
     const pageSize = Math.max(1, params.pageSize ?? 20)
     const offset = (page - 1) * pageSize
 
-    const conds = []
+    const conds: SQL[] = []
     if (params.type === "inbox") conds.push(eq(messages.receiverId, params.userId))
     else if (params.type === "sent") conds.push(eq(messages.senderId, params.userId))
     else {
@@ -171,34 +175,42 @@ export const getRecipients = cache(
       return all.filter((r) => r.id !== userId).map((r) => ({ ...r, name: r.name ?? r.email }))
     }
     if (scope.type === "class_taught" && scope.classIds.length > 0) {
-      const rows = await db
-        .selectDistinct({ id: users.id, name: users.name, email: users.email })
-        .from(users)
-        .innerJoin(classEnrollments, eq(classEnrollments.studentId, users.id))
-        .where(inArray(classEnrollments.classId, scope.classIds))
-      return rows.map((r) => ({ ...r, name: r.name ?? r.email, role: "student" }))
+      // 通过 classes data-access 获取学生 ID，避免直接 JOIN classEnrollments 表
+      const studentIds = await getStudentIdsByClassIds(scope.classIds)
+      const userMap = await getUserNamesByIds(studentIds)
+      return Array.from(userMap.values())
+        .filter((u) => u.id !== userId)
+        .map((u) => ({ id: u.id, name: u.name ?? u.email, email: u.email, role: "student" }))
     }
     if (scope.type === "grade_managed" && scope.gradeIds.length > 0) {
-      const rows = await db
-        .selectDistinct({ id: users.id, name: users.name, email: users.email })
-        .from(users)
-        .innerJoin(classEnrollments, eq(classEnrollments.studentId, users.id))
-        .innerJoin(classes, eq(classes.id, classEnrollments.classId))
-        .where(inArray(classes.gradeId, scope.gradeIds))
-      return rows.map((r) => ({ ...r, name: r.name ?? r.email, role: "student" }))
+      // 通过 classes data-access 获取年级下所有班级，再获取学生 ID，
+      // 避免直接 JOIN classes / classEnrollments 表
+      const classLists = await Promise.all(scope.gradeIds.map((g) => getClassesByGradeId(g)))
+      const classIds = classLists.flat().map((c) => c.id)
+      const studentIds = await getStudentIdsByClassIds(classIds)
+      const userMap = await getUserNamesByIds(studentIds)
+      return Array.from(userMap.values())
+        .filter((u) => u.id !== userId)
+        .map((u) => ({ id: u.id, name: u.name ?? u.email, email: u.email, role: "student" }))
+    }
+    if (scope.type === "class_members" && scope.classIds.length > 0) {
+      // 学生可以给自己班级的任课教师/班主任发消息
+      const teacherIds = await getTeacherIdsByClassIds(scope.classIds)
+      const userMap = await getUserNamesByIds(teacherIds)
+      return Array.from(userMap.values())
+        .filter((u) => u.id !== userId)
+        .map((u) => ({ id: u.id, name: u.name ?? u.email, email: u.email, role: "teacher" }))
+    }
+    if (scope.type === "children" && scope.childrenIds.length > 0) {
+      // 家长可以给孩子的班主任/任课教师发消息
+      const classIds = await Promise.all(scope.childrenIds.map((id) => getStudentActiveClassId(id)))
+      const validClassIds = classIds.filter((id): id is string => id !== null)
+      const teacherIds = await getTeacherIdsByClassIds(validClassIds)
+      const userMap = await getUserNamesByIds(teacherIds)
+      return Array.from(userMap.values())
+        .filter((u) => u.id !== userId)
+        .map((u) => ({ id: u.id, name: u.name ?? u.email, email: u.email, role: "teacher" }))
     }
     return []
   }
 )
-
-// ---------------------------------------------------------------------------
-// 向后兼容 re-export：通知 CRUD 已迁移到 notifications/data-access.ts
-// ---------------------------------------------------------------------------
-
-export {
-  createNotification,
-  getNotifications,
-  markNotificationAsRead,
-  markAllNotificationsAsRead,
-  getUnreadNotificationCount,
-} from "@/modules/notifications/data-access"

src/modules/messaging/notification-preferences.ts

@@ -1,11 +0,0 @@
-/**
- * 通知偏好数据访问（向后兼容重导出）
- *
- * 注意: 通知偏好函数已迁移到 notifications/preferences.ts（P0-4 / P1-5 修复）。
- * 本文件通过 re-export 保持向后兼容，现有调用方无需修改 import 路径。
- */
-
-export {
-  getNotificationPreferences,
-  upsertNotificationPreferences,
-} from "@/modules/notifications/preferences"

src/modules/messaging/types.ts

@@ -1,10 +1,9 @@
 /**
  * 私信模块类型定义
  *
- * 注意: 通知相关类型（NotificationType, Notification, NotificationPreferences,
+ * 通知相关类型（NotificationType, Notification, NotificationPreferences,
  * UpdateNotificationPreferencesInput, CreateNotificationInput, GetNotificationsParams,
- * PaginatedResult）已迁移到 notifications/types.ts（P0-4 / P1-5 修复）。
- * 本文件通过 re-export 保持向后兼容，现有调用方无需修改 import 路径。
+ * PaginatedResult）已迁移到 notifications/types.ts，请直接从该模块导入。
  */
 
 export type MessageType = "inbox" | "sent" | "all"
@@ -50,18 +49,3 @@ export interface RecipientOption {
   email: string
   role?: string
 }
-
-// ---------------------------------------------------------------------------
-// 向后兼容 re-export：通知相关类型已迁移到 notifications/types.ts
-// ---------------------------------------------------------------------------
-
-export type {
-  NotificationType,
-  Notification,
-  NotificationListItem,
-  GetNotificationsParams,
-  CreateNotificationInput,
-  PaginatedResult,
-  NotificationPreferences,
-  UpdateNotificationPreferencesInput,
-} from "@/modules/notifications/types"