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/elective/data-access-operations.ts

@@ -46,7 +46,12 @@ export async function runLottery(courseId: string): Promise<{
     return { enrolled: 0, waitlist: 0 }
   }
 
-  const shuffled = [...selections].sort(() => Math.random() - 0.5)
+  // Fisher-Yates shuffle: 无偏均匀随机排列，避免 sort(() => Math.random() - 0.5) 的分布偏差
+  const shuffled = [...selections]
+  for (let i = shuffled.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1))
+    ;[shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]]
+  }
   const capacity = course.capacity
   const now = new Date()
 
@@ -99,13 +104,26 @@ export async function selectCourse(
   studentId: string,
   priority?: number
 ): Promise<{ status: CourseSelectionStatus; message: string }> {
-  const [courseRows, existingRows] = await Promise.all([
-    db
+  return db.transaction(async (tx) => {
+    // 锁定课程行，防止 FCFS 模式下并发超卖
+    const [course] = await tx
       .select()
       .from(electiveCourses)
       .where(eq(electiveCourses.id, courseId))
-      .limit(1),
-    db
+      .for("update")
+      .limit(1)
+    if (!course) throw new Error("Course not found")
+    if (course.status !== "open") throw new Error("Course selection is not open")
+
+    const now = new Date()
+    if (course.selectionStartAt && now < course.selectionStartAt) {
+      throw new Error("Selection has not started yet")
+    }
+    if (course.selectionEndAt && now > course.selectionEndAt) {
+      throw new Error("Selection has ended")
+    }
+
+    const [existing] = await tx
       .select()
       .from(courseSelections)
       .where(
@@ -115,68 +133,55 @@ export async function selectCourse(
           inArray(courseSelections.status, ["selected", "enrolled", "waitlist"])
         )
       )
-      .limit(1),
-  ])
-  const course = courseRows[0]
-  if (!course) throw new Error("Course not found")
-  if (course.status !== "open") throw new Error("Course selection is not open")
+      .limit(1)
+    if (existing) throw new Error("Already selected this course")
 
-  const now = new Date()
-  if (course.selectionStartAt && now < course.selectionStartAt) {
-    throw new Error("Selection has not started yet")
-  }
-  if (course.selectionEndAt && now > course.selectionEndAt) {
-    throw new Error("Selection has ended")
-  }
+    const id = createId()
+    let status: CourseSelectionStatus = "selected"
+    let enrolledAt: Date | null = null
 
-  const existing = existingRows[0]
-  if (existing) throw new Error("Already selected this course")
+    if (course.selectionMode === "fcfs" && course.enrolledCount < course.capacity) {
+      status = "enrolled"
+      enrolledAt = now
+      await tx
+        .update(electiveCourses)
+        .set({
+          enrolledCount: course.enrolledCount + 1,
+          updatedAt: now,
+        })
+        .where(eq(electiveCourses.id, courseId))
+    } else if (course.selectionMode === "fcfs") {
+      status = "waitlist"
+    }
 
-  const id = createId()
-  let status: CourseSelectionStatus = "selected"
-  let enrolledAt: Date | null = null
+    await tx.insert(courseSelections).values({
+      id,
+      courseId,
+      studentId,
+      status,
+      priority: priority ?? 1,
+      selectedAt: now,
+      enrolledAt,
+    })
 
-  if (course.selectionMode === "fcfs" && course.enrolledCount < course.capacity) {
-    status = "enrolled"
-    enrolledAt = now
-    await db
-      .update(electiveCourses)
-      .set({
-        enrolledCount: course.enrolledCount + 1,
-        updatedAt: now,
-      })
-      .where(eq(electiveCourses.id, courseId))
-  } else if (course.selectionMode === "fcfs") {
-    status = "waitlist"
-  }
-
-  await db.insert(courseSelections).values({
-    id,
-    courseId,
-    studentId,
-    status,
-    priority: priority ?? 1,
-    selectedAt: now,
-    enrolledAt,
+    return {
+      status,
+      message:
+        status === "enrolled"
+          ? "Enrolled successfully"
+          : status === "waitlist"
+            ? "Added to waitlist"
+            : "Selection submitted",
+    }
   })
-
-  return {
-    status,
-    message:
-      status === "enrolled"
-        ? "Enrolled successfully"
-        : status === "waitlist"
-          ? "Added to waitlist"
-          : "Selection submitted",
-  }
 }
 
 export async function dropCourse(
   courseId: string,
   studentId: string
 ): Promise<void> {
-  const [existingRows, courseRows] = await Promise.all([
-    db
+  await db.transaction(async (tx) => {
+    const [existing] = await tx
       .select()
       .from(courseSelections)
       .where(
@@ -186,32 +191,31 @@ export async function dropCourse(
           inArray(courseSelections.status, ["selected", "enrolled", "waitlist"])
         )
       )
-      .limit(1),
-    db
+      .limit(1)
+    if (!existing) throw new Error("No active selection found")
+
+    // 锁定课程行，确保 enrolledCount 更新与候补递补的原子性
+    const [course] = await tx
       .select()
       .from(electiveCourses)
       .where(eq(electiveCourses.id, courseId))
-      .limit(1),
-  ])
-  const existing = existingRows[0]
-  if (!existing) throw new Error("No active selection found")
+      .for("update")
+      .limit(1)
 
-  const course = courseRows[0]
-  const now = new Date()
-  await db
-    .update(courseSelections)
-    .set({ status: "dropped", droppedAt: now, updatedAt: now })
-    .where(eq(courseSelections.id, existing.id))
+    const now = new Date()
+    await tx
+      .update(courseSelections)
+      .set({ status: "dropped", droppedAt: now, updatedAt: now })
+      .where(eq(courseSelections.id, existing.id))
 
-  if (existing.status === "enrolled") {
-    if (course && course.selectionMode === "fcfs") {
+    if (existing.status === "enrolled" && course && course.selectionMode === "fcfs") {
       const newEnrolledCount = Math.max(0, course.enrolledCount - 1)
-      await db
+      await tx
         .update(electiveCourses)
         .set({ enrolledCount: newEnrolledCount, updatedAt: now })
         .where(eq(electiveCourses.id, courseId))
 
-      const [nextWait] = await db
+      const [nextWait] = await tx
         .select()
         .from(courseSelections)
         .where(
@@ -223,7 +227,7 @@ export async function dropCourse(
         .orderBy(asc(courseSelections.priority), asc(courseSelections.selectedAt))
         .limit(1)
       if (nextWait) {
-        await db
+        await tx
           .update(courseSelections)
           .set({
             status: "enrolled",
@@ -231,11 +235,11 @@ export async function dropCourse(
             updatedAt: now,
           })
           .where(eq(courseSelections.id, nextWait.id))
-        await db
+        await tx
           .update(electiveCourses)
           .set({ enrolledCount: newEnrolledCount + 1, updatedAt: now })
           .where(eq(electiveCourses.id, courseId))
       }
     }
-  }
+  })
 }