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/lib/auth-guard.ts

@@ -1,7 +1,8 @@
-import type { Permission, DataScope, AuthContext } from "@/shared/types/permissions"
+import type { Permission, DataScope, AuthContext, Role } from "@/shared/types/permissions"
 import { db } from "@/shared/db"
 import {
   classes,
+  classEnrollments,
   classSubjectTeachers,
   grades,
   parentStudentRelations,
@@ -11,7 +12,9 @@ import { getSession } from "@/shared/lib/session"
 
 export class PermissionDeniedError extends Error {
   constructor(permission: string) {
-    super(`Permission denied: ${permission}`)
+    super(
+      `权限不足：需要 ${permission} 权限。请联系管理员授权或切换账号后重试。`
+    )
     this.name = "PermissionDeniedError"
   }
 }
@@ -26,7 +29,7 @@ export async function getAuthContext(): Promise<AuthContext> {
   if (!userId) throw new PermissionDeniedError("auth_required")
 
   // Prefer session data (already resolved in JWT callback)
-  const roleNames = (session.user.roles ?? []) as string[]
+  const roleNames = (session.user.roles ?? []) as Role[]
   const permissions = (session.user.permissions ?? []) as Permission[]
 
   // Resolve data scope from DB (not cached in JWT since it can change)
@@ -61,7 +64,7 @@ export async function checkPermission(
  * Resolve the data scope for a user based on their roles.
  * Queries the DB for resource ownership information.
  */
-async function resolveDataScope(userId: string, roleNames: string[]): Promise<DataScope> {
+async function resolveDataScope(userId: string, roleNames: Role[]): Promise<DataScope> {
   // Admin sees everything
   if (roleNames.includes("admin")) {
     return { type: "all" }
@@ -111,8 +114,17 @@ async function resolveDataScope(userId: string, roleNames: string[]): Promise<Da
   }
 
   // Student: can see data from their enrolled classes
+  // Pre-resolve classIds here to avoid N+1 queries in data-access layer
   if (roleNames.includes("student")) {
-    return { type: "class_members" }
+    const enrolledClasses = await db
+      .select({ classId: classEnrollments.classId })
+      .from(classEnrollments)
+      .where(eq(classEnrollments.studentId, userId))
+
+    return {
+      type: "class_members",
+      classIds: enrolledClasses.map((c) => c.classId),
+    }
   }
 
   // Parent: can see their children's data

src/shared/lib/download.ts

@@ -0,0 +1,47 @@
+/**
+ * 客户端文件下载工具
+ *
+ * 覆盖以下重复模式：
+ * - grades/export-button.tsx 中的 downloadBase64File
+ * - users/user-import-dialog.tsx 中的 downloadBase64File
+ * - audit/audit-log-export-button.tsx 中的 Blob 下载逻辑
+ *
+ * 注意：仅在客户端使用（依赖 document、URL.createObjectURL 等 API）。
+ */
+
+const EXCEL_MIME_TYPE =
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+
+/**
+ * 将 base64 编码的数据下载为文件
+ * @param base64 base64 编码的文件内容
+ * @param filename 下载文件名
+ * @param mimeType MIME 类型，默认为 Excel
+ */
+export function downloadBase64File(
+  base64: string,
+  filename: string,
+  mimeType: string = EXCEL_MIME_TYPE
+): void {
+  const binary = atob(base64)
+  const bytes = new Uint8Array(binary.length)
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i)
+  const blob = new Blob([bytes], { type: mimeType })
+  downloadBlob(blob, filename)
+}
+
+/**
+ * 将 Blob 数据下载为文件
+ * @param blob Blob 数据
+ * @param filename 下载文件名
+ */
+export function downloadBlob(blob: Blob, filename: string): void {
+  const url = URL.createObjectURL(blob)
+  const a = document.createElement("a")
+  a.href = url
+  a.download = filename
+  document.body.appendChild(a)
+  a.click()
+  document.body.removeChild(a)
+  URL.revokeObjectURL(url)
+}

src/shared/lib/permissions.ts

@@ -1,8 +1,8 @@
-import { Permissions, type Permission } from "@/shared/types/permissions"
+import { Permissions, type Permission, type Role } from "@/shared/types/permissions"
 
 // Role → Permission mapping
 // New roles only need to add an entry here + seed the DB
-export const ROLE_PERMISSIONS: Record<string, Permission[]> = {
+export const ROLE_PERMISSIONS: Record<Role, Permission[]> = {
   admin: [
     Permissions.EXAM_CREATE,
     Permissions.EXAM_READ,
@@ -59,6 +59,9 @@ export const ROLE_PERMISSIONS: Record<string, Permission[]> = {
     Permissions.LESSON_PLAN_UPDATE,
     Permissions.LESSON_PLAN_DELETE,
     Permissions.LESSON_PLAN_PUBLISH,
+    Permissions.FILE_UPLOAD,
+    Permissions.FILE_READ,
+    Permissions.FILE_DELETE,
   ],
   teacher: [
     Permissions.EXAM_CREATE,
@@ -116,6 +119,7 @@ export const ROLE_PERMISSIONS: Record<string, Permission[]> = {
     Permissions.GRADE_RECORD_READ,
     Permissions.COURSE_PLAN_READ,
     Permissions.ATTENDANCE_READ,
+    Permissions.MESSAGE_SEND,
     Permissions.MESSAGE_READ,
     Permissions.MESSAGE_DELETE,
     Permissions.ELECTIVE_SELECT,
@@ -208,7 +212,7 @@ export const ROLE_PERMISSIONS: Record<string, Permission[]> = {
 /**
  * Merge permissions from all roles (deduplicated)
  */
-export function resolvePermissions(roleNames: string[]): Permission[] {
+export function resolvePermissions(roleNames: Role[]): Permission[] {
   const set = new Set<Permission>()
   for (const name of roleNames) {
     const perms = ROLE_PERMISSIONS[name] ?? []

src/shared/lib/search-params.ts

@@ -0,0 +1,9 @@
+/**
+ * Search params utility for Next.js pages.
+ *
+ * Re-exports from utils.ts for consistency with admin pages.
+ * Next.js 15+ passes `searchParams` as a Promise. Values may be string,
+ * string[], or undefined. This helper normalizes access to a single value.
+ */
+
+export { getSearchParam as getParam, type SearchParams } from "./utils"

src/shared/lib/utils.ts

@@ -12,3 +12,54 @@ export function formatDate(date: string | Date, locale: string = "zh-CN") {
     day: "numeric",
   }).format(new Date(date))
 }
+
+/** Next.js App Router 搜索参数类型 */
+export type SearchParams = { [key: string]: string | string[] | undefined }
+
+/** 从 SearchParams 中安全提取单个字符串值 */
+export function getSearchParam(params: SearchParams, key: string): string | undefined {
+  const v = params[key]
+  if (typeof v === "string") return v
+  if (Array.isArray(v)) return v[0]
+  return undefined
+}
+
+/** 格式化数字，null/undefined/非有限数返回 "-" */
+export function formatNumber(v: number | null | undefined, digits = 1): string {
+  if (typeof v !== "number" || !Number.isFinite(v)) return "-"
+  return v.toFixed(digits)
+}
+
+/**
+ * 从姓名生成头像占位用的首字母（最多 2 个字符）。
+ * 用于 AvatarFallback 组件。
+ * - 含空格的姓名：取各单词首字母拼接（如 "John Doe" -> "JD"）
+ * - 无空格的姓名：取前 2 个字符（如 "张三" -> "张三"）
+ * - 空值：返回 "U"（User 通用占位）
+ */
+export function getInitials(name: string | null | undefined): string {
+  if (!name) return "U"
+  const trimmed = name.trim()
+  if (!trimmed) return "U"
+  if (trimmed.includes(" ")) {
+    return trimmed
+      .split(/\s+/)
+      .map((n) => n[0])
+      .join("")
+      .toUpperCase()
+      .slice(0, 2)
+  }
+  return trimmed.slice(0, 2).toUpperCase()
+}
+
+/**
+ * 格式化日期为文件名安全的 YYYY-MM-DD 格式。
+ * 用于导出文件名（如 `grades_export_2026-06-20.xlsx`）。
+ * @param d 日期对象，默认为当前时间
+ */
+export function formatDateForFile(d: Date = new Date()): string {
+  const y = d.getFullYear()
+  const m = String(d.getMonth() + 1).padStart(2, "0")
+  const day = String(d.getDate()).padStart(2, "0")
+  return `${y}-${m}-${day}`
+}