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

@@ -19,6 +19,14 @@ import {
 } from "./data-access"
 import type { GetAnnouncementsParams, Announcement } from "./types"
 
+function handleActionError(e: unknown): ActionState<never> {
+  if (e instanceof PermissionDeniedError) {
+    return { success: false, message: e.message }
+  }
+  if (e instanceof Error) return { success: false, message: e.message }
+  return { success: false, message: "Unexpected error" }
+}
+
 export async function createAnnouncementAction(
   prevState: ActionState<string> | null,
   formData: FormData
@@ -71,11 +79,7 @@ export async function createAnnouncementAction(
 
     return { success: true, message: "Announcement created", data: id }
   } catch (e) {
-    if (e instanceof PermissionDeniedError) {
-      return { success: false, message: e.message }
-    }
-    if (e instanceof Error) return { success: false, message: e.message }
-    return { success: false, message: "Unexpected error" }
+    return handleActionError(e)
   }
 }
 
@@ -135,11 +139,7 @@ export async function updateAnnouncementAction(
 
     return { success: true, message: "Announcement updated", data: id }
   } catch (e) {
-    if (e instanceof PermissionDeniedError) {
-      return { success: false, message: e.message }
-    }
-    if (e instanceof Error) return { success: false, message: e.message }
-    return { success: false, message: "Unexpected error" }
+    return handleActionError(e)
   }
 }
 
@@ -157,11 +157,7 @@ export async function deleteAnnouncementAction(id: string): Promise<ActionState<
 
     return { success: true, message: "Announcement deleted" }
   } catch (e) {
-    if (e instanceof PermissionDeniedError) {
-      return { success: false, message: e.message }
-    }
-    if (e instanceof Error) return { success: false, message: e.message }
-    return { success: false, message: "Unexpected error" }
+    return handleActionError(e)
   }
 }
 
@@ -183,11 +179,7 @@ export async function publishAnnouncementAction(id: string): Promise<ActionState
 
     return { success: true, message: "Announcement published" }
   } catch (e) {
-    if (e instanceof PermissionDeniedError) {
-      return { success: false, message: e.message }
-    }
-    if (e instanceof Error) return { success: false, message: e.message }
-    return { success: false, message: "Unexpected error" }
+    return handleActionError(e)
   }
 }
 
@@ -206,11 +198,7 @@ export async function archiveAnnouncementAction(id: string): Promise<ActionState
 
     return { success: true, message: "Announcement archived" }
   } catch (e) {
-    if (e instanceof PermissionDeniedError) {
-      return { success: false, message: e.message }
-    }
-    if (e instanceof Error) return { success: false, message: e.message }
-    return { success: false, message: "Unexpected error" }
+    return handleActionError(e)
   }
 }
 
@@ -222,10 +210,6 @@ export async function getAnnouncementsAction(
     const data = await getAnnouncements(params)
     return { success: true, data }
   } catch (e) {
-    if (e instanceof PermissionDeniedError) {
-      return { success: false, message: e.message }
-    }
-    if (e instanceof Error) return { success: false, message: e.message }
-    return { success: false, message: "Unexpected error" }
+    return handleActionError(e)
   }
 }

src/modules/announcements/components/announcement-card.tsx

@@ -1,7 +1,6 @@
 "use client"
 
 import Link from "next/link"
-import { useMemo } from "react"
 import { Badge } from "@/shared/components/ui/badge"
 import { Card, CardContent, CardHeader, CardTitle } from "@/shared/components/ui/card"
 import { formatDate } from "@/shared/lib/utils"
@@ -35,36 +34,33 @@ export function AnnouncementCard({
   announcement: Announcement
   href?: string
 }) {
-  const card = useMemo(
-    () => (
-      <Card className="h-full transition-colors hover:bg-accent/50">
-        <CardHeader className="flex flex-row items-start justify-between gap-2 space-y-0">
-          <CardTitle className="line-clamp-2 text-base">{announcement.title}</CardTitle>
-          <Badge variant={STATUS_VARIANT[announcement.status]} className="shrink-0">
-            {STATUS_LABEL[announcement.status]}
+  const card = (
+    <Card className="h-full transition-colors hover:bg-accent/50">
+      <CardHeader className="flex flex-row items-start justify-between gap-2 space-y-0">
+        <CardTitle className="line-clamp-2 text-base">{announcement.title}</CardTitle>
+        <Badge variant={STATUS_VARIANT[announcement.status]} className="shrink-0">
+          {STATUS_LABEL[announcement.status]}
+        </Badge>
+      </CardHeader>
+      <CardContent className="space-y-2">
+        <p className="line-clamp-3 text-sm text-muted-foreground whitespace-pre-wrap">
+          {announcement.content}
+        </p>
+        <div className="flex flex-wrap items-center gap-2 text-xs text-muted-foreground">
+          <Badge variant="outline" className="capitalize">
+            {TYPE_LABEL[announcement.type]}
           </Badge>
-        </CardHeader>
-        <CardContent className="space-y-2">
-          <p className="line-clamp-3 text-sm text-muted-foreground whitespace-pre-wrap">
-            {announcement.content}
-          </p>
-          <div className="flex flex-wrap items-center gap-2 text-xs text-muted-foreground">
-            <Badge variant="outline" className="capitalize">
-              {TYPE_LABEL[announcement.type]}
-            </Badge>
-            <span>
-              {announcement.publishedAt
-                ? `Published ${formatDate(announcement.publishedAt)}`
-                : `Updated ${formatDate(announcement.updatedAt)}`}
-            </span>
-            {announcement.authorName ? (
-              <span className="ml-auto">by {announcement.authorName}</span>
-            ) : null}
-          </div>
-        </CardContent>
-      </Card>
-    ),
-    [announcement]
+          <span>
+            {announcement.publishedAt
+              ? `Published ${formatDate(announcement.publishedAt)}`
+              : `Updated ${formatDate(announcement.updatedAt)}`}
+          </span>
+          {announcement.authorName ? (
+            <span className="ml-auto">by {announcement.authorName}</span>
+          ) : null}
+        </div>
+      </CardContent>
+    </Card>
   )
 
   if (href) {

src/modules/announcements/components/announcement-detail.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 {
@@ -120,9 +121,9 @@ export function AnnouncementDetail({
         <div className="flex items-center gap-2">
           {backHref ? (
             <Button asChild variant="ghost" size="icon">
-              <a href={backHref}>
+              <Link href={backHref}>
                 <ArrowLeft className="h-4 w-4" />
-              </a>
+              </Link>
             </Button>
           ) : null}
           <h2 className="text-2xl font-bold tracking-tight">Announcement</h2>
@@ -143,10 +144,10 @@ export function AnnouncementDetail({
             ) : null}
             {editHref ? (
               <Button asChild>
-                <a href={editHref}>
+                <Link href={editHref}>
                   <Pencil className="mr-2 h-4 w-4" />
                   Edit
-                </a>
+                </Link>
               </Button>
             ) : null}
             <Button

src/modules/announcements/components/announcement-list.tsx

@@ -1,6 +1,7 @@
 "use client"
 
 import { useMemo, useState } from "react"
+import Link from "next/link"
 import { useRouter } from "next/navigation"
 import { Plus } from "lucide-react"
 
@@ -73,10 +74,10 @@ export function AnnouncementList({
         </Select>
         {canManage && createHref ? (
           <Button asChild>
-            <a href={createHref}>
+            <Link href={createHref}>
               <Plus className="mr-2 h-4 w-4" />
               New Announcement
-            </a>
+            </Link>
           </Button>
         ) : null}
       </div>

src/modules/announcements/data-access.ts

@@ -49,77 +49,67 @@ const mapRow = (
 
 export const getAnnouncements = cache(
   async (params?: GetAnnouncementsParams): Promise<Announcement[]> => {
-    try {
-      const page = Math.max(1, params?.page ?? 1)
-      const pageSize = Math.max(1, params?.pageSize ?? 20)
-      const offset = (page - 1) * pageSize
+    const page = Math.max(1, params?.page ?? 1)
+    const pageSize = Math.max(1, params?.pageSize ?? 20)
+    const offset = (page - 1) * pageSize
 
-      const conditions = []
-      if (params?.status) {
-        conditions.push(eq(announcements.status, params.status))
-      }
-      if (params?.type) {
-        conditions.push(eq(announcements.type, params.type))
-      }
-
-      const rows = await db
-        .select({
-          id: announcements.id,
-          title: announcements.title,
-          content: announcements.content,
-          type: announcements.type,
-          status: announcements.status,
-          targetGradeId: announcements.targetGradeId,
-          targetClassId: announcements.targetClassId,
-          authorId: announcements.authorId,
-          authorName: users.name,
-          publishedAt: announcements.publishedAt,
-          createdAt: announcements.createdAt,
-          updatedAt: announcements.updatedAt,
-        })
-        .from(announcements)
-        .leftJoin(users, eq(users.id, announcements.authorId))
-        .where(conditions.length > 0 ? and(...conditions) : undefined)
-        .orderBy(desc(announcements.createdAt))
-        .limit(pageSize)
-        .offset(offset)
-
-      return rows.map(mapRow)
-    } catch (error) {
-      console.error("getAnnouncements failed:", error)
-      return []
+    const conditions = []
+    if (params?.status) {
+      conditions.push(eq(announcements.status, params.status))
     }
+    if (params?.type) {
+      conditions.push(eq(announcements.type, params.type))
+    }
+
+    const rows = await db
+      .select({
+        id: announcements.id,
+        title: announcements.title,
+        content: announcements.content,
+        type: announcements.type,
+        status: announcements.status,
+        targetGradeId: announcements.targetGradeId,
+        targetClassId: announcements.targetClassId,
+        authorId: announcements.authorId,
+        authorName: users.name,
+        publishedAt: announcements.publishedAt,
+        createdAt: announcements.createdAt,
+        updatedAt: announcements.updatedAt,
+      })
+      .from(announcements)
+      .leftJoin(users, eq(users.id, announcements.authorId))
+      .where(conditions.length > 0 ? and(...conditions) : undefined)
+      .orderBy(desc(announcements.createdAt))
+      .limit(pageSize)
+      .offset(offset)
+
+    return rows.map(mapRow)
   }
 )
 
 export const getAnnouncementById = cache(
   async (id: string): Promise<Announcement | null> => {
-    try {
-      const [row] = await db
-        .select({
-          id: announcements.id,
-          title: announcements.title,
-          content: announcements.content,
-          type: announcements.type,
-          status: announcements.status,
-          targetGradeId: announcements.targetGradeId,
-          targetClassId: announcements.targetClassId,
-          authorId: announcements.authorId,
-          authorName: users.name,
-          publishedAt: announcements.publishedAt,
-          createdAt: announcements.createdAt,
-          updatedAt: announcements.updatedAt,
-        })
-        .from(announcements)
-        .leftJoin(users, eq(users.id, announcements.authorId))
-        .where(eq(announcements.id, id))
-        .limit(1)
+    const [row] = await db
+      .select({
+        id: announcements.id,
+        title: announcements.title,
+        content: announcements.content,
+        type: announcements.type,
+        status: announcements.status,
+        targetGradeId: announcements.targetGradeId,
+        targetClassId: announcements.targetClassId,
+        authorId: announcements.authorId,
+        authorName: users.name,
+        publishedAt: announcements.publishedAt,
+        createdAt: announcements.createdAt,
+        updatedAt: announcements.updatedAt,
+      })
+      .from(announcements)
+      .leftJoin(users, eq(users.id, announcements.authorId))
+      .where(eq(announcements.id, id))
+      .limit(1)
 
-      return row ? mapRow(row) : null
-    } catch (error) {
-      console.error("getAnnouncementById failed:", error)
-      return null
-    }
+    return row ? mapRow(row) : null
   }
 )