Start Study Desk V2: remove V1 sources, add backend foundation
V1 remains intact on main and in history. This branch replaces it with a new application: node:sqlite storage with migrations, scrypt auth and sessions, content/SRS/attempt/stats services, document extraction and chunking, a provider-neutral AI layer (OpenAI, Anthropic, Gemini, OpenAI-compatible, Ollama), the generation pipeline and the tool-using assistant. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
This commit is contained in:
parent
7bd0a9aad4
commit
3e74ecd843
268 changed files with 17740 additions and 55423 deletions
431
server/services/attempts.ts
Normal file
431
server/services/attempts.ts
Normal file
|
|
@ -0,0 +1,431 @@
|
|||
/**
|
||||
* Quiz sessions. An attempt freezes its questions (and their shuffled answer order) in a
|
||||
* snapshot when it starts, so editing or deleting the quiz later can never corrupt a session
|
||||
* in progress or the review of a finished one.
|
||||
*/
|
||||
import { z } from 'zod';
|
||||
import { isFullyCorrect, scoreQuestion, seededShuffle, type Option, type QuestionType, type SataScoring } from '../../shared/content.ts';
|
||||
import type { DB } from '../db.ts';
|
||||
import { badRequest, notFound } from '../http.ts';
|
||||
import { newId, now, parseJson } from '../util.ts';
|
||||
import { getClass, getQuiz, mapQuestion, type QuestionRow } from './content.ts';
|
||||
|
||||
export interface SnapshotQuestion {
|
||||
id: string;
|
||||
quizId: string | null;
|
||||
quizTitle: string;
|
||||
type: QuestionType;
|
||||
stem: string;
|
||||
options: Option[];
|
||||
rationale: string;
|
||||
topic: string;
|
||||
difficulty: string;
|
||||
}
|
||||
|
||||
export interface AnswerState {
|
||||
selected: string[];
|
||||
/** Practice mode: the answer has been checked and feedback shown. */
|
||||
checked: boolean;
|
||||
at: number;
|
||||
}
|
||||
|
||||
export interface AttemptSettings {
|
||||
shuffleQuestions: boolean;
|
||||
shuffleOptions: boolean;
|
||||
timeLimitSec: number | null;
|
||||
sataScoring: SataScoring;
|
||||
}
|
||||
|
||||
interface AttemptRow {
|
||||
id: string;
|
||||
quiz_id: string | null;
|
||||
class_id: string | null;
|
||||
title: string;
|
||||
mode: 'practice' | 'exam';
|
||||
kind: string;
|
||||
status: 'active' | 'completed';
|
||||
settings: string;
|
||||
snapshot: string;
|
||||
answers: string;
|
||||
flags: string;
|
||||
current_index: number;
|
||||
elapsed_sec: number;
|
||||
question_count: number;
|
||||
score: number | null;
|
||||
max_score: number | null;
|
||||
started_at: number;
|
||||
updated_at: number;
|
||||
completed_at: number | null;
|
||||
}
|
||||
|
||||
export const attemptCreateSchema = z.object({
|
||||
mode: z.enum(['practice', 'exam']).default('practice'),
|
||||
source: z.discriminatedUnion('type', [
|
||||
z.object({ type: z.literal('quiz'), quizId: z.string() }),
|
||||
/** Questions missed in one finished attempt. */
|
||||
z.object({ type: z.literal('retake'), attemptId: z.string() }),
|
||||
/** Questions answered wrong most often, across a class or everything. */
|
||||
z.object({ type: z.literal('missed'), classId: z.string().optional(), quizId: z.string().optional() }),
|
||||
/** Every question on the given topics within a class. */
|
||||
z.object({ type: z.literal('topics'), classId: z.string(), topics: z.array(z.string()).min(1).max(50) }),
|
||||
z.object({ type: z.literal('questions'), questionIds: z.array(z.string()).min(1).max(1000), title: z.string().max(200).optional() }),
|
||||
]),
|
||||
shuffleQuestions: z.boolean().default(true),
|
||||
shuffleOptions: z.boolean().default(true),
|
||||
count: z.number().int().min(1).max(1000).optional(),
|
||||
timeLimitMin: z.number().min(1).max(600).nullish(),
|
||||
});
|
||||
export type AttemptCreate = z.input<typeof attemptCreateSchema>;
|
||||
|
||||
const PINNED_OPTION = /^(all|none|both|neither)\b.*\b(above|these|options|answers)\b|^(a|b|c|d)\s*(and|&)\s*(a|b|c|d)\b/i;
|
||||
|
||||
/** Shuffles options but keeps "All of the above"-style choices at the end. */
|
||||
function shuffleOptions(options: Option[], seed: number): Option[] {
|
||||
const pinned = options.filter((o) => PINNED_OPTION.test(o.text.trim()));
|
||||
const free = options.filter((o) => !PINNED_OPTION.test(o.text.trim()));
|
||||
return [...seededShuffle(free, seed), ...pinned];
|
||||
}
|
||||
|
||||
function loadQuestionRows(db: DB, ids: string[]): (QuestionRow & { quiz_title: string })[] {
|
||||
if (ids.length === 0) return [];
|
||||
const out: (QuestionRow & { quiz_title: string })[] = [];
|
||||
for (let i = 0; i < ids.length; i += 400) {
|
||||
const batch = ids.slice(i, i + 400);
|
||||
out.push(
|
||||
...db.all<QuestionRow & { quiz_title: string }>(
|
||||
`SELECT q.*, z.title AS quiz_title FROM questions q JOIN quizzes z ON z.id = q.quiz_id WHERE q.id IN (${batch.map(() => '?').join(',')})`,
|
||||
...batch,
|
||||
),
|
||||
);
|
||||
}
|
||||
const order = new Map(ids.map((id, i) => [id, i]));
|
||||
return out.sort((a, b) => (order.get(a.id) ?? 0) - (order.get(b.id) ?? 0));
|
||||
}
|
||||
|
||||
/** Question ids ordered from most to least troublesome, using recent responses. */
|
||||
export function missedQuestionIds(db: DB, scope: { classId?: string; quizId?: string }, limit = 200): string[] {
|
||||
const where = scope.quizId ? 'AND r.quiz_id = ?' : scope.classId ? 'AND r.class_id = ?' : '';
|
||||
const params = scope.quizId ? [scope.quizId] : scope.classId ? [scope.classId] : [];
|
||||
const rows = db.all<{ question_id: string }>(
|
||||
`SELECT r.question_id, COUNT(*) AS seen, SUM(CASE WHEN r.correct = 0 THEN 1 ELSE 0 END) AS wrong,
|
||||
(SELECT r2.correct FROM responses r2 WHERE r2.question_id = r.question_id ORDER BY r2.answered_at DESC LIMIT 1) AS last_correct
|
||||
FROM responses r JOIN questions q ON q.id = r.question_id
|
||||
WHERE 1 = 1 ${where}
|
||||
GROUP BY r.question_id
|
||||
HAVING wrong > 0 AND (last_correct = 0 OR wrong * 2 >= seen)
|
||||
ORDER BY last_correct ASC, (wrong * 1.0 / seen) DESC, wrong DESC
|
||||
LIMIT ?`,
|
||||
...params,
|
||||
limit,
|
||||
);
|
||||
return rows.map((r) => r.question_id);
|
||||
}
|
||||
|
||||
export function createAttempt(db: DB, input: AttemptCreate, sataScoring: SataScoring): string {
|
||||
const opts = attemptCreateSchema.parse(input);
|
||||
const src = opts.source;
|
||||
let quizId: string | null = null;
|
||||
let classId: string | null = null;
|
||||
let title = '';
|
||||
let kind = 'full';
|
||||
let rows: (QuestionRow & { quiz_title: string })[] = [];
|
||||
let frozen: SnapshotQuestion[] | null = null;
|
||||
|
||||
if (src.type === 'quiz') {
|
||||
const quiz = getQuiz(db, src.quizId);
|
||||
quizId = quiz.id;
|
||||
classId = quiz.class_id;
|
||||
title = quiz.title;
|
||||
rows = db
|
||||
.all<QuestionRow>('SELECT * FROM questions WHERE quiz_id = ? ORDER BY sort_order, created_at', quiz.id)
|
||||
.map((r) => ({ ...r, quiz_title: quiz.title }));
|
||||
} else if (src.type === 'retake') {
|
||||
const prev = db.get<AttemptRow>('SELECT * FROM attempts WHERE id = ?', src.attemptId);
|
||||
if (!prev) throw notFound('Attempt');
|
||||
const snap = parseJson<{ questions: SnapshotQuestion[] }>(prev.snapshot, { questions: [] });
|
||||
const answers = parseJson<Record<string, AnswerState>>(prev.answers, {});
|
||||
const prevSettings = parseJson<AttemptSettings>(prev.settings, { shuffleQuestions: true, shuffleOptions: true, timeLimitSec: null, sataScoring });
|
||||
const missed = snap.questions.filter((q) => !isFullyCorrect(scoreQuestion(q, answers[q.id]?.selected ?? [], prevSettings.sataScoring)));
|
||||
const current = new Map(loadQuestionRows(db, missed.map((q) => q.id)).map((r) => [r.id, r]));
|
||||
// Prefer the live question (it may have been corrected since); fall back to the frozen copy.
|
||||
frozen = missed.map((q) => {
|
||||
const live = current.get(q.id);
|
||||
if (!live) return q;
|
||||
const m = mapQuestion(live);
|
||||
return { id: m.id, quizId: m.quizId, quizTitle: live.quiz_title, type: m.type, stem: m.stem, options: m.options, rationale: m.rationale, topic: m.topic, difficulty: m.difficulty };
|
||||
});
|
||||
quizId = prev.quiz_id;
|
||||
classId = prev.class_id;
|
||||
title = `${prev.title.replace(/ · missed$/, '')} · missed`;
|
||||
kind = 'retake';
|
||||
} else if (src.type === 'missed') {
|
||||
const ids = missedQuestionIds(db, { classId: src.classId, quizId: src.quizId });
|
||||
rows = loadQuestionRows(db, ids);
|
||||
kind = 'missed';
|
||||
if (src.quizId) {
|
||||
const quiz = getQuiz(db, src.quizId);
|
||||
quizId = quiz.id;
|
||||
classId = quiz.class_id;
|
||||
title = `${quiz.title} · missed`;
|
||||
} else if (src.classId) {
|
||||
classId = src.classId;
|
||||
title = `${getClass(db, src.classId).name} · missed questions`;
|
||||
} else {
|
||||
title = 'Missed questions';
|
||||
}
|
||||
} else if (src.type === 'topics') {
|
||||
const cls = getClass(db, src.classId);
|
||||
classId = cls.id;
|
||||
rows = db.all<QuestionRow & { quiz_title: string }>(
|
||||
`SELECT q.*, z.title AS quiz_title FROM questions q JOIN quizzes z ON z.id = q.quiz_id
|
||||
WHERE z.class_id = ? AND q.topic IN (${src.topics.map(() => '?').join(',')}) ORDER BY z.sort_order, q.sort_order`,
|
||||
cls.id,
|
||||
...src.topics,
|
||||
);
|
||||
title = src.topics.length === 1 ? `${src.topics[0]} · practice` : `${cls.name} · ${src.topics.length} topics`;
|
||||
kind = 'topics';
|
||||
} else {
|
||||
rows = loadQuestionRows(db, src.questionIds);
|
||||
title = src.title ?? 'Custom practice';
|
||||
kind = 'custom';
|
||||
const classes = new Set(rows.map((r) => db.get<{ class_id: string }>('SELECT class_id FROM quizzes WHERE id = ?', r.quiz_id)?.class_id));
|
||||
if (classes.size === 1) classId = [...classes][0] ?? null;
|
||||
}
|
||||
|
||||
let questions: SnapshotQuestion[] =
|
||||
frozen ??
|
||||
rows.map((r) => {
|
||||
const m = mapQuestion(r);
|
||||
return { id: m.id, quizId: m.quizId, quizTitle: r.quiz_title, type: m.type, stem: m.stem, options: m.options, rationale: m.rationale, topic: m.topic, difficulty: m.difficulty };
|
||||
});
|
||||
if (questions.length === 0) {
|
||||
throw badRequest(src.type === 'quiz' ? 'This quiz has no questions yet' : src.type === 'missed' || src.type === 'retake' ? 'No missed questions to review' : 'No questions matched');
|
||||
}
|
||||
|
||||
const seed = (Math.random() * 2 ** 32) >>> 0;
|
||||
if (opts.shuffleQuestions) questions = seededShuffle(questions, seed);
|
||||
if (opts.count && opts.count < questions.length) questions = questions.slice(0, opts.count);
|
||||
if (opts.shuffleOptions) questions = questions.map((q, i) => ({ ...q, options: shuffleOptions(q.options, seed + i + 1) }));
|
||||
|
||||
const settings: AttemptSettings = {
|
||||
shuffleQuestions: opts.shuffleQuestions,
|
||||
shuffleOptions: opts.shuffleOptions,
|
||||
timeLimitSec: opts.timeLimitMin ? Math.round(opts.timeLimitMin * 60) : null,
|
||||
sataScoring,
|
||||
};
|
||||
const id = newId();
|
||||
const at = now();
|
||||
db.run(
|
||||
`INSERT INTO attempts (id, quiz_id, class_id, title, mode, kind, status, settings, snapshot, question_count, started_at, updated_at)
|
||||
VALUES (?, ?, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?)`,
|
||||
id,
|
||||
quizId,
|
||||
classId,
|
||||
title,
|
||||
opts.mode,
|
||||
kind,
|
||||
JSON.stringify(settings),
|
||||
JSON.stringify({ questions }),
|
||||
questions.length,
|
||||
at,
|
||||
at,
|
||||
);
|
||||
return id;
|
||||
}
|
||||
|
||||
function loadAttempt(db: DB, id: string): AttemptRow {
|
||||
const row = db.get<AttemptRow>('SELECT * FROM attempts WHERE id = ?', id);
|
||||
if (!row) throw notFound('Session');
|
||||
return row;
|
||||
}
|
||||
|
||||
function recordResponse(db: DB, row: AttemptRow, q: SnapshotQuestion, selected: string[], sata: SataScoring, at: number): void {
|
||||
const score = scoreQuestion(q, selected, sata);
|
||||
db.run(
|
||||
`INSERT INTO responses (attempt_id, question_id, quiz_id, class_id, topic, score, correct, answered_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
|
||||
ON CONFLICT(attempt_id, question_id) DO UPDATE SET score = excluded.score, correct = excluded.correct, answered_at = excluded.answered_at`,
|
||||
row.id,
|
||||
q.id,
|
||||
q.quizId ?? row.quiz_id,
|
||||
row.class_id,
|
||||
q.topic,
|
||||
score,
|
||||
isFullyCorrect(score) ? 1 : 0,
|
||||
at,
|
||||
);
|
||||
}
|
||||
|
||||
export function mapAttempt(row: AttemptRow) {
|
||||
const settings = parseJson<AttemptSettings>(row.settings, { shuffleQuestions: true, shuffleOptions: true, timeLimitSec: null, sataScoring: 'partial' });
|
||||
const snapshot = parseJson<{ questions: SnapshotQuestion[] }>(row.snapshot, { questions: [] });
|
||||
const answers = parseJson<Record<string, AnswerState>>(row.answers, {});
|
||||
const results =
|
||||
row.status === 'completed'
|
||||
? Object.fromEntries(
|
||||
snapshot.questions.map((q) => {
|
||||
const selected = answers[q.id]?.selected ?? [];
|
||||
const score = scoreQuestion(q, selected, settings.sataScoring);
|
||||
return [q.id, { score, correct: isFullyCorrect(score), answered: selected.length > 0 }];
|
||||
}),
|
||||
)
|
||||
: null;
|
||||
return {
|
||||
id: row.id,
|
||||
quizId: row.quiz_id,
|
||||
classId: row.class_id,
|
||||
title: row.title,
|
||||
mode: row.mode,
|
||||
kind: row.kind,
|
||||
status: row.status,
|
||||
settings,
|
||||
questions: snapshot.questions,
|
||||
answers,
|
||||
flags: parseJson<string[]>(row.flags, []),
|
||||
currentIndex: row.current_index,
|
||||
elapsedSec: row.elapsed_sec,
|
||||
score: row.score,
|
||||
maxScore: row.max_score,
|
||||
startedAt: row.started_at,
|
||||
updatedAt: row.updated_at,
|
||||
completedAt: row.completed_at,
|
||||
results,
|
||||
};
|
||||
}
|
||||
export type AttemptDto = ReturnType<typeof mapAttempt>;
|
||||
|
||||
export const mapAttemptSummary = (row: AttemptRow) => {
|
||||
const answers = parseJson<Record<string, AnswerState>>(row.answers, {});
|
||||
return {
|
||||
id: row.id,
|
||||
quizId: row.quiz_id,
|
||||
classId: row.class_id,
|
||||
title: row.title,
|
||||
mode: row.mode,
|
||||
kind: row.kind,
|
||||
status: row.status,
|
||||
questionCount: row.question_count,
|
||||
answeredCount: Object.values(answers).filter((a) => a.selected.length > 0).length,
|
||||
currentIndex: row.current_index,
|
||||
elapsedSec: row.elapsed_sec,
|
||||
score: row.score,
|
||||
maxScore: row.max_score,
|
||||
startedAt: row.started_at,
|
||||
updatedAt: row.updated_at,
|
||||
completedAt: row.completed_at,
|
||||
};
|
||||
};
|
||||
export type AttemptSummary = ReturnType<typeof mapAttemptSummary>;
|
||||
|
||||
export function getAttempt(db: DB, id: string): AttemptDto {
|
||||
return mapAttempt(loadAttempt(db, id));
|
||||
}
|
||||
|
||||
export const attemptPatchSchema = z.object({
|
||||
answers: z
|
||||
.record(z.string(), z.object({ selected: z.array(z.string().max(40)).max(12), checked: z.boolean().optional().default(false) }))
|
||||
.optional(),
|
||||
flags: z.array(z.string()).max(1000).optional(),
|
||||
currentIndex: z.number().int().min(0).optional(),
|
||||
elapsedSec: z.number().int().min(0).max(1_000_000).optional(),
|
||||
});
|
||||
|
||||
export function patchAttempt(db: DB, id: string, input: z.input<typeof attemptPatchSchema>): AttemptDto {
|
||||
const patch = attemptPatchSchema.parse(input);
|
||||
const row = loadAttempt(db, id);
|
||||
if (row.status !== 'active') throw badRequest('This session is already finished');
|
||||
const snapshot = parseJson<{ questions: SnapshotQuestion[] }>(row.snapshot, { questions: [] });
|
||||
const settings = parseJson<AttemptSettings>(row.settings, { shuffleQuestions: true, shuffleOptions: true, timeLimitSec: null, sataScoring: 'partial' });
|
||||
const answers = parseJson<Record<string, AnswerState>>(row.answers, {});
|
||||
const at = now();
|
||||
db.tx(() => {
|
||||
if (patch.answers) {
|
||||
const byId = new Map(snapshot.questions.map((q) => [q.id, q]));
|
||||
for (const [qid, a] of Object.entries(patch.answers)) {
|
||||
const q = byId.get(qid);
|
||||
if (!q) continue;
|
||||
const prev = answers[qid];
|
||||
// A checked practice answer is final: feedback has been shown.
|
||||
if (prev?.checked && row.mode === 'practice') continue;
|
||||
const valid = new Set(q.options.map((o) => o.id));
|
||||
const selected = [...new Set(a.selected.filter((s) => valid.has(s)))];
|
||||
const checked = row.mode === 'practice' && a.checked && selected.length > 0;
|
||||
answers[qid] = { selected, checked, at };
|
||||
if (checked) recordResponse(db, row, q, selected, settings.sataScoring, at);
|
||||
}
|
||||
}
|
||||
db.run(
|
||||
'UPDATE attempts SET answers = ?, flags = ?, current_index = ?, elapsed_sec = ?, updated_at = ? WHERE id = ?',
|
||||
JSON.stringify(answers),
|
||||
patch.flags ? JSON.stringify(patch.flags) : row.flags,
|
||||
patch.currentIndex !== undefined ? Math.min(patch.currentIndex, Math.max(0, snapshot.questions.length - 1)) : row.current_index,
|
||||
patch.elapsedSec !== undefined ? Math.max(row.elapsed_sec, patch.elapsedSec) : row.elapsed_sec,
|
||||
at,
|
||||
id,
|
||||
);
|
||||
});
|
||||
return getAttempt(db, id);
|
||||
}
|
||||
|
||||
/**
|
||||
* Finishes a session. Exams score every question (blank = wrong). Practice sessions that are
|
||||
* ended early are scored on the questions actually answered.
|
||||
*/
|
||||
export function completeAttempt(db: DB, id: string, elapsedSec?: number): AttemptDto {
|
||||
const row = loadAttempt(db, id);
|
||||
if (row.status === 'completed') return mapAttempt(row);
|
||||
const snapshot = parseJson<{ questions: SnapshotQuestion[] }>(row.snapshot, { questions: [] });
|
||||
const settings = parseJson<AttemptSettings>(row.settings, { shuffleQuestions: true, shuffleOptions: true, timeLimitSec: null, sataScoring: 'partial' });
|
||||
const answers = parseJson<Record<string, AnswerState>>(row.answers, {});
|
||||
const at = now();
|
||||
let score = 0;
|
||||
let max = 0;
|
||||
db.tx(() => {
|
||||
for (const q of snapshot.questions) {
|
||||
const selected = answers[q.id]?.selected ?? [];
|
||||
const answered = selected.length > 0;
|
||||
if (row.mode === 'practice' && !answered) continue;
|
||||
max += 1;
|
||||
score += scoreQuestion(q, selected, settings.sataScoring);
|
||||
const already = row.mode === 'practice' && answers[q.id]?.checked;
|
||||
if (!already) recordResponse(db, row, q, selected, settings.sataScoring, answers[q.id]?.at ?? at);
|
||||
}
|
||||
db.run(
|
||||
`UPDATE attempts SET status = 'completed', score = ?, max_score = ?, completed_at = ?, updated_at = ?, elapsed_sec = ? WHERE id = ?`,
|
||||
score,
|
||||
max,
|
||||
at,
|
||||
at,
|
||||
elapsedSec !== undefined ? Math.max(row.elapsed_sec, elapsedSec) : row.elapsed_sec,
|
||||
id,
|
||||
);
|
||||
});
|
||||
return getAttempt(db, id);
|
||||
}
|
||||
|
||||
export function deleteAttempt(db: DB, id: string): void {
|
||||
const row = loadAttempt(db, id);
|
||||
db.run('DELETE FROM attempts WHERE id = ?', row.id);
|
||||
}
|
||||
|
||||
export function listAttempts(db: DB, filter: { status?: 'active' | 'completed'; quizId?: string; classId?: string; limit?: number }): AttemptSummary[] {
|
||||
const where: string[] = [];
|
||||
const params: (string | number)[] = [];
|
||||
if (filter.status) {
|
||||
where.push('status = ?');
|
||||
params.push(filter.status);
|
||||
}
|
||||
if (filter.quizId) {
|
||||
where.push('quiz_id = ?');
|
||||
params.push(filter.quizId);
|
||||
}
|
||||
if (filter.classId) {
|
||||
where.push('class_id = ?');
|
||||
params.push(filter.classId);
|
||||
}
|
||||
const rows = db.all<AttemptRow>(
|
||||
`SELECT * FROM attempts ${where.length ? `WHERE ${where.join(' AND ')}` : ''} ORDER BY COALESCE(completed_at, updated_at) DESC LIMIT ?`,
|
||||
...params,
|
||||
Math.min(filter.limit ?? 50, 500),
|
||||
);
|
||||
return rows.map(mapAttemptSummary);
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue