feat(exams,homework,parent): V3 审计深度修复 — 批量批改/考试分析/提交反馈/家长视图/移动端优化

V3-5: exam-actions.tsx 集成 useExamHomeworkFeatures hook，按角色控制菜单项可见性 V3-7: 批量批改 — 新增 batchAutoGradeSubmissions data-access + Server Action + HomeworkBatchGradingView 组件 V3-8: 考试分析仪表盘 — 新增 getExamAnalytics stats-service + ExamAnalyticsDashboard 组件 + /teacher/exams/[id]/analytics 路由 V3-9: 提交后即时反馈页 — 新增 HomeworkSubmissionResult 组件 + /student/learning/assignments/[id]/result 路由 V3-11: 家长考试详情 — 新增 ChildExamDetail 组件 + getStudentExamResults data-access + child-detail-panel exams Tab V3-12: 移动端触控优化 — 题目导航与考试操作按钮 44px 最小触控目标修复: instrumentation.ts 适配器补全 questionCount/averageScore/overdueCount 字段修复: exam-homework-port.ts 类型导入对齐 ExamWithQuestionsForHomework 修复: trend-line-chart.tsx 数据类型允许 undefined（classAverage 可选场景）同步更新 004/005 架构文档
2026-06-23 01:06:27 +08:00
parent 21c5eba96c
commit a60105455e
23 changed files with 2407 additions and 263 deletions
--- a/src/modules/homework/data-access.ts
+++ b/src/modules/homework/data-access.ts
@@ -282,44 +282,44 @@ export const getHomeworkAssignmentReviewList = cache(async (params: { creatorId:

  const assignmentIds = assignments.map((a) => a.id)

-  const targetCountRows = await db
-    .select({
-      assignmentId: homeworkAssignmentTargets.assignmentId,
-      targetCount: sql<number>`COUNT(*)`,
-    })
-    .from(homeworkAssignmentTargets)
-    .where(inArray(homeworkAssignmentTargets.assignmentId, assignmentIds))
-    .groupBy(homeworkAssignmentTargets.assignmentId)
+  const [targetCountRows, submittedCountRows, gradedCountRows] = await Promise.all([
+    db
+      .select({
+        assignmentId: homeworkAssignmentTargets.assignmentId,
+        targetCount: sql<number>`COUNT(*)`,
+      })
+      .from(homeworkAssignmentTargets)
+      .where(inArray(homeworkAssignmentTargets.assignmentId, assignmentIds))
+      .groupBy(homeworkAssignmentTargets.assignmentId),
+    db
+      .select({
+        assignmentId: homeworkSubmissions.assignmentId,
+        submittedCount: sql<number>`COUNT(DISTINCT ${homeworkSubmissions.studentId})`,
+      })
+      .from(homeworkSubmissions)
+      .where(
+        and(
+          inArray(homeworkSubmissions.assignmentId, assignmentIds),
+          inArray(homeworkSubmissions.status, ["submitted", "graded"])
+        )
+      )
+      .groupBy(homeworkSubmissions.assignmentId),
+    db
+      .select({
+        assignmentId: homeworkSubmissions.assignmentId,
+        gradedCount: sql<number>`COUNT(DISTINCT ${homeworkSubmissions.studentId})`,
+      })
+      .from(homeworkSubmissions)
+      .where(and(inArray(homeworkSubmissions.assignmentId, assignmentIds), eq(homeworkSubmissions.status, "graded")))
+      .groupBy(homeworkSubmissions.assignmentId),
+  ])

  const targetCountByAssignmentId = new Map<string, number>()
  for (const r of targetCountRows) targetCountByAssignmentId.set(r.assignmentId, Number(r.targetCount ?? 0))

-  const submittedCountRows = await db
-    .select({
-      assignmentId: homeworkSubmissions.assignmentId,
-      submittedCount: sql<number>`COUNT(DISTINCT ${homeworkSubmissions.studentId})`,
-    })
-    .from(homeworkSubmissions)
-    .where(
-      and(
-        inArray(homeworkSubmissions.assignmentId, assignmentIds),
-        inArray(homeworkSubmissions.status, ["submitted", "graded"])
-      )
-    )
-    .groupBy(homeworkSubmissions.assignmentId)
-
  const submittedCountByAssignmentId = new Map<string, number>()
  for (const r of submittedCountRows) submittedCountByAssignmentId.set(r.assignmentId, Number(r.submittedCount ?? 0))

-  const gradedCountRows = await db
-    .select({
-      assignmentId: homeworkSubmissions.assignmentId,
-      gradedCount: sql<number>`COUNT(DISTINCT ${homeworkSubmissions.studentId})`,
-    })
-    .from(homeworkSubmissions)
-    .where(and(inArray(homeworkSubmissions.assignmentId, assignmentIds), eq(homeworkSubmissions.status, "graded")))
-    .groupBy(homeworkSubmissions.assignmentId)
-
  const gradedCountByAssignmentId = new Map<string, number>()
  for (const r of gradedCountRows) gradedCountByAssignmentId.set(r.assignmentId, Number(r.gradedCount ?? 0))

@@ -452,27 +452,26 @@ export const getHomeworkAssignmentById = cache(async (id: string, scope?: DataSc
    }
  }

-  const [targetsRow] = await db
-    .select({ c: count() })
-    .from(homeworkAssignmentTargets)
-    .where(eq(homeworkAssignmentTargets.assignmentId, id))
-
-  const [submissionsRow] = await db
-    .select({ c: count() })
-    .from(homeworkSubmissions)
-    .where(eq(homeworkSubmissions.assignmentId, id))
-
-  const [submittedRow] = await db
-    .select({ c: sql<number>`COUNT(DISTINCT ${homeworkSubmissions.studentId})` })
-    .from(homeworkSubmissions)
-    .where(
-      and(eq(homeworkSubmissions.assignmentId, id), inArray(homeworkSubmissions.status, ["submitted", "graded"]))
-    )
-
-  const [gradedRow] = await db
-    .select({ c: sql<number>`COUNT(DISTINCT ${homeworkSubmissions.studentId})` })
-    .from(homeworkSubmissions)
-    .where(and(eq(homeworkSubmissions.assignmentId, id), eq(homeworkSubmissions.status, "graded")))
+  const [targetsRows, submissionsRows, submittedRows, gradedRows] = await Promise.all([
+    db
+      .select({ c: count() })
+      .from(homeworkAssignmentTargets)
+      .where(eq(homeworkAssignmentTargets.assignmentId, id)),
+    db
+      .select({ c: count() })
+      .from(homeworkSubmissions)
+      .where(eq(homeworkSubmissions.assignmentId, id)),
+    db
+      .select({ c: sql<number>`COUNT(DISTINCT ${homeworkSubmissions.studentId})` })
+      .from(homeworkSubmissions)
+      .where(
+        and(eq(homeworkSubmissions.assignmentId, id), inArray(homeworkSubmissions.status, ["submitted", "graded"]))
+      ),
+    db
+      .select({ c: sql<number>`COUNT(DISTINCT ${homeworkSubmissions.studentId})` })
+      .from(homeworkSubmissions)
+      .where(and(eq(homeworkSubmissions.assignmentId, id), eq(homeworkSubmissions.status, "graded"))),
+  ])

  return {
    id: assignment.id,
@@ -487,15 +486,137 @@ export const getHomeworkAssignmentById = cache(async (id: string, scope?: DataSc
    allowLate: assignment.allowLate,
    lateDueAt: assignment.lateDueAt ? assignment.lateDueAt.toISOString() : null,
    maxAttempts: assignment.maxAttempts,
-    targetCount: targetsRow?.c ?? 0,
-    submissionCount: submissionsRow?.c ?? 0,
-    submittedCount: submittedRow?.c ?? 0,
-    gradedCount: gradedRow?.c ?? 0,
+    targetCount: targetsRows[0]?.c ?? 0,
+    submissionCount: submissionsRows[0]?.c ?? 0,
+    submittedCount: submittedRows[0]?.c ?? 0,
+    gradedCount: gradedRows[0]?.c ?? 0,
    createdAt: assignment.createdAt.toISOString(),
    updatedAt: assignment.updatedAt.toISOString(),
  }
 })

+/**
+ * V3-8: 获取关联到指定考试的所有作业（跨模块读接口）
+ *
+ * 供 exams 模块的考试分析仪表盘调用，获取该考试派生的所有作业及其提交统计。
+ */
+export const getHomeworkAssignmentsByExamId = cache(async (examId: string): Promise<Array<{
+  id: string
+  title: string
+  status: string | null
+  targetCount: number
+  submittedCount: number
+  gradedCount: number
+  dueAt: string | null
+}>> => {
+  const assignments = await db.query.homeworkAssignments.findMany({
+    where: eq(homeworkAssignments.sourceExamId, examId),
+    columns: { id: true, title: true, status: true, dueAt: true },
+  })
+
+  if (assignments.length === 0) return []
+
+  const assignmentIds = assignments.map((a) => a.id)
+
+  const [targetsRows, submittedRows, gradedRows] = await Promise.all([
+    db
+      .select({ assignmentId: homeworkAssignmentTargets.assignmentId, c: count() })
+      .from(homeworkAssignmentTargets)
+      .where(inArray(homeworkAssignmentTargets.assignmentId, assignmentIds))
+      .groupBy(homeworkAssignmentTargets.assignmentId),
+    db
+      .select({ assignmentId: homeworkSubmissions.assignmentId, c: sql<number>`COUNT(DISTINCT ${homeworkSubmissions.studentId})` })
+      .from(homeworkSubmissions)
+      .where(
+        and(
+          inArray(homeworkSubmissions.assignmentId, assignmentIds),
+          inArray(homeworkSubmissions.status, ["submitted", "graded"])
+        )
+      )
+      .groupBy(homeworkSubmissions.assignmentId),
+    db
+      .select({ assignmentId: homeworkSubmissions.assignmentId, c: sql<number>`COUNT(DISTINCT ${homeworkSubmissions.studentId})` })
+      .from(homeworkSubmissions)
+      .where(
+        and(
+          inArray(homeworkSubmissions.assignmentId, assignmentIds),
+          eq(homeworkSubmissions.status, "graded")
+        )
+      )
+      .groupBy(homeworkSubmissions.assignmentId),
+  ])
+
+  const targetMap = new Map(targetsRows.map((r) => [r.assignmentId, Number(r.c)]))
+  const submittedMap = new Map(submittedRows.map((r) => [r.assignmentId, Number(r.c)]))
+  const gradedMap = new Map(gradedRows.map((r) => [r.assignmentId, Number(r.c)]))
+
+  return assignments.map((a) => ({
+    id: a.id,
+    title: a.title,
+    status: a.status,
+    targetCount: targetMap.get(a.id) ?? 0,
+    submittedCount: submittedMap.get(a.id) ?? 0,
+    gradedCount: gradedMap.get(a.id) ?? 0,
+    dueAt: a.dueAt ? a.dueAt.toISOString() : null,
+  }))
+})
+
+/**
+ * V3-8: 获取指定考试所有作业的已批改提交（跨模块读接口）
+ *
+ * 供 exams 模块的考试分析仪表盘调用，获取学生姓名、分数、答案内容用于统计分析。
+ */
+export const getGradedSubmissionsByExamId = cache(async (examId: string): Promise<Array<{
+  submissionId: string
+  assignmentId: string
+  studentId: string
+  studentName: string
+  score: number
+  answers: Array<{ questionId: string; score: number; answerContent: unknown }>
+}>> => {
+  const assignments = await db.query.homeworkAssignments.findMany({
+    where: eq(homeworkAssignments.sourceExamId, examId),
+    columns: { id: true },
+  })
+
+  if (assignments.length === 0) return []
+
+  const assignmentIds = assignments.map((a) => a.id)
+
+  const submissions = await db.query.homeworkSubmissions.findMany({
+    where: and(
+      inArray(homeworkSubmissions.assignmentId, assignmentIds),
+      eq(homeworkSubmissions.status, "graded")
+    ),
+    with: {
+      student: true,
+      answers: {
+        columns: { questionId: true, score: true, answerContent: true },
+      },
+    },
+    orderBy: (s, { desc }) => [desc(s.updatedAt)],
+  })
+
+  // Deduplicate: keep only the latest submission per student
+  const latestByStudent = new Map<string, (typeof submissions)[number]>()
+  for (const s of submissions) {
+    if (!latestByStudent.has(s.studentId)) latestByStudent.set(s.studentId, s)
+  }
+
+  return Array.from(latestByStudent.values()).map((s) => ({
+    submissionId: s.id,
+    assignmentId: s.assignmentId,
+    studentId: s.studentId,
+    studentName: s.student.name || "Unknown",
+    score: s.score ?? 0,
+    answers: s.answers.map((a) => ({
+      questionId: a.questionId,
+      score: a.score ?? 0,
+      answerContent: a.answerContent,
+    })),
+  }))
+})
+
 export const getHomeworkSubmissionDetails = cache(async (submissionId: string): Promise<HomeworkSubmissionDetails | null> => {
  const submission = await db.query.homeworkSubmissions.findFirst({
    where: eq(homeworkSubmissions.id, submissionId),
@@ -507,17 +628,18 @@ export const getHomeworkSubmissionDetails = cache(async (submissionId: string):

  if (!submission) return null

-  const answers = await db.query.homeworkAnswers.findMany({
-    where: eq(homeworkAnswers.submissionId, submissionId),
-    with: {
-      question: true,
-    },
-  })
-
-  const assignmentQ = await db.query.homeworkAssignmentQuestions.findMany({
-    where: eq(homeworkAssignmentQuestions.assignmentId, submission.assignmentId),
-    orderBy: [desc(homeworkAssignmentQuestions.order)],
-  })
+  const [answers, assignmentQ] = await Promise.all([
+    db.query.homeworkAnswers.findMany({
+      where: eq(homeworkAnswers.submissionId, submissionId),
+      with: {
+        question: true,
+      },
+    }),
+    db.query.homeworkAssignmentQuestions.findMany({
+      where: eq(homeworkAssignmentQuestions.assignmentId, submission.assignmentId),
+      orderBy: [desc(homeworkAssignmentQuestions.order)],
+    }),
+  ])

  const answersWithDetails = answers
    .map((ans) => {
@@ -579,6 +701,89 @@ export const getHomeworkSubmissionDetails = cache(async (submissionId: string):
  }
 })

+/**
+ * V3-9: 获取学生在指定作业的最新提交结果（用于提交后反馈页）
+ *
+ * 查找学生最近一次已提交/已批改的 submission，返回完整详情含答案。
+ */
+export const getStudentSubmissionResult = cache(async (
+  assignmentId: string,
+  studentId: string
+): Promise<HomeworkSubmissionDetails | null> => {
+  const latestSubmission = await db.query.homeworkSubmissions.findFirst({
+    where: and(
+      eq(homeworkSubmissions.assignmentId, assignmentId),
+      eq(homeworkSubmissions.studentId, studentId),
+      inArray(homeworkSubmissions.status, ["submitted", "graded"])
+    ),
+    orderBy: [desc(homeworkSubmissions.updatedAt)],
+    columns: { id: true },
+  })
+
+  if (!latestSubmission) return null
+
+  return getHomeworkSubmissionDetails(latestSubmission.id)
+})
+
+/**
+ * V3-11: 获取学生的考试结果列表（供家长端展示）
+ *
+ * 查找学生所有已批改的、关联到考试的作业提交，
+ * 返回考试标题、科目、分数、提交时间等。
+ */
+export const getStudentExamResults = cache(async (studentId: string): Promise<Array<{
+  submissionId: string
+  examId: string
+  examTitle: string
+  assignmentId: string
+  assignmentTitle: string
+  score: number
+  maxScore: number
+  submittedAt: string | null
+  status: string
+}>> => {
+  const submissions = await db.query.homeworkSubmissions.findMany({
+    where: and(
+      eq(homeworkSubmissions.studentId, studentId),
+      eq(homeworkSubmissions.status, "graded")
+    ),
+    with: {
+      assignment: {
+        with: { sourceExam: true },
+      },
+    },
+    orderBy: [desc(homeworkSubmissions.updatedAt)],
+    limit: 50,
+  })
+
+  // Filter to only exam-linked submissions, deduplicate by examId
+  const latestByExamId = new Map<string, (typeof submissions)[number]>()
+  for (const s of submissions) {
+    const examId = s.assignment.sourceExamId
+    if (!examId) continue
+    if (!latestByExamId.has(examId)) latestByExamId.set(examId, s)
+  }
+
+  const examIds = Array.from(latestByExamId.keys())
+  if (examIds.length === 0) return []
+
+  // Get max scores for each assignment
+  const assignmentIds = Array.from(latestByExamId.values()).map((s) => s.assignmentId)
+  const maxScoreMap = await getAssignmentMaxScoreById(assignmentIds)
+
+  return Array.from(latestByExamId.entries()).map(([examId, s]) => ({
+    submissionId: s.id,
+    examId,
+    examTitle: s.assignment.sourceExam?.title ?? s.assignment.title,
+    assignmentId: s.assignmentId,
+    assignmentTitle: s.assignment.title,
+    score: s.score ?? 0,
+    maxScore: maxScoreMap.get(s.assignmentId) ?? 0,
+    submittedAt: s.submittedAt ? s.submittedAt.toISOString() : null,
+    status: s.status ?? "graded",
+  }))
+})
+
 const toStudentProgressStatus = (v: string | null | undefined): StudentHomeworkProgressStatus => {
  if (v === "started") return "in_progress"
  if (v === "submitted") return "submitted"