@zhouchangui/math-ati 0.1.0

package/server/pdfSubmissionGrader.js

@@ -0,0 +1,846 @@
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { mkdir, readdir, writeFile } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import {
+  buildCorrectionPackMarkdown,
+  buildKnowledgeEvidence,
+  buildPositiveReportMarkdown,
+  buildWeakPoints,
+  gradingStats,
+  syncKnowledgeMasteryMarkers
+} from './knowledgeFeedback.js';
+import {
+  chapterDataPaths,
+  ensureChapterDataDirs,
+  paths,
+  readJson,
+  relativeDataPath,
+  writeJson
+} from './fileStore.js';
+import { callChatAgent, callVisionAgent } from './agentClient.js';
+import { promptPayload, readPrompt } from './promptStore.js';
+import { readPractice } from './practiceService.js';
+import {
+  confirmSubmission,
+  writeSubmissionMirrors
+} from './submissionService.js';
+
+const execFileAsync = promisify(execFile);
+
+async function appendLog(logPath, event) {
+  if (!logPath) return;
+  await writeFile(logPath, `${JSON.stringify(event)}\n`, { flag: 'a' });
+}
+
+function progressMessage(event) {
+  switch (event.step) {
+    case 'submission.start':
+      return `开始批改提交 ${event.submissionId}，练习 ${event.practiceId}`;
+    case 'pdf_render.start':
+      return '正在把 PDF 渲染成逐页图片';
+    case 'pdf_render.done':
+      return `PDF 渲染完成，共 ${event.pageCount} 页`;
+    case 'page_extract.start':
+      return `正在识别第 ${event.page}/${event.totalPages || '?'} 页作答`;
+    case 'page_extract.done':
+      return `第 ${event.page}/${event.totalPages || '?'} 页识别完成，提取 ${event.answers} 条作答片段`;
+    case 'practice_match.failed':
+      return `上传 PDF 与当前试卷不匹配：${event.mismatchPages?.join('、') || '未知页'} 页题干不一致`;
+    case 'stitch.start':
+      return '正在按题号合并跨页作答片段';
+    case 'stitch.done':
+      return `作答拼接完成，${event.answersFound}/${event.questions} 题找到作答内容`;
+    case 'grading.start':
+      return `开始逐题批改，共 ${event.questions} 题，每批 ${event.batchSize} 题`;
+    case 'grading_batch.start':
+      return `正在批改第 ${event.batch}/${event.totalBatches} 批：${(event.questionIds || []).join('、')}`;
+    case 'grading_batch.done':
+      return `第 ${event.batch}/${event.totalBatches} 批批改完成，已批 ${event.gradedQuestions} 题`;
+    case 'grading.done':
+      return `逐题批改完成，共 ${event.gradedQuestions} 题，来源：${event.source}`;
+    case 'recheck.plan':
+      return event.maxRechecks > 0 ? `准备二次复核，最多复核 ${event.maxRechecks} 题` : '跳过二次复核';
+    case 'recheck.start':
+      return `正在二次复核 ${event.questionId}`;
+    case 'recheck.skipped':
+      return `${event.questionId} 二次复核跳过：${event.reason}`;
+    case 'recheck.done':
+      return `${event.questionId} 二次复核完成：${event.initialStatus} -> ${event.finalStatus}`;
+    case 'artifacts.start':
+      return '正在生成批改文件、知识点证据、薄弱点和讲解包';
+    case 'artifacts.done':
+      return `文件输出完成，结构核对${event.selfCheckPassed ? '通过' : '未通过'}，薄弱点 ${event.weakPoints} 个`;
+    case 'archive.start':
+      return '正在归档并更新知识点掌握状态';
+    case 'archive.done':
+      return `归档完成，正确率 ${event.accuracy}%`;
+    case 'archive.skipped':
+      return '跳过归档：本次只输出批改文件，不更新掌握状态';
+    case 'submission.done':
+      return `批改流程完成，正确率 ${event.stats?.accuracy ?? 0}%`;
+    default:
+      return event.step;
+  }
+}
+
+function createProgressLogger({ logPath, onProgress }) {
+  return async function log(step, data = {}) {
+    const event = {
+      ts: new Date().toISOString(),
+      step,
+      ...data
+    };
+    event.message ||= progressMessage(event);
+    await appendLog(logPath, event);
+    if (onProgress) onProgress(event);
+  };
+}
+
+function argSafeFilename(filePath) {
+  return path.basename(filePath, path.extname(filePath)).replace(/[^\p{L}\p{N}.-]+/gu, '-').slice(0, 80);
+}
+
+function questionNumber(questionId) {
+  return Number(String(questionId || '').replace(/^q/, '')) || 0;
+}
+
+function sortQuestionIds(ids) {
+  return [...ids].sort((a, b) => questionNumber(a) - questionNumber(b));
+}
+
+function sortPageNumbers(pages) {
+  return [...pages].sort((a, b) => Number(a) - Number(b));
+}
+
+function chunk(items, size) {
+  const chunks = [];
+  for (let index = 0; index < items.length; index += size) {
+    chunks.push(items.slice(index, index + size));
+  }
+  return chunks;
+}
+
+function pdfGradingError(reason, detail = '') {
+  const error = new Error(`pdf_grading_failed:${reason}`);
+  error.status = 502;
+  error.reason = reason;
+  error.detail = detail;
+  return error;
+}
+
+function compactPracticeForPrompt(practice) {
+  return {
+    id: practice.id,
+    title: practice.title,
+    chapterId: practice.chapterId,
+    chapterTitle: practice.chapterTitle,
+    questions: (practice.questions || []).map((question) => ({
+      id: question.id,
+      displayNumber: questionNumber(question.id),
+      stem: question.stem,
+      questionKind: question.questionKind || 'short_answer',
+      difficulty: question.difficulty || 'basic',
+      score: question.score,
+      knowledgePointIds: question.knowledgePointIds || [],
+      knowledgePoints: question.knowledgePoints || [],
+      expectedErrorTypes: question.expectedErrorTypes || [],
+      abilityIds: question.abilityIds || [],
+      skillAtoms: question.skillAtoms || [],
+      expectedAbilityErrors: question.expectedAbilityErrors || [],
+      answer: question.answer || '',
+      solutionSteps: Array.isArray(question.solutionSteps) ? question.solutionSteps : [],
+      rubric: Array.isArray(question.rubric) ? question.rubric : []
+    }))
+  };
+}
+
+async function commandExists(command) {
+  try {
+    await execFileAsync(command, ['-v']);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function renderPdfPages({ pdfPath, pagesDir }) {
+  await mkdir(pagesDir, { recursive: true });
+  if (!(await commandExists('pdftoppm'))) {
+    const error = new Error('missing_pdftoppm');
+    error.hint = 'Install poppler: brew install poppler';
+    throw error;
+  }
+  const prefix = path.join(pagesDir, 'page');
+  await execFileAsync('pdftoppm', ['-png', '-r', '180', pdfPath, prefix], { maxBuffer: 1024 * 1024 * 20 });
+  const files = (await readdir(pagesDir))
+    .filter((file) => /^page-\d+\.png$/.test(file))
+    .sort();
+  return files.map((file, index) => ({
+    page: index + 1,
+    imagePath: path.join(pagesDir, file)
+  }));
+}
+
+function normalizePageExtract(data, page) {
+  const visibleQuestionIds = Array.isArray(data?.visibleQuestionIds) ? data.visibleQuestionIds : [];
+  const answers = Array.isArray(data?.answers) ? data.answers : [];
+  return {
+    page,
+    visibleQuestionIds: sortQuestionIds(visibleQuestionIds.filter(Boolean)),
+    answers: answers
+      .filter((item) => item?.questionId)
+      .map((item) => ({
+        questionId: item.questionId,
+        recognizedAnswerFragment: item.recognizedAnswerFragment || item.recognizedAnswer || '',
+        position: item.position || '',
+        confidence: item.confidence || 'medium',
+        isContinuation: Boolean(item.isContinuation),
+        continuesToNextPage: Boolean(item.continuesToNextPage),
+        evidence: item.evidence || '',
+        needsReview: Boolean(item.needsReview)
+      })),
+    warnings: Array.isArray(data?.warnings) ? data.warnings : [],
+    source: data?.source || 'agent'
+  };
+}
+
+function practiceMismatchWarnings(pageExtracts) {
+  const mismatchPattern = /practice_mismatch|题干不一致|题面不一致|内容不一致|同编号题干不一致|题号对应冲突|not match|mismatch/i;
+  return pageExtracts
+    .map((extract) => {
+      const warnings = (extract.warnings || []).filter((warning) => mismatchPattern.test(String(warning || '')));
+      return warnings.length ? { page: extract.page, warnings } : null;
+    })
+    .filter(Boolean);
+}
+
+function assertPracticeMatchesSubmission(practice, pageExtracts) {
+  const mismatches = practiceMismatchWarnings(pageExtracts);
+  if (!mismatches.length) return;
+  const pageList = mismatches.map((item) => `page ${item.page}: ${item.warnings.join('；')}`).join(' | ');
+  throw pdfGradingError(
+    'practice_mismatch',
+    `Uploaded PDF does not match selected practice ${practice.id}. ${pageList}`
+  );
+}
+
+async function extractPageAnswers({
+  practice,
+  pageImage,
+  outputPath,
+  useAgent = true,
+  totalPages = null,
+  log = async () => {}
+}) {
+  if (!useAgent) {
+    throw pdfGradingError('agent_required', 'PDF extraction requires the configured AI agent.');
+  }
+
+  const systemPrompt = await readPrompt('pdf-page-extract.system.md');
+  const agent = await callVisionAgent({
+    timeoutMs: 90000,
+    retries: 1,
+    system: systemPrompt,
+    text: promptPayload({
+      task: '逐页识别学生作答。只记录本页可见题号和答案片段，不进行批改。要特别标记跨页、续写、低置信度和看不清。',
+      requirements: [
+        '不要推测看不清的内容。',
+        '题号必须来自 practice.questions[].id。',
+        '必须核对页面中可见题干和 practice 中同编号题干是否一致；如果同编号题干明显不一致，在 warnings 中写入 practice_mismatch，并不要把该页作答当作该题答案。',
+        '一题可能跨页；只输出本页片段，使用 isContinuation 和 continuesToNextPage 标记。',
+        '如果只看到题目没有看到作答，也可以把题号放入 visibleQuestionIds。'
+      ],
+      context: {
+        page: pageImage.page,
+        practice: compactPracticeForPrompt(practice)
+      },
+      schema: {
+        page: pageImage.page,
+        visibleQuestionIds: ['q1'],
+        answers: [
+          {
+            questionId: 'q1',
+            recognizedAnswerFragment: 'string',
+            position: 'page_top|page_middle|page_bottom|unknown',
+            confidence: 'high|medium|low',
+            isContinuation: false,
+            continuesToNextPage: false,
+            evidence: 'string',
+            needsReview: false
+          }
+        ],
+        warnings: ['string']
+      }
+    }),
+    imagePaths: [pageImage.imagePath]
+  });
+
+  if (!agent.ok) {
+    throw pdfGradingError(`page_extract_${agent.reason || 'agent_failed'}`, agent.detail || '');
+  }
+  const extract = normalizePageExtract(agent.data, pageImage.page);
+  extract.agentReason = null;
+  await writeJson(outputPath, extract);
+  await log('page_extract.done', {
+    page: pageImage.page,
+    totalPages,
+    source: extract.source,
+    answers: extract.answers.length,
+    visibleQuestionIds: extract.visibleQuestionIds.length,
+    warnings: extract.warnings.length,
+    agentReason: extract.agentReason
+  });
+  return extract;
+}
+
+export function stitchPageAnswers(practice, pageExtracts) {
+  const byQuestion = new Map();
+  for (const extract of pageExtracts) {
+    for (const answer of extract.answers || []) {
+      const current = byQuestion.get(answer.questionId) || {
+        questionId: answer.questionId,
+        sourcePages: [],
+        fragments: [],
+        mergedAnswer: '',
+        stitchingConfidence: 'high',
+        warnings: []
+      };
+      current.sourcePages.push(extract.page);
+      current.fragments.push({
+        page: extract.page,
+        text: answer.recognizedAnswerFragment || '',
+        confidence: answer.confidence || 'medium',
+        isContinuation: Boolean(answer.isContinuation),
+        continuesToNextPage: Boolean(answer.continuesToNextPage),
+        evidence: answer.evidence || ''
+      });
+      if (answer.needsReview) current.warnings.push(`page_${extract.page}_needs_review`);
+      if (answer.confidence === 'low') current.stitchingConfidence = 'low';
+      if (answer.confidence === 'medium' && current.stitchingConfidence !== 'low') current.stitchingConfidence = 'medium';
+      byQuestion.set(answer.questionId, current);
+    }
+  }
+
+  const stitched = (practice.questions || []).map((question) => {
+    const current = byQuestion.get(question.id) || {
+      questionId: question.id,
+      sourcePages: [],
+      fragments: [],
+      mergedAnswer: '',
+      stitchingConfidence: 'low',
+      warnings: ['answer_not_found']
+    };
+    current.sourcePages = sortPageNumbers([...new Set(current.sourcePages.map(String))])
+      .map((page) => Number(page));
+    current.fragments.sort((a, b) => a.page - b.page);
+    current.mergedAnswer = current.fragments.map((fragment) => fragment.text).filter(Boolean).join('\n');
+    if (current.fragments.some((fragment) => fragment.continuesToNextPage || fragment.isContinuation)) {
+      current.warnings.push('cross_page_or_continuation');
+    }
+    current.warnings = [...new Set(current.warnings)];
+    return current;
+  });
+
+  return stitched.sort((a, b) => questionNumber(a.questionId) - questionNumber(b.questionId));
+}
+
+function normalizeGradingResult(data, practice, stitchedAnswers) {
+  const stitchedByQuestion = new Map(stitchedAnswers.map((item) => [item.questionId, item]));
+  const items = Array.isArray(data?.grading) ? data.grading : [];
+  const byQuestion = new Map(items.filter((item) => item?.questionId).map((item) => [item.questionId, item]));
+  const grading = (practice.questions || []).map((question) => {
+    const item = byQuestion.get(question.id) || {};
+    const maxScore = Number(item.maxScore ?? question.score ?? 0);
+    const score = Math.max(0, Math.min(maxScore, Number(item.score ?? 0)));
+    const stitched = stitchedByQuestion.get(question.id);
+    return {
+      questionId: question.id,
+      sourcePages: item.sourcePages || stitched?.sourcePages || [],
+      recognizedAnswer: item.recognizedAnswer || stitched?.mergedAnswer || '',
+      status: ['correct', 'partial', 'wrong', 'unrecognized', 'needs_review'].includes(item.status)
+        ? item.status
+        : 'needs_review',
+      score,
+      maxScore,
+      confidence: item.confidence || stitched?.stitchingConfidence || 'medium',
+      errorTypes: Array.isArray(item.errorTypes) ? item.errorTypes : [],
+      comment: item.comment || '',
+      positiveFeedback: item.positiveFeedback || '',
+      mistakeSummary: item.mistakeSummary || '',
+      referenceAnswer: item.referenceAnswer || question.answer || '',
+      solutionMethod: Array.isArray(item.solutionMethod)
+        ? item.solutionMethod
+        : Array.isArray(question.solutionSteps)
+          ? question.solutionSteps
+          : [],
+      teachingHint: item.teachingHint || '',
+      reviewPasses: Number(item.reviewPasses || 1),
+      initialStatus: item.initialStatus || item.status || null,
+      reviewReason: item.reviewReason || ''
+    };
+  });
+
+  return {
+    source: data?.source || 'agent',
+    summary: data?.summary || '',
+    masterySignals: Array.isArray(data?.masterySignals) ? data.masterySignals : [],
+    nextPracticeSuggestion: data?.nextPracticeSuggestion || '',
+    grading
+  };
+}
+
+async function gradeStitchedAnswersBatch({ practice, stitchedAnswers }) {
+  const systemPrompt = await readPrompt('pdf-grading.system.md');
+  const agent = await callChatAgent({
+    timeoutMs: 120000,
+    retries: 1,
+    system: systemPrompt,
+    user: promptPayload({
+      task: '根据练习题目、标准答案和拼接后的学生作答完成逐题批改。练习 JSON 必须提供答案元数据；尽量给出 correct/partial/wrong/unrecognized，少用 needs_review。',
+      requirements: [
+        'practice 是批改的唯一题目结构来源。',
+        '必须使用题目自带 answer、solutionSteps、rubric 作为 referenceAnswer、讲解和评分依据。',
+        '不能臆造学生答案。',
+        '每题必须输出 grading。',
+        '正确题可以只给简短 referenceAnswer 和 positiveFeedback；错误或部分正确题必须输出 mistakeSummary、solutionMethod、teachingHint，方便讲解纠错。',
+        'errorTypes 应尽量使用题目 expectedErrorTypes 中的错因标签，也可补充更具体的错因。',
+        '分数不能超过 maxScore。'
+      ],
+      context: {
+        practice: compactPracticeForPrompt(practice),
+        stitchedAnswers
+      },
+      schema: {
+        summary: 'string',
+        masterySignals: ['string'],
+        nextPracticeSuggestion: 'string',
+        grading: [
+          {
+            questionId: 'q1',
+            sourcePages: [1],
+            recognizedAnswer: 'string',
+            status: 'correct|partial|wrong|unrecognized|needs_review',
+            score: 0,
+            maxScore: 8,
+            confidence: 'high|medium|low',
+            positiveFeedback: 'string',
+            errorTypes: ['string'],
+            comment: 'string',
+            mistakeSummary: 'string',
+            referenceAnswer: 'string',
+            solutionMethod: ['string'],
+            teachingHint: 'string'
+          }
+        ]
+      }
+    })
+  });
+
+  if (!agent.ok) {
+    throw pdfGradingError(`grading_${agent.reason || 'agent_failed'}`, agent.detail || '');
+  }
+  return normalizeGradingResult({ ...agent.data, source: 'agent' }, practice, stitchedAnswers);
+}
+
+async function gradeStitchedAnswers({
+  practice,
+  stitchedAnswers,
+  useAgent = true,
+  batchSize = 5,
+  log = async () => {}
+}) {
+  if (!useAgent) {
+    throw pdfGradingError('agent_required', 'PDF grading requires the configured AI agent.');
+  }
+
+  const batches = chunk(practice.questions || [], batchSize);
+  const grading = [];
+  const summaries = [];
+  const masterySignals = [];
+  const suggestions = [];
+
+  for (const questions of batches) {
+    await log('grading_batch.start', {
+      batch: grading.length ? Math.floor(grading.length / batchSize) + 1 : 1,
+      totalBatches: batches.length,
+      questionIds: questions.map((question) => question.id)
+    });
+    const ids = new Set(questions.map((question) => question.id));
+    const batchPractice = { ...practice, questions };
+    const batchStitched = stitchedAnswers.filter((item) => ids.has(item.questionId));
+    const result = await gradeStitchedAnswersBatch({
+      practice: batchPractice,
+      stitchedAnswers: batchStitched
+    });
+    grading.push(...result.grading);
+    if (result.summary) summaries.push(result.summary);
+    masterySignals.push(...(result.masterySignals || []));
+    if (result.nextPracticeSuggestion) suggestions.push(result.nextPracticeSuggestion);
+    await log('grading_batch.done', {
+      batch: Math.ceil(grading.length / batchSize),
+      totalBatches: batches.length,
+      source: result.source,
+      gradedQuestions: result.grading.length,
+      agentReason: null
+    });
+  }
+
+  return {
+    source: 'agent',
+    agentReason: null,
+    summary: summaries.join('\n'),
+    masterySignals: [...new Set(masterySignals)].slice(0, 20),
+    nextPracticeSuggestion: suggestions.filter(Boolean).slice(0, 3).join('\n'),
+    grading: grading.sort((a, b) => questionNumber(a.questionId) - questionNumber(b.questionId))
+  };
+}
+
+function questionsForRecheck(gradingResult, stitchedAnswers) {
+  const stitchedByQuestion = new Map(stitchedAnswers.map((item) => [item.questionId, item]));
+  return gradingResult.grading
+    .filter((item) => {
+      const stitched = stitchedByQuestion.get(item.questionId);
+      return item.status === 'needs_review' ||
+        item.status === 'unrecognized' ||
+        item.confidence === 'low' ||
+        stitched?.warnings?.includes('cross_page_or_continuation');
+    })
+    .map((item) => item.questionId);
+}
+
+async function recheckQuestions({
+  practice,
+  gradingResult,
+  stitchedAnswers,
+  pageImages,
+  maxRechecks = 12,
+  log = async () => {}
+}) {
+  if (maxRechecks <= 0) return { gradingResult, recheckedQuestionIds: [] };
+  if (gradingResult.source !== 'agent') {
+    return { gradingResult, recheckedQuestionIds: [] };
+  }
+  const questionIds = questionsForRecheck(gradingResult, stitchedAnswers).slice(0, maxRechecks);
+  if (!questionIds.length) return { gradingResult, recheckedQuestionIds: [] };
+
+  const systemPrompt = await readPrompt('pdf-recheck.system.md');
+  const questions = new Map((practice.questions || []).map((question) => [question.id, question]));
+  const stitchedByQuestion = new Map(stitchedAnswers.map((item) => [item.questionId, item]));
+  const pageByNumber = new Map(pageImages.map((item) => [item.page, item.imagePath]));
+  const nextByQuestion = new Map(gradingResult.grading.map((item) => [item.questionId, item]));
+  const recheckedQuestionIds = [];
+
+  for (const questionId of questionIds) {
+    await log('recheck.start', { questionId });
+    const question = questions.get(questionId);
+    const stitched = stitchedByQuestion.get(questionId);
+    if (!question || !stitched) continue;
+    const imagePaths = (stitched.sourcePages || []).map((page) => pageByNumber.get(page)).filter(Boolean);
+    if (!imagePaths.length) continue;
+    const current = nextByQuestion.get(questionId);
+    const agent = await callVisionAgent({
+      timeoutMs: 90000,
+      retries: 1,
+      system: systemPrompt,
+      text: promptPayload({
+        task: '对单题进行自动二次复核。目标是尽量减少 needs_review，但不能猜测看不清内容。',
+        requirements: [
+          '只复核这一题。',
+          '可以改判为 correct/partial/wrong/unrecognized。',
+          '只有题号或作答证据仍矛盾时才保留 needs_review。',
+          '保留 initialStatus 和说明改判原因。'
+        ],
+        context: {
+          question: compactPracticeForPrompt({ ...practice, questions: [question] }).questions[0],
+          stitchedAnswer: stitched,
+          initialGrading: current
+        },
+        schema: {
+          questionId,
+          recognizedAnswer: 'string',
+          status: 'correct|partial|wrong|unrecognized|needs_review',
+          score: 0,
+          maxScore: question.score || 0,
+          confidence: 'high|medium|low',
+          positiveFeedback: 'string',
+          errorTypes: ['string'],
+          comment: 'string',
+          mistakeSummary: 'string',
+          referenceAnswer: 'string',
+          solutionMethod: ['string'],
+          teachingHint: 'string',
+          reviewReason: 'string'
+        }
+      }),
+      imagePaths
+    });
+    if (!agent.ok || agent.data?.questionId !== questionId) {
+      await log('recheck.skipped', {
+        questionId,
+        reason: agent.ok ? 'question_id_mismatch' : agent.reason
+      });
+      continue;
+    }
+    const normalized = normalizeGradingResult(
+      { grading: [{ ...agent.data, sourcePages: stitched.sourcePages }] },
+      { ...practice, questions: [question] },
+      [stitched]
+    ).grading[0];
+    nextByQuestion.set(questionId, {
+      ...current,
+      ...normalized,
+      initialStatus: current.status,
+      reviewPasses: Number(current.reviewPasses || 1) + 1,
+      reviewReason: normalized.reviewReason || agent.data.reviewReason || '自动二次复核'
+    });
+    recheckedQuestionIds.push(questionId);
+    await log('recheck.done', {
+      questionId,
+      initialStatus: current.status,
+      finalStatus: normalized.status
+    });
+  }
+
+  return {
+    gradingResult: {
+      ...gradingResult,
+      grading: gradingResult.grading.map((item) => nextByQuestion.get(item.questionId) || item)
+    },
+    recheckedQuestionIds
+  };
+}
+
+function selfCheck({ practice, gradingResult, recheckedQuestionIds }) {
+  const expectedIds = new Set((practice.questions || []).map((question) => question.id));
+  const actualIds = new Set((gradingResult.grading || []).map((item) => item.questionId));
+  const missingQuestionIds = [...expectedIds].filter((id) => !actualIds.has(id));
+  const unknownQuestionIds = [...actualIds].filter((id) => !expectedIds.has(id));
+  const scoreIssues = (gradingResult.grading || [])
+    .filter((item) => Number(item.score || 0) > Number(item.maxScore || 0) || Number(item.score || 0) < 0)
+    .map((item) => item.questionId);
+  return {
+    passed: !missingQuestionIds.length && !unknownQuestionIds.length && !scoreIssues.length,
+    missingQuestionIds,
+    unknownQuestionIds,
+    scoreIssues,
+    recheckedQuestionIds
+  };
+}
+
+function shouldAutoArchive({ gradingResult, forceArchive }) {
+  if (forceArchive) return true;
+  if (gradingResult.source !== 'agent') return false;
+  const stats = gradingStats(gradingResult.grading || []);
+  return stats.totalQuestions > 0 && stats.needsReview <= Math.ceil(stats.totalQuestions * 0.15);
+}
+
+export async function gradePdfSubmission({
+  practiceId,
+  pdfPath,
+  notes = '',
+  autoArchive = true,
+  forceArchive = false,
+  submissionId = '',
+  useAgent = true,
+  maxRechecks = 12,
+  gradingBatchSize = 5,
+  onProgress = null
+}) {
+  const resolvedPdfPath = path.resolve(pdfPath);
+  const practice = await readPractice(practiceId);
+  const chapterPaths = await ensureChapterDataDirs(practice.chapterId);
+  const id = submissionId || `submission-${new Date().toISOString().replace(/[:.]/g, '-')}-${randomUUID().slice(0, 8)}`;
+  const submissionDir = path.join(chapterPaths.submissions, id);
+  const pagesDir = path.join(submissionDir, 'pages');
+  const pageExtractsDir = path.join(submissionDir, 'page_extracts');
+  await mkdir(pageExtractsDir, { recursive: true });
+  const processLogPath = path.join(submissionDir, 'process_log.jsonl');
+  await writeFile(processLogPath, '', 'utf8');
+  const log = createProgressLogger({ logPath: processLogPath, onProgress });
+  await log('submission.start', {
+    submissionId: id,
+    practiceId: practice.id,
+    pdfPath: relativeDataPath(resolvedPdfPath),
+    useAgent,
+    autoArchive,
+    forceArchive
+  });
+
+  const submission = {
+    id,
+    practiceId: practice.id,
+    chapterId: practice.chapterId,
+    status: 'pdf_received',
+    notes,
+    pdfPath: relativeDataPath(resolvedPdfPath),
+    photoPaths: [],
+    gradingResult: null,
+    parentConfirmed: false,
+    createdAt: new Date().toISOString()
+  };
+  await writeSubmissionMirrors(submission);
+
+  await log('pdf_render.start', { pdfPath: relativeDataPath(resolvedPdfPath) });
+  const pageImages = await renderPdfPages({ pdfPath: resolvedPdfPath, pagesDir });
+  await log('pdf_render.done', {
+    pageCount: pageImages.length,
+    pagesDir: relativeDataPath(pagesDir)
+  });
+  const pageExtracts = [];
+  for (const pageImage of pageImages) {
+    await log('page_extract.start', {
+      page: pageImage.page,
+      totalPages: pageImages.length,
+      imagePath: relativeDataPath(pageImage.imagePath)
+    });
+    const outputPath = path.join(pageExtractsDir, `page-${String(pageImage.page).padStart(3, '0')}.json`);
+    pageExtracts.push(await extractPageAnswers({
+      practice,
+      pageImage,
+      outputPath,
+      useAgent,
+      totalPages: pageImages.length,
+      log
+    }));
+  }
+
+  const mismatches = practiceMismatchWarnings(pageExtracts);
+  if (mismatches.length) {
+    await log('practice_match.failed', {
+      mismatchPages: mismatches.map((item) => item.page),
+      warnings: mismatches
+    });
+  }
+  assertPracticeMatchesSubmission(practice, pageExtracts);
+
+  await log('stitch.start', { pageExtracts: pageExtracts.length });
+  const stitchedAnswers = stitchPageAnswers(practice, pageExtracts);
+  const stitchedPath = path.join(submissionDir, 'stitched_answers.json');
+  await writeJson(stitchedPath, stitchedAnswers);
+  await log('stitch.done', {
+    questions: stitchedAnswers.length,
+    answersFound: stitchedAnswers.filter((item) => item.mergedAnswer).length,
+    warnings: stitchedAnswers.filter((item) => item.warnings?.length).length
+  });
+
+  await log('grading.start', {
+    questions: practice.questions.length,
+    batchSize: gradingBatchSize
+  });
+  let gradingResult = await gradeStitchedAnswers({
+    practice,
+    stitchedAnswers,
+    useAgent,
+    batchSize: gradingBatchSize,
+    log
+  });
+  await log('grading.done', {
+    source: gradingResult.source,
+    gradedQuestions: gradingResult.grading.length,
+    agentReason: gradingResult.agentReason || null
+  });
+
+  await log('recheck.plan', {
+    maxRechecks
+  });
+  const recheck = await recheckQuestions({
+    practice,
+    gradingResult,
+    stitchedAnswers,
+    pageImages,
+    maxRechecks,
+    log
+  });
+  gradingResult = recheck.gradingResult;
+
+  await log('artifacts.start');
+  const check = selfCheck({ practice, gradingResult, recheckedQuestionIds: recheck.recheckedQuestionIds });
+  const knowledgeEvidence = buildKnowledgeEvidence({ practice, grading: gradingResult.grading, stitchedAnswers });
+  const weakPoints = buildWeakPoints({ practice, grading: gradingResult.grading, knowledgeEvidence });
+  const correctionPack = buildCorrectionPackMarkdown({ practice, grading: gradingResult.grading, weakPoints });
+  const positiveReport = buildPositiveReportMarkdown({
+    practice,
+    gradingResult,
+    knowledgeEvidence,
+    weakPoints,
+    selfCheck: check
+  });
+
+  await writeJson(path.join(submissionDir, 'grading.json'), gradingResult);
+  await writeJson(path.join(submissionDir, 'knowledge_evidence.json'), knowledgeEvidence);
+  await writeJson(path.join(submissionDir, 'weak_points.json'), weakPoints);
+  await writeJson(path.join(submissionDir, 'self_check.json'), check);
+  await writeFile(path.join(submissionDir, 'correction_pack.md'), correctionPack, 'utf8');
+  await writeFile(path.join(submissionDir, 'positive_report.md'), positiveReport, 'utf8');
+  await log('artifacts.done', {
+    selfCheckPassed: check.passed,
+    weakPoints: weakPoints.length
+  });
+
+  const gradedSubmission = {
+    ...submission,
+    status: 'graded',
+    pageImagePaths: pageImages.map((item) => relativeDataPath(item.imagePath)),
+    gradingResult,
+      artifactPaths: {
+        submissionDir: relativeDataPath(submissionDir),
+        originalPdf: relativeDataPath(resolvedPdfPath),
+        stitchedAnswers: relativeDataPath(stitchedPath),
+      grading: relativeDataPath(path.join(submissionDir, 'grading.json')),
+      knowledgeEvidence: relativeDataPath(path.join(submissionDir, 'knowledge_evidence.json')),
+      weakPoints: relativeDataPath(path.join(submissionDir, 'weak_points.json')),
+      correctionPack: relativeDataPath(path.join(submissionDir, 'correction_pack.md')),
+      positiveReport: relativeDataPath(path.join(submissionDir, 'positive_report.md')),
+      selfCheck: relativeDataPath(path.join(submissionDir, 'self_check.json')),
+      processLog: relativeDataPath(processLogPath)
+    },
+    gradedAt: new Date().toISOString()
+  };
+  await writeSubmissionMirrors(gradedSubmission);
+
+  let archivedSubmission = null;
+  if (autoArchive && shouldAutoArchive({ gradingResult, forceArchive })) {
+    await log('archive.start');
+    archivedSubmission = await confirmSubmission({
+      submissionId: id,
+      grading: gradingResult.grading,
+      parentSummary: gradingResult.summary || ''
+    });
+    if (practice.type !== 'ability_assessment') {
+      await syncKnowledgeMasteryMarkers(practice.chapterId);
+    }
+    await log('archive.done', {
+      accuracy: archivedSubmission.accuracy,
+      status: archivedSubmission.status
+    });
+  } else {
+    await log('archive.skipped', {
+      autoArchive,
+      source: gradingResult.source,
+      forceArchive,
+      needsReview: gradingStats(gradingResult.grading).needsReview
+    });
+  }
+
+  await log('submission.done', {
+    archived: Boolean(archivedSubmission),
+    stats: gradingStats(gradingResult.grading)
+  });
+
+  return {
+    submission: archivedSubmission || gradedSubmission,
+    archived: Boolean(archivedSubmission),
+    practiceId: practice.id,
+    chapterId: practice.chapterId,
+    pageCount: pageImages.length,
+    stats: gradingStats(gradingResult.grading),
+    source: gradingResult.source,
+    agentReason: gradingResult.agentReason || null,
+    selfCheck: check,
+    artifacts: gradedSubmission.artifactPaths,
+    weakPoints: weakPoints.slice(0, 10),
+    pdfLabel: argSafeFilename(resolvedPdfPath)
+  };
+}