refactor: P0-1/2/4 解耦修复 - 拆分过耦合文件 + dashboard 解耦

src/modules/classes/data-access-admin.ts

@@ -0,0 +1,441 @@
+import "server-only";
+
+import { cache } from "react"
+import { and, asc, eq, inArray, or, sql } from "drizzle-orm"
+import { createId } from "@paralleldrive/cuid2"
+
+import { db } from "@/shared/db"
+import {
+  classes,
+  classEnrollments,
+  classSubjectTeachers,
+  grades,
+  schools,
+  subjects,
+  roles,
+  users,
+  usersToRoles,
+} from "@/shared/db/schema"
+import { DEFAULT_CLASS_SUBJECTS } from "./types"
+import type {
+  AdminClassListItem,
+  ClassSubject,
+  ClassSubjectTeacherAssignment,
+  CreateTeacherClassInput,
+  TeacherOption,
+  UpdateTeacherClassInput,
+} from "./types"
+import {
+  compareClassLike,
+  generateUniqueInvitationCode,
+  isDuplicateInvitationCodeError,
+} from "./data-access"
+
+export const getAdminClasses = cache(async (): Promise<AdminClassListItem[]> => {
+  const [rows, subjectRows] = await Promise.all([
+    (async () => {
+      try {
+        return await db
+          .select({
+            id: classes.id,
+            schoolName: classes.schoolName,
+            schoolId: classes.schoolId,
+            name: classes.name,
+            grade: classes.grade,
+            gradeId: classes.gradeId,
+            homeroom: classes.homeroom,
+            room: classes.room,
+            invitationCode: classes.invitationCode,
+            teacherId: users.id,
+            teacherName: users.name,
+            teacherEmail: users.email,
+            studentCount: sql<number>`COALESCE(SUM(CASE WHEN ${classEnrollments.status} = 'active' THEN 1 ELSE 0 END), 0)`,
+            createdAt: classes.createdAt,
+            updatedAt: classes.updatedAt,
+          })
+          .from(classes)
+          .innerJoin(users, eq(users.id, classes.teacherId))
+          .leftJoin(classEnrollments, eq(classEnrollments.classId, classes.id))
+          .groupBy(
+            classes.id,
+            classes.schoolName,
+            classes.schoolId,
+            classes.name,
+            classes.grade,
+            classes.gradeId,
+            classes.homeroom,
+            classes.room,
+            classes.invitationCode,
+            users.id,
+            users.name,
+            users.email,
+            classes.createdAt,
+            classes.updatedAt
+          )
+          .orderBy(
+            asc(classes.schoolName),
+            asc(classes.grade),
+            asc(classes.name),
+            asc(classes.homeroom),
+            asc(classes.room)
+          )
+      } catch {
+        return await db
+          .select({
+            id: classes.id,
+            schoolName: sql<string | null>`NULL`.as("schoolName"),
+            schoolId: sql<string | null>`NULL`.as("schoolId"),
+            name: classes.name,
+            grade: classes.grade,
+            gradeId: sql<string | null>`NULL`.as("gradeId"),
+            homeroom: classes.homeroom,
+            room: classes.room,
+            invitationCode: sql<string | null>`NULL`.as("invitationCode"),
+            teacherId: users.id,
+            teacherName: users.name,
+            teacherEmail: users.email,
+            studentCount: sql<number>`COALESCE(SUM(CASE WHEN ${classEnrollments.status} = 'active' THEN 1 ELSE 0 END), 0)`,
+            createdAt: classes.createdAt,
+            updatedAt: classes.updatedAt,
+          })
+          .from(classes)
+          .innerJoin(users, eq(users.id, classes.teacherId))
+          .leftJoin(classEnrollments, eq(classEnrollments.classId, classes.id))
+          .groupBy(
+            classes.id,
+            classes.name,
+            classes.grade,
+            classes.homeroom,
+            classes.room,
+            users.id,
+            users.name,
+            users.email,
+            classes.createdAt,
+            classes.updatedAt
+          )
+          .orderBy(asc(classes.grade), asc(classes.name), asc(classes.homeroom), asc(classes.room))
+      }
+    })(),
+    db
+      .select({
+        classId: classSubjectTeachers.classId,
+        subject: subjects.name,
+        teacherId: users.id,
+        teacherName: users.name,
+        teacherEmail: users.email,
+      })
+      .from(classSubjectTeachers)
+      .innerJoin(subjects, eq(subjects.id, classSubjectTeachers.subjectId))
+      .leftJoin(users, eq(users.id, classSubjectTeachers.teacherId))
+      .orderBy(asc(classSubjectTeachers.classId), asc(subjects.name)),
+  ])
+
+  const subjectsByClassId = new Map<string, Map<ClassSubject, TeacherOption | null>>()
+  for (const r of subjectRows) {
+    const subject = r.subject as ClassSubject
+    if (!DEFAULT_CLASS_SUBJECTS.includes(subject)) continue
+    const teacher =
+      typeof r.teacherId === "string" && r.teacherId.length > 0
+        ? { id: r.teacherId, name: r.teacherName ?? "Unnamed", email: r.teacherEmail ?? "" }
+        : null
+    const bySubject = subjectsByClassId.get(r.classId) ?? new Map<ClassSubject, TeacherOption | null>()
+    bySubject.set(subject, teacher)
+    subjectsByClassId.set(r.classId, bySubject)
+  }
+
+  const list = rows.map((r) => {
+    const bySubject = subjectsByClassId.get(r.id)
+    const subjectTeachers: ClassSubjectTeacherAssignment[] = DEFAULT_CLASS_SUBJECTS.map((subject) => ({
+      subject,
+      teacher: bySubject?.get(subject) ?? null,
+    }))
+
+    return {
+      id: r.id,
+      schoolName: r.schoolName,
+      schoolId: r.schoolId,
+      name: r.name,
+      grade: r.grade,
+      gradeId: r.gradeId,
+      homeroom: r.homeroom,
+      room: r.room,
+      invitationCode: r.invitationCode ?? null,
+      teacher: {
+        id: r.teacherId,
+        name: r.teacherName ?? "Unnamed",
+        email: r.teacherEmail,
+      },
+      subjectTeachers,
+      studentCount: Number(r.studentCount ?? 0),
+      createdAt: r.createdAt.toISOString(),
+      updatedAt: r.updatedAt.toISOString(),
+    }
+  })
+
+  list.sort(compareClassLike)
+  return list
+})
+
+export const getGradeManagedClasses = cache(async (userId: string): Promise<AdminClassListItem[]> => {
+  const managedGradeIds = await db
+    .select({ id: grades.id })
+    .from(grades)
+    .where(or(eq(grades.gradeHeadId, userId), eq(grades.teachingHeadId, userId)))
+
+  if (managedGradeIds.length === 0) return []
+
+  const gradeIds = managedGradeIds.map((g) => g.id)
+
+  const [rows, subjectRows] = await Promise.all([
+    (async () => {
+      try {
+        return await db
+          .select({
+            id: classes.id,
+            schoolName: classes.schoolName,
+            schoolId: classes.schoolId,
+            name: classes.name,
+            grade: classes.grade,
+            gradeId: classes.gradeId,
+            homeroom: classes.homeroom,
+            room: classes.room,
+            invitationCode: classes.invitationCode,
+            teacherId: users.id,
+            teacherName: users.name,
+            teacherEmail: users.email,
+            studentCount: sql<number>`COALESCE(SUM(CASE WHEN ${classEnrollments.status} = 'active' THEN 1 ELSE 0 END), 0)`,
+            createdAt: classes.createdAt,
+            updatedAt: classes.updatedAt,
+          })
+          .from(classes)
+          .innerJoin(users, eq(users.id, classes.teacherId))
+          .leftJoin(classEnrollments, eq(classEnrollments.classId, classes.id))
+          .where(inArray(classes.gradeId, gradeIds))
+          .groupBy(
+            classes.id,
+            classes.schoolName,
+            classes.schoolId,
+            classes.name,
+            classes.grade,
+            classes.gradeId,
+            classes.homeroom,
+            classes.room,
+            classes.invitationCode,
+            users.id,
+            users.name,
+            users.email,
+            classes.createdAt,
+            classes.updatedAt
+          )
+          .orderBy(
+            asc(classes.schoolName),
+            asc(classes.grade),
+            asc(classes.name),
+            asc(classes.homeroom),
+            asc(classes.room)
+          )
+      } catch {
+        return []
+      }
+    })(),
+    db
+      .select({
+        classId: classSubjectTeachers.classId,
+        subject: subjects.name,
+        teacherId: users.id,
+        teacherName: users.name,
+        teacherEmail: users.email,
+      })
+      .from(classSubjectTeachers)
+      .innerJoin(subjects, eq(subjects.id, classSubjectTeachers.subjectId))
+      .innerJoin(classes, eq(classes.id, classSubjectTeachers.classId))
+      .leftJoin(users, eq(users.id, classSubjectTeachers.teacherId))
+      .where(inArray(classes.gradeId, gradeIds))
+      .orderBy(asc(classSubjectTeachers.classId), asc(subjects.name)),
+  ])
+
+  const subjectsByClassId = new Map<string, Map<ClassSubject, TeacherOption | null>>()
+  for (const r of subjectRows) {
+    const subject = r.subject as ClassSubject
+    if (!DEFAULT_CLASS_SUBJECTS.includes(subject)) continue
+    const teacher =
+      typeof r.teacherId === "string" && r.teacherId.length > 0
+        ? { id: r.teacherId, name: r.teacherName ?? "Unnamed", email: r.teacherEmail ?? "" }
+        : null
+    const bySubject = subjectsByClassId.get(r.classId) ?? new Map<ClassSubject, TeacherOption | null>()
+    bySubject.set(subject, teacher)
+    subjectsByClassId.set(r.classId, bySubject)
+  }
+
+  const list = rows.map((r) => {
+    const bySubject = subjectsByClassId.get(r.id)
+    const subjectTeachers: ClassSubjectTeacherAssignment[] = DEFAULT_CLASS_SUBJECTS.map((subject) => ({
+      subject,
+      teacher: bySubject?.get(subject) ?? null,
+    }))
+
+    return {
+      id: r.id,
+      schoolName: r.schoolName,
+      schoolId: r.schoolId,
+      name: r.name,
+      grade: r.grade,
+      gradeId: r.gradeId,
+      homeroom: r.homeroom,
+      room: r.room,
+      invitationCode: r.invitationCode ?? null,
+      teacher: {
+        id: r.teacherId,
+        name: r.teacherName ?? "Unnamed",
+        email: r.teacherEmail,
+      },
+      subjectTeachers,
+      studentCount: Number(r.studentCount ?? 0),
+      createdAt: r.createdAt.toISOString(),
+      updatedAt: r.updatedAt.toISOString(),
+    }
+  })
+
+  list.sort(compareClassLike)
+  return list
+})
+
+export const getManagedGrades = cache(async (userId: string) => {
+  return await db
+    .select({
+      id: grades.id,
+      name: grades.name,
+      schoolId: grades.schoolId,
+      schoolName: schools.name,
+    })
+    .from(grades)
+    .innerJoin(schools, eq(schools.id, grades.schoolId))
+    .where(or(eq(grades.gradeHeadId, userId), eq(grades.teachingHeadId, userId)))
+    .orderBy(asc(schools.name), asc(grades.name))
+})
+
+export async function createAdminClass(data: CreateTeacherClassInput & { teacherId: string }): Promise<string> {
+  const id = createId()
+
+  const schoolName = data.schoolName?.trim() || null
+  const schoolId = data.schoolId?.trim() || null
+  const name = data.name.trim()
+  const grade = data.grade.trim()
+  const gradeId = data.gradeId?.trim() || null
+  const homeroom = data.homeroom?.trim() || null
+  const room = data.room?.trim() || null
+  const teacherId = data.teacherId.trim()
+
+  if (!name) throw new Error("Name is required")
+  if (!grade) throw new Error("Grade is required")
+  if (!teacherId) throw new Error("Teacher is required")
+
+  const [teacher] = await db
+    .select({ id: users.id })
+    .from(users)
+    .innerJoin(usersToRoles, eq(usersToRoles.userId, users.id))
+    .innerJoin(roles, eq(usersToRoles.roleId, roles.id))
+    .where(and(eq(users.id, teacherId), eq(roles.name, "teacher")))
+    .limit(1)
+  if (!teacher) throw new Error("Teacher not found")
+
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    const invitationCode = await generateUniqueInvitationCode()
+    try {
+      const subjectRows = await db
+        .select({ id: subjects.id, name: subjects.name })
+        .from(subjects)
+        .where(inArray(subjects.name, DEFAULT_CLASS_SUBJECTS))
+      const idByName = new Map(subjectRows.map((r) => [r.name as ClassSubject, r.id]))
+
+      await db.transaction(async (tx) => {
+        await tx.insert(classes).values({
+          id,
+          schoolName,
+          schoolId,
+          name,
+          grade,
+          gradeId,
+          homeroom,
+          room,
+          invitationCode,
+          teacherId,
+        })
+
+        const values = DEFAULT_CLASS_SUBJECTS
+          .filter((name) => idByName.has(name))
+          .map((name) => ({
+            classId: id,
+            subjectId: idByName.get(name)!,
+            teacherId: null,
+          }))
+        await tx.insert(classSubjectTeachers).values(values)
+      })
+      return id
+    } catch (err) {
+      if (isDuplicateInvitationCodeError(err)) continue
+      throw err
+    }
+  }
+  throw new Error("Failed to create class")
+
+  return id
+}
+
+export async function updateAdminClass(
+  classId: string,
+  data: UpdateTeacherClassInput & { teacherId?: string }
+): Promise<void> {
+  const id = classId.trim()
+  if (!id) throw new Error("Missing class id")
+
+  const [existing] = await db
+    .select({ id: classes.id })
+    .from(classes)
+    .where(eq(classes.id, id))
+    .limit(1)
+  if (!existing) throw new Error("Class not found")
+
+  const update: Partial<typeof classes.$inferSelect> = {}
+  if (data.schoolName !== undefined) update.schoolName = data.schoolName?.trim() || null
+  if (data.schoolId !== undefined) update.schoolId = data.schoolId?.trim() || null
+  if (typeof data.name === "string") update.name = data.name.trim()
+  if (typeof data.grade === "string") update.grade = data.grade.trim()
+  if (data.gradeId !== undefined) update.gradeId = data.gradeId?.trim() || null
+  if (data.homeroom !== undefined) update.homeroom = data.homeroom?.trim() || null
+  if (data.room !== undefined) update.room = data.room?.trim() || null
+
+  if (typeof data.teacherId === "string") {
+    const nextTeacherId = data.teacherId.trim()
+    if (!nextTeacherId) throw new Error("Teacher is required")
+
+    const [teacher] = await db
+      .select({ id: users.id })
+      .from(users)
+      .innerJoin(usersToRoles, eq(usersToRoles.userId, users.id))
+      .innerJoin(roles, eq(usersToRoles.roleId, roles.id))
+      .where(and(eq(users.id, nextTeacherId), eq(roles.name, "teacher")))
+      .limit(1)
+    if (!teacher) throw new Error("Teacher not found")
+
+    update.teacherId = nextTeacherId
+  }
+
+  if (Object.keys(update).length === 0) return
+
+  await db.update(classes).set(update).where(eq(classes.id, id))
+}
+
+export async function deleteAdminClass(classId: string): Promise<void> {
+  const id = classId.trim()
+  if (!id) throw new Error("Missing class id")
+
+  const [existing] = await db
+    .select({ id: classes.id })
+    .from(classes)
+    .where(eq(classes.id, id))
+    .limit(1)
+  if (!existing) throw new Error("Class not found")
+
+  await db.delete(classes).where(eq(classes.id, id))
+}

src/modules/classes/data-access-schedule.ts

@@ -0,0 +1,230 @@
+import "server-only";
+
+import { cache } from "react"
+import { and, asc, eq, inArray, type SQL } from "drizzle-orm"
+
+import { db } from "@/shared/db"
+import {
+  classes,
+  classEnrollments,
+  classSchedule,
+} from "@/shared/db/schema"
+import {
+  insertClassScheduleItem,
+  updateClassScheduleItemById,
+  deleteClassScheduleItemById,
+} from "@/modules/scheduling/data-access"
+import type {
+  ClassScheduleItem,
+  CreateClassScheduleItemInput,
+  StudentScheduleItem,
+  UpdateClassScheduleItemInput,
+} from "./types"
+import {
+  getAccessibleClassIdsForTeacher,
+  getSessionTeacherId,
+  getTeacherIdForMutations,
+} from "./data-access"
+
+export const getStudentSchedule = cache(async (studentId: string): Promise<StudentScheduleItem[]> => {
+  const id = studentId.trim()
+  if (!id) return []
+
+  const rows = await db
+    .select({
+      id: classSchedule.id,
+      classId: classSchedule.classId,
+      className: classes.name,
+      weekday: classSchedule.weekday,
+      startTime: classSchedule.startTime,
+      endTime: classSchedule.endTime,
+      course: classSchedule.course,
+      location: classSchedule.location,
+    })
+    .from(classEnrollments)
+    .innerJoin(classes, eq(classes.id, classEnrollments.classId))
+    .innerJoin(classSchedule, eq(classSchedule.classId, classes.id))
+    .where(and(eq(classEnrollments.studentId, id), eq(classEnrollments.status, "active")))
+    .orderBy(asc(classSchedule.weekday), asc(classSchedule.startTime))
+
+  return rows.map((r) => ({
+    id: r.id,
+    classId: r.classId,
+    className: r.className,
+    weekday: r.weekday as StudentScheduleItem["weekday"],
+    startTime: r.startTime,
+    endTime: r.endTime,
+    course: r.course,
+    location: r.location,
+  }))
+})
+
+export const getClassSchedule = cache(
+  async (params?: { classId?: string; teacherId?: string }): Promise<ClassScheduleItem[]> => {
+    const teacherId = params?.teacherId ?? (await getSessionTeacherId())
+    if (!teacherId) return []
+
+    const classId = params?.classId?.trim()
+
+    const accessibleIds = await getAccessibleClassIdsForTeacher(teacherId)
+    if (accessibleIds.length === 0) return []
+
+    const conditions: SQL[] = [inArray(classes.id, accessibleIds)]
+    if (classId) conditions.push(eq(classSchedule.classId, classId))
+
+    const rows = await db
+      .select({
+        id: classSchedule.id,
+        classId: classSchedule.classId,
+        weekday: classSchedule.weekday,
+        startTime: classSchedule.startTime,
+        endTime: classSchedule.endTime,
+        course: classSchedule.course,
+        location: classSchedule.location,
+      })
+      .from(classSchedule)
+      .innerJoin(classes, eq(classes.id, classSchedule.classId))
+      .where(and(...conditions))
+      .orderBy(asc(classSchedule.weekday), asc(classSchedule.startTime))
+
+    return rows.map((r) => ({
+      id: r.id,
+      classId: r.classId,
+      weekday: r.weekday as ClassScheduleItem["weekday"],
+      startTime: r.startTime,
+      endTime: r.endTime,
+      course: r.course,
+      location: r.location,
+    }))
+  }
+)
+
+const isTimeHHMM = (v: string) => /^\d{2}:\d{2}$/.test(v)
+
+export async function createClassScheduleItem(data: CreateClassScheduleItemInput): Promise<string> {
+  const teacherId = await getTeacherIdForMutations()
+
+  const classId = data.classId.trim()
+  const course = data.course.trim()
+  const startTime = data.startTime.trim()
+  const endTime = data.endTime.trim()
+  const location = data.location?.trim() || null
+  const weekday = data.weekday
+
+  if (!classId) throw new Error("Class is required")
+  if (!course) throw new Error("Course is required")
+  if (!isTimeHHMM(startTime) || !isTimeHHMM(endTime)) throw new Error("Invalid time format")
+  if (startTime >= endTime) throw new Error("Start time must be earlier than end time")
+  if (weekday < 1 || weekday > 7) throw new Error("Invalid weekday")
+
+  const [owned] = await db
+    .select({ id: classes.id })
+    .from(classes)
+    .where(and(eq(classes.id, classId), eq(classes.teacherId, teacherId)))
+    .limit(1)
+
+  if (!owned) throw new Error("Class not found")
+
+  // Delegate DB write to scheduling module (unified write entry point)
+  return insertClassScheduleItem({
+    classId,
+    weekday,
+    startTime,
+    endTime,
+    course,
+    location,
+  })
+}
+
+export async function updateClassScheduleItem(scheduleId: string, data: UpdateClassScheduleItemInput): Promise<void> {
+  const teacherId = await getTeacherIdForMutations()
+  const id = scheduleId.trim()
+  if (!id) throw new Error("Missing schedule id")
+
+  const [existing] = await db
+    .select({
+      id: classSchedule.id,
+      classId: classSchedule.classId,
+      startTime: classSchedule.startTime,
+      endTime: classSchedule.endTime,
+    })
+    .from(classSchedule)
+    .innerJoin(classes, eq(classes.id, classSchedule.classId))
+    .where(and(eq(classSchedule.id, id), eq(classes.teacherId, teacherId)))
+    .limit(1)
+
+  if (!existing) throw new Error("Schedule item not found")
+
+  const update: Partial<typeof classSchedule.$inferSelect> = {}
+
+  if (typeof data.classId === "string") {
+    const nextClassId = data.classId.trim()
+    if (!nextClassId) throw new Error("Class is required")
+
+    const [ownedNext] = await db
+      .select({ id: classes.id })
+      .from(classes)
+      .where(and(eq(classes.id, nextClassId), eq(classes.teacherId, teacherId)))
+      .limit(1)
+
+    if (!ownedNext) throw new Error("Class not found")
+    update.classId = nextClassId
+  }
+
+  if (typeof data.weekday === "number") {
+    if (data.weekday < 1 || data.weekday > 7) throw new Error("Invalid weekday")
+    update.weekday = data.weekday
+  }
+
+  if (typeof data.course === "string") {
+    const course = data.course.trim()
+    if (!course) throw new Error("Course is required")
+    update.course = course
+  }
+
+  const nextStart = typeof data.startTime === "string" ? data.startTime.trim() : undefined
+  const nextEnd = typeof data.endTime === "string" ? data.endTime.trim() : undefined
+  if (nextStart !== undefined) {
+    if (!isTimeHHMM(nextStart)) throw new Error("Invalid time format")
+    update.startTime = nextStart
+  }
+  if (nextEnd !== undefined) {
+    if (!isTimeHHMM(nextEnd)) throw new Error("Invalid time format")
+    update.endTime = nextEnd
+  }
+
+  if (update.startTime !== undefined || update.endTime !== undefined) {
+    const mergedStart = update.startTime ?? existing.startTime
+    const mergedEnd = update.endTime ?? existing.endTime
+    if (typeof mergedStart === "string" && typeof mergedEnd === "string" && mergedStart >= mergedEnd) {
+      throw new Error("Start time must be earlier than end time")
+    }
+  }
+
+  if (data.location !== undefined) {
+    update.location = data.location?.trim() || null
+  }
+
+  if (Object.keys(update).length === 0) return
+
+  // Delegate DB write to scheduling module (unified write entry point)
+  await updateClassScheduleItemById(id, update)
+}
+
+export async function deleteClassScheduleItem(scheduleId: string): Promise<void> {
+  const teacherId = await getTeacherIdForMutations()
+  const id = scheduleId.trim()
+  if (!id) throw new Error("Missing schedule id")
+
+  const [owned] = await db
+    .select({ id: classSchedule.id })
+    .from(classSchedule)
+    .innerJoin(classes, eq(classes.id, classSchedule.classId))
+    .where(and(eq(classSchedule.id, id), eq(classes.teacherId, teacherId)))
+    .limit(1)
+
+  if (!owned) throw new Error("Schedule item not found")
+
+  // Delegate DB write to scheduling module (unified write entry point)
+  await deleteClassScheduleItemById(id)
+}

src/modules/classes/data-access-stats.ts

@@ -0,0 +1,604 @@
+import "server-only";
+
+import { cache } from "react"
+import { and, asc, count, desc, eq, inArray, sql, type SQL } from "drizzle-orm"
+
+import { db } from "@/shared/db"
+import {
+  classes,
+  classEnrollments,
+  grades,
+  homeworkAssignmentQuestions,
+  homeworkAssignmentTargets,
+  homeworkAssignments,
+  homeworkSubmissions,
+  schools,
+  subjects,
+  exams,
+} from "@/shared/db/schema"
+import type {
+  ClassHomeworkInsights,
+  ClassHomeworkAssignmentStats,
+  GradeHomeworkClassSummary,
+  GradeHomeworkInsights,
+  ScoreStats,
+} from "./types"
+import {
+  getAccessibleClassIdsForTeacher,
+  getSessionTeacherId,
+  getTeacherSubjectIdsForClass,
+} from "./data-access"
+
+const median = (sorted: number[]): number | null => {
+  if (sorted.length === 0) return null
+  const mid = Math.floor(sorted.length / 2)
+  if (sorted.length % 2 === 1) return sorted[mid] ?? null
+  const a = sorted[mid - 1]
+  const b = sorted[mid]
+  if (typeof a !== "number" || typeof b !== "number") return null
+  return (a + b) / 2
+}
+
+const toScoreStats = (scores: number[]): ScoreStats => {
+  if (scores.length === 0) return { count: 0, avg: null, median: null, min: null, max: null }
+  const sorted = [...scores].sort((a, b) => a - b)
+  const sum = sorted.reduce((acc, v) => acc + v, 0)
+  return {
+    count: sorted.length,
+    avg: sum / sorted.length,
+    median: median(sorted),
+    min: sorted[0] ?? null,
+    max: sorted[sorted.length - 1] ?? null,
+  }
+}
+
+export const getClassHomeworkInsights = cache(
+  async (params: { classId: string; teacherId?: string; limit?: number }): Promise<ClassHomeworkInsights | null> => {
+    const teacherId = params.teacherId ?? (await getSessionTeacherId())
+    if (!teacherId) return null
+
+    const classId = params.classId.trim()
+    if (!classId) return null
+    const accessibleIds = await getAccessibleClassIdsForTeacher(teacherId)
+    if (accessibleIds.length === 0 || !accessibleIds.includes(classId)) return null
+
+    const [classRow] = await db
+      .select({
+        id: classes.id,
+        name: classes.name,
+        grade: classes.grade,
+        homeroom: classes.homeroom,
+        room: classes.room,
+        invitationCode: classes.invitationCode,
+        teacherId: classes.teacherId,
+      })
+      .from(classes)
+      .where(and(eq(classes.id, classId), inArray(classes.id, accessibleIds)))
+      .limit(1)
+
+    if (!classRow) return null
+    const isHomeroomTeacher = classRow.teacherId === teacherId
+    const subjectIdFilter = isHomeroomTeacher ? [] : await getTeacherSubjectIdsForClass(teacherId, classId)
+
+    const enrollments = await db
+      .select({
+        studentId: classEnrollments.studentId,
+        status: classEnrollments.status,
+      })
+      .from(classEnrollments)
+      .innerJoin(classes, eq(classes.id, classEnrollments.classId))
+      .where(and(inArray(classes.id, accessibleIds), eq(classEnrollments.classId, classId)))
+
+    const activeStudentIds = enrollments.filter((e) => e.status === "active").map((e) => e.studentId)
+    const inactiveStudentIds = enrollments.filter((e) => e.status !== "active").map((e) => e.studentId)
+    const studentIds = enrollments.map((e) => e.studentId)
+
+    if (!isHomeroomTeacher && subjectIdFilter.length === 0) {
+      return {
+        class: {
+          id: classRow.id,
+          name: classRow.name,
+          grade: classRow.grade,
+          homeroom: classRow.homeroom,
+          room: classRow.room,
+          invitationCode: classRow.invitationCode ?? null,
+        },
+        studentCounts: { total: studentIds.length, active: activeStudentIds.length, inactive: inactiveStudentIds.length },
+        assignments: [],
+        latest: null,
+        overallScores: { count: 0, avg: null, median: null, min: null, max: null },
+      }
+    }
+
+    if (studentIds.length === 0) {
+      return {
+        class: {
+          id: classRow.id,
+          name: classRow.name,
+          grade: classRow.grade,
+          homeroom: classRow.homeroom,
+          room: classRow.room,
+          invitationCode: classRow.invitationCode ?? null,
+        },
+        studentCounts: { total: 0, active: 0, inactive: 0 },
+        assignments: [],
+        latest: null,
+        overallScores: { count: 0, avg: null, median: null, min: null, max: null },
+      }
+    }
+
+    const assignmentIdRows = await db
+      .selectDistinct({ assignmentId: homeworkAssignmentTargets.assignmentId })
+      .from(homeworkAssignmentTargets)
+      .where(inArray(homeworkAssignmentTargets.studentId, studentIds))
+
+    const assignmentIds = assignmentIdRows.map((r) => r.assignmentId)
+    if (assignmentIds.length === 0) {
+      return {
+        class: {
+          id: classRow.id,
+          name: classRow.name,
+          grade: classRow.grade,
+          homeroom: classRow.homeroom,
+          room: classRow.room,
+          invitationCode: classRow.invitationCode ?? null,
+        },
+        studentCounts: { total: studentIds.length, active: activeStudentIds.length, inactive: inactiveStudentIds.length },
+        assignments: [],
+        latest: null,
+        overallScores: { count: 0, avg: null, median: null, min: null, max: null },
+      }
+    }
+
+    const limit = typeof params.limit === "number" && params.limit > 0 ? params.limit : 50
+    const assignmentConditions: SQL[] = [inArray(homeworkAssignments.id, assignmentIds)]
+    if (subjectIdFilter.length > 0) {
+      assignmentConditions.push(inArray(exams.subjectId, subjectIdFilter))
+    }
+    const assignments = await db
+      .select({
+        id: homeworkAssignments.id,
+        title: homeworkAssignments.title,
+        status: homeworkAssignments.status,
+        createdAt: homeworkAssignments.createdAt,
+        dueAt: homeworkAssignments.dueAt,
+        subjectId: exams.subjectId,
+        subjectName: subjects.name
+      })
+      .from(homeworkAssignments)
+      .innerJoin(exams, eq(homeworkAssignments.sourceExamId, exams.id))
+      .leftJoin(subjects, eq(exams.subjectId, subjects.id))
+      .where(and(...assignmentConditions))
+      .orderBy(desc(homeworkAssignments.createdAt))
+      .limit(limit)
+
+    const usedAssignmentIds = assignments.map((a) => a.id)
+    if (usedAssignmentIds.length === 0) {
+      return {
+        class: {
+          id: classRow.id,
+          name: classRow.name,
+          grade: classRow.grade,
+          homeroom: classRow.homeroom,
+          room: classRow.room,
+          invitationCode: classRow.invitationCode ?? null,
+        },
+        studentCounts: { total: studentIds.length, active: activeStudentIds.length, inactive: inactiveStudentIds.length },
+        assignments: [],
+        latest: null,
+        overallScores: { count: 0, avg: null, median: null, min: null, max: null },
+      }
+    }
+
+    const maxScoreRows = await db
+      .select({
+        assignmentId: homeworkAssignmentQuestions.assignmentId,
+        maxScore: sql<number>`COALESCE(SUM(${homeworkAssignmentQuestions.score}), 0)`,
+      })
+      .from(homeworkAssignmentQuestions)
+      .where(inArray(homeworkAssignmentQuestions.assignmentId, usedAssignmentIds))
+      .groupBy(homeworkAssignmentQuestions.assignmentId)
+
+    const maxScoreByAssignmentId = new Map<string, number>()
+    for (const r of maxScoreRows) maxScoreByAssignmentId.set(r.assignmentId, Number(r.maxScore ?? 0))
+
+    const targetCountRows = await db
+      .select({
+        assignmentId: homeworkAssignmentTargets.assignmentId,
+        targetCount: sql<number>`COUNT(*)`,
+      })
+      .from(homeworkAssignmentTargets)
+      .where(
+        and(
+          inArray(homeworkAssignmentTargets.assignmentId, usedAssignmentIds),
+          inArray(homeworkAssignmentTargets.studentId, studentIds)
+        )
+      )
+      .groupBy(homeworkAssignmentTargets.assignmentId)
+
+    const targetCountByAssignmentId = new Map<string, number>()
+    for (const r of targetCountRows) targetCountByAssignmentId.set(r.assignmentId, Number(r.targetCount ?? 0))
+
+    const submissions = await db.query.homeworkSubmissions.findMany({
+      where: and(
+        inArray(homeworkSubmissions.assignmentId, usedAssignmentIds),
+        inArray(homeworkSubmissions.studentId, studentIds)
+      ),
+      orderBy: [desc(homeworkSubmissions.createdAt)],
+    })
+
+    const latestByKey = new Map<string, (typeof submissions)[number]>()
+    for (const s of submissions) {
+      const key = `${s.assignmentId}:${s.studentId}`
+      if (!latestByKey.has(key)) latestByKey.set(key, s)
+    }
+
+    const allScored: number[] = []
+    const nowMs = Date.now()
+
+    const stats: ClassHomeworkAssignmentStats[] = assignments.map((a) => {
+      const targetCount = targetCountByAssignmentId.get(a.id) ?? 0
+      let submittedCount = 0
+      let gradedCount = 0
+      const scores: number[] = []
+      const dueMs = a.dueAt ? a.dueAt.getTime() : null
+
+      for (const studentId of studentIds) {
+        const s = latestByKey.get(`${a.id}:${studentId}`)
+        if (!s) continue
+
+        const status = (s.status ?? "started") as string
+        if (status === "submitted" || status === "graded") submittedCount += 1
+        if (status === "graded" || typeof s.score === "number") gradedCount += 1
+        if (typeof s.score === "number") scores.push(s.score)
+      }
+
+      allScored.push(...scores)
+
+      return {
+        assignmentId: a.id,
+        title: a.title,
+        status: (a.status as string) ?? "draft",
+        subject: a.subjectName,
+        createdAt: a.createdAt.toISOString(),
+        dueAt: a.dueAt ? a.dueAt.toISOString() : null,
+        isActive: dueMs === null || dueMs >= nowMs,
+        isOverdue: typeof dueMs === "number" && dueMs < nowMs,
+        maxScore: maxScoreByAssignmentId.get(a.id) ?? 0,
+        targetCount,
+        submittedCount,
+        gradedCount,
+        scoreStats: toScoreStats(scores),
+      }
+    })
+
+    const overallScores = toScoreStats(allScored)
+    const latest = stats[0] ?? null
+
+    return {
+      class: {
+        id: classRow.id,
+        name: classRow.name,
+        grade: classRow.grade,
+        homeroom: classRow.homeroom,
+        room: classRow.room,
+        invitationCode: classRow.invitationCode ?? null,
+      },
+      studentCounts: { total: studentIds.length, active: activeStudentIds.length, inactive: inactiveStudentIds.length },
+      assignments: stats,
+      latest,
+      overallScores,
+    }
+  }
+)
+
+const avg = (values: number[]): number | null => {
+  if (values.length === 0) return null
+  const sum = values.reduce((acc, v) => acc + v, 0)
+  return sum / values.length
+}
+
+export const getGradeHomeworkInsights = cache(
+  async (params: { gradeId: string; limit?: number }): Promise<GradeHomeworkInsights | null> => {
+    const gradeId = params.gradeId.trim()
+    if (!gradeId) return null
+
+    const [gradeRow] = await db
+      .select({
+        id: grades.id,
+        name: grades.name,
+        schoolId: schools.id,
+        schoolName: schools.name,
+      })
+      .from(grades)
+      .innerJoin(schools, eq(schools.id, grades.schoolId))
+      .where(eq(grades.id, gradeId))
+      .limit(1)
+
+    if (!gradeRow) return null
+
+    const classRows = await db
+      .select({
+        id: classes.id,
+        name: classes.name,
+        grade: classes.grade,
+        homeroom: classes.homeroom,
+        room: classes.room,
+      })
+      .from(classes)
+      .where(eq(classes.gradeId, gradeId))
+      .orderBy(asc(classes.name), asc(classes.homeroom), asc(classes.room))
+
+    const classIds = classRows.map((r) => r.id)
+    if (classIds.length === 0) {
+      return {
+        grade: { id: gradeRow.id, name: gradeRow.name, school: { id: gradeRow.schoolId, name: gradeRow.schoolName } },
+        classCount: 0,
+        studentCounts: { total: 0, active: 0, inactive: 0 },
+        assignments: [],
+        latest: null,
+        overallScores: { count: 0, avg: null, median: null, min: null, max: null },
+        classes: [],
+      }
+    }
+
+    const enrollmentRows = await db
+      .select({
+        classId: classEnrollments.classId,
+        studentId: classEnrollments.studentId,
+        status: classEnrollments.status,
+      })
+      .from(classEnrollments)
+      .where(inArray(classEnrollments.classId, classIds))
+
+    const studentActiveById = new Map<string, boolean>()
+    const studentsByClassId = new Map<string, { all: Set<string>; active: Set<string> }>()
+
+    for (const e of enrollmentRows) {
+      const prev = studentActiveById.get(e.studentId) ?? false
+      const next = prev || e.status === "active"
+      studentActiveById.set(e.studentId, next)
+
+      const bucket = studentsByClassId.get(e.classId) ?? { all: new Set<string>(), active: new Set<string>() }
+      bucket.all.add(e.studentId)
+      if (e.status === "active") bucket.active.add(e.studentId)
+      studentsByClassId.set(e.classId, bucket)
+    }
+
+    const studentIds = Array.from(studentActiveById.keys())
+    const activeCount = Array.from(studentActiveById.values()).filter(Boolean).length
+    const inactiveCount = studentIds.length - activeCount
+
+    if (studentIds.length === 0) {
+      const summaries: GradeHomeworkClassSummary[] = classRows.map((c) => ({
+        class: { id: c.id, name: c.name, grade: c.grade, homeroom: c.homeroom, room: c.room },
+        studentCounts: { total: 0, active: 0, inactive: 0 },
+        latestAvg: null,
+        prevAvg: null,
+        deltaAvg: null,
+        overallScores: { count: 0, avg: null, median: null, min: null, max: null },
+      }))
+
+      return {
+        grade: { id: gradeRow.id, name: gradeRow.name, school: { id: gradeRow.schoolId, name: gradeRow.schoolName } },
+        classCount: classRows.length,
+        studentCounts: { total: 0, active: 0, inactive: 0 },
+        assignments: [],
+        latest: null,
+        overallScores: { count: 0, avg: null, median: null, min: null, max: null },
+        classes: summaries,
+      }
+    }
+
+    const assignmentIdRows = await db
+      .selectDistinct({ assignmentId: homeworkAssignmentTargets.assignmentId })
+      .from(homeworkAssignmentTargets)
+      .where(inArray(homeworkAssignmentTargets.studentId, studentIds))
+
+    const assignmentIds = assignmentIdRows.map((r) => r.assignmentId)
+    if (assignmentIds.length === 0) {
+      const summaries: GradeHomeworkClassSummary[] = classRows.map((c) => {
+        const bucket = studentsByClassId.get(c.id) ?? { all: new Set<string>(), active: new Set<string>() }
+        return {
+          class: { id: c.id, name: c.name, grade: c.grade, homeroom: c.homeroom, room: c.room },
+          studentCounts: { total: bucket.all.size, active: bucket.active.size, inactive: bucket.all.size - bucket.active.size },
+          latestAvg: null,
+          prevAvg: null,
+          deltaAvg: null,
+          overallScores: { count: 0, avg: null, median: null, min: null, max: null },
+        }
+      })
+
+      return {
+        grade: { id: gradeRow.id, name: gradeRow.name, school: { id: gradeRow.schoolId, name: gradeRow.schoolName } },
+        classCount: classRows.length,
+        studentCounts: { total: studentIds.length, active: activeCount, inactive: inactiveCount },
+        assignments: [],
+        latest: null,
+        overallScores: { count: 0, avg: null, median: null, min: null, max: null },
+        classes: summaries,
+      }
+    }
+
+    const limit = typeof params.limit === "number" && params.limit > 0 ? params.limit : 50
+    const assignments = await db.query.homeworkAssignments.findMany({
+      where: inArray(homeworkAssignments.id, assignmentIds),
+      orderBy: [desc(homeworkAssignments.createdAt)],
+      limit,
+    })
+
+    const usedAssignmentIds = assignments.map((a) => a.id)
+    if (usedAssignmentIds.length === 0) {
+      const summaries: GradeHomeworkClassSummary[] = classRows.map((c) => {
+        const bucket = studentsByClassId.get(c.id) ?? { all: new Set<string>(), active: new Set<string>() }
+        return {
+          class: { id: c.id, name: c.name, grade: c.grade, homeroom: c.homeroom, room: c.room },
+          studentCounts: { total: bucket.all.size, active: bucket.active.size, inactive: bucket.all.size - bucket.active.size },
+          latestAvg: null,
+          prevAvg: null,
+          deltaAvg: null,
+          overallScores: { count: 0, avg: null, median: null, min: null, max: null },
+        }
+      })
+
+      return {
+        grade: { id: gradeRow.id, name: gradeRow.name, school: { id: gradeRow.schoolId, name: gradeRow.schoolName } },
+        classCount: classRows.length,
+        studentCounts: { total: studentIds.length, active: activeCount, inactive: inactiveCount },
+        assignments: [],
+        latest: null,
+        overallScores: { count: 0, avg: null, median: null, min: null, max: null },
+        classes: summaries,
+      }
+    }
+
+    const maxScoreRows = await db
+      .select({
+        assignmentId: homeworkAssignmentQuestions.assignmentId,
+        maxScore: sql<number>`COALESCE(SUM(${homeworkAssignmentQuestions.score}), 0)`,
+      })
+      .from(homeworkAssignmentQuestions)
+      .where(inArray(homeworkAssignmentQuestions.assignmentId, usedAssignmentIds))
+      .groupBy(homeworkAssignmentQuestions.assignmentId)
+
+    const maxScoreByAssignmentId = new Map<string, number>()
+    for (const r of maxScoreRows) maxScoreByAssignmentId.set(r.assignmentId, Number(r.maxScore ?? 0))
+
+    const targetCountRows = await db
+      .select({
+        assignmentId: homeworkAssignmentTargets.assignmentId,
+        targetCount: sql<number>`COUNT(*)`,
+      })
+      .from(homeworkAssignmentTargets)
+      .where(
+        and(
+          inArray(homeworkAssignmentTargets.assignmentId, usedAssignmentIds),
+          inArray(homeworkAssignmentTargets.studentId, studentIds)
+        )
+      )
+      .groupBy(homeworkAssignmentTargets.assignmentId)
+
+    const targetCountByAssignmentId = new Map<string, number>()
+    for (const r of targetCountRows) targetCountByAssignmentId.set(r.assignmentId, Number(r.targetCount ?? 0))
+
+    const submissions = await db.query.homeworkSubmissions.findMany({
+      where: and(
+        inArray(homeworkSubmissions.assignmentId, usedAssignmentIds),
+        inArray(homeworkSubmissions.studentId, studentIds)
+      ),
+      orderBy: [desc(homeworkSubmissions.createdAt)],
+    })
+
+    const latestByKey = new Map<string, (typeof submissions)[number]>()
+    for (const s of submissions) {
+      const key = `${s.assignmentId}:${s.studentId}`
+      if (!latestByKey.has(key)) latestByKey.set(key, s)
+    }
+
+    const allScored: number[] = []
+    const nowMs = Date.now()
+
+    const stats: ClassHomeworkAssignmentStats[] = assignments.map((a) => {
+      const targetCount = targetCountByAssignmentId.get(a.id) ?? 0
+      let submittedCount = 0
+      let gradedCount = 0
+      const scores: number[] = []
+      const dueMs = a.dueAt ? a.dueAt.getTime() : null
+
+      for (const studentId of studentIds) {
+        const s = latestByKey.get(`${a.id}:${studentId}`)
+        if (!s) continue
+
+        const status = (s.status ?? "started") as string
+        if (status === "submitted" || status === "graded") submittedCount += 1
+        if (status === "graded" || typeof s.score === "number") gradedCount += 1
+        if (typeof s.score === "number") scores.push(s.score)
+      }
+
+      allScored.push(...scores)
+
+      return {
+        assignmentId: a.id,
+        title: a.title,
+        status: (a.status as string) ?? "draft",
+        createdAt: a.createdAt.toISOString(),
+        dueAt: a.dueAt ? a.dueAt.toISOString() : null,
+        isActive: dueMs === null || dueMs >= nowMs,
+        isOverdue: typeof dueMs === "number" && dueMs < nowMs,
+        maxScore: maxScoreByAssignmentId.get(a.id) ?? 0,
+        targetCount,
+        submittedCount,
+        gradedCount,
+        scoreStats: toScoreStats(scores),
+      }
+    })
+
+    const overallScores = toScoreStats(allScored)
+    const latest = stats[0] ?? null
+    const latestAssignmentId = stats[0]?.assignmentId ?? null
+    const prevAssignmentId = stats[1]?.assignmentId ?? null
+
+    const classSummaries: GradeHomeworkClassSummary[] = classRows.map((c) => {
+      const bucket = studentsByClassId.get(c.id) ?? { all: new Set<string>(), active: new Set<string>() }
+      const classStudentIds = Array.from(bucket.all)
+
+      const latestScores: number[] = []
+      const prevScores: number[] = []
+      const overallClassScores: number[] = []
+
+      if (latestAssignmentId) {
+        for (const studentId of classStudentIds) {
+          const s = latestByKey.get(`${latestAssignmentId}:${studentId}`)
+          if (typeof s?.score === "number") latestScores.push(s.score)
+        }
+      }
+
+      if (prevAssignmentId) {
+        for (const studentId of classStudentIds) {
+          const s = latestByKey.get(`${prevAssignmentId}:${studentId}`)
+          if (typeof s?.score === "number") prevScores.push(s.score)
+        }
+      }
+
+      for (const assignmentId of usedAssignmentIds) {
+        for (const studentId of classStudentIds) {
+          const s = latestByKey.get(`${assignmentId}:${studentId}`)
+          if (typeof s?.score === "number") overallClassScores.push(s.score)
+        }
+      }
+
+      const latestAvg = avg(latestScores)
+      const prevAvg = avg(prevScores)
+
+      return {
+        class: { id: c.id, name: c.name, grade: c.grade, homeroom: c.homeroom, room: c.room },
+        studentCounts: { total: bucket.all.size, active: bucket.active.size, inactive: bucket.all.size - bucket.active.size },
+        latestAvg,
+        prevAvg,
+        deltaAvg: typeof latestAvg === "number" && typeof prevAvg === "number" ? latestAvg - prevAvg : null,
+        overallScores: toScoreStats(overallClassScores),
+      }
+    })
+
+    classSummaries.sort((a, b) => (b.latestAvg ?? -Infinity) - (a.latestAvg ?? -Infinity))
+
+    return {
+      grade: { id: gradeRow.id, name: gradeRow.name, school: { id: gradeRow.schoolId, name: gradeRow.schoolName } },
+      classCount: classRows.length,
+      studentCounts: { total: studentIds.length, active: activeCount, inactive: inactiveCount },
+      assignments: stats,
+      latest,
+      overallScores,
+      classes: classSummaries,
+    }
+  }
+)
+
+export type ClassesDashboardStats = {
+  classCount: number
+}
+
+export const getClassesDashboardStats = cache(async (): Promise<ClassesDashboardStats> => {
+  const [row] = await db.select({ value: count() }).from(classes)
+  return { classCount: Number(row?.value ?? 0) }
+})

src/modules/classes/data-access-students.ts

@@ -0,0 +1,280 @@
+import "server-only";
+
+import { cache } from "react"
+import { and, asc, desc, eq, inArray, sql, type SQL } from "drizzle-orm"
+
+import { db } from "@/shared/db"
+import {
+  classes,
+  classEnrollments,
+  homeworkAssignmentTargets,
+  homeworkAssignments,
+  homeworkSubmissions,
+  subjects,
+  exams,
+  users,
+} from "@/shared/db/schema"
+import type {
+  ClassStudent,
+  StudentEnrolledClass,
+} from "./types"
+import {
+  compareClassLike,
+  getAccessibleClassIdsForTeacher,
+  getSessionTeacherId,
+  getTeacherSubjectIdsForClass,
+} from "./data-access"
+
+export const getStudentsSubjectScores = cache(
+  async (studentIds: string[]): Promise<Map<string, Record<string, number | null>>> => {
+    if (studentIds.length === 0) return new Map()
+
+    // 1. Find assignments targeted at these students
+    const assignmentTargets = await db
+      .select({ assignmentId: homeworkAssignmentTargets.assignmentId })
+      .from(homeworkAssignmentTargets)
+      .where(inArray(homeworkAssignmentTargets.studentId, studentIds))
+
+    const assignmentIds = Array.from(new Set(assignmentTargets.map(t => t.assignmentId)))
+    if (assignmentIds.length === 0) return new Map()
+
+    // 2. Get assignment details including subject from linked exam
+    const assignments = await db
+      .select({
+        id: homeworkAssignments.id,
+        createdAt: homeworkAssignments.createdAt,
+        subjectId: exams.subjectId,
+        subjectName: subjects.name
+      })
+      .from(homeworkAssignments)
+      .innerJoin(exams, eq(homeworkAssignments.sourceExamId, exams.id))
+      .leftJoin(subjects, eq(exams.subjectId, subjects.id))
+      .where(and(
+        inArray(homeworkAssignments.id, assignmentIds),
+        eq(homeworkAssignments.status, "published")
+      ))
+      .orderBy(desc(homeworkAssignments.createdAt))
+
+    // 3. Filter subjects (exclude PE, Music, Art)
+    const excludeSubjects = ["体育", "音乐", "美术"]
+    const subjectAssignments = new Map<string, string>() // subject -> assignmentId (latest)
+
+    for (const a of assignments) {
+      if (!a.subjectName) continue
+      if (excludeSubjects.includes(a.subjectName)) continue
+      if (!subjectAssignments.has(a.subjectName)) {
+        subjectAssignments.set(a.subjectName, a.id)
+      }
+    }
+
+    const targetAssignmentIds = Array.from(subjectAssignments.values())
+    if (targetAssignmentIds.length === 0) return new Map()
+
+    // 4. Get submissions for these assignments
+    const submissions = await db
+      .select({
+        studentId: homeworkSubmissions.studentId,
+        assignmentId: homeworkSubmissions.assignmentId,
+        score: homeworkSubmissions.score,
+        createdAt: homeworkSubmissions.createdAt,
+      })
+      .from(homeworkSubmissions)
+      .where(inArray(homeworkSubmissions.assignmentId, targetAssignmentIds))
+      .orderBy(desc(homeworkSubmissions.createdAt))
+
+    // 5. Map back to subject scores per student
+    const studentScores = new Map<string, Record<string, number | null>>()
+
+    // Create reverse map for assignment -> subject
+    const assignmentSubjectMap = new Map<string, string>()
+    for (const [subject, id] of subjectAssignments.entries()) {
+      assignmentSubjectMap.set(id, subject)
+    }
+
+    for (const s of submissions) {
+      const subject = assignmentSubjectMap.get(s.assignmentId)
+      if (!subject) continue
+
+      if (!studentScores.has(s.studentId)) {
+        studentScores.set(s.studentId, {})
+      }
+
+      const scores = studentScores.get(s.studentId)!
+      // Only set if not already set (since we ordered by desc createdAt, first one is latest)
+      if (scores[subject] === undefined) {
+        scores[subject] = s.score
+      }
+    }
+
+    return studentScores
+  }
+)
+
+export const getClassStudentSubjectScoresV2 = cache(
+  async (params: { classId: string; teacherId?: string }): Promise<Map<string, Record<string, number | null>>> => {
+    const teacherId = params.teacherId ?? (await getSessionTeacherId())
+    if (!teacherId) return new Map()
+    const classId = params.classId.trim()
+    if (!classId) return new Map()
+
+    const accessibleIds = await getAccessibleClassIdsForTeacher(teacherId)
+    if (accessibleIds.length === 0 || !accessibleIds.includes(classId)) return new Map()
+
+    const [classRow] = await db
+      .select({ id: classes.id, teacherId: classes.teacherId })
+      .from(classes)
+      .where(eq(classes.id, classId))
+      .limit(1)
+    if (!classRow) return new Map()
+
+    const isHomeroomTeacher = classRow.teacherId === teacherId
+    const subjectIds = isHomeroomTeacher ? [] : await getTeacherSubjectIdsForClass(teacherId, classId)
+    if (!isHomeroomTeacher && subjectIds.length === 0) return new Map()
+
+    const enrollments = await db
+      .select({ studentId: classEnrollments.studentId })
+      .from(classEnrollments)
+      .where(and(
+        eq(classEnrollments.classId, classId),
+        eq(classEnrollments.status, "active")
+      ))
+
+    const studentIds = enrollments.map((e) => e.studentId)
+    const studentScores = await getStudentsSubjectScores(studentIds)
+    if (subjectIds.length === 0) return studentScores
+
+    // Map subjectIds to names for filtering
+    const subjectRows = await db
+      .select({ id: subjects.id, name: subjects.name })
+      .from(subjects)
+      .where(inArray(subjects.id, subjectIds))
+    const allowed = new Set(subjectRows.map((s) => s.name))
+    const filtered = new Map<string, Record<string, number | null>>()
+    for (const [studentId, scores] of studentScores.entries()) {
+      const nextScores: Record<string, number | null> = {}
+      for (const [subject, score] of Object.entries(scores)) {
+        if (allowed.has(subject)) nextScores[subject] = score
+      }
+      filtered.set(studentId, nextScores)
+    }
+    return filtered
+  }
+)
+
+export const getStudentClasses = cache(async (studentId: string): Promise<StudentEnrolledClass[]> => {
+  const id = studentId.trim()
+  if (!id) return []
+
+  const rows = await (async () => {
+    try {
+      return await db
+        .select({
+          id: classes.id,
+          schoolName: classes.schoolName,
+          name: classes.name,
+          grade: classes.grade,
+          homeroom: classes.homeroom,
+          room: classes.room,
+          teacherName: users.name,
+          teacherEmail: users.email,
+        })
+        .from(classEnrollments)
+        .innerJoin(classes, eq(classes.id, classEnrollments.classId))
+        .leftJoin(users, eq(users.id, classes.teacherId))
+        .where(and(eq(classEnrollments.studentId, id), eq(classEnrollments.status, "active")))
+        .orderBy(asc(classes.schoolName), asc(classes.grade), asc(classes.name), asc(classes.homeroom), asc(classes.room))
+    } catch {
+      return await db
+        .select({
+          id: classes.id,
+          schoolName: sql<string | null>`NULL`.as("schoolName"),
+          name: classes.name,
+          grade: classes.grade,
+          homeroom: classes.homeroom,
+          room: classes.room,
+          teacherName: users.name,
+          teacherEmail: users.email,
+        })
+        .from(classEnrollments)
+        .innerJoin(classes, eq(classes.id, classEnrollments.classId))
+        .leftJoin(users, eq(users.id, classes.teacherId))
+        .where(and(eq(classEnrollments.studentId, id), eq(classEnrollments.status, "active")))
+        .orderBy(asc(classes.grade), asc(classes.name), asc(classes.homeroom), asc(classes.room))
+    }
+  })()
+
+  const list = rows.map((r) => ({
+    id: r.id,
+    schoolName: r.schoolName,
+    name: r.name,
+    grade: r.grade,
+    homeroom: r.homeroom,
+    room: r.room,
+    teacherName: r.teacherName,
+    teacherEmail: r.teacherEmail,
+  }))
+
+  list.sort(compareClassLike)
+  return list
+})
+
+export const getClassStudents = cache(
+  async (params?: { classId?: string; q?: string; status?: string; teacherId?: string }): Promise<ClassStudent[]> => {
+    const teacherId = params?.teacherId ?? (await getSessionTeacherId())
+    if (!teacherId) return []
+
+    const classId = params?.classId?.trim()
+    const q = params?.q?.trim().toLowerCase()
+    const status = params?.status?.trim().toLowerCase()
+
+    const accessibleIds = await getAccessibleClassIdsForTeacher(teacherId)
+    if (accessibleIds.length === 0) return []
+
+    const conditions: SQL[] = [inArray(classes.id, accessibleIds)]
+
+    if (classId) {
+      conditions.push(eq(classes.id, classId))
+    }
+
+    if (status === "active" || status === "inactive") {
+      conditions.push(eq(classEnrollments.status, status))
+    }
+
+    if (q && q.length > 0) {
+      const needle = `%${q}%`
+      conditions.push(
+        sql`(LOWER(COALESCE(${users.name}, '')) LIKE ${needle} OR LOWER(${users.email}) LIKE ${needle})`
+      )
+    }
+
+    const rows = await db
+      .select({
+        id: users.id,
+        name: users.name,
+        email: users.email,
+        image: users.image,
+        gender: users.gender,
+        classId: classes.id,
+        className: classes.name,
+        status: classEnrollments.status,
+        joinedAt: classEnrollments.createdAt,
+      })
+      .from(classEnrollments)
+      .innerJoin(classes, eq(classes.id, classEnrollments.classId))
+      .innerJoin(users, eq(users.id, classEnrollments.studentId))
+      .where(and(...conditions))
+      .orderBy(asc(users.name), asc(users.email))
+
+    return rows.map((r) => ({
+      id: r.id,
+      name: r.name ?? "Unnamed",
+      email: r.email,
+      image: r.image,
+      gender: r.gender,
+      classId: r.classId,
+      className: r.className,
+      status: r.status,
+      joinedAt: r.joinedAt,
+    }))
+  }
+)