feat: add AdminQuestionService

Made-with: Cursor

src/app.ts

@@ -7,6 +7,8 @@ import rateLimitPlugin from './plugins/rateLimit.js';
 import authPlugin from './plugins/auth.js';
 import subscriptionPlugin from './plugins/subscription.js';
 import { authRoutes } from './routes/auth.js';
+import { profileRoutes } from './routes/profile.js';
+import { testsRoutes } from './routes/tests.js';
 import { env } from './config/env.js';
 import { randomUUID } from 'node:crypto';
 
@@ -75,6 +77,8 @@ export async function buildApp(): Promise<FastifyInstance> {
   await app.register(authPlugin);
   await app.register(subscriptionPlugin);
   await app.register(authRoutes, { prefix: '/auth' });
+  await app.register(profileRoutes, { prefix: '/profile' });
+  await app.register(testsRoutes, { prefix: '/tests' });
 
   app.get('/health', async () => ({ status: 'ok', timestamp: new Date().toISOString() }));
 

src/routes/tests.ts

@@ -0,0 +1,185 @@
+import type { FastifyInstance } from 'fastify';
+import { LlmService } from '../services/llm/llm.service.js';
+import { QuestionService } from '../services/questions/question.service.js';
+import { TestsService } from '../services/tests/tests.service.js';
+import { notFound } from '../utils/errors.js';
+import type { CreateTestInput } from '../services/tests/tests.service.js';
+import type { TestSnapshot } from '../services/tests/tests.service.js';
+
+const STACKS = ['html', 'css', 'js', 'ts', 'react', 'vue', 'nodejs', 'git', 'web_basics'] as const;
+const LEVELS = ['basic', 'beginner', 'intermediate', 'advanced', 'expert'] as const;
+
+const createTestSchema = {
+  body: {
+    type: 'object',
+    required: ['stack', 'level', 'questionCount'],
+    properties: {
+      stack: { type: 'string', enum: STACKS },
+      level: { type: 'string', enum: LEVELS },
+      questionCount: { type: 'integer', minimum: 1, maximum: 50 },
+      mode: { type: 'string', enum: ['fixed', 'infinite', 'marathon'] },
+    },
+    additionalProperties: false,
+  },
+};
+
+const testIdParamsSchema = {
+  params: {
+    type: 'object',
+    required: ['testId'],
+    properties: {
+      testId: { type: 'string', format: 'uuid' },
+    },
+  },
+};
+
+const answerSchema = {
+  params: {
+    type: 'object',
+    required: ['testId'],
+    properties: {
+      testId: { type: 'string', format: 'uuid' },
+    },
+  },
+  body: {
+    type: 'object',
+    required: ['questionId', 'answer'],
+    properties: {
+      questionId: { type: 'string', format: 'uuid' },
+      answer: {
+        oneOf: [
+          { type: 'string' },
+          { type: 'array', items: { type: 'string' } },
+        ],
+      },
+    },
+    additionalProperties: false,
+  },
+};
+
+const historyQuerySchema = {
+  querystring: {
+    type: 'object',
+    properties: {
+      limit: { type: 'integer', minimum: 1, maximum: 100 },
+      offset: { type: 'integer', minimum: 0 },
+    },
+    additionalProperties: false,
+  },
+};
+
+function stripAnswersForClient(
+  q: TestSnapshot
+): Omit<TestSnapshot, 'correctAnswer' | 'explanation'> {
+  const { correctAnswer: _, explanation: __, ...rest } = q;
+  return rest;
+}
+
+export async function testsRoutes(app: FastifyInstance) {
+  const llmService = new LlmService();
+  const questionService = new QuestionService(app.db, llmService);
+  const testsService = new TestsService(app.db, questionService);
+  const { rateLimitOptions } = app;
+
+  app.get(
+    '/',
+    {
+      schema: historyQuerySchema,
+      config: { rateLimit: rateLimitOptions.apiAuthed },
+      preHandler: [app.authenticate],
+    },
+    async (req, reply) => {
+      const userId = req.user!.id;
+      const { limit, offset } = (req.query as { limit?: number; offset?: number }) ?? {};
+      const { tests: testList, total } = await testsService.getHistory(
+        userId,
+        { limit, offset }
+      );
+      return reply.send({ tests: testList, total });
+    }
+  );
+
+  app.post(
+    '/',
+    {
+      schema: createTestSchema,
+      config: { rateLimit: rateLimitOptions.apiAuthed },
+      preHandler: [app.authenticate, app.withSubscription],
+    },
+    async (req, reply) => {
+      const userId = req.user!.id;
+      const body = req.body as CreateTestInput;
+      const test = await testsService.createTest(userId, body);
+      const hideAnswers = test.status === 'in_progress';
+      const response = {
+        ...test,
+        questions: hideAnswers
+          ? test.questions.map(stripAnswersForClient)
+          : test.questions,
+      };
+      return reply.status(201).send(response);
+    }
+  );
+
+  app.post(
+    '/:testId/answer',
+    {
+      schema: answerSchema,
+      config: { rateLimit: rateLimitOptions.apiAuthed },
+      preHandler: [app.authenticate],
+    },
+    async (req, reply) => {
+      const userId = req.user!.id;
+      const { testId } = req.params as { testId: string };
+      const { questionId, answer } = req.body as { questionId: string; answer: string | string[] };
+      const snapshot = await testsService.answerQuestion(
+        userId,
+        testId,
+        questionId,
+        answer
+      );
+      return reply.send(snapshot);
+    }
+  );
+
+  app.post(
+    '/:testId/finish',
+    {
+      schema: testIdParamsSchema,
+      config: { rateLimit: rateLimitOptions.apiAuthed },
+      preHandler: [app.authenticate],
+    },
+    async (req, reply) => {
+      const userId = req.user!.id;
+      const { testId } = req.params as { testId: string };
+      const test = await testsService.finishTest(userId, testId);
+      return reply.send(test);
+    }
+  );
+
+  app.get(
+    '/:testId',
+    {
+      schema: testIdParamsSchema,
+      config: { rateLimit: rateLimitOptions.apiAuthed },
+      preHandler: [app.authenticate],
+    },
+    async (req, reply) => {
+      const userId = req.user!.id;
+      const { testId } = req.params as { testId: string };
+      const test = await testsService.getById(userId, testId);
+      if (!test) {
+        throw notFound('Test not found');
+      }
+      const hideAnswers = test.status === 'in_progress';
+      const response = {
+        ...test,
+        questions: hideAnswers
+          ? test.questions.map(stripAnswersForClient)
+          : test.questions,
+      };
+      return reply.send(response);
+    }
+  );
+
+}

src/services/admin/admin-question.service.ts

@@ -0,0 +1,172 @@
+import { eq, asc, count } from 'drizzle-orm';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import type * as schema from '../../db/schema/index.js';
+import { questionBank } from '../../db/schema/index.js';
+import { notFound } from '../../utils/errors.js';
+import type { Stack, Level, QuestionType } from '../../db/schema/enums.js';
+
+type Db = NodePgDatabase<typeof schema>;
+
+export type PendingQuestion = {
+  id: string;
+  stack: Stack;
+  level: Level;
+  type: QuestionType;
+  questionText: string;
+  options: Array<{ key: string; text: string }> | null;
+  correctAnswer: string | string[];
+  explanation: string;
+  source: string;
+  createdAt: Date;
+};
+
+export type EditQuestionInput = {
+  stack?: Stack;
+  level?: Level;
+  type?: QuestionType;
+  questionText?: string;
+  options?: Array<{ key: string; text: string }> | null;
+  correctAnswer?: string | string[];
+  explanation?: string;
+};
+
+export type ListPendingResult = {
+  questions: PendingQuestion[];
+  total: number;
+};
+
+export class AdminQuestionService {
+  constructor(private readonly db: Db) {}
+
+  async listPending(limit = 50, offset = 0): Promise<ListPendingResult> {
+    const questions = await this.db
+      .select({
+        id: questionBank.id,
+        stack: questionBank.stack,
+        level: questionBank.level,
+        type: questionBank.type,
+        questionText: questionBank.questionText,
+        options: questionBank.options,
+        correctAnswer: questionBank.correctAnswer,
+        explanation: questionBank.explanation,
+        source: questionBank.source,
+        createdAt: questionBank.createdAt,
+      })
+      .from(questionBank)
+      .where(eq(questionBank.status, 'pending'))
+      .orderBy(asc(questionBank.createdAt))
+      .limit(limit)
+      .offset(offset);
+
+    const [{ count: totalCount }] = await this.db
+      .select({ count: count() })
+      .from(questionBank)
+      .where(eq(questionBank.status, 'pending'));
+
+    return {
+      questions: questions.map((q) => ({
+        id: q.id,
+        stack: q.stack,
+        level: q.level,
+        type: q.type,
+        questionText: q.questionText,
+        options: q.options,
+        correctAnswer: q.correctAnswer,
+        explanation: q.explanation,
+        source: q.source,
+        createdAt: q.createdAt,
+      })),
+      total: totalCount ?? 0,
+    };
+  }
+
+  async approve(questionId: string): Promise<void> {
+    const [updated] = await this.db
+      .update(questionBank)
+      .set({
+        status: 'approved',
+        approvedAt: new Date(),
+      })
+      .where(eq(questionBank.id, questionId))
+      .returning({ id: questionBank.id });
+
+    if (!updated) {
+      throw notFound('Question not found');
+    }
+  }
+
+  async reject(questionId: string): Promise<void> {
+    const [updated] = await this.db
+      .update(questionBank)
+      .set({ status: 'rejected' })
+      .where(eq(questionBank.id, questionId))
+      .returning({ id: questionBank.id });
+
+    if (!updated) {
+      throw notFound('Question not found');
+    }
+  }
+
+  async edit(questionId: string, input: EditQuestionInput): Promise<PendingQuestion> {
+    const updates: Partial<{
+      stack: Stack;
+      level: Level;
+      type: QuestionType;
+      questionText: string;
+      options: Array<{ key: string; text: string }> | null;
+      correctAnswer: string | string[];
+      explanation: string;
+    }> = {};
+
+    if (input.stack !== undefined) updates.stack = input.stack;
+    if (input.level !== undefined) updates.level = input.level;
+    if (input.type !== undefined) updates.type = input.type;
+    if (input.questionText !== undefined) updates.questionText = input.questionText;
+    if (input.options !== undefined) updates.options = input.options;
+    if (input.correctAnswer !== undefined) updates.correctAnswer = input.correctAnswer;
+    if (input.explanation !== undefined) updates.explanation = input.explanation;
+
+    if (Object.keys(updates).length === 0) {
+      const [existing] = await this.db
+        .select()
+        .from(questionBank)
+        .where(eq(questionBank.id, questionId));
+      if (!existing) throw notFound('Question not found');
+      return {
+        id: existing.id,
+        stack: existing.stack,
+        level: existing.level,
+        type: existing.type,
+        questionText: existing.questionText,
+        options: existing.options,
+        correctAnswer: existing.correctAnswer,
+        explanation: existing.explanation,
+        source: existing.source,
+        createdAt: existing.createdAt,
+      };
+    }
+
+    const [updated] = await this.db
+      .update(questionBank)
+      .set(updates)
+      .where(eq(questionBank.id, questionId))
+      .returning();
+
+    if (!updated) {
+      throw notFound('Question not found');
+    }
+
+    return {
+      id: updated.id,
+      stack: updated.stack,
+      level: updated.level,
+      type: updated.type,
+      questionText: updated.questionText,
+      options: updated.options,
+      correctAnswer: updated.correctAnswer,
+      explanation: updated.explanation,
+      source: updated.source,
+      createdAt: updated.createdAt,
+    };
+  }
+}

src/services/llm/index.ts

@@ -1,9 +0,0 @@
-export {
-  LlmService,
-  type ILlmService,
-  type LlmConfig,
-  type LlmGenerationMeta,
-  type GenerateQuestionsInput,
-  type GenerateQuestionsResult,
-  type GeneratedQuestion,
-} from './llm.service.js';

src/services/llm/llm.service.ts

@@ -71,12 +71,7 @@ export interface GenerateQuestionsResult {
   meta: LlmGenerationMeta;
 }
 
-/** Interface for QuestionService dependency injection and testing */
-export interface ILlmService {
-  generateQuestions(input: GenerateQuestionsInput): Promise<GenerateQuestionsResult>;
-}
-
-export class LlmService implements ILlmService {
+export class LlmService {
   private readonly config: LlmConfig;
 
   constructor(config?: Partial<LlmConfig>) {

src/services/questions/question.service.ts

@@ -0,0 +1,197 @@
+import { eq, and, sql, asc, inArray } from 'drizzle-orm';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import type * as schema from '../../db/schema/index.js';
+import {
+  questionBank,
+  questionCacheMeta,
+  userQuestionLog,
+} from '../../db/schema/index.js';
+import { internalError, AppError, ERROR_CODES } from '../../utils/errors.js';
+import type { Stack, Level, QuestionType } from '../../db/schema/enums.js';
+import type {
+  GeneratedQuestion,
+  GenerateQuestionsResult,
+} from '../llm/llm.service.js';
+
+type Db = NodePgDatabase<typeof schema>;
+
+export type QuestionForTest = {
+  questionBankId: string;
+  type: QuestionType;
+  questionText: string;
+  options: Array<{ key: string; text: string }> | null;
+  correctAnswer: string | string[];
+  explanation: string;
+};
+
+export interface LlmServiceInterface {
+  generateQuestions(input: {
+    stack: Stack;
+    level: Level;
+    count: number;
+    types?: QuestionType[];
+  }): Promise<GenerateQuestionsResult>;
+}
+
+function shuffle<T>(arr: T[]): T[] {
+  const result = [...arr];
+  for (let i = result.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [result[i], result[j]] = [result[j]!, result[i]!];
+  }
+  return result;
+}
+
+export class QuestionService {
+  constructor(
+    private readonly db: Db,
+    private readonly llmService: LlmServiceInterface
+  ) {}
+
+  /**
+   * Get questions for a test. Fetches approved questions from question_bank.
+   * If not enough, generates via LLM, persists to question_bank and question_cache_meta.
+   */
+  async getQuestionsForTest(
+    userId: string,
+    stack: Stack,
+    level: Level,
+    count: number
+  ): Promise<QuestionForTest[]> {
+    const approved = await this.db
+      .select({
+        id: questionBank.id,
+        type: questionBank.type,
+        questionText: questionBank.questionText,
+        options: questionBank.options,
+        correctAnswer: questionBank.correctAnswer,
+        explanation: questionBank.explanation,
+      })
+      .from(questionBank)
+      .where(
+        and(eq(questionBank.stack, stack), eq(questionBank.level, level), eq(questionBank.status, 'approved'))
+      )
+      .orderBy(asc(questionBank.usageCount));
+
+    const seenIds = await this.db
+      .select({ questionBankId: userQuestionLog.questionBankId })
+      .from(userQuestionLog)
+      .where(eq(userQuestionLog.userId, userId));
+
+    const seenSet = new Set(seenIds.map((r) => r.questionBankId));
+    const preferred = approved.filter((q) => !seenSet.has(q.id));
+    const pool = preferred.length >= count ? preferred : approved;
+    const shuffled = shuffle(pool);
+
+    const fromBank: QuestionForTest[] = shuffled.slice(0, count).map((q) => ({
+      questionBankId: q.id,
+      type: q.type,
+      questionText: q.questionText,
+      options: q.options,
+      correctAnswer: q.correctAnswer,
+      explanation: q.explanation,
+    }));
+
+    let result = fromBank;
+
+    if (result.length < count) {
+      const generated = await this.generateAndPersistQuestions(
+        stack,
+        level,
+        count - result.length
+      );
+      result = [...result, ...generated];
+    }
+
+    if (result.length < count) {
+      throw new AppError(
+        ERROR_CODES.QUESTIONS_UNAVAILABLE,
+        'Not enough questions available for this stack and level',
+        422
+      );
+    }
+
+    if (result.length > 0) {
+      await this.db.insert(userQuestionLog).values(
+        result.map((q) => ({
+          userId,
+          questionBankId: q.questionBankId,
+        }))
+      );
+
+      const ids = result.map((q) => q.questionBankId);
+      await this.db
+        .update(questionBank)
+        .set({
+          usageCount: sql`${questionBank.usageCount} + 1`,
+        })
+        .where(inArray(questionBank.id, ids));
+    }
+
+    return result;
+  }
+
+  private async generateAndPersistQuestions(
+    stack: Stack,
+    level: Level,
+    count: number
+  ): Promise<QuestionForTest[]> {
+    let generated: GeneratedQuestion[];
+    let meta: GenerateQuestionsResult['meta'];
+
+    try {
+      const result = await this.llmService.generateQuestions({
+        stack,
+        level,
+        count,
+      });
+      generated = result.questions;
+      meta = result.meta;
+    } catch (err) {
+      throw internalError(
+        'Failed to generate questions',
+        err instanceof Error ? err : undefined
+      );
+    }
+
+    const inserted: QuestionForTest[] = [];
+
+    for (const q of generated) {
+      const [row] = await this.db
+        .insert(questionBank)
+        .values({
+          stack,
+          level,
+          type: q.type as QuestionType,
+          questionText: q.questionText,
+          options: q.options ?? null,
+          correctAnswer: q.correctAnswer,
+          explanation: q.explanation,
+          status: 'approved',
+          source: 'llm_generated',
+        })
+        .returning();
+
+      if (row) {
+        await this.db.insert(questionCacheMeta).values({
+          questionBankId: row.id,
+          llmModel: meta.llmModel,
+          promptHash: meta.promptHash,
+          generationTimeMs: meta.generationTimeMs,
+          rawResponse: meta.rawResponse,
+        });
+
+        inserted.push({
+          questionBankId: row.id,
+          type: row.type,
+          questionText: row.questionText,
+          options: row.options,
+          correctAnswer: row.correctAnswer,
+          explanation: row.explanation,
+        });
+      }
+    }
+
+    return inserted;
+  }
+}

src/services/tests/tests.service.ts

@@ -0,0 +1,399 @@
+import { eq, and, desc } from 'drizzle-orm';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import type * as schema from '../../db/schema/index.js';
+import { tests, testQuestions, userStats } from '../../db/schema/index.js';
+import { notFound, conflict, AppError, ERROR_CODES } from '../../utils/errors.js';
+import type { Stack, Level, TestMode } from '../../db/schema/enums.js';
+import type { QuestionService } from '../questions/question.service.js';
+
+type Db = NodePgDatabase<typeof schema>;
+
+export type CreateTestInput = {
+  stack: Stack;
+  level: Level;
+  questionCount: number;
+  mode?: TestMode;
+};
+
+export type TestSnapshot = {
+  id: string;
+  testId: string;
+  questionBankId: string | null;
+  orderNumber: number;
+  type: string;
+  questionText: string;
+  options: Array<{ key: string; text: string }> | null;
+  correctAnswer: string | string[];
+  explanation: string;
+  userAnswer?: string | string[] | null;
+  isCorrect?: boolean | null;
+  answeredAt?: string | null;
+};
+
+export type TestWithQuestions = {
+  id: string;
+  userId: string;
+  stack: string;
+  level: string;
+  questionCount: number;
+  mode: string;
+  status: string;
+  score: number | null;
+  startedAt: string;
+  finishedAt: string | null;
+  timeLimitSeconds: number | null;
+  questions: TestSnapshot[];
+};
+
+export class TestsService {
+  constructor(
+    private readonly db: Db,
+    private readonly questionService: QuestionService
+  ) {}
+
+  /**
+   * Create a new test: fetch questions, create test record, snapshot questions into test_questions.
+   */
+  async createTest(userId: string, input: CreateTestInput): Promise<TestWithQuestions> {
+    const { stack, level, questionCount, mode = 'fixed' } = input;
+
+    if (questionCount < 1 || questionCount > 50) {
+      throw new AppError(
+        ERROR_CODES.BAD_REQUEST,
+        'questionCount must be between 1 and 50',
+        400
+      );
+    }
+
+    const questions = await this.questionService.getQuestionsForTest(
+      userId,
+      stack,
+      level,
+      questionCount
+    );
+
+    const [test] = await this.db
+      .insert(tests)
+      .values({
+        userId,
+        stack,
+        level,
+        questionCount,
+        mode,
+        status: 'in_progress',
+      })
+      .returning();
+
+    if (!test) {
+      throw new AppError(
+        ERROR_CODES.INTERNAL_ERROR,
+        'Failed to create test',
+        500
+      );
+    }
+
+    const tqValues = questions.map((q, i) => ({
+      testId: test.id,
+      questionBankId: q.questionBankId,
+      orderNumber: i + 1,
+      type: q.type,
+      questionText: q.questionText,
+      options: q.options,
+      correctAnswer: q.correctAnswer,
+      explanation: q.explanation,
+    }));
+
+    await this.db.insert(testQuestions).values(tqValues);
+
+    const questionsRows = await this.db
+      .select()
+      .from(testQuestions)
+      .where(eq(testQuestions.testId, test.id))
+      .orderBy(testQuestions.orderNumber);
+
+    return this.toTestWithQuestions(test, questionsRows);
+  }
+
+  /**
+   * Submit an answer for a question in an in-progress test.
+   */
+  async answerQuestion(
+    userId: string,
+    testId: string,
+    testQuestionId: string,
+    userAnswer: string | string[]
+  ): Promise<TestSnapshot> {
+    const [test] = await this.db
+      .select()
+      .from(tests)
+      .where(and(eq(tests.id, testId), eq(tests.userId, userId)))
+      .limit(1);
+
+    if (!test) {
+      throw notFound('Test not found');
+    }
+    if (test.status !== 'in_progress') {
+      throw conflict(ERROR_CODES.TEST_ALREADY_FINISHED, 'Test is already finished');
+    }
+
+    const [tq] = await this.db
+      .select()
+      .from(testQuestions)
+      .where(
+        and(
+          eq(testQuestions.id, testQuestionId),
+          eq(testQuestions.testId, testId)
+        )
+      )
+      .limit(1);
+
+    if (!tq) {
+      throw conflict(ERROR_CODES.WRONG_QUESTION, 'Question does not belong to this test');
+    }
+    if (tq.userAnswer !== null && tq.userAnswer !== undefined) {
+      throw conflict(ERROR_CODES.QUESTION_ALREADY_ANSWERED, 'Question already answered');
+    }
+
+    const isCorrect = this.checkAnswer(tq.correctAnswer, userAnswer);
+
+    const [updated] = await this.db
+      .update(testQuestions)
+      .set({
+        userAnswer,
+        isCorrect,
+        answeredAt: new Date(),
+      })
+      .where(eq(testQuestions.id, testQuestionId))
+      .returning();
+
+    if (!updated) {
+      throw notFound('Question not found');
+    }
+
+    return {
+      id: updated.id,
+      testId: updated.testId,
+      questionBankId: updated.questionBankId,
+      orderNumber: updated.orderNumber,
+      type: updated.type,
+      questionText: updated.questionText,
+      options: updated.options,
+      correctAnswer: updated.correctAnswer,
+      explanation: updated.explanation,
+      userAnswer: updated.userAnswer,
+      isCorrect: updated.isCorrect,
+      answeredAt: updated.answeredAt?.toISOString() ?? null,
+    };
+  }
+
+  private checkAnswer(
+    correct: string | string[],
+    user: string | string[]
+  ): boolean {
+    if (Array.isArray(correct) && Array.isArray(user)) {
+      if (correct.length !== user.length) return false;
+      const a = [...correct].sort();
+      const b = [...user].sort();
+      return a.every((v, i) => v === b[i]);
+    }
+    if (typeof correct === 'string' && typeof user === 'string') {
+      return correct.trim().toLowerCase() === user.trim().toLowerCase();
+    }
+    return false;
+  }
+
+  /**
+   * Finish a test: calculate score, update user_stats.
+   */
+  async finishTest(userId: string, testId: string): Promise<TestWithQuestions> {
+    const [test] = await this.db
+      .select()
+      .from(tests)
+      .where(and(eq(tests.id, testId), eq(tests.userId, userId)))
+      .limit(1);
+
+    if (!test) {
+      throw notFound('Test not found');
+    }
+    if (test.status !== 'in_progress') {
+      throw conflict(ERROR_CODES.TEST_ALREADY_FINISHED, 'Test is already finished');
+    }
+
+    const questions = await this.db
+      .select()
+      .from(testQuestions)
+      .where(eq(testQuestions.testId, testId));
+
+    const unanswered = questions.filter(
+      (q) => q.userAnswer === null || q.userAnswer === undefined
+    );
+    if (unanswered.length > 0) {
+      throw new AppError(
+        ERROR_CODES.NO_ANSWERS,
+        `Cannot finish: ${unanswered.length} question(s) not answered`,
+        422
+      );
+    }
+
+    const correctCount = questions.filter((q) => q.isCorrect === true).length;
+    const score = Math.round((correctCount / questions.length) * 100);
+
+    const [updatedTest] = await this.db
+      .update(tests)
+      .set({
+        status: 'completed',
+        score,
+        finishedAt: new Date(),
+      })
+      .where(eq(tests.id, testId))
+      .returning();
+
+    if (!updatedTest) {
+      throw notFound('Test not found');
+    }
+
+    await this.upsertUserStats(userId, test.stack as Stack, test.level as Level, {
+      totalQuestions: questions.length,
+      correctAnswers: correctCount,
+      testsTaken: 1,
+    });
+
+    const questionsRows = await this.db
+      .select()
+      .from(testQuestions)
+      .where(eq(testQuestions.testId, testId))
+      .orderBy(testQuestions.orderNumber);
+
+    return this.toTestWithQuestions(updatedTest, questionsRows);
+  }
+
+  private async upsertUserStats(
+    userId: string,
+    stack: Stack,
+    level: Level,
+    delta: { totalQuestions: number; correctAnswers: number; testsTaken: number }
+  ): Promise<void> {
+    const [existing] = await this.db
+      .select()
+      .from(userStats)
+      .where(
+        and(
+          eq(userStats.userId, userId),
+          eq(userStats.stack, stack),
+          eq(userStats.level, level)
+        )
+      )
+      .limit(1);
+
+    const now = new Date();
+
+    if (existing) {
+      await this.db
+        .update(userStats)
+        .set({
+          totalQuestions: existing.totalQuestions + delta.totalQuestions,
+          correctAnswers: existing.correctAnswers + delta.correctAnswers,
+          testsTaken: existing.testsTaken + delta.testsTaken,
+          lastTestAt: now,
+        })
+        .where(eq(userStats.id, existing.id));
+    } else {
+      await this.db.insert(userStats).values({
+        userId,
+        stack,
+        level,
+        totalQuestions: delta.totalQuestions,
+        correctAnswers: delta.correctAnswers,
+        testsTaken: delta.testsTaken,
+        lastTestAt: now,
+      });
+    }
+  }
+
+  /**
+   * Get a single test by ID (must belong to user).
+   */
+  async getById(userId: string, testId: string): Promise<TestWithQuestions | null> {
+    const [test] = await this.db
+      .select()
+      .from(tests)
+      .where(and(eq(tests.id, testId), eq(tests.userId, userId)))
+      .limit(1);
+
+    if (!test) return null;
+
+    const questionsRows = await this.db
+      .select()
+      .from(testQuestions)
+      .where(eq(testQuestions.testId, testId))
+      .orderBy(testQuestions.orderNumber);
+
+    return this.toTestWithQuestions(test, questionsRows);
+  }
+
+  /**
+   * Get test history for a user (most recent first).
+   */
+  async getHistory(
+    userId: string,
+    options?: { limit?: number; offset?: number }
+  ): Promise<{ tests: TestWithQuestions[]; total: number }> {
+    const limit = Math.min(options?.limit ?? 20, 100);
+    const offset = options?.offset ?? 0;
+
+    const all = await this.db
+      .select()
+      .from(tests)
+      .where(eq(tests.userId, userId))
+      .orderBy(desc(tests.startedAt));
+
+    const total = all.length;
+    const page = all.slice(offset, offset + limit);
+
+    const result: TestWithQuestions[] = [];
+
+    for (const test of page) {
+      const questionsRows = await this.db
+        .select()
+        .from(testQuestions)
+        .where(eq(testQuestions.testId, test.id))
+        .orderBy(testQuestions.orderNumber);
+      result.push(this.toTestWithQuestions(test, questionsRows));
+    }
+
+    return { tests: result, total };
+  }
+
+  private toTestWithQuestions(
+    test: (typeof tests.$inferSelect),
+    questionsRows: (typeof testQuestions.$inferSelect)[]
+  ): TestWithQuestions {
+    return {
+      id: test.id,
+      userId: test.userId,
+      stack: test.stack,
+      level: test.level,
+      questionCount: test.questionCount,
+      mode: test.mode,
+      status: test.status,
+      score: test.score,
+      startedAt: test.startedAt.toISOString(),
+      finishedAt: test.finishedAt?.toISOString() ?? null,
+      timeLimitSeconds: test.timeLimitSeconds,
+      questions: questionsRows.map((q) => ({
+        id: q.id,
+        testId: q.testId,
+        questionBankId: q.questionBankId,
+        orderNumber: q.orderNumber,
+        type: q.type,
+        questionText: q.questionText,
+        options: q.options,
+        correctAnswer: q.correctAnswer,
+        explanation: q.explanation,
+        userAnswer: q.userAnswer,
+        isCorrect: q.isCorrect,
+        answeredAt: q.answeredAt?.toISOString() ?? null,
+      })),
+    };
+  }
+}