=test_update_homework_tests_and_work_log

src/modules/exams/actions.ts

@@ -5,9 +5,24 @@ import { ActionState } from "@/shared/types/action-state"
 import { z } from "zod"
 import { createId } from "@paralleldrive/cuid2"
 import { db } from "@/shared/db"
-import { exams, examQuestions, subjects, grades } from "@/shared/db/schema"
+import { exams, examQuestions } from "@/shared/db/schema"
 import { eq } from "drizzle-orm"
-import { omitScheduledAtFromDescription } from "./data-access"
+import { buildExamDescription, omitScheduledAtFromDescription, persistAiGeneratedExamDraft, persistExamDraft, resolveSubjectGradeNames } from "./data-access"
+import {
+  AiGeneratedStructureSchema,
+  AiInsertQuestionSchema,
+  AiQuestionSchema,
+  generateAiCreateDraftFromSource,
+  generateAiPreviewData,
+  regenerateAiQuestionByInstruction,
+} from "./ai-pipeline"
+import type {
+  AiGeneratedQuestion,
+  AiGeneratedStructureNode,
+  AiPreviewData,
+  AiRewriteQuestionData,
+} from "./ai-pipeline"
+export type { AiPreviewData, AiRewriteQuestionData } from "./ai-pipeline"
 
 const ExamCreateSchema = z.object({
   title: z.string().min(1),
@@ -27,6 +42,213 @@ const ExamCreateSchema = z.object({
     .optional(),
 })
 
+const getStringValue = (formData: FormData, key: string) => {
+  const value = formData.get(key)
+  return typeof value === "string" ? value : undefined
+}
+
+const failState = <T>(message: string, errors?: Record<string, string[]>): ActionState<T> => ({
+  success: false,
+  message,
+  errors,
+})
+
+const successState = <T>(data: T, message?: string): ActionState<T> => ({
+  success: true,
+  message,
+  data,
+})
+
+const invalidFormState = <T>(
+  error: z.ZodError,
+  options?: { fallbackMessage?: string; useFirstMessage?: boolean }
+): ActionState<T> => {
+  const errors = error.flatten().fieldErrors
+  const fallbackMessage = options?.fallbackMessage ?? "Invalid form data"
+  const useFirstMessage = options?.useFirstMessage ?? true
+  const messages = Object.values(errors).flatMap((items) => items ?? [])
+  const firstMessage = messages.find((msg): msg is string => typeof msg === "string" && msg.length > 0)
+  return failState<T>(useFirstMessage ? (firstMessage ?? fallbackMessage) : fallbackMessage, errors)
+}
+
+const prepareExamCreateContext = async (input: {
+  subject: string
+  grade: string
+  difficulty: number
+  totalScore: number
+  durationMin: number
+  scheduledAt?: string | null
+}) => {
+  const examId = createId()
+  const scheduled = input.scheduledAt || undefined
+  const resolvedNames = await resolveSubjectGradeNames({
+    subjectId: input.subject,
+    gradeId: input.grade,
+  })
+  const subjectName = resolvedNames.subjectName ?? input.subject
+  const gradeName = resolvedNames.gradeName ?? input.grade
+  const buildDescription = (options?: { questionCount?: number }) => buildExamDescription({
+    subject: subjectName,
+    grade: gradeName,
+    difficulty: input.difficulty,
+    totalScore: input.totalScore,
+    durationMin: input.durationMin,
+    scheduledAt: scheduled,
+    questionCount: options?.questionCount,
+  })
+  return { examId, scheduled, subjectName, gradeName, buildDescription }
+}
+
+const loadAiDraftQuestionsAndStructure = async (input: {
+  rawAiQuestions: string | null
+  rawStructure: string | null
+  title: string
+  subject: string
+  grade: string
+  difficulty: number
+  totalScore: number
+  durationMin: number
+  aiSourceText?: string
+  aiQuestionCount?: number
+  aiProviderId?: string
+}): Promise<
+  | { ok: true; generated: AiGeneratedQuestion[]; structure: AiGeneratedStructureNode[] }
+  | { ok: false; message: string }
+> => {
+  if (input.rawAiQuestions) {
+    let parsedQuestions: unknown = null
+    try {
+      parsedQuestions = JSON.parse(input.rawAiQuestions)
+    } catch {
+      return { ok: false, message: "Invalid AI preview payload" }
+    }
+    const validated = z.array(AiInsertQuestionSchema).safeParse(parsedQuestions)
+    if (!validated.success || validated.data.length === 0) {
+      return { ok: false, message: "Invalid AI preview payload" }
+    }
+    const generated = validated.data.map((q) => ({
+      id: q.id,
+      type: q.type,
+      difficulty: q.difficulty,
+      content: q.content,
+      score: q.score,
+    }))
+    let structure: AiGeneratedStructureNode[] = []
+    if (input.rawStructure) {
+      try {
+        const parsedStructure = JSON.parse(input.rawStructure)
+        const validatedStructure = AiGeneratedStructureSchema.safeParse(parsedStructure)
+        if (validatedStructure.success) {
+          structure = validatedStructure.data
+        } else {
+          return { ok: false, message: "Invalid preview structure" }
+        }
+      } catch {
+        return { ok: false, message: "Invalid preview structure" }
+      }
+    }
+    if (structure.length === 0) {
+      structure = generated.map((q) => ({
+        id: createId(),
+        type: "question",
+        questionId: q.id,
+        score: q.score,
+      }))
+    }
+    return { ok: true, generated, structure }
+  }
+
+  const sourceText = input.aiSourceText?.trim()
+  if (!sourceText) {
+    return { ok: false, message: "Please analyze and preview before creating" }
+  }
+  const aiDraft = await generateAiCreateDraftFromSource({
+    title: input.title,
+    subject: input.subject,
+    grade: input.grade,
+    difficulty: input.difficulty,
+    totalScore: input.totalScore,
+    durationMin: input.durationMin,
+    questionCount: input.aiQuestionCount,
+    sourceText,
+    aiProviderId: input.aiProviderId,
+  })
+  if (!aiDraft.ok) {
+    return { ok: false, message: aiDraft.message }
+  }
+  return { ok: true, generated: aiDraft.generated, structure: aiDraft.structure }
+}
+
+const prepareAiPreviewRequest = async (input: {
+  title?: string
+  subject?: string
+  grade?: string
+  difficulty?: number
+  totalScore?: number
+  durationMin?: number
+  aiSourceText: string
+  aiQuestionCount?: number
+  aiProviderId?: string
+}) => {
+  const resolvedNames = await resolveSubjectGradeNames({
+    subjectId: input.subject,
+    gradeId: input.grade,
+  })
+  const title = input.title && input.title.trim().length > 0 ? input.title : "AI Exam"
+  const subjectName = input.subject ? resolvedNames.subjectName ?? input.subject : undefined
+  const gradeName = input.grade ? resolvedNames.gradeName ?? input.grade : undefined
+  return {
+    title,
+    subject: subjectName,
+    grade: gradeName,
+    difficulty: input.difficulty ?? 3,
+    totalScore: input.totalScore ?? 100,
+    durationMin: input.durationMin ?? 90,
+    questionCount: input.aiQuestionCount,
+    sourceText: input.aiSourceText,
+    aiProviderId: input.aiProviderId,
+  }
+}
+
+const parseRegenerateAiQuestionInput = (
+  formData: FormData
+):
+  | {
+    ok: true
+    instruction: string
+    aiProviderId?: string
+    sourceText?: string
+    originalQuestion: z.infer<typeof AiQuestionSchema>
+  }
+  | { ok: false; state: ActionState<AiRewriteQuestionData> } => {
+  const instruction = getStringValue(formData, "instruction")?.trim()
+  const aiProviderId = getStringValue(formData, "aiProviderId")?.trim()
+  const sourceText = getStringValue(formData, "sourceText")?.trim()
+  const questionJson = getStringValue(formData, "questionJson")
+  if (!instruction) {
+    return { ok: false, state: failState<AiRewriteQuestionData>("Please enter rewrite instruction") }
+  }
+  if (!questionJson) {
+    return { ok: false, state: failState<AiRewriteQuestionData>("No selected question data") }
+  }
+  try {
+    const parsedQuestion = JSON.parse(questionJson) as unknown
+    const validatedQuestion = AiQuestionSchema.safeParse(parsedQuestion)
+    if (!validatedQuestion.success) {
+      return { ok: false, state: failState<AiRewriteQuestionData>("Selected question format invalid") }
+    }
+    return {
+      ok: true,
+      instruction,
+      aiProviderId,
+      sourceText,
+      originalQuestion: validatedQuestion.data,
+    }
+  } catch {
+    return { ok: false, state: failState<AiRewriteQuestionData>("Selected question format invalid") }
+  }
+}
+
 export async function createExamAction(
   prevState: ActionState<string> | null,
   formData: FormData
@@ -34,72 +256,235 @@ export async function createExamAction(
   const rawQuestions = formData.get("questionsJson") as string | null
 
   const parsed = ExamCreateSchema.safeParse({
-    title: formData.get("title"),
-    subject: formData.get("subject"),
-    grade: formData.get("grade"),
-    difficulty: formData.get("difficulty"),
-    totalScore: formData.get("totalScore"),
-    durationMin: formData.get("durationMin"),
-    scheduledAt: formData.get("scheduledAt"),
+    title: getStringValue(formData, "title"),
+    subject: getStringValue(formData, "subject"),
+    grade: getStringValue(formData, "grade"),
+    difficulty: getStringValue(formData, "difficulty"),
+    totalScore: getStringValue(formData, "totalScore"),
+    durationMin: getStringValue(formData, "durationMin"),
+    scheduledAt: getStringValue(formData, "scheduledAt") ?? null,
     questions: rawQuestions ? JSON.parse(rawQuestions) : [],
   })
 
   if (!parsed.success) {
-    return {
-      success: false,
-      message: "Invalid form data",
-      errors: parsed.error.flatten().fieldErrors,
-    }
+    return invalidFormState<string>(parsed.error, { useFirstMessage: false })
   }
 
   const input = parsed.data
-
-  const examId = createId()
-  const scheduled = input.scheduledAt || undefined
-
-  // Retrieve names for JSON description (to maintain compatibility)
-  const subjectRecord = await db.query.subjects.findFirst({
-    where: eq(subjects.id, input.subject),
-  })
-  const gradeRecord = await db.query.grades.findFirst({
-    where: eq(grades.id, input.grade),
-  })
-
-  const meta = {
-    subject: subjectRecord?.name ?? input.subject,
-    grade: gradeRecord?.name ?? input.grade,
+  const context = await prepareExamCreateContext({
+    subject: input.subject,
+    grade: input.grade,
     difficulty: input.difficulty,
     totalScore: input.totalScore,
     durationMin: input.durationMin,
-    scheduledAt: scheduled ?? undefined,
-  }
+    scheduledAt: input.scheduledAt,
+  })
+  const description = context.buildDescription()
 
   try {
     const user = await getCurrentUser()
-    await db.insert(exams).values({
-      id: examId,
+    await persistExamDraft({
+      examId: context.examId,
       title: input.title,
-      description: JSON.stringify(meta),
       creatorId: user?.id ?? "user_teacher_math",
       subjectId: input.subject,
       gradeId: input.grade,
-      startTime: scheduled ? new Date(scheduled) : null,
-      status: "draft",
+      scheduledAt: context.scheduled,
+      description,
     })
   } catch (error) {
     console.error("Failed to create exam:", error)
-    return {
-      success: false,
-      message: "Database error: Failed to create exam",
-    }
+    return failState<string>("Database error: Failed to create exam")
   }
 
   revalidatePath("/teacher/exams/all")
 
-  return {
-    success: true,
-    message: "Exam created successfully.",
-    data: examId,
+  return successState(context.examId, "Exam created successfully.")
+}
+
+const AiExamCreateSchema = ExamCreateSchema.extend({
+  aiSourceText: z.string().optional(),
+  aiQuestionCount: z.coerce.number().int().min(1).max(200).optional(),
+  aiProviderId: z.string().min(1).optional(),
+})
+
+const AiExamPreviewSchema = z.object({
+  title: z.string().optional(),
+  subject: z.string().optional(),
+  grade: z.string().optional(),
+  difficulty: z.coerce.number().int().min(1).max(5).optional(),
+  totalScore: z.coerce.number().int().min(1).optional(),
+  durationMin: z.coerce.number().int().min(1).optional(),
+  aiSourceText: z.string().min(1),
+  aiQuestionCount: z.coerce.number().int().min(1).max(200).optional(),
+  aiProviderId: z.string().min(1).optional(),
+})
+
+export async function createAiExamAction(
+  prevState: ActionState<string> | null,
+  formData: FormData
+): Promise<ActionState<string>> {
+  const rawQuestions = formData.get("questionsJson") as string | null
+  const rawAiQuestions = formData.get("aiQuestionsJson") as string | null
+  const rawStructure = formData.get("structureJson") as string | null
+  const aiSourceTextRaw = formData.get("aiSourceText")
+  const aiQuestionCountRaw = formData.get("aiQuestionCount")
+  const aiProviderIdRaw = formData.get("aiProviderId")
+
+  const parsed = AiExamCreateSchema.safeParse({
+    title: getStringValue(formData, "title"),
+    subject: getStringValue(formData, "subject"),
+    grade: getStringValue(formData, "grade"),
+    difficulty: getStringValue(formData, "difficulty"),
+    totalScore: getStringValue(formData, "totalScore"),
+    durationMin: getStringValue(formData, "durationMin"),
+    scheduledAt: getStringValue(formData, "scheduledAt") ?? null,
+    questions: rawQuestions ? JSON.parse(rawQuestions) : [],
+    aiSourceText: typeof aiSourceTextRaw === "string" ? aiSourceTextRaw.trim() : undefined,
+    aiQuestionCount: typeof aiQuestionCountRaw === "string" && aiQuestionCountRaw.trim().length > 0
+      ? aiQuestionCountRaw
+      : undefined,
+    aiProviderId: typeof aiProviderIdRaw === "string" && aiProviderIdRaw.trim().length > 0
+      ? aiProviderIdRaw
+      : undefined,
+  })
+
+  if (!parsed.success) {
+    return invalidFormState<string>(parsed.error)
+  }
+
+  const input = parsed.data
+  if (!rawAiQuestions && !input.aiSourceText) {
+    return failState<string>("Please analyze and preview before creating")
+  }
+  const context = await prepareExamCreateContext({
+    subject: input.subject,
+    grade: input.grade,
+    difficulty: input.difficulty,
+    totalScore: input.totalScore,
+    durationMin: input.durationMin,
+    scheduledAt: input.scheduledAt,
+  })
+
+  const user = await getCurrentUser()
+  const aiDraftResult = await loadAiDraftQuestionsAndStructure({
+    rawAiQuestions,
+    rawStructure,
+    title: input.title,
+    subject: context.subjectName,
+    grade: context.gradeName,
+    difficulty: input.difficulty,
+    totalScore: input.totalScore,
+    durationMin: input.durationMin,
+    aiSourceText: input.aiSourceText,
+    aiQuestionCount: input.aiQuestionCount,
+    aiProviderId: input.aiProviderId,
+  })
+  if (!aiDraftResult.ok) {
+    return failState<string>(aiDraftResult.message)
+  }
+  const { generated, structure } = aiDraftResult
+
+  const questionCount = generated.length
+  const description = context.buildDescription({ questionCount })
+
+  try {
+    await persistAiGeneratedExamDraft({
+      examId: context.examId,
+      title: input.title,
+      creatorId: user?.id ?? "user_teacher_math",
+      subjectId: input.subject,
+      gradeId: input.grade,
+      scheduledAt: context.scheduled,
+      description,
+      structure,
+      generated,
+    })
+  } catch (error) {
+    console.error("Failed to create exam:", error)
+    return failState<string>("Database error: Failed to create exam")
+  }
+
+  revalidatePath("/teacher/exams/all")
+
+  return successState(context.examId, "Exam created successfully.")
+}
+
+export async function previewAiExamAction(
+  prevState: ActionState<AiPreviewData> | null,
+  formData: FormData
+): Promise<ActionState<AiPreviewData>> {
+  const aiSourceTextRaw = formData.get("aiSourceText")
+  const aiQuestionCountRaw = formData.get("aiQuestionCount")
+  const aiProviderIdRaw = formData.get("aiProviderId")
+
+  const sourceText = typeof aiSourceTextRaw === "string" ? aiSourceTextRaw.trim() : ""
+  if (!sourceText) {
+    return failState<AiPreviewData>("Please paste the full exam text first", {
+      aiSourceText: ["Please paste the full exam text first"],
+    })
+  }
+
+  const parsed = AiExamPreviewSchema.safeParse({
+    title: getStringValue(formData, "title"),
+    subject: getStringValue(formData, "subject"),
+    grade: getStringValue(formData, "grade"),
+    difficulty: getStringValue(formData, "difficulty"),
+    totalScore: getStringValue(formData, "totalScore"),
+    durationMin: getStringValue(formData, "durationMin"),
+    aiSourceText: sourceText,
+    aiQuestionCount: typeof aiQuestionCountRaw === "string" && aiQuestionCountRaw.trim().length > 0
+      ? aiQuestionCountRaw
+      : undefined,
+    aiProviderId: typeof aiProviderIdRaw === "string" && aiProviderIdRaw.trim().length > 0
+      ? aiProviderIdRaw
+      : undefined,
+  })
+
+  if (!parsed.success) {
+    return invalidFormState<AiPreviewData>(parsed.error)
+  }
+
+  const input = parsed.data
+  const previewRequest = await prepareAiPreviewRequest(input)
+  const aiDraft = await generateAiPreviewData(previewRequest)
+  if (!aiDraft.ok) {
+    return failState<AiPreviewData>(aiDraft.message)
+  }
+  return successState({ ...aiDraft.data, rawOutput: aiDraft.rawOutput })
+}
+
+export async function regenerateAiQuestionAction(
+  prevState: ActionState<AiRewriteQuestionData> | null,
+  formData: FormData
+): Promise<ActionState<AiRewriteQuestionData>> {
+  const parsedInput = parseRegenerateAiQuestionInput(formData)
+  if (!parsedInput.ok) {
+    return parsedInput.state
+  }
+  const { instruction, aiProviderId, sourceText, originalQuestion } = parsedInput
+
+  const originalDifficulty = originalQuestion.difficulty ?? 3
+  const originalScore = originalQuestion.score ?? 0
+
+  try {
+    const result = await regenerateAiQuestionByInstruction({
+      instruction,
+      originalQuestion,
+      sourceText,
+      aiProviderId,
+    })
+    if (!result.ok) {
+      return failState<AiRewriteQuestionData>(result.message)
+    }
+    return successState({
+      type: result.data.type,
+      difficulty: result.data.difficulty ?? originalDifficulty,
+      score: result.data.score ?? originalScore,
+      content: result.data.content,
+    })
+  } catch {
+    return failState<AiRewriteQuestionData>("AI question format invalid")
   }
 }
 
@@ -134,11 +519,10 @@ export async function updateExamAction(
   })
 
   if (!parsed.success) {
-    return {
-      success: false,
-      message: "Invalid update data",
-      errors: parsed.error.flatten().fieldErrors,
-    }
+    return invalidFormState<string>(parsed.error, {
+      fallbackMessage: "Invalid update data",
+      useFirstMessage: false,
+    })
   }
 
   const { examId, questions, structure, status } = parsed.data
@@ -168,19 +552,12 @@ export async function updateExamAction(
     }
     
   } catch {
-    return {
-      success: false,
-      message: "Database error: Failed to update exam",
-    }
+    return failState<string>("Database error: Failed to update exam")
   }
 
   revalidatePath("/teacher/exams/all")
 
-  return {
-    success: true,
-    message: "Exam updated",
-    data: examId,
-  }
+  return successState(examId, "Exam updated")
 }
 
 const ExamDeleteSchema = z.object({
@@ -196,11 +573,10 @@ export async function deleteExamAction(
   })
 
   if (!parsed.success) {
-    return {
-      success: false,
-      message: "Invalid delete data",
-      errors: parsed.error.flatten().fieldErrors,
-    }
+    return invalidFormState<string>(parsed.error, {
+      fallbackMessage: "Invalid delete data",
+      useFirstMessage: false,
+    })
   }
 
   const { examId } = parsed.data
@@ -208,19 +584,12 @@ export async function deleteExamAction(
   try {
     await db.delete(exams).where(eq(exams.id, examId))
   } catch {
-    return {
-      success: false,
-      message: "Database error: Failed to delete exam",
-    }
+    return failState<string>("Database error: Failed to delete exam")
   }
 
   revalidatePath("/teacher/exams/all")
 
-  return {
-    success: true,
-    message: "Exam deleted",
-    data: examId,
-  }
+  return successState(examId, "Exam deleted")
 }
 
 const ExamDuplicateSchema = z.object({
@@ -236,11 +605,10 @@ export async function duplicateExamAction(
   })
 
   if (!parsed.success) {
-    return {
-      success: false,
-      message: "Invalid duplicate data",
-      errors: parsed.error.flatten().fieldErrors,
-    }
+    return invalidFormState<string>(parsed.error, {
+      fallbackMessage: "Invalid duplicate data",
+      useFirstMessage: false,
+    })
   }
 
   const { examId } = parsed.data
@@ -255,10 +623,7 @@ export async function duplicateExamAction(
   })
 
   if (!source) {
-    return {
-      success: false,
-      message: "Exam not found",
-    }
+    return failState<string>("Exam not found")
   }
 
   const newExamId = createId()
@@ -289,22 +654,17 @@ export async function duplicateExamAction(
       }
     })
   } catch {
-    return {
-      success: false,
-      message: "Database error: Failed to duplicate exam",
-    }
+    return failState<string>("Database error: Failed to duplicate exam")
   }
 
   revalidatePath("/teacher/exams/all")
 
-  return {
-    success: true,
-    message: "Exam duplicated",
-    data: newExamId,
-  }
+  return successState(newExamId, "Exam duplicated")
 }
 
-export async function getExamPreviewAction(examId: string) {
+export async function getExamPreviewAction(
+  examId: string
+): Promise<ActionState<{ structure: unknown; questions: Array<{ id: string }> }>> {
   try {
     const exam = await db.query.exams.findFirst({
       where: eq(exams.id, examId),
@@ -319,23 +679,17 @@ export async function getExamPreviewAction(examId: string) {
     })
 
     if (!exam) {
-      return { success: false, message: "Exam not found" }
+      return failState<{ structure: unknown; questions: Array<{ id: string }> }>("Exam not found")
     }
-
-    // Extract questions from the relation
-    const questions = exam.questions.map(eq => eq.question)
-
-    return {
-    success: true,
-    data: {
+    const questions = exam.questions.map((eq) => eq.question)
+    return successState({
       structure: exam.structure,
-      questions: questions
-    }
+      questions,
+    })
+  } catch (error) {
+    console.error(error)
+    return failState<{ structure: unknown; questions: Array<{ id: string }> }>("Failed to load exam preview")
   }
-} catch (error) {
-  console.error(error)
-  return { success: false, message: "Failed to load exam preview" }
-}
 }
 
 export async function getSubjectsAction(): Promise<ActionState<{ id: string; name: string }[]>> {
@@ -344,16 +698,10 @@ export async function getSubjectsAction(): Promise<ActionState<{ id: string; nam
       orderBy: (subjects, { asc }) => [asc(subjects.order), asc(subjects.name)],
     })
 
-    return {
-      success: true,
-      data: allSubjects.map((s) => ({ id: s.id, name: s.name })),
-    }
+    return successState(allSubjects.map((s) => ({ id: s.id, name: s.name })))
   } catch (error) {
     console.error("Failed to fetch subjects:", error)
-    return {
-      success: false,
-      message: "Failed to load subjects",
-    }
+    return failState<{ id: string; name: string }[]>("Failed to load subjects")
   }
 }
 
@@ -363,16 +711,10 @@ export async function getGradesAction(): Promise<ActionState<{ id: string; name:
       orderBy: (grades, { asc }) => [asc(grades.order), asc(grades.name)],
     })
 
-    return {
-      success: true,
-      data: allGrades.map((g) => ({ id: g.id, name: g.name })),
-    }
+    return successState(allGrades.map((g) => ({ id: g.id, name: g.name })))
   } catch (error) {
     console.error("Failed to fetch grades:", error)
-    return {
-      success: false,
-      message: "Failed to load grades",
-    }
+    return failState<{ id: string; name: string }[]>("Failed to load grades")
   }
 }
 

src/modules/exams/ai-pipeline.ts

@@ -0,0 +1,912 @@
+import { createId } from "@paralleldrive/cuid2"
+import { z } from "zod"
+import { createAiChatCompletion, getAiErrorMessage } from "@/shared/lib/ai"
+import { env } from "@/env.mjs"
+
+const AiSubQuestionSchema = z.object({
+  id: z.string().min(1).optional(),
+  text: z.string().min(1),
+  answer: z.string().min(1).optional(),
+  score: z.coerce.number().int().min(0).optional(),
+})
+
+const AiQuestionContentSchema = z.object({
+  text: z.string().min(1),
+  options: z
+    .array(
+      z.object({
+        id: z.string().min(1).optional(),
+        text: z.string().min(1),
+        isCorrect: z.boolean().optional(),
+      })
+    )
+    .optional(),
+  subQuestions: z.array(AiSubQuestionSchema).optional(),
+})
+
+export const AiQuestionSchema = z.object({
+  type: z.enum(["single_choice", "multiple_choice", "text", "judgment"]),
+  difficulty: z.coerce.number().int().min(1).max(5).optional(),
+  score: z.coerce.number().int().min(0).optional(),
+  content: AiQuestionContentSchema,
+})
+
+export const AiInsertQuestionSchema = z.object({
+  id: z.string().min(1),
+  type: z.enum(["single_choice", "multiple_choice", "text", "judgment"]),
+  difficulty: z.coerce.number().int().min(1).max(5),
+  score: z.coerce.number().int().min(0),
+  content: AiQuestionContentSchema.extend({
+    options: z
+      .array(
+        z.object({
+          id: z.string().min(1),
+          text: z.string().min(1),
+          isCorrect: z.boolean().optional(),
+        })
+      )
+      .optional(),
+    subQuestions: z.array(
+      AiSubQuestionSchema.extend({
+        id: z.string().min(1),
+      })
+    ).optional(),
+  }),
+})
+
+const AiSectionSchema = z.object({
+  title: z.string().min(1),
+  questions: z.array(AiQuestionSchema).min(1),
+})
+
+const AiExamResponseSchema = z.object({
+  title: z.string().optional(),
+  questions: z.array(AiQuestionSchema).optional(),
+  sections: z.array(AiSectionSchema).optional(),
+})
+
+const sanitizeJsonCandidate = (value: string) => value
+  .replace(/\[\s*\.\.\.\s*\]/g, "[]")
+  .replace(/\{\s*\.\.\.\s*\}/g, "{}")
+  .trim()
+
+const tryParseJson = (value: string): unknown | null => {
+  const sanitized = sanitizeJsonCandidate(value)
+  if (!sanitized) return null
+  try {
+    return JSON.parse(sanitized)
+  } catch {
+    return null
+  }
+}
+
+const extractBalancedJsonSegment = (value: string): string | null => {
+  const startBrace = value.indexOf("{")
+  const startBracket = value.indexOf("[")
+  const start =
+    startBrace === -1
+      ? startBracket
+      : startBracket === -1
+        ? startBrace
+        : Math.min(startBrace, startBracket)
+  if (start === -1) return null
+  const opening = value[start]
+  const closing = opening === "{" ? "}" : "]"
+  let depth = 0
+  let inString = false
+  let escaped = false
+  for (let i = start; i < value.length; i += 1) {
+    const char = value[i]
+    if (inString) {
+      if (escaped) {
+        escaped = false
+      } else if (char === "\\") {
+        escaped = true
+      } else if (char === "\"") {
+        inString = false
+      }
+      continue
+    }
+    if (char === "\"") {
+      inString = true
+      continue
+    }
+    if (char === opening) {
+      depth += 1
+      continue
+    }
+    if (char === closing) {
+      depth -= 1
+      if (depth === 0) {
+        return value.slice(start, i + 1)
+      }
+    }
+  }
+  return null
+}
+
+const extractJson = (raw: string): unknown => {
+  const trimmed = raw.trim()
+  const candidates: string[] = []
+  const fencedMatches = [...trimmed.matchAll(/```(?:json)?\s*([\s\S]*?)```/ig)]
+  if (fencedMatches.length > 0) {
+    candidates.push(...fencedMatches.map((match) => (match[1] ?? "").trim()))
+  }
+  candidates.push(trimmed)
+  for (const candidate of candidates) {
+    const direct = tryParseJson(candidate)
+    if (direct !== null) return direct
+    const segment = extractBalancedJsonSegment(candidate)
+    if (!segment) continue
+    const parsed = tryParseJson(segment)
+    if (parsed !== null) return parsed
+  }
+  throw new Error("Invalid AI response")
+}
+
+const AI_JSON_REPAIR_PROMPT = [
+  "You are a JSON repair engine.",
+  "Fix the provided invalid JSON into valid JSON only.",
+  "Keep the original structure and values as much as possible.",
+  "Do not use placeholders such as ... or [...].",
+  "Return JSON only without markdown.",
+].join("\n")
+
+const repairJson = async (raw: string, providerId?: string) => {
+  const aiResult = await createAiChatCompletion({
+    model: String(env.AI_MODEL ?? "gpt-4o-mini"),
+    providerId,
+    messages: [
+      { role: "system" as const, content: AI_JSON_REPAIR_PROMPT },
+      { role: "user" as const, content: raw },
+    ],
+    temperature: 0,
+    maxTokens: 4000,
+  })
+  return extractJson(aiResult.content)
+}
+
+const parseAiResponse = async (raw: string, providerId?: string) => {
+  try {
+    return extractJson(raw)
+  } catch {
+    return repairJson(raw, providerId)
+  }
+}
+
+const normalizeScores = (scores: number[], totalScore: number) => {
+  if (scores.length === 0) return []
+  const sum = scores.reduce((acc, s) => acc + s, 0)
+  if (sum <= 0) {
+    const base = Math.floor(totalScore / scores.length)
+    const remainder = totalScore - base * scores.length
+    return scores.map((_, idx) => base + (idx < remainder ? 1 : 0))
+  }
+  const scaled = scores.map((s) => Math.max(0, Math.round((s / sum) * totalScore)))
+  let diff = totalScore - scaled.reduce((acc, s) => acc + s, 0)
+  let i = 0
+  while (diff !== 0 && i < scaled.length * 2) {
+    const idx = i % scaled.length
+    if (diff > 0) {
+      scaled[idx] += 1
+      diff -= 1
+    } else if (scaled[idx] > 0) {
+      scaled[idx] -= 1
+      diff += 1
+    }
+    i += 1
+  }
+  return scaled
+}
+
+const AI_EXAM_SYSTEM_PROMPT = [
+  "You are an exam parsing engine.",
+  "Parse the provided exam text and output JSON only.",
+  "Allowed question types: single_choice, multiple_choice, judgment, text.",
+  "Preserve the original order and sectioning if present.",
+  "Escape double quotes inside string values.",
+  "Output schema:",
+  "{",
+  '  "sections": [',
+  '    { "title": "Section Title", "questions": [',
+  '      { "type": "single_choice", "difficulty": 1, "score": 5, "content": { "text": "...", "options": [ { "id": "A", "text": "...", "isCorrect": true } ] } }',
+  "    ] }",
+  "  ]",
+  "}",
+  "For grouped blanks or one prompt with multiple small questions, keep one parent question and place each child item into content.subQuestions.",
+  'content.subQuestions item schema: { "id": "1", "text": "lǎn duò（ ）", "answer": "懒惰", "score": 1 }',
+  "If you do not need sections, return { \"questions\": [] } or include real question items.",
+  "Never output placeholders like ..., [...], or {...}.",
+  "Return JSON only without markdown.",
+].join("\n")
+
+const AI_REWRITE_QUESTION_SYSTEM_PROMPT = [
+  "You are a question rewriting engine.",
+  "Rewrite exactly one question based on teacher instruction.",
+  "Return JSON only without markdown.",
+  "Allowed question types: single_choice, multiple_choice, judgment, text.",
+  "Output schema:",
+  "{",
+  '  "type": "single_choice | multiple_choice | judgment | text",',
+  '  "difficulty": 1,',
+  '  "score": 5,',
+  '  "content": { "text": "...", "options": [ { "id": "A", "text": "...", "isCorrect": true } ], "subQuestions": [ { "id": "1", "text": "...", "answer": "...", "score": 1 } ] }',
+  "}",
+  "For judgment/text, options can be omitted. Keep subQuestions when original question has multiple child items.",
+  "Never output placeholders like ..., [...], or {...}.",
+].join("\n")
+
+const AiStructureQuestionSchema = z.object({
+  text: z.string().min(1),
+  score: z.coerce.number().int().min(0).optional(),
+})
+
+const AiStructureSectionSchema = z.object({
+  title: z.string().min(1),
+  questions: z.array(AiStructureQuestionSchema).min(1),
+})
+
+const AiStructureResponseSchema = z.object({
+  title: z.string().optional(),
+  sections: z.array(AiStructureSectionSchema).optional(),
+  questions: z.array(AiStructureQuestionSchema).optional(),
+})
+
+const AiSourceValidationSchema = z.object({
+  valid: z.boolean(),
+  reason: z.string().optional(),
+})
+
+const AI_EXAM_STRUCTURE_SYSTEM_PROMPT = [
+  "You are an exam splitter engine.",
+  "Split the provided exam text into ordered question units quickly.",
+  "Do not deeply analyze choices or answers in this step.",
+  "Keep original sectioning and question order.",
+  "If one stem contains multiple numbered sub-items, keep them in one question unit and include all sub-items in the same text.",
+  "Do not split one parent question into several child-only units.",
+  "Output JSON only.",
+  "Output schema:",
+  "{",
+  '  "title": "Optional title",',
+  '  "sections": [',
+  '    { "title": "Section Title", "questions": [',
+  '      { "text": "Original full question text", "score": 5 }',
+  "    ] }",
+  "  ]",
+  "}",
+  "If no sections, return:",
+  '{ "questions": [ { "text": "Original full question text", "score": 5 } ] }',
+  "Never output placeholders like ..., [...], or {...}.",
+].join("\n")
+
+const AI_EXAM_SOURCE_VALIDATION_SYSTEM_PROMPT = [
+  "You are an exam text validator.",
+  "Judge whether the input text is readable and likely a normal exam/question text.",
+  "Reject garbled text, random symbols, severely disordered fragments, or meaningless content.",
+  "Do not require strict section formatting. Focus only on readability and whether it resembles exam questions.",
+  "Return JSON only without markdown.",
+  "Output schema:",
+  '{ "valid": true, "reason": "short reason" }',
+].join("\n")
+
+const AI_QUESTION_DETAIL_SYSTEM_PROMPT = [
+  "You are an exam question detail parser.",
+  "Given one split question text, output one structured question JSON only.",
+  "Allowed question types: single_choice, multiple_choice, judgment, text.",
+  "For one stem with multiple child sub-items, keep one parent content.text and place child items in content.subQuestions.",
+  "Use exact key name content.subQuestions (camelCase).",
+  "Output schema:",
+  "{",
+  '  "type": "single_choice | multiple_choice | judgment | text",',
+  '  "difficulty": 1,',
+  '  "score": 5,',
+  '  "content": { "text": "...", "options": [ { "id": "A", "text": "...", "isCorrect": true } ], "subQuestions": [ { "id": "1", "text": "...", "answer": "...", "score": 1 } ] }',
+  "}",
+  "For judgment/text, options can be omitted.",
+  "Never output placeholders like ..., [...], or {...}.",
+].join("\n")
+
+const buildAiMessages = (input: {
+  title?: string
+  subject?: string
+  grade?: string
+  difficulty?: number
+  totalScore?: number
+  durationMin?: number
+  questionCount?: number
+  sourceText: string
+}) => {
+  const userLines = [
+    input.title ? `Title: ${input.title}` : "",
+    input.subject ? `Subject: ${input.subject}` : "",
+    input.grade ? `Grade: ${input.grade}` : "",
+    typeof input.difficulty === "number" ? `Difficulty: ${input.difficulty}` : "",
+    typeof input.totalScore === "number" ? `Total Score: ${input.totalScore}` : "",
+    typeof input.durationMin === "number" ? `Duration (min): ${input.durationMin}` : "",
+    input.questionCount ? `Question Count: ${input.questionCount}` : "",
+    `Source Exam Text:\n${input.sourceText}`,
+  ]
+  const userContent = userLines.filter((l) => l.length > 0).join("\n")
+  return [
+    { role: "system" as const, content: AI_EXAM_SYSTEM_PROMPT },
+    { role: "user" as const, content: userContent },
+  ]
+}
+
+type AiDraftResult =
+  | { ok: true; data: z.infer<typeof AiExamResponseSchema>; rawOutput: string }
+  | { ok: false; message: string }
+
+type AiStructureDraftResult =
+  | { ok: true; data: z.infer<typeof AiStructureResponseSchema>; rawOutput: string }
+  | { ok: false; message: string }
+
+const requestAiExamDraft = async (input: {
+  title?: string
+  subject?: string
+  grade?: string
+  difficulty?: number
+  totalScore?: number
+  durationMin?: number
+  questionCount?: number
+  sourceText: string
+  aiProviderId?: string
+}): Promise<AiDraftResult> => {
+  try {
+    const aiResult = await createAiChatCompletion({
+      model: String(env.AI_MODEL ?? "gpt-4o-mini"),
+      providerId: input.aiProviderId,
+      messages: buildAiMessages(input),
+      temperature: 0.7,
+      maxTokens: 4000,
+    })
+    const rawOutput = aiResult.content
+    const data = await parseAiResponse(rawOutput, input.aiProviderId)
+    const validated = AiExamResponseSchema.safeParse(data)
+    if (!validated.success) {
+      return { ok: false, message: "AI response format invalid" }
+    }
+    return { ok: true, data: validated.data, rawOutput }
+  } catch (error) {
+    return { ok: false, message: getAiErrorMessage(error) }
+  }
+}
+
+const requestAiExamStructureDraft = async (input: {
+  title?: string
+  subject?: string
+  grade?: string
+  difficulty?: number
+  totalScore?: number
+  durationMin?: number
+  questionCount?: number
+  sourceText: string
+  aiProviderId?: string
+}): Promise<AiStructureDraftResult> => {
+  try {
+    const aiResult = await createAiChatCompletion({
+      model: String(env.AI_MODEL ?? "gpt-4o-mini"),
+      providerId: input.aiProviderId,
+      messages: [
+        { role: "system" as const, content: AI_EXAM_STRUCTURE_SYSTEM_PROMPT },
+        { role: "user" as const, content: buildAiMessages(input)[1].content },
+      ],
+      temperature: 0.2,
+      maxTokens: 4000,
+    })
+    const rawOutput = aiResult.content
+    const data = await parseAiResponse(rawOutput, input.aiProviderId)
+    const validated = AiStructureResponseSchema.safeParse(data)
+    if (!validated.success) {
+      return { ok: false, message: "AI response format invalid" }
+    }
+    return { ok: true, data: validated.data, rawOutput }
+  } catch (error) {
+    return { ok: false, message: getAiErrorMessage(error) }
+  }
+}
+
+type SplitQuestionItem = {
+  sectionIndex: number | null
+  sectionTitle?: string
+  text: string
+  score?: number
+}
+
+const validateExamSourceText = async (input: { sourceText: string; aiProviderId?: string }) => {
+  const text = input.sourceText.trim()
+  if (!text) {
+    return { ok: false as const, message: "请先粘贴试卷文本" }
+  }
+  const userContent = [
+    "请判断下面文本是否是可读、正常的题目/试卷内容（不是乱码、随机字符或混乱文本）。",
+    `文本内容：\n${text}`,
+  ].join("\n\n")
+  try {
+    const aiResult = await createAiChatCompletion({
+      model: String(env.AI_MODEL ?? "gpt-4o-mini"),
+      providerId: input.aiProviderId,
+      messages: [
+        { role: "system" as const, content: AI_EXAM_SOURCE_VALIDATION_SYSTEM_PROMPT },
+        { role: "user" as const, content: userContent },
+      ],
+      temperature: 0,
+      maxTokens: 300,
+    })
+    const parsed = await parseAiResponse(aiResult.content, input.aiProviderId)
+    const validated = AiSourceValidationSchema.safeParse(parsed)
+    if (!validated.success) {
+      return { ok: false as const, message: "试卷文本校验失败，请重试" }
+    }
+    if (!validated.data.valid) {
+      return {
+        ok: false as const,
+        message: validated.data.reason?.trim() || "识别为乱码或混乱文本，请粘贴清晰完整的题目内容",
+      }
+    }
+    return { ok: true as const }
+  } catch (error) {
+    return { ok: false as const, message: getAiErrorMessage(error) }
+  }
+}
+
+const splitStructureItems = (draft: z.infer<typeof AiStructureResponseSchema>) => {
+  const hasSections = Array.isArray(draft.sections) && draft.sections.length > 0
+  if (!hasSections) {
+    return (draft.questions ?? []).map((q) => ({
+      sectionIndex: null,
+      sectionTitle: undefined,
+      text: q.text,
+      score: q.score,
+    } satisfies SplitQuestionItem))
+  }
+  const rows: SplitQuestionItem[] = []
+  draft.sections!.forEach((section, sectionIndex) => {
+    section.questions.forEach((q) => {
+      rows.push({
+        sectionIndex,
+        sectionTitle: section.title,
+        text: q.text,
+        score: q.score,
+      })
+    })
+  })
+  return rows
+}
+
+const mapWithConcurrency = async <T, R>(
+  items: T[],
+  concurrency: number,
+  worker: (item: T, index: number) => Promise<R>
+) => {
+  const results = new Array<R>(items.length)
+  let cursor = 0
+  const runWorker = async () => {
+    while (cursor < items.length) {
+      const index = cursor
+      cursor += 1
+      results[index] = await worker(items[index], index)
+    }
+  }
+  const workers = Array.from({ length: Math.max(1, Math.min(concurrency, items.length)) }, () => runWorker())
+  await Promise.all(workers)
+  return results
+}
+
+const parseQuestionDetail = async (input: {
+  item: SplitQuestionItem
+  subject?: string
+  grade?: string
+  difficulty: number
+  aiProviderId?: string
+}) => {
+  const normalizeQuestionCandidate = (value: unknown): unknown => {
+    if (!value || typeof value !== "object") return value
+    const record = value as Record<string, unknown>
+    const contentRaw = record.content
+    if (!contentRaw || typeof contentRaw !== "object") return value
+    const content = contentRaw as Record<string, unknown>
+    const normalizedSubQuestions = Array.isArray(content.subQuestions)
+      ? content.subQuestions
+      : Array.isArray(content.subquestions)
+        ? content.subquestions
+        : Array.isArray(content.sub_questions)
+          ? content.sub_questions
+          : undefined
+    if (!normalizedSubQuestions) return value
+    return {
+      ...record,
+      content: {
+        ...content,
+        subQuestions: normalizedSubQuestions,
+      },
+    }
+  }
+
+  const userContent = [
+    input.subject ? `Subject: ${input.subject}` : "",
+    input.grade ? `Grade: ${input.grade}` : "",
+    `Question Text:\n${input.item.text}`,
+  ].filter((line) => line.length > 0).join("\n\n")
+
+  try {
+    const aiResult = await createAiChatCompletion({
+      model: String(env.AI_MODEL ?? "gpt-4o-mini"),
+      providerId: input.aiProviderId,
+      messages: [
+        { role: "system" as const, content: AI_QUESTION_DETAIL_SYSTEM_PROMPT },
+        { role: "user" as const, content: userContent },
+      ],
+      temperature: 0.4,
+      maxTokens: 1200,
+    })
+    const parsed = await parseAiResponse(aiResult.content, input.aiProviderId)
+    const candidate = parsed && typeof parsed === "object" && "question" in parsed
+      ? (parsed as { question: unknown }).question
+      : parsed
+    const validated = AiQuestionSchema.safeParse(normalizeQuestionCandidate(candidate))
+    if (validated.success) {
+      const q = validated.data
+      return {
+        type: q.type,
+        difficulty: q.difficulty ?? input.difficulty,
+        score: q.score ?? input.item.score ?? 0,
+        content: q.content,
+      } satisfies z.infer<typeof AiQuestionSchema>
+    }
+  } catch {
+  }
+
+  return {
+    type: "text",
+    difficulty: input.difficulty,
+    score: input.item.score ?? 0,
+    content: { text: input.item.text },
+  } satisfies z.infer<typeof AiQuestionSchema>
+}
+
+const buildQuestionContent = (q: z.infer<typeof AiQuestionSchema>) => {
+  const base = { text: q.content.text }
+  const subQuestions = Array.isArray(q.content.subQuestions)
+    ? q.content.subQuestions.map((item, index) => ({
+      id: item.id ?? String(index + 1),
+      text: item.text,
+      answer: item.answer,
+      score: item.score,
+    }))
+    : []
+  if (q.type === "single_choice" || q.type === "multiple_choice") {
+    const options = (q.content.options ?? []).map((opt, idx) => ({
+      id: opt.id ?? String.fromCharCode(65 + idx),
+      text: opt.text,
+      isCorrect: opt.isCorrect ?? false,
+    }))
+    if (options.length > 0 && subQuestions.length > 0) return { ...base, options, subQuestions }
+    if (options.length > 0) return { ...base, options }
+    if (subQuestions.length > 0) return { ...base, subQuestions }
+    return base
+  }
+  if (subQuestions.length > 0) return { ...base, subQuestions }
+  return base
+}
+
+type AiPreviewQuestion = {
+  id: string
+  type: z.infer<typeof AiQuestionSchema>["type"]
+  difficulty: number
+  score: number
+  content: ReturnType<typeof buildQuestionContent>
+}
+
+export type AiPreviewData = {
+  title: string
+  rawOutput?: string
+  sections?: Array<{
+    id: string
+    title: string
+    questions: AiPreviewQuestion[]
+  }>
+  questions?: AiPreviewQuestion[]
+}
+
+export type AiRewriteQuestionData = {
+  type: z.infer<typeof AiQuestionSchema>["type"]
+  difficulty: number
+  score: number
+  content: ReturnType<typeof buildQuestionContent>
+}
+
+export type AiGeneratedQuestion = {
+  id: string
+  type: z.infer<typeof AiQuestionSchema>["type"]
+  difficulty: number
+  score: number
+  content: ReturnType<typeof buildQuestionContent>
+}
+
+export type AiGeneratedStructureNode = {
+  id: string
+  type: "group" | "question"
+  title?: string
+  questionId?: string
+  score?: number
+  children?: AiGeneratedStructureNode[]
+}
+
+export const AiGeneratedStructureNodeSchema: z.ZodType<AiGeneratedStructureNode> = z.lazy(() => z.object({
+  id: z.string().min(1),
+  type: z.enum(["group", "question"]),
+  title: z.string().optional(),
+  questionId: z.string().optional(),
+  score: z.coerce.number().int().min(0).optional(),
+  children: z.array(AiGeneratedStructureNodeSchema).optional(),
+}))
+
+export const AiGeneratedStructureSchema = z.array(AiGeneratedStructureNodeSchema)
+
+const buildPreviewPayload = (
+  aiParsed: z.infer<typeof AiExamResponseSchema>,
+  input: {
+    title: string
+    difficulty: number
+    totalScore: number
+    questionCount?: number
+  }
+): AiPreviewData => {
+  const hasSections = Array.isArray(aiParsed.sections) && aiParsed.sections.length > 0
+  const baseQuestions = hasSections ? aiParsed.sections!.flatMap((s) => s.questions) : aiParsed.questions ?? []
+  const limit = input.questionCount
+  let sections = aiParsed.sections
+  let flatQuestions = baseQuestions
+
+  if (typeof limit === "number" && limit > 0) {
+    if (hasSections) {
+      let remaining = limit
+      sections = aiParsed.sections!.map((s) => {
+        if (remaining <= 0) return { ...s, questions: [] }
+        const sliced = s.questions.slice(0, remaining)
+        remaining -= sliced.length
+        return { ...s, questions: sliced }
+      }).filter((s) => s.questions.length > 0)
+      flatQuestions = sections.flatMap((s) => s.questions)
+    } else {
+      flatQuestions = baseQuestions.slice(0, limit)
+    }
+  }
+
+  const scores = normalizeScores(
+    flatQuestions.map((q) => q.score ?? 0),
+    input.totalScore
+  )
+
+  let scoreIndex = 0
+  const toPreviewQuestion = (q: z.infer<typeof AiQuestionSchema>): AiPreviewQuestion => ({
+    id: createId(),
+    type: q.type,
+    difficulty: q.difficulty ?? input.difficulty,
+    score: scores[scoreIndex++] ?? 0,
+    content: buildQuestionContent(q),
+  })
+
+  if (hasSections && sections && sections.length > 0) {
+    return {
+      title: aiParsed.title ?? input.title,
+      sections: sections.map((section) => ({
+        id: createId(),
+        title: section.title,
+        questions: section.questions.map((q) => toPreviewQuestion(q)),
+      })),
+    }
+  }
+
+  return {
+    title: aiParsed.title ?? input.title,
+    questions: flatQuestions.map((q) => toPreviewQuestion(q)),
+  }
+}
+
+const previewToDraft = (preview: AiPreviewData) => {
+  const generated: AiGeneratedQuestion[] = []
+  const structure: AiGeneratedStructureNode[] = []
+  if (Array.isArray(preview.sections) && preview.sections.length > 0) {
+    for (const section of preview.sections) {
+      const children: AiGeneratedStructureNode[] = []
+      for (const question of section.questions) {
+        generated.push({
+          id: question.id,
+          type: question.type,
+          difficulty: question.difficulty,
+          score: question.score,
+          content: question.content,
+        })
+        children.push({
+          id: createId(),
+          type: "question",
+          questionId: question.id,
+          score: question.score,
+        })
+      }
+      structure.push({
+        id: section.id || createId(),
+        type: "group",
+        title: section.title,
+        children,
+      })
+    }
+    return { generated, structure }
+  }
+  for (const question of preview.questions ?? []) {
+    generated.push({
+      id: question.id,
+      type: question.type,
+      difficulty: question.difficulty,
+      score: question.score,
+      content: question.content,
+    })
+    structure.push({
+      id: createId(),
+      type: "question",
+      questionId: question.id,
+      score: question.score,
+    })
+  }
+  return { generated, structure }
+}
+
+export async function generateAiPreviewData(input: {
+  title: string
+  subject?: string
+  grade?: string
+  difficulty: number
+  totalScore: number
+  durationMin: number
+  questionCount?: number
+  sourceText: string
+  aiProviderId?: string
+}) {
+  const sourceValidation = await validateExamSourceText({
+    sourceText: input.sourceText,
+    aiProviderId: input.aiProviderId,
+  })
+  if (!sourceValidation.ok) {
+    return { ok: false as const, message: sourceValidation.message }
+  }
+  const structureDraft = await requestAiExamStructureDraft(input)
+  if (!structureDraft.ok) return structureDraft
+  const splitItems = splitStructureItems(structureDraft.data)
+  const limitedItems = typeof input.questionCount === "number" && input.questionCount > 0
+    ? splitItems.slice(0, input.questionCount)
+    : splitItems
+  if (limitedItems.length === 0) {
+    return { ok: false as const, message: "AI returned no questions" }
+  }
+  const detailedQuestions = await mapWithConcurrency(limitedItems, 6, (item) => parseQuestionDetail({
+    item,
+    subject: input.subject,
+    grade: input.grade,
+    difficulty: input.difficulty,
+    aiProviderId: input.aiProviderId,
+  }))
+  const hasSectionStructure = limitedItems.some((item) => item.sectionIndex !== null)
+  const aiParsed: z.infer<typeof AiExamResponseSchema> = hasSectionStructure
+    ? {
+      title: structureDraft.data.title ?? input.title,
+      sections: (() => {
+        const sectionMap = new Map<number, { title: string; questions: z.infer<typeof AiQuestionSchema>[] }>()
+        limitedItems.forEach((item, index) => {
+          if (item.sectionIndex === null) return
+          const existed = sectionMap.get(item.sectionIndex)
+          const question = detailedQuestions[index]
+          if (existed) {
+            existed.questions.push(question)
+            return
+          }
+          sectionMap.set(item.sectionIndex, {
+            title: item.sectionTitle || `Section ${item.sectionIndex + 1}`,
+            questions: [question],
+          })
+        })
+        return Array.from(sectionMap.entries())
+          .sort((a, b) => a[0] - b[0])
+          .map(([, section]) => section)
+      })(),
+      questions: undefined,
+    }
+    : {
+      title: structureDraft.data.title ?? input.title,
+      questions: detailedQuestions,
+      sections: undefined,
+    }
+  const payload = buildPreviewPayload(aiParsed, input)
+  return {
+    ok: true as const,
+    data: payload,
+    rawOutput: structureDraft.rawOutput,
+  }
+}
+
+export async function generateAiCreateDraftFromSource(input: {
+  title: string
+  subject?: string
+  grade?: string
+  difficulty: number
+  totalScore: number
+  durationMin: number
+  questionCount?: number
+  sourceText: string
+  aiProviderId?: string
+}) {
+  const preview = await generateAiPreviewData(input)
+  if (!preview.ok) {
+    return preview
+  }
+  const draft = previewToDraft(preview.data)
+  return {
+    ok: true as const,
+    generated: draft.generated,
+    structure: draft.structure,
+    rawOutput: preview.rawOutput,
+  }
+}
+
+export async function regenerateAiQuestionByInstruction(input: {
+  instruction: string
+  originalQuestion: z.infer<typeof AiQuestionSchema>
+  sourceText?: string
+  aiProviderId?: string
+}) {
+  const originalDifficulty = input.originalQuestion.difficulty ?? 3
+  const originalScore = input.originalQuestion.score ?? 0
+  const contextLines = [
+    `Instruction:\n${input.instruction}`,
+    `Original Question JSON:\n${JSON.stringify(input.originalQuestion, null, 2)}`,
+    input.sourceText ? `Source Exam Text:\n${input.sourceText}` : "",
+  ]
+  const userContent = contextLines.filter((line) => line.length > 0).join("\n\n")
+  try {
+    const aiResult = await createAiChatCompletion({
+      model: String(env.AI_MODEL ?? "gpt-4o-mini"),
+      providerId: input.aiProviderId && input.aiProviderId.length > 0 ? input.aiProviderId : undefined,
+      messages: [
+        { role: "system" as const, content: AI_REWRITE_QUESTION_SYSTEM_PROMPT },
+        { role: "user" as const, content: userContent },
+      ],
+      temperature: 0.7,
+      maxTokens: 2000,
+    })
+    const parsed = await parseAiResponse(aiResult.content, input.aiProviderId)
+    const candidate = parsed && typeof parsed === "object" && "question" in parsed
+      ? (parsed as { question: unknown }).question
+      : parsed
+    const validated = AiQuestionSchema.safeParse(candidate)
+    if (!validated.success) {
+      return { ok: false as const, message: "AI question format invalid" }
+    }
+    const question = validated.data
+    return {
+      ok: true as const,
+      data: {
+        type: question.type,
+        difficulty: question.difficulty ?? originalDifficulty,
+        score: question.score ?? originalScore,
+        content: buildQuestionContent(question),
+      } satisfies AiRewriteQuestionData,
+    }
+  } catch (error) {
+    return { ok: false as const, message: getAiErrorMessage(error) }
+  }
+}
+
+export async function generateAiExamDraft(input: {
+  title?: string
+  subject?: string
+  grade?: string
+  difficulty?: number
+  totalScore?: number
+  durationMin?: number
+  questionCount?: number
+  sourceText: string
+  aiProviderId?: string
+}) {
+  return requestAiExamDraft(input)
+}

src/modules/exams/data-access.ts

@@ -1,9 +1,10 @@
 import { db } from "@/shared/db"
-import { exams } from "@/shared/db/schema"
+import { exams, examQuestions, questions, subjects, grades } from "@/shared/db/schema"
 import { eq, desc, like, and, or } from "drizzle-orm"
 import { cache } from "react"
 
 import type { Exam, ExamDifficulty, ExamStatus } from "./types"
+import type { AiGeneratedQuestion, AiGeneratedStructureNode } from "./ai-pipeline"
 
 export type GetExamsParams = {
   q?: string
@@ -158,3 +159,139 @@ export const omitScheduledAtFromDescription = (description: string | null): stri
     return description || "{}"
   }
 }
+
+export const resolveSubjectGradeNames = async (input: {
+  subjectId?: string
+  gradeId?: string
+}) => {
+  const [subjectRecord, gradeRecord] = await Promise.all([
+    input.subjectId
+      ? db.query.subjects.findFirst({
+        where: eq(subjects.id, input.subjectId),
+      })
+      : Promise.resolve(null),
+    input.gradeId
+      ? db.query.grades.findFirst({
+        where: eq(grades.id, input.gradeId),
+      })
+      : Promise.resolve(null),
+  ])
+  return {
+    subjectName: subjectRecord?.name,
+    gradeName: gradeRecord?.name,
+  }
+}
+
+export const buildExamDescription = (input: {
+  subject: string
+  grade: string
+  difficulty: number
+  totalScore: number
+  durationMin: number
+  scheduledAt?: string
+  questionCount?: number
+}) => JSON.stringify({
+  subject: input.subject,
+  grade: input.grade,
+  difficulty: input.difficulty,
+  totalScore: input.totalScore,
+  durationMin: input.durationMin,
+  scheduledAt: input.scheduledAt,
+  questionCount: input.questionCount,
+})
+
+export const persistExamDraft = async (input: {
+  examId: string
+  title: string
+  creatorId: string
+  subjectId: string
+  gradeId: string
+  scheduledAt?: string
+  description: string
+}) => {
+  await db.insert(exams).values({
+    id: input.examId,
+    title: input.title,
+    description: input.description,
+    creatorId: input.creatorId,
+    subjectId: input.subjectId,
+    gradeId: input.gradeId,
+    startTime: input.scheduledAt ? new Date(input.scheduledAt) : null,
+    status: "draft",
+  })
+}
+
+const buildOrderedQuestionsFromStructure = (
+  structure: AiGeneratedStructureNode[],
+  generated: AiGeneratedQuestion[]
+) => {
+  const questionById = new Map(generated.map((q) => [q.id, q] as const))
+  const orderedQuestions: Array<{ id: string; score: number }> = []
+  const collectOrder = (nodes: AiGeneratedStructureNode[]) => {
+    for (const node of nodes) {
+      if (node.type === "question" && typeof node.questionId === "string" && node.questionId) {
+        const score = typeof node.score === "number" ? node.score : questionById.get(node.questionId)?.score ?? 0
+        orderedQuestions.push({ id: node.questionId, score })
+        continue
+      }
+      if (node.type === "group" && Array.isArray(node.children) && node.children.length > 0) {
+        collectOrder(node.children)
+      }
+    }
+  }
+  collectOrder(structure)
+  if (orderedQuestions.length === 0) {
+    return generated.map((q) => ({ id: q.id, score: q.score ?? 0 }))
+  }
+  return orderedQuestions
+}
+
+export const persistAiGeneratedExamDraft = async (input: {
+  examId: string
+  title: string
+  creatorId: string
+  subjectId: string
+  gradeId: string
+  scheduledAt?: string
+  description: string
+  structure: AiGeneratedStructureNode[]
+  generated: AiGeneratedQuestion[]
+}) => {
+  const orderedQuestions = buildOrderedQuestionsFromStructure(input.structure, input.generated)
+  await db.transaction(async (tx) => {
+    await tx.insert(exams).values({
+      id: input.examId,
+      title: input.title,
+      description: input.description,
+      creatorId: input.creatorId,
+      subjectId: input.subjectId,
+      gradeId: input.gradeId,
+      startTime: input.scheduledAt ? new Date(input.scheduledAt) : null,
+      status: "draft",
+      structure: input.structure,
+    })
+
+    if (input.generated.length > 0) {
+      await tx.insert(questions).values(
+        input.generated.map((q) => ({
+          id: q.id,
+          content: q.content,
+          type: q.type,
+          difficulty: q.difficulty,
+          authorId: input.creatorId,
+        }))
+      )
+    }
+
+    if (orderedQuestions.length > 0) {
+      await tx.insert(examQuestions).values(
+        orderedQuestions.map((q, idx) => ({
+          examId: input.examId,
+          questionId: q.id,
+          score: q.score ?? 0,
+          order: idx,
+        }))
+      )
+    }
+  })
+}