Study/server/routes/study.ts
Elijah 3e74ecd843 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>
2026-11-11 08:16:41 -07:00

201 lines
9 KiB
TypeScript

import { Hono } from 'hono';
import { z } from 'zod';
import { badRequest, idParam, readBody, type AppContext } from '../http.ts';
import { getAppSettings } from '../settings.ts';
import {
attemptCreateSchema,
attemptPatchSchema,
completeAttempt,
createAttempt,
deleteAttempt,
getAttempt,
listAttempts,
missedQuestionIds,
patchAttempt,
} from '../services/attempts.ts';
import { answerCard, buildQueue, dueCounts, forecast, logCram, undoReview, type RatingValue } from '../services/srs.ts';
import { accuracyTrend, activityByDay, computeStreak, topicStats, totals, weakTopics } from '../services/stats.ts';
import { ftsQuery } from '../util.ts';
export function studyRoutes(app: AppContext): Hono {
const { db } = app;
const r = new Hono();
const settings = () => getAppSettings(db, app.config.timezone);
/* ------------------------------ quiz sessions ------------------------------ */
r.post('/attempts', async (c) => {
const body = await readBody(c, attemptCreateSchema);
const id = createAttempt(db, body, settings().sataScoring);
return c.json({ attempt: getAttempt(db, id) }, 201);
});
r.get('/attempts', (c) => {
const status = c.req.query('status');
return c.json({
attempts: listAttempts(db, {
status: status === 'active' || status === 'completed' ? status : undefined,
quizId: c.req.query('quizId') || undefined,
classId: c.req.query('classId') || undefined,
limit: Number(c.req.query('limit') ?? 50) || 50,
}),
});
});
r.get('/attempts/:id', (c) => c.json({ attempt: getAttempt(db, idParam(c)) }));
r.patch('/attempts/:id', async (c) => {
const body = await readBody(c, attemptPatchSchema);
return c.json({ attempt: patchAttempt(db, idParam(c), body) });
});
r.post('/attempts/:id/complete', async (c) => {
const body = (await c.req.json().catch(() => ({}))) as { elapsedSec?: unknown };
const elapsed = typeof body.elapsedSec === 'number' && Number.isFinite(body.elapsedSec) ? Math.max(0, Math.round(body.elapsedSec)) : undefined;
return c.json({ attempt: completeAttempt(db, idParam(c), elapsed) });
});
r.delete('/attempts/:id', (c) => {
deleteAttempt(db, idParam(c));
return c.json({ ok: true });
});
/* ------------------------------ spaced repetition ------------------------------ */
r.get('/review/queue', (c) => {
const scope = { deckId: c.req.query('deckId') || undefined, classId: c.req.query('classId') || undefined };
const limit = Math.min(Number(c.req.query('limit') ?? 100) || 100, 300);
return c.json(buildQueue(db, scope, settings(), limit));
});
r.post('/review/answer', async (c) => {
const body = await readBody(c, z.object({ cardId: z.string(), rating: z.number().int().min(1).max(4) }));
return c.json({ result: answerCard(db, body.cardId, body.rating as RatingValue, settings()) });
});
r.post('/review/undo', async (c) => {
const body = await readBody(c, z.object({ cardId: z.string() }));
return c.json({ result: undoReview(db, body.cardId, settings()) });
});
r.post('/review/cram', async (c) => {
const body = await readBody(c, z.object({ cardId: z.string(), known: z.boolean() }));
logCram(db, body.cardId, body.known);
return c.json({ ok: true });
});
/* ------------------------------ dashboards ------------------------------ */
r.get('/overview', (c) => {
const s = settings();
const days = activityByDay(db, s, 26 * 7);
return c.json({
settings: s,
due: dueCounts(db, {}, s),
streak: computeStreak(days, s.dailyGoal),
activity: days,
activeAttempts: listAttempts(db, { status: 'active', limit: 6 }),
recentAttempts: listAttempts(db, { status: 'completed', limit: 6 }),
weakTopics: weakTopics(db, {}, 6),
missedCount: missedQuestionIds(db, {}, 500).length,
totals: totals(db, s, {}, 7),
forecast: forecast(db, {}, s, 7),
});
});
r.get('/insights', (c) => {
const s = settings();
const classId = c.req.query('classId') || undefined;
const range = Math.min(Math.max(Number(c.req.query('days') ?? 30) || 30, 7), 365);
const scope = { classId };
const days = activityByDay(db, s, 53 * 7, scope);
return c.json({
range,
totals: totals(db, s, scope, range),
streak: computeStreak(activityByDay(db, s, 53 * 7), s.dailyGoal),
activity: days,
accuracy: accuracyTrend(db, s, range, scope),
topics: topicStats(db, scope, range),
forecast: forecast(db, scope, s, 14),
due: dueCounts(db, scope, s),
missedCount: missedQuestionIds(db, scope, 500).length,
recentAttempts: listAttempts(db, { status: 'completed', classId, limit: 15 }),
});
});
/* ------------------------------ search ------------------------------ */
r.get('/search', (c) => {
const q = (c.req.query('q') ?? '').trim().slice(0, 120);
if (q.length < 2) return c.json({ query: q, results: [] });
const like = `%${q.replace(/[\\%_]/g, (m) => `\\${m}`)}%`;
const classId = c.req.query('classId') || null;
const scoped = (col: string) => (classId ? `AND ${col} = ?` : '');
const p = (...base: string[]) => (classId ? [...base, classId] : base);
type Hit = { kind: string; id: string; title: string; snippet: string; classId: string; className: string; classColor: string; parentId?: string; page?: number | null };
const results: Hit[] = [];
for (const row of db.all<Record<string, string>>(`SELECT id, name, color FROM classes WHERE name LIKE ? ESCAPE '\\' OR code LIKE ? ESCAPE '\\' LIMIT 5`, like, like)) {
results.push({ kind: 'class', id: row.id, title: row.name, snippet: '', classId: row.id, className: row.name, classColor: row.color });
}
const simple = (kind: string, table: string) => {
for (const row of db.all<Record<string, string>>(
`SELECT t.id, t.title, k.id AS class_id, k.name AS class_name, k.color AS class_color FROM ${table} t JOIN classes k ON k.id = t.class_id
WHERE t.title LIKE ? ESCAPE '\\' ${scoped('t.class_id')} ORDER BY t.updated_at DESC LIMIT 8`,
...p(like),
)) {
results.push({ kind, id: row.id, title: row.title, snippet: '', classId: row.class_id, className: row.class_name, classColor: row.class_color });
}
};
simple('quiz', 'quizzes');
simple('deck', 'decks');
simple('note', 'notes');
simple('document', 'documents');
for (const row of db.all<Record<string, string>>(
`SELECT q.id, q.stem, z.id AS quiz_id, z.title AS quiz_title, k.id AS class_id, k.name AS class_name, k.color AS class_color
FROM questions q JOIN quizzes z ON z.id = q.quiz_id JOIN classes k ON k.id = z.class_id
WHERE (q.stem LIKE ? ESCAPE '\\' OR q.topic LIKE ? ESCAPE '\\') ${scoped('z.class_id')} LIMIT 10`,
...p(like, like),
)) {
results.push({ kind: 'question', id: row.id, parentId: row.quiz_id, title: row.stem.slice(0, 140), snippet: row.quiz_title, classId: row.class_id, className: row.class_name, classColor: row.class_color });
}
for (const row of db.all<Record<string, string>>(
`SELECT c.id, c.front, c.back, d.id AS deck_id, d.title AS deck_title, k.id AS class_id, k.name AS class_name, k.color AS class_color
FROM cards c JOIN decks d ON d.id = c.deck_id JOIN classes k ON k.id = d.class_id
WHERE (c.front LIKE ? ESCAPE '\\' OR c.back LIKE ? ESCAPE '\\') ${scoped('d.class_id')} LIMIT 10`,
...p(like, like),
)) {
results.push({ kind: 'card', id: row.id, parentId: row.deck_id, title: row.front.slice(0, 140), snippet: row.deck_title, classId: row.class_id, className: row.class_name, classColor: row.class_color });
}
const match = ftsQuery(q, 'and');
if (match) {
try {
for (const row of db.all<Record<string, any>>(
`SELECT ch.id, ch.page_start, d.id AS doc_id, d.title AS doc_title, k.id AS class_id, k.name AS class_name, k.color AS class_color,
snippet(chunks_fts, 0, '', '', ' … ', 18) AS snip
FROM chunks_fts JOIN chunks ch ON ch.id = chunks_fts.rowid JOIN documents d ON d.id = ch.document_id JOIN classes k ON k.id = d.class_id
WHERE chunks_fts MATCH ? ${scoped('d.class_id')} ORDER BY bm25(chunks_fts) LIMIT 10`,
...p(match),
)) {
results.push({ kind: 'passage', id: String(row.id), parentId: row.doc_id, page: row.page_start, title: row.doc_title, snippet: row.snip, classId: row.class_id, className: row.class_name, classColor: row.class_color });
}
} catch {
/* a malformed FTS query should never break search */
}
}
return c.json({ query: q, results });
});
r.get('/topics', (c) => {
const classId = c.req.query('classId');
if (!classId) throw badRequest('classId is required');
const rows = db.all<{ topic: string; n: number }>(
`SELECT q.topic AS topic, COUNT(*) AS n FROM questions q JOIN quizzes z ON z.id = q.quiz_id WHERE z.class_id = ? AND q.topic != '' GROUP BY q.topic ORDER BY n DESC`,
classId,
);
return c.json({ topics: rows });
});
return r;
}