feat: quiz bff and grading

ops/README.md

@@ -325,3 +325,13 @@ regeneration (must print 0):
 ```bash
 grep -c '"correct"\|"feedback"' fixtures/quizbank-3.json
 ```
+
+### Grist table `QuizAttempts` (doc `bPfitC7Poc4r2xGRx7FgHL`)
+
+Created one-shot via the Grist API (`/apply` AddTable) on 2026-06-10 — the
+app never creates tables. Columns: `user_sub` Text, `email` Text,
+`course_slug` Text, `quiz_n` Int, `score` Int, `total` Int, `reponses`
+Text (JSON `{questionId: [choiceIds]}`), `date` DateTime (epoch seconds),
+`moodle_synced` Bool. One row per submitted attempt (retakes unlimited,
+best wins); same Bool-filter caveat as Progression — filter `quiz_n` /
+`moodle_synced` in app code, only Text equality filters via the API.

src/lib/grist.ts

@@ -10,7 +10,7 @@ export interface ReadMark {
   id: number;
 }
 
-async function grist<T = unknown>(path: string, init?: RequestInit): Promise<T> {
+export async function grist<T = unknown>(path: string, init?: RequestInit): Promise<T> {
   const res = await fetch(`${BASE()}/api/docs/${DOC()}${path}`, {
     ...init,
     headers: { Authorization: `Bearer ${KEY()}`, 'Content-Type': 'application/json', ...(init?.headers ?? {}) },

src/lib/quiz.test.ts

@@ -0,0 +1,164 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import {
+  mapQuizRecords, mapAttemptRecords, toPublic, gradeQuiz, isPassed, bestByQuiz,
+  type Quiz, type QuizQuestion, type QuizChoice, type QuizAttempt,
+} from './quiz';
+
+// --- helpers -------------------------------------------------------------
+
+const choice = (id: number, correct = false, feedback = ''): QuizChoice =>
+  ({ id, text: `<p>choice ${id}</p>`, correct, feedback });
+
+const question = (id: number, choices: QuizChoice[], single = 1): QuizQuestion =>
+  ({ id, text: `<p>Q${id} ?</p>`, single, choices });
+
+const quiz = (questions: QuizQuestion[], gradepass = 60): Quiz =>
+  ({ quizN: 1, cmid: 51, name: 'Quiz 1 : Découverte', gradepass, questions });
+
+const fixture = JSON.parse(
+  readFileSync(new URL('../../fixtures/quizbank-3.json', import.meta.url), 'utf8'),
+) as { courses: Record<string, { quizzes: { quiz_n: number; cmid: number; name: string; gradepass: number; questions: QuizQuestion[] }[] }> };
+
+// --- mapQuizRecords ------------------------------------------------------
+
+describe('mapQuizRecords', () => {
+  it('parses real QuizBank rows (sanitized fixture) and sorts by quiz_n', () => {
+    // Reverse order on purpose: Grist row order is not guaranteed.
+    const records = [...fixture.courses['3'].quizzes].reverse().map((q, i) => ({
+      id: i + 1,
+      fields: {
+        course_slug: 'kicad-makers', quiz_n: q.quiz_n, cmid: q.cmid,
+        name: q.name, gradepass: q.gradepass,
+        payload: JSON.stringify({ questions: q.questions }),
+      },
+    }));
+    const quizzes = mapQuizRecords({ records });
+    expect(quizzes.map((q) => q.quizN)).toEqual([1, 2, 3, 4]);
+    expect(quizzes[0]).toMatchObject({ cmid: 51, name: 'Quiz 1 : Découverte', gradepass: 60 });
+    for (const q of quizzes) {
+      expect(q.questions).toHaveLength(5);
+      for (const qu of q.questions) expect(qu.choices).toHaveLength(4);
+    }
+  });
+
+  it('skips rows whose payload is not valid JSON', () => {
+    const records = [
+      { id: 1, fields: { course_slug: 's', quiz_n: 2, cmid: 9, name: 'Quiz 2', gradepass: 60, payload: '{broken' } },
+      { id: 2, fields: { course_slug: 's', quiz_n: 1, cmid: 8, name: 'Quiz 1', gradepass: 60, payload: '{"questions":[]}' } },
+    ];
+    const quizzes = mapQuizRecords({ records });
+    expect(quizzes).toHaveLength(1);
+    expect(quizzes[0].quizN).toBe(1);
+  });
+});
+
+// --- toPublic ------------------------------------------------------------
+
+describe('toPublic', () => {
+  it('strips every correct flag and feedback (stringify scan)', () => {
+    const full = quiz([
+      question(106, [choice(421, true, 'Bravo !'), choice(422, false, 'Non : relisez le chapitre 2.')]),
+      question(107, [choice(425, false, 'Raté'), choice(426, true, 'Oui')], 0),
+    ]);
+    const pub = toPublic(full);
+    const dump = JSON.stringify(pub);
+    expect(dump).not.toContain('correct');
+    expect(dump).not.toContain('feedback');
+    expect(dump).not.toContain('Bravo');
+    // structure preserved
+    expect(pub.questions).toHaveLength(2);
+    expect(pub.questions[0].choices.map((c) => c.id)).toEqual([421, 422]);
+    expect(pub.questions[0].text).toBe('<p>Q106 ?</p>');
+    // and the source quiz is untouched
+    expect(full.questions[0].choices[0].correct).toBe(true);
+  });
+});
+
+// --- gradeQuiz -----------------------------------------------------------
+
+describe('gradeQuiz', () => {
+  const single = quiz([
+    question(1, [choice(11, true, 'Exact.'), choice(12, false, 'Faux : voir module 1.')]),
+    question(2, [choice(21, false, 'Non.'), choice(22, true, 'Oui.')]),
+  ]);
+
+  it('scores a fully correct single-choice submission', () => {
+    const r = gradeQuiz(single, { '1': ['11'], '2': ['22'] });
+    expect(r.score).toBe(2);
+    expect(r.total).toBe(2);
+    expect(r.detail.every((d) => d.ok)).toBe(true);
+    expect(r.detail[0].correctIds).toEqual([11]);
+  });
+
+  it('scores 0 on a wrong choice and reports the chosen feedback', () => {
+    const r = gradeQuiz(single, { '1': ['12'], '2': ['22'] });
+    expect(r.score).toBe(1);
+    expect(r.detail[0]).toMatchObject({ questionId: 1, ok: false, chosenIds: [12], feedback: 'Faux : voir module 1.' });
+  });
+
+  it('is all-or-nothing on multi-answer questions', () => {
+    const multi = quiz([question(3, [choice(31, true), choice(32, true), choice(33, false)], 0)]);
+    expect(gradeQuiz(multi, { '3': ['31', '32'] }).score).toBe(1); // exact set
+    expect(gradeQuiz(multi, { '3': ['31'] }).score).toBe(0); // partial
+    expect(gradeQuiz(multi, { '3': ['31', '32', '33'] }).score).toBe(0); // superset
+  });
+
+  it('treats empty or missing answers as 0 points, never throws', () => {
+    const r = gradeQuiz(single, {});
+    expect(r.score).toBe(0);
+    expect(r.total).toBe(2);
+    expect(r.detail.map((d) => d.ok)).toEqual([false, false]);
+    expect(gradeQuiz(single, { '1': [] }).score).toBe(0);
+  });
+});
+
+// --- isPassed ------------------------------------------------------------
+
+describe('isPassed', () => {
+  const five = quiz([1, 2, 3, 4, 5].map((i) => question(i, [choice(i * 10, true), choice(i * 10 + 1)])), 60);
+
+  it('passes at the 60 % boundary (3/5)', () => {
+    expect(isPassed(five, 3)).toBe(true);
+  });
+
+  it('fails below 60 % (2/5)', () => {
+    expect(isPassed(five, 2)).toBe(false);
+  });
+
+  it('defaults to 50 % when gradepass is 0', () => {
+    const noGate = quiz(five.questions, 0);
+    expect(isPassed(noGate, 3)).toBe(true); // 60 % ≥ 50 %
+    expect(isPassed(noGate, 2)).toBe(false); // 40 % < 50 %
+  });
+
+  it('honours an explicit attempt total over the question count', () => {
+    expect(isPassed(five, 3, 5)).toBe(true);
+    expect(isPassed(five, 3, 6)).toBe(false); // 50 % < 60 %
+  });
+});
+
+// --- attempts ------------------------------------------------------------
+
+describe('mapAttemptRecords / bestByQuiz', () => {
+  it('maps raw Grist attempt rows with safe coercions', () => {
+    const raw = {
+      records: [
+        { id: 4, fields: { user_sub: 'kc-1', email: 'a@b.c', course_slug: 'kicad-makers', quiz_n: 1, score: 4, total: 5, reponses: '{"106":["421"]}', date: 1760000000, moodle_synced: 0 } },
+        { id: 5, fields: { quiz_n: '2', score: null, total: undefined, moodle_synced: true } },
+      ],
+    };
+    expect(mapAttemptRecords(raw)).toEqual([
+      { id: 4, quiz_n: 1, score: 4, total: 5, reponses: '{"106":["421"]}', date: 1760000000, moodle_synced: false },
+      { id: 5, quiz_n: 2, score: 0, total: 0, reponses: '', date: 0, moodle_synced: true },
+    ]);
+  });
+
+  it('keeps the best attempt per quiz, newest on tie', () => {
+    const att = (id: number, quizN: number, score: number, date: number): QuizAttempt =>
+      ({ id, quiz_n: quizN, score, total: 5, reponses: '', date, moodle_synced: false });
+    const best = bestByQuiz([att(1, 1, 2, 100), att(2, 1, 4, 200), att(3, 2, 3, 300), att(4, 2, 3, 400)]);
+    expect(best.get(1)?.id).toBe(2); // higher score wins
+    expect(best.get(2)?.id).toBe(4); // tie → newest
+  });
+});

src/lib/quiz.ts

@@ -0,0 +1,163 @@
+import { swrCache } from './cache';
+import { grist } from './grist';
+
+export interface QuizChoice { id: number; text: string; correct?: boolean; feedback?: string; }
+export interface QuizQuestion { id: number; text: string; single: number; choices: QuizChoice[]; }
+export interface Quiz { quizN: number; cmid: number; name: string; gradepass: number; questions: QuizQuestion[]; }
+
+export interface PublicChoice { id: number; text: string; }
+export interface PublicQuestion { id: number; text: string; single: number; choices: PublicChoice[]; }
+export interface PublicQuiz { quizN: number; cmid: number; name: string; gradepass: number; questions: PublicQuestion[]; }
+
+type RawRecords = { records: { id: number; fields: Record<string, unknown> }[] };
+
+const TTL = Number(process.env.GRIST_CACHE_TTL_MS || 5 * 60_000);
+
+/** Map Grist QuizBank rows → Quiz[] sorted by quiz_n. Rows whose payload
+ *  does not parse are skipped (logged) rather than poisoning the course. */
+export function mapQuizRecords(raw: RawRecords): Quiz[] {
+  const out: Quiz[] = [];
+  for (const r of raw.records) {
+    try {
+      const payload = JSON.parse(String(r.fields.payload ?? '')) as { questions?: QuizQuestion[] };
+      out.push({
+        quizN: Number(r.fields.quiz_n ?? 0),
+        cmid: Number(r.fields.cmid ?? 0),
+        name: String(r.fields.name ?? ''),
+        gradepass: Number(r.fields.gradepass ?? 0),
+        questions: Array.isArray(payload.questions) ? payload.questions : [],
+      });
+    } catch (err) {
+      console.error(`[quiz] bad QuizBank payload (row ${r.id}): ${(err as Error).message}`);
+    }
+  }
+  return out.sort((a, b) => a.quizN - b.quizN);
+}
+
+const fetchQuizzes = async (slug: string): Promise<Quiz[]> => {
+  const filter = encodeURIComponent(JSON.stringify({ course_slug: [slug] }));
+  return mapQuizRecords(await grist<RawRecords>(`/tables/QuizBank/records?filter=${filter}`));
+};
+const cachedQuizzes = swrCache(fetchQuizzes, TTL);
+
+/** Full quizzes of a course (WITH correct flags + feedback — server-side only). */
+export const getQuizzes = (slug: string): Promise<Quiz[]> => cachedQuizzes(slug);
+
+/** Deep-strip correct flags and feedback before anything reaches the client. */
+export function toPublic(quiz: Quiz): PublicQuiz {
+  return {
+    quizN: quiz.quizN, cmid: quiz.cmid, name: quiz.name, gradepass: quiz.gradepass,
+    questions: quiz.questions.map((q) => ({
+      id: q.id, text: q.text, single: q.single,
+      choices: q.choices.map((c) => ({ id: c.id, text: c.text })),
+    })),
+  };
+}
+
+export interface QuestionResult {
+  questionId: number;
+  ok: boolean;
+  chosenIds: number[];
+  correctIds: number[];
+  /** Feedback of the chosen choice(s), '' when none. */
+  feedback: string;
+}
+
+/** All-or-nothing per question: chosen id set must equal the correct id set.
+ *  `answers` keys are question ids (string), values are choice ids (string). */
+export function gradeQuiz(quiz: Quiz, answers: Record<string, string[]>): { score: number; total: number; detail: QuestionResult[] } {
+  const detail = quiz.questions.map((q) => {
+    const chosenIds = (answers[String(q.id)] ?? []).map(Number).filter(Number.isInteger);
+    const correctIds = q.choices.filter((c) => c.correct).map((c) => c.id);
+    const chosen = new Set(chosenIds);
+    const ok = correctIds.length > 0 && chosen.size === correctIds.length && correctIds.every((id) => chosen.has(id));
+    const feedback = q.choices
+      .filter((c) => chosen.has(c.id) && c.feedback)
+      .map((c) => c.feedback as string)
+      .join(' ');
+    return { questionId: q.id, ok, chosenIds, correctIds, feedback };
+  });
+  return { score: detail.filter((d) => d.ok).length, total: quiz.questions.length, detail };
+}
+
+/** gradepass is a percentage (Moodle grade_items); 0/unset → 50 % default. */
+export function isPassed(quiz: Pick<Quiz, 'gradepass' | 'questions'>, score: number, total = quiz.questions.length): boolean {
+  if (total <= 0) return false;
+  const pct = (score / total) * 100;
+  return quiz.gradepass > 0 ? pct >= quiz.gradepass : pct >= 50;
+}
+
+// --- QuizAttempts (Grist) --------------------------------------------------
+
+export interface QuizAttempt {
+  id: number;
+  quiz_n: number;
+  score: number;
+  total: number;
+  reponses: string; // JSON Record<questionId, choiceIds[]>
+  date: number; // epoch seconds
+  moodle_synced: boolean;
+}
+
+export function mapAttemptRecords(raw: RawRecords): QuizAttempt[] {
+  return raw.records.map((r) => ({
+    id: r.id,
+    quiz_n: Number(r.fields.quiz_n ?? 0),
+    score: Number(r.fields.score ?? 0),
+    total: Number(r.fields.total ?? 0),
+    reponses: String(r.fields.reponses ?? ''),
+    date: Number(r.fields.date ?? 0),
+    moodle_synced: Boolean(r.fields.moodle_synced),
+  }));
+}
+
+/** All attempts of a user on a course. Only Text equality filters are
+ *  reliable in the Grist API (see ops/README.md) — quiz_n and moodle_synced
+ *  are filtered in app code. */
+export async function getAttempts(sub: string, courseSlug: string): Promise<QuizAttempt[]> {
+  const filter = encodeURIComponent(JSON.stringify({ user_sub: [sub], course_slug: [courseSlug] }));
+  return mapAttemptRecords(await grist<RawRecords>(`/tables/QuizAttempts/records?filter=${filter}`));
+}
+
+export async function addAttempt(
+  user: { sub: string; email: string },
+  courseSlug: string,
+  quizN: number,
+  score: number,
+  total: number,
+  answers: Record<string, string[]>,
+): Promise<void> {
+  await grist('/tables/QuizAttempts/records', {
+    method: 'POST',
+    body: JSON.stringify({
+      records: [{
+        fields: {
+          user_sub: user.sub, email: user.email, course_slug: courseSlug,
+          quiz_n: quizN, score, total,
+          reponses: JSON.stringify(answers),
+          date: Math.floor(Date.now() / 1000), // Grist DateTime accepts epoch seconds
+          moodle_synced: false,
+        },
+      }],
+    }),
+  });
+}
+
+/** Best attempt per quiz_n (highest score, newest on tie). */
+export function bestByQuiz(attempts: QuizAttempt[]): Map<number, QuizAttempt> {
+  const best = new Map<number, QuizAttempt>();
+  for (const a of attempts) {
+    const cur = best.get(a.quiz_n);
+    if (!cur || a.score > cur.score || (a.score === cur.score && (a.date > cur.date || (a.date === cur.date && a.id > cur.id))))
+      best.set(a.quiz_n, a);
+  }
+  return best;
+}
+
+export async function markAttemptsSynced(ids: number[]): Promise<void> {
+  if (!ids.length) return;
+  await grist('/tables/QuizAttempts/records', {
+    method: 'PATCH',
+    body: JSON.stringify({ records: ids.map((id) => ({ id, fields: { moodle_synced: true } })) }),
+  });
+}