feat: синхронизация бэкенда с документацией (AGENT_TASK_BACKEND_SYNC)

- Добвлен @fastify/cookie и настройку httpOnly cookie для refresh token
- Добавлен префикс /api/v1 для auth, profile, tests, admin
- Скорректировано в Login: возвращать user (id, nickname, avatarUrl, role, emailVerified),
  ставить refreshToken в Set-Cookie
- Скорректировано в Logout: Bearer + cookie, пустое тело, 200 + { message }, очищать cookie
- Скорректировано в Refresh: token из cookie, пустое тело, 200 + { accessToken }, Set-Cookie
- Добавлено в getPrivateProfile: поля role и plan
- Скорректировано в Tests: score = количество правильных, ответ { score, totalQuestions, percentage }
- Добавлено в question_cache_meta: поля valid, retryCount, questionsGenerated
- Обновлены тесты

.cursor/plans/документация_vs_реализация_0932d1a0.plan.md

@@ -0,0 +1,366 @@
+---
+name: Документация vs Реализация
+overview: "Подробный отчёт о соответствии бэкенда документации samreshu_docs: выявлены расхождения в API контрактах, схеме БД, аутентификации, тестах и других компонентах."
+todos: []
+isProject: false
+---
+
+# Отчёт: Соответствие бэкенда документации Samreshu
+
+## 1. Базовый URL и структура API
+
+**Документация** ([contracts.md](samreshu_docs/api/contracts.md)):
+
+- Базовый URL: `/api/v1`
+- Все эндпоинты: `/api/v1/auth/`*, `/api/v1/profile/`*, `/api/v1/tests/*`, `/api/v1/admin/*`
+
+**Реализация** ([app.ts](src/app.ts)):
+
+- Префикс `/api/v1` отсутствует. Маршруты зарегистрированы как `/auth`, `/profile`, `/tests`, `/admin`
+- Фактические URL: `/auth/`*, `/profile/`*, `/tests/*`, `/admin/*`
+
+**Вывод:** Критическое расхождение. Клиент, следующий документации, будет отправлять запросы на несуществующие эндпоинты.
+
+---
+
+## 2. Аутентификация (Auth)
+
+### 2.1 POST /auth/register
+
+
+| Аспект         | Документация                                      | Реализация                                                            |
+| -------------- | ------------------------------------------------- | --------------------------------------------------------------------- |
+| Response 201   | `{ user, accessToken }` + Set-Cookie refreshToken | `{ userId, message, verificationCode }`                               |
+| Логика         | Сразу выдаёт токены, отправляет письмо            | Требует верификацию email; не выдаёт токены; возвращает код (для dev) |
+| NICKNAME_TAKEN | —                                                 | Есть в коде; в документации не описан                                 |
+
+
+**Вывод:** Разный flow. Документация описывает выдачу токенов сразу после регистрации; реализация ожидает верификацию email.
+
+### 2.2 POST /auth/login
+
+
+| Аспект                  | Документация                         | Реализация                                              |
+| ----------------------- | ------------------------------------ | ------------------------------------------------------- |
+| Response                | `{ user, accessToken }` + Set-Cookie | `{ accessToken, refreshToken, expiresIn }` — без `user` |
+| Lockout при brute force | 403 `ACCOUNT_LOCKED`                 | 429 `RATE_LIMIT_EXCEEDED`                               |
+| Ошибка неверных данных  | 401 `INVALID_CREDENTIALS`            | 401 `UNAUTHORIZED` (общий код)                          |
+
+
+**Вывод:** Расхождения в формате ответа, коде ошибки и семантике блокировки (403 vs 429).
+
+### 2.3 POST /auth/logout
+
+
+| Аспект       | Документация             | Реализация                 |
+| ------------ | ------------------------ | -------------------------- |
+| Авторизация  | Bearer token             | refreshToken в теле        |
+| Request body | Пустое                   | `{ refreshToken: string }` |
+| Response     | 200 `{ message: "..." }` | 204 (без тела)             |
+
+
+**Вывод:** Другой механизм авторизации и формат ответа.
+
+### 2.4 POST /auth/refresh
+
+
+| Аспект       | Документация    | Реализация                 |
+| ------------ | --------------- | -------------------------- |
+| Токен        | httpOnly cookie | `{ refreshToken }` в body  |
+| Request body | Пустое          | `{ refreshToken: string }` |
+
+
+**Вывод:** Документация предполагает cookie; реализация использует body.
+
+### 2.5 POST /auth/verify-email
+
+
+| Аспект      | Документация | Реализация         |
+| ----------- | ------------ | ------------------ |
+| Request     | `{ code }`   | `{ userId, code }` |
+| Авторизация | Bearer token | Не требуется       |
+
+
+**Вывод:** Документация — только `code` с Bearer; реализация — `userId` и `code` без Bearer.
+
+### 2.6 POST /auth/reset-password
+
+
+| Аспект      | Документация | Реализация    |
+| ----------- | ------------ | ------------- |
+| Поле пароля | `password`   | `newPassword` |
+
+
+**Вывод:** Разные имена полей в теле запроса.
+
+### 2.7 Set-Cookie для refresh token
+
+**Документация:** RefreshToken в httpOnly cookie (`Path=/api/v1/auth`, `Max-Age=604800`).
+
+**Реализация:** Cookie не устанавливаются; refresh token возвращается только в JSON.
+
+---
+
+## 3. Profile
+
+### 3.1 GET /profile
+
+**Документация:** Ответ включает `role`, `plan` (из subscriptions).
+
+**Реализация** ([user.service.ts](src/services/user/user.service.ts)): `getPrivateProfile` возвращает `id`, `nickname`, `avatarUrl`, `country`, `city`, `selfLevel`, `isPublic`, `email`, `emailVerifiedAt`, `createdAt`, `updatedAt`, `stats`. Поля `role` и `plan` отсутствуют.
+
+**Вывод:** В ответе нет полей, указанных в документации.
+
+### 3.2 GET /profile/:username
+
+**Документация:** `stats: { testsCompleted, averageScore }`.
+
+**Реализация:** `stats: { byStack, totalTestsTaken, totalQuestions, correctAnswers, accuracy }` — другая структура.
+
+**Вывод:** Формат статистики не совпадает.
+
+### 3.3 PATCH /profile
+
+**Документация:** Поле `avatarUrl` не описано.
+
+**Реализация:** Поддерживается `avatarUrl`.
+
+**Вывод:** Документация неполная (расхождение в пользу реализации).
+
+---
+
+## 4. Tests
+
+### 4.1 POST /tests (создание)
+
+
+| Аспект              | Документация                                                                                                                         | Реализация                                    |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- |
+| questionCount       | enum: 10 / 20                                                                                                                        | integer 1–50                                  |
+| stack/level (MVP 0) | html, css / basic, beginner                                                                                                          | Все значения enum                             |
+| Response структура  | `{ id, stack, level, questionCount, status, currentQuestion, startedAt, timeLimitSeconds, question: {...} }` — только текущий вопрос | `{ ...test, questions: [...] }` — все вопросы |
+
+
+**Вывод:** Разная структура ответа и валидация параметров.
+
+### 4.2 POST /tests/:id/answer
+
+**Документация:** `{ answered: {...}, progress: {...}, nextQuestion: {...} }`.
+
+**Реализация:** Возвращает полный `TestSnapshot` отвеченного вопроса, без `progress` и `nextQuestion`.
+
+**Вывод:** Формат ответа не совпадает с документацией.
+
+### 4.3 POST /tests/:id/finish
+
+
+| Аспект         | Документация                            | Реализация              |
+| -------------- | --------------------------------------- | ----------------------- |
+| score          | Количество правильных ответов (8 из 10) | Процент (0–100)         |
+| totalQuestions | В ответе                                | Нет в ответе            |
+| percentage     | В ответе                                | Нет (score как процент) |
+
+
+**Реализация** ([tests.service.ts](src/services/tests/tests.service.ts) 239–241):
+
+```ts
+const score = Math.round((correctCount / questions.length) * 100);
+```
+
+**Вывод:** Критическое расхождение: `score` в документации — количество, в реализации — процент.
+
+### 4.4 GET /tests/:id/results
+
+**Документация:** Детальные результаты с `questions`, `userAnswer`, `correctAnswer`, `isCorrect`, `explanation`.
+
+**Реализация:** Эндпоинт отсутствует.
+
+**Вывод:** Критическое расхождение: описанный эндпоинт не реализован.
+
+### 4.5 GET /tests/history
+
+
+| Аспект        | Документация                                           | Реализация                     |
+| ------------- | ------------------------------------------------------ | ------------------------------ |
+| Путь          | GET /tests/history                                     | GET /tests (то же для истории) |
+| Пагинация     | cursor-based (limit, cursor)                           | offset-based (limit, offset)   |
+| Формат ответа | `{ data: [...], pagination: { nextCursor, hasMore } }` | `{ tests: [...], total }`      |
+| Параметры     | stack, status фильтры                                  | Нет фильтров                   |
+
+
+**Вывод:** Другая схема пагинации и структура ответа.
+
+### 4.6 Параметр теста
+
+**Документация:** `:id`.
+
+**Реализация:** `:testId` в params.
+
+**Вывод:** Незначительное расхождение в именовании.
+
+---
+
+## 5. Admin
+
+### 5.1 Список вопросов
+
+
+| Аспект         | Документация                  | Реализация                   |
+| -------------- | ----------------------------- | ---------------------------- |
+| Эндпоинт       | GET /admin/questions/queue    | GET /admin/questions/pending |
+| Пагинация      | cursor (limit, cursor)        | offset (limit, offset)       |
+| status в query | pending / approved / rejected | —                            |
+
+
+### 5.2 Редактирование
+
+**Документация:** PATCH /admin/questions/:id с `status: approved | rejected` и полями для правок.
+
+**Реализация:**
+
+- POST /admin/questions/:questionId/approve
+- POST /admin/questions/:questionId/reject
+- PATCH /admin/questions/:questionId — для редактирования
+
+**Вывод:** Другая схема: отдельные approve/reject вместо смены статуса через PATCH.
+
+---
+
+## 6. База данных
+
+### 6.1 Таблицы
+
+**Документация** ([schema.md](samreshu_docs/database/schema.md)): `verification_tokens` (обобщённо).
+
+**Реализация:** Отдельные таблицы `email_verification_codes` и `password_reset_tokens` (в [verificationTokens.ts](src/db/schema/verificationTokens.ts)).
+
+**Вывод:** Расхождение в модели хранения токенов.
+
+### 6.2 Отсутствующие таблицы (Phase 2+)
+
+В документации есть таблицы, которых нет в текущем коде: `oauth_accounts`, `totp_secrets`, `payments`, `payment_events`, `notifications_log`, `promo_codes`, `user_achievements`. Это ожидаемо для Phase 2+.
+
+---
+
+## 7. Безопасность
+
+### 7.1 Argon2
+
+**Документация:** argon2id, 19 MiB, 2 iterations.
+
+**Реализация** ([password.ts](src/utils/password.ts)): `memoryCost: 19456` (KiB), `timeCost: 2`.
+
+**Вывод:** Совпадение.
+
+### 7.2 JWT
+
+**Документация:** Access 15 мин, Refresh 7 дней, HS256.
+
+**Реализация:** `JWT_ACCESS_TTL=15m`, `JWT_REFRESH_TTL=7d`.
+
+**Вывод:** Совпадение.
+
+### 7.3 Login lockout
+
+**Документация:** 5/15 мин, 10/1 ч, 20/24 ч.
+
+**Реализация** ([loginLockout.ts](src/utils/loginLockout.ts)): Те же пороги (5, 10, 20).
+
+**Вывод:** Совпадение.
+
+### 7.4 Rate limits
+
+**Документация:** RATE_LIMIT_LOGIN, RATE_LIMIT_REGISTER, RATE_LIMIT_FORGOT_PASSWORD, RATE_LIMIT_VERIFY_EMAIL, RATE_LIMIT_API_AUTHED, RATE_LIMIT_API_GUEST.
+
+**Реализация** ([env.ts](src/config/env.ts)): RATE_LIMIT_LOGIN отсутствует (используется progressive lockout). Остальные переменные есть.
+
+**Вывод:** Незначительное расхождение; security.md упоминает RATE_LIMIT_LOGIN, но логика lockout иная.
+
+### 7.5 CORS
+
+**Документация:** `http://localhost:5173`, `https://samreshu.ru`, `credentials: true`, методы GET, POST, PATCH, DELETE.
+
+**Реализация:** Origins из `CORS_ORIGINS`, `credentials: true`, методы включают PUT и OPTIONS.
+
+**Вывод:** Реализация шире, расхождение несущественное.
+
+### 7.6 Helmet
+
+**Документация:** Полный набор заголовков, включая CSP.
+
+**Реализация:** `contentSecurityPolicy: false`, `crossOriginEmbedderPolicy: false`.
+
+**Вывод:** CSP и COEP отключены.
+
+---
+
+## 8. LLM
+
+### 8.1 Конфигурация
+
+**Документация:** LLM_BASE_URL, LLM_MODEL, LLM_API_KEY, LLM_TIMEOUT_MS, LLM_MAX_RETRIES, LLM_TEMPERATURE, LLM_MAX_TOKENS.
+
+**Реализация:** Дополнительно `LLM_FALLBACK_MODEL`, `LLM_RETRY_DELAY_MS`.
+
+**Вывод:** Реализация расширяет документацию.
+
+### 8.2 question_cache_meta
+
+**Документация:** model, generation_time_ms, prompt_hash. Также упоминаются valid, retry_count, questions_generated.
+
+**Реализация:** Нужно проверить сохранение этих полей в [questionCacheMeta](src/db/schema/questionCacheMeta.ts) и связанных сервисах.
+
+---
+
+## 9. Код и инфраструктура
+
+### 9.1 Onboarding / setup
+
+**Документация:** docker-compose.dev.yml с postgres и redis.
+
+**Реализация:** Соответствует.
+
+### 9.2 .env.example
+
+**Документация:** Полный перечень переменных.
+
+**Реализация:** Совпадает, включая rate limits и LLM. JWT_SECRET требует не менее 32 символов — в примере выполнено.
+
+---
+
+## 10. Сводка расхождений
+
+### Критические
+
+1. Отсутствие префикса `/api/v1`
+2. Auth: другой flow (verify-email до токенов, refresh/logout через body вместо cookie)
+3. Tests: `score` как процент вместо количества
+4. Отсутствует GET /tests/:id/results
+5. Формат ответов create/answer/finish/history не совпадает с документацией
+
+### Значительные
+
+1. Login lockout: 429 вместо 403 ACCOUNT_LOCKED
+2. Login: нет поля `user` в ответе
+3. Profile: нет `role`, `plan`; другая структура `stats`
+4. Admin: другой набор эндпоинтов и логика approve/reject
+5. Пагинация: offset вместо cursor
+
+### Незначительные
+
+1. Имена полей (testId vs id, newPassword vs password)
+2. verify-email: userId + code вместо только code
+3. Эндпоинт admin: /pending вместо /queue
+
+---
+
+## Рекомендации
+
+1. **Привести маршрутизацию к документации:** добавить префикс `/api/v1` при регистрации роутов.
+2. **Унифицировать auth:** реализовать cookie для refresh token и обновить logout/refresh под документацию, либо явно зафиксировать в документации текущий подход (body).
+3. **Исправить score в тестах:** хранить и возвращать количество правильных ответов, а процент считать отдельно.
+4. **Реализовать GET /tests/:id/results** по описанному в документации формату.
+5. **Привести ответы create/answer/finish/history** к формату из contracts.md.
+6. **Обновить документацию** под уже реализованные отличия (offset, admin approve/reject и т.д.), если менять реализацию не планируется.
+7. **Расширить getPrivateProfile** полями `role` и `plan` из subscription middleware.
+

.env.example

@@ -23,8 +23,7 @@ LLM_MAX_RETRIES=1
 LLM_TEMPERATURE=0.7
 LLM_MAX_TOKENS=2048
 
-# Rate limits
+# Rate limits (login uses progressive lockout: 5/10/20 failed attempts -> 15m/1h/24h block)
-RATE_LIMIT_LOGIN=5
 RATE_LIMIT_REGISTER=3
 RATE_LIMIT_FORGOT_PASSWORD=3
 RATE_LIMIT_VERIFY_EMAIL=5

AGENT_TASKS.md

@@ -69,6 +69,21 @@ Implement Agent H tasks from AGENT_TASKS.md. Work in branch feat/testing.
 Do H1–H7, commit after each. Target ≥70% coverage on services.
 ```
 
+**Agent A2 (Progressive Login Lockout):**
+
+```text
+Implement Agent A2 task from AGENT_TASKS.md. Work in branch feat/progressive-login-lockout.
+Branch from dev. Do task A2-1. Commit with the message from the table.
+```
+
+**Agent A2-2 (Fix Login Lockout Tests):**
+
+```text
+Implement Agent A2-2 task from AGENT_TASKS.md. Work in branch fix/login-lockout-test-mock.
+Branch from dev. Do task A2-2. Commit with the message from the table.
+Ensure tests/integration/auth.routes.test.ts passes.
+```
+
 ## Текущее состояние репозитория
 
 Часть работы уже выполнена одним агентом:
@@ -138,6 +153,69 @@ Do H1–H7, commit after each. Target ≥70% coverage on services.
 
 ---
 
+## Agent A2: Progressive Login Lockout
+
+**Зависимости:** Agent A (redis, rateLimit), Agent C (auth routes). Уже есть Auth и rateLimit.
+
+**Ветка:** `feat/progressive-login-lockout`
+
+**Контекст:** Сейчас `POST /auth/login` использует фиксированный лимит через `@fastify/rate-limit` (N попыток на 15 мин). По [security.md](samreshu_docs/principles/security.md) нужен **прогрессивный lockout** — считаются только **неудачные** попытки входа, с нарастающим временем блокировки:
+
+| Неудачных попыток | Блокировка |
+|-------------------|------------|
+| 5 за 15 мин       | 15 минут   |
+| 10 за 1 час       | 1 час      |
+| 20 за 24 часа     | 24 часа    |
+
+Счётчики в Redis по ключу `lockout:<ip>`. При успешном логине — сброс счётчиков.
+
+**Задача A2-1:**
+
+1. **Создать `src/utils/loginLockout.ts`** — утилита для работы с Redis:
+   - `checkBlocked(redis, ip: string)` → `{ blocked: boolean, retryAfter?: number }` — проверяет `lockout:blocked:<ip>`; если ключ есть и TTL > 0, возвращает `{ blocked: true, retryAfter }`.
+   - `recordFailedAttempt(redis, ip: string)` — INCR по ключам `lockout:15m:<ip>`, `lockout:1h:<ip>`, `lockout:24h:<ip>` с TTL 15m/1h/24h; при достижении порогов (5/10/20) устанавливает `lockout:blocked:<ip>` с соответствующим TTL.
+   - `clearOnSuccess(redis, ip: string)` — DEL всех ключей `lockout:*:<ip>` и `lockout:blocked:<ip>`.
+
+2. **Обновить `src/plugins/rateLimit.ts`** — убрать `login` из `rateLimitOptions` (больше не используется для login). Остальные endpoints без изменений.
+
+3. **Обновить `src/routes/auth.ts`** — для `POST /login`:
+   - Убрать `config: { rateLimit: rateLimitOptions.login }`.
+   - Добавить `preValidation`: вызвать `checkBlocked(app.redis, req.ip)`; если `blocked` — `reply.status(429).send({ error: { code: 'RATE_LIMIT_EXCEEDED', message: '...', retryAfter } })`.
+   - В handler: обернуть `authService.login(...)` в try/catch; при успехе — `clearOnSuccess(app.redis, ip)`; при throw (например `unauthorized`) — `recordFailedAttempt(app.redis, ip)`, затем rethrow.
+
+4. **Опционально** — вынести пороги (5, 10, 20) и окна в `env.ts` или оставить константами в `loginLockout.ts` (документация security.md указывает фиксированные значения).
+
+**Коммит:** `feat: replace fixed login rate limit with progressive lockout`
+
+**Итого:** 1 коммит. После — PR в `dev`.
+
+---
+
+## Agent A2-2: Fix Login Lockout Tests (после A2)
+
+**Зависимости:** Agent A2 выполнен.
+
+**Ветка:** `fix/login-lockout-test-mock`
+
+**Проблема:** Auth routes используют `app.redis` для `checkBlocked`, `recordFailedAttempt`, `clearOnSuccess`. В `buildAuthTestApp` Redis не подключён — тесты `POST /auth/login` падают с 500.
+
+**Задача A2-2:**
+
+1. **Добавить mock Redis** в `tests/helpers/build-test-app.ts`:
+   - Создать объект, реализующий минимальный интерфейс ioredis для loginLockout: `ttl`, `setex`, `del`, `eval`.
+   - `ttl(key)` → -2 (ключ не существует) или -1/положительное значение для тестов.
+   - `setex`, `del` → no-op или простая in-memory имитация.
+   - `eval(script, keysCount, ...keys, ...args)` → вернуть `[0, 0, 0]` (счётчики не достигли порога).
+   - `app.decorate('redis', mockRedis)` перед регистрацией auth routes.
+
+2. **Обновить `rateLimitOptions`** в buildAuthTestApp — убрать `login` (его больше нет в типе из rateLimit.ts).
+
+**Коммит:** `test: add mock Redis for auth integration tests with login lockout`
+
+**Итого:** 1 коммит. Проверить: `npm run test -- tests/integration/auth.routes.test.ts` проходит.
+
+---
+
 ## Agent B: Data Model & Drizzle Schema
 
 **Зависимости:** Agent A (нужен database plugin). Может стартовать после A4.

AGENT_TASK_BACKEND_SYNC.md

@@ -0,0 +1,221 @@
+# Задача: Синхронизация бэкенда с документацией
+
+## Контекст
+
+По итогам аудита документации vs кода приняты решения. Данная задача — изменения в backend-репозитории.
+
+---
+
+## 0. Настройка Cookie в Fastify
+
+Cookie нужны для хранения refresh token (httpOnly). Без этого разделы 3, 4 и 5 (logout, refresh, login Set-Cookie) не реализуемы.
+
+### 0.1 Установка плагина
+
+```bash
+npm install @fastify/cookie
+```
+
+### 0.2 Регистрация в app.ts
+
+Зарегистрировать **до** auth-роутов (cookie должны быть доступны в onRequest):
+
+```ts
+import cookie from '@fastify/cookie';
+
+// После securityPlugin, до authPlugin
+await app.register(cookie, {
+  secret: env.JWT_SECRET,  // для подписанных cookie (опционально)
+  parseOptions: {},       // опции для парсинга входящих cookie
+});
+```
+
+Порядок плагинов: `redis` → `database` → `security` → `cookie` → `rateLimit` → `auth` → `subscription` → routes.
+
+### 0.3 Чтение cookie в роуте
+
+```ts
+const refreshToken = req.cookies.refreshToken;  // string | undefined
+```
+
+Если cookie не передан, `refreshToken` будет `undefined`.
+
+### 0.4 Установка cookie в ответе
+
+```ts
+reply.setCookie('refreshToken', token, {
+  httpOnly: true,
+  secure: env.NODE_ENV === 'production',
+  sameSite: 'strict',
+  path: '/api/v1/auth',
+  maxAge: 604800,        // 7 дней в секундах
+  signed: false,         // если не используем подпись
+});
+```
+
+Для production: `secure: true` (только HTTPS). Для development: `secure: false`, иначе cookie не установится на localhost:3000 (если без HTTPS).
+
+### 0.5 Очистка cookie (logout)
+
+```ts
+reply.clearCookie('refreshToken', {
+  path: '/api/v1/auth',
+  httpOnly: true,
+  secure: env.NODE_ENV === 'production',
+  sameSite: 'strict',
+});
+```
+
+Либо `reply.setCookie('refreshToken', '', { ... same opts ..., maxAge: 0 })`.
+
+### 0.6 CORS и credentials
+
+Убедиться, что CORS настроен с `credentials: true` (уже есть в `@fastify/cors`), иначе браузер не будет отправлять cookie с cross-origin запросами. Origin фронтенда должен быть в whitelist `CORS_ORIGINS`.
+
+### 0.7 Согласование пути cookie и роутов
+
+Cookie с `path: '/api/v1/auth'` отправляется только на запросы к `/api/v1/auth/*`. Refresh и logout должны вызываться по этим путям.
+
+---
+
+## 1. Префикс /api/v1
+
+**Файл:** `src/app.ts`
+
+При регистрации роутов добавить префикс `/api/v1`:
+
+```ts
+await app.register(authRoutes, { prefix: '/api/v1/auth' });
+await app.register(profileRoutes, { prefix: '/api/v1/profile' });
+await app.register(testsRoutes, { prefix: '/api/v1/tests' });
+await app.register(adminQuestionsRoutes, { prefix: '/api/v1/admin' });
+```
+
+Health check оставить без префикса (например `/health`) или перенести по необходимости.
+
+---
+
+## 2. Auth: Login — вернуть объект user в ответ
+
+**Файлы:** `src/routes/auth.ts`, `src/services/auth/auth.service.ts`
+
+- `AuthService.login()` должен возвращать `{ user, accessToken, refreshToken, expiresIn }`.
+- `user`: `{ id, email, nickname, avatarUrl, role, emailVerified }` — нужно подтянуть из БД.
+- Фронтенду нужны id, nickname, avatarUrl для стейта (шапка, Redux/Pinia).
+
+---
+
+## 3. Auth: Logout — по документации (cookie, Bearer)
+
+**Файлы:** `src/routes/auth.ts`, `src/services/auth/auth.service.ts`
+
+- **Авторизация:** Bearer token в заголовке.
+- **Request:** пустое тело (refresh token читается из cookie).
+- **Response:** 200 с `{ message: "Logged out successfully" }`.
+- Set-Cookie: `refreshToken=; ... Max-Age=0` для очистки cookie.
+
+Требуется:
+
+- Читать refresh token из cookie `refreshToken` (httpOnly cookie).
+- Удалять сессию по хешу refresh token.
+- Очищать cookie в ответе.
+
+---
+
+## 4. Auth: Refresh — по документации (cookie)
+
+**Файлы:** `src/routes/auth.ts`, `src/services/auth/auth.service.ts`
+
+- **Request:** пустое тело (refresh token из cookie).
+- **Response:** 200 с `{ accessToken }`.
+- Set-Cookie: новый refreshToken (ротация).
+
+Требуется:
+
+- Читать refresh token из cookie.
+- Убрать `refreshToken` из body в schema и коде.
+- Устанавливать httpOnly cookie с новым refresh token в ответе.
+
+---
+
+## 5. Auth: Login — установка cookie при успехе
+
+При успешном login устанавливать refresh token в httpOnly cookie:
+
+```text
+Set-Cookie: refreshToken=<token>; HttpOnly; Secure; SameSite=Strict; Path=/api/v1/auth; Max-Age=604800
+```
+
+В development (`NODE_ENV=development`) Secure можно опустить, если используется HTTP.
+
+---
+
+## 6. Profile: добавить role и plan в getPrivateProfile
+
+**Файлы:** `src/services/user/user.service.ts`, `src/routes/profile.ts`
+
+- Расширить `PrivateProfile`: добавить `role`, `plan`.
+- `role` — из `users.role`.
+- `plan` — из `subscriptions` через subscription middleware (уже загружается в `req.subscription` для GET /profile).
+- В route GET /profile после `getPrivateProfile` добавить в ответ `role: req.user` (из users) и `plan: req.subscription?.plan ?? 'free'`.
+
+Либо загружать subscription в UserService при запросе профиля и включать plan/role в ответ.
+
+---
+
+## 7. Tests: score — хранить и отдавать количество правильных
+
+**Файлы:** `src/services/tests/tests.service.ts`, `src/db/schema/tests.ts` (если нужно)
+
+- `score` в БД и API = количество правильных ответов (integer), не процент.
+- В `finishTest`: `score = correctCount` (не `Math.round((correctCount / questions.length) * 100)`).
+- В ответе finish и results: `{ score, totalQuestions, percentage }`, где `percentage = (score / totalQuestions) * 100`.
+
+---
+
+## 8. question_cache_meta: привести схему к документации
+
+**Файлы:** `src/db/schema/questionCacheMeta.ts`, миграция, `src/services/llm/llm.service.ts`, `src/services/questions/question.service.ts`
+
+Документация (llm/strategy.md) требует:
+
+| Поле | Тип | Описание |
+| - | - | - |
+| model | varchar | Уже есть как llm_model |
+| generation_time_ms | integer | Есть |
+| prompt_hash | varchar | Есть |
+| valid | boolean | Прошёл ли валидацию с первого раза |
+| retry_count | integer | Сколько retry потребовалось |
+| questions_generated | integer | Сколько вопросов вернул LLM |
+
+Действия:
+
+1. Добавить в схему `questionCacheMeta`: `valid` (boolean), `retryCount` (integer), `questionsGenerated` (integer).
+2. Создать миграцию Drizzle.
+3. Расширить `LlmGenerationMeta` в llm.service: `valid`, `retryCount`, `questionsGenerated`.
+4. В `LlmService.generateQuestions` и `chatWithMeta`: при необходимости возвращать retry count.
+5. В `QuestionService.generateAndPersistQuestions`: при вставке в `questionCacheMeta` передавать новые поля.
+
+---
+
+## 9. Cookie-настройки
+
+- Путь для cookie: `/api/v1/auth` (совпадает с префиксом auth-роутов).
+- Max-Age для refresh: 604800 (7 дней).
+- Secure: только в production (NODE_ENV=production).
+- SameSite=Strict.
+
+---
+
+## Чеклист
+
+- [x] @fastify/cookie установлен и зарегистрирован (раздел 0)
+- [x] Префикс /api/v1 для роутов
+- [x] Login: user в ответе (id, nickname, avatarUrl, role, emailVerified)
+- [x] Login: Set-Cookie refreshToken
+- [x] Logout: Bearer + cookie, пустое тело, 200 + message
+- [x] Refresh: cookie, пустое тело, 200 + accessToken + Set-Cookie
+- [x] getPrivateProfile: role, plan
+- [x] Tests finish: score = correctCount, возвращать score, totalQuestions, percentage
+- [x] question_cache_meta: valid, retryCount, questionsGenerated
+- [x] Обновить тесты под новые контракты

AGENT_TASK_DOCS_SYNC.md

@@ -0,0 +1,157 @@
+# Задача: Синхронизация документации с реализацией
+
+## Контекст
+
+По итогам аудита документация должна быть приведена в соответствие с текущей реализацией backend. Данная задача — правки в samreshu_docs (submodule или основной репо с документацией).
+
+---
+
+## 1. API: Базовый URL
+
+Убедиться, что базовый URL `/api/v1` соответствует backend (после внесения префикса агентом backend). Если в docs есть примеры с другим базовым путём — исправить.
+
+---
+
+## 2. Auth: Register
+
+**Файл:** `samreshu_docs/api/contracts.md`
+
+- Регистрация **не выдаёт токены** до подтверждения email.
+- Response 201: `{ userId, message, verificationCode }` (verificationCode — для dev/тестов, в prod не отдаётся).
+- Добавить ошибку `NICKNAME_TAKEN` (409), если в коде она есть.
+
+---
+
+## 3. Auth: Login
+
+- Ошибка при блокировке (lockout): **429** `RATE_LIMIT_EXCEEDED` (не 403 ACCOUNT_LOCKED).
+- Response 200 должен включать объект `user`: `{ id, email, nickname, avatarUrl, role, emailVerified }`.
+- Set-Cookie: refreshToken (httpOnly, Secure, SameSite=Strict, Path=/api/v1/auth).
+
+---
+
+## 4. Auth: Verify-email
+
+- **Request:** `{ userId, code }` (не только code).
+- **Авторизация:** не требуется (Bearer не нужен).
+
+---
+
+## 5. Auth: Reset-password
+
+- **Request:** поле `newPassword` (не `password`).
+
+---
+
+## 6. Profile: GET /profile
+
+- В ответе: `role`, `plan` (из subscriptions).
+
+---
+
+## 7. Profile: GET /profile/:username (публичный профиль)
+
+- Структура `stats`: `{ byStack, totalTestsTaken, totalQuestions, correctAnswers, accuracy }` (а не только testsCompleted, averageScore).
+- Описать формат `byStack` и остальных полей.
+
+---
+
+## 8. Tests: POST /tests (создание)
+
+- Response: тест со списком **всех** вопросов в `questions` (не только текущий в `question`).
+- Структура ответа: `{ id, stack, level, questionCount, status, startedAt, timeLimitSeconds, questions: [...] }`.
+
+---
+
+## 9. Tests: POST /tests/:id/answer
+
+- Response: полный snapshot отвеченного вопроса (формат из реализации).
+- Указать, что структура может отличаться от минимальной "answered + progress + nextQuestion".
+
+---
+
+## 10. Tests: POST /tests/:id/finish
+
+- `score` — количество правильных ответов (integer).
+- В ответе: `score`, `totalQuestions`, `percentage` (процент считает фронтенд или он приходит с бэка).
+
+---
+
+## 11. Tests: GET /tests/history (или GET /tests для истории)
+
+- **Пагинация:** offset-based: `limit`, `offset` (не cursor).
+- Формат: `{ tests: [...], total }` (не `{ data, pagination }`).
+- Указать параметры `limit`, `offset`.
+
+---
+
+## 12. Admin
+
+- Эндпоинт списка: **GET /admin/questions/pending** (не /queue).
+- Отдельные эндпоинты: **POST /admin/questions/:id/approve**, **POST /admin/questions/:id/reject**.
+- **PATCH /admin/questions/:id** — для редактирования контента (без смены статуса).
+- Пагинация: limit/offset.
+
+---
+
+## 13. Database: Токены верификации
+
+**Файл:** `samreshu_docs/database/schema.md`
+
+- Вместо общей таблицы `verification_tokens` описать:
+  - `email_verification_codes` (userId, code, expiresAt)
+  - `password_reset_tokens` (userId, tokenHash, expiresAt)
+
+---
+
+## 14. Security: CORS
+
+**Файл:** `samreshu_docs/principles/security.md`
+
+- Origins задаются через переменную окружения **CORS_ORIGINS** (не хардкод localhost/prod).
+- Методы: **GET, POST, PATCH, DELETE, PUT, OPTIONS** (OPTIONS нужен для preflight, PUT — для идемпотентных обновлений).
+
+---
+
+## 15. Security: Helmet (CSP, COEP)
+
+- **CSP и COEP отключены** — бэкенд отдаёт только JSON API.
+- Эти заголовки предназначены для HTML-страниц; для REST API они не нужны и могут мешать Swagger UI.
+
+---
+
+## 16. LLM: Переменные окружения
+
+**Файлы:** `samreshu_docs/llm/strategy.md`, `samreshu_docs/onboarding/setup.md`
+
+Добавить в документацию:
+- **LLM_FALLBACK_MODEL** — запасная модель при падении основной.
+- **LLM_RETRY_DELAY_MS** — задержка между retry при ошибках API.
+
+---
+
+## 17. LLM: Логирование в question_cache_meta
+
+**Файл:** `samreshu_docs/llm/strategy.md`
+
+- Актуальная структура: `llm_model`, `prompt_hash`, `generation_time_ms`, `valid`, `retry_count`, `questions_generated`, `raw_response` (опционально).
+
+---
+
+## 18. Onboarding: .env.example
+
+- Закрепить правило: `.env.example` обновляется при добавлении новых фич (новые переменные, rate limits, LLM и т.д.).
+- Упомянуть требование JWT_SECRET >= 32 символа.
+
+---
+
+## Чеклист
+
+- [ ] api/contracts.md: register, login, verify-email, reset-password, logout, refresh
+- [ ] api/contracts.md: profile (role, plan, stats)
+- [ ] api/contracts.md: tests (create, answer, finish, history)
+- [ ] api/contracts.md: admin (pending, approve, reject, PATCH)
+- [ ] database/schema.md: email_verification_codes, password_reset_tokens
+- [ ] principles/security.md: CORS, Helmet
+- [ ] llm/strategy.md: LLM_FALLBACK_MODEL, LLM_RETRY_DELAY_MS, question_cache_meta
+- [ ] onboarding/setup.md: правило .env.example

package-lock.json

@@ -8,6 +8,7 @@
       "name": "samreshu-backend",
       "version": "0.1.0",
       "dependencies": {
+        "@fastify/cookie": "^11.0.2",
         "@fastify/cors": "^10.0.0",
         "@fastify/helmet": "^12.0.0",
         "@fastify/rate-limit": "^10.0.0",
@@ -1180,6 +1181,42 @@
       "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
       "license": "MIT"
     },
+    "node_modules/@fastify/cookie": {
+      "version": "11.0.2",
+      "resolved": "https://registry.npmjs.org/@fastify/cookie/-/cookie-11.0.2.tgz",
+      "integrity": "sha512-GWdwdGlgJxyvNv+QcKiGNevSspMQXncjMZ1J8IvuDQk0jvkzgWWZFNC2En3s+nHndZBGV8IbLwOI/sxCZw/mzA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fastify"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fastify"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "cookie": "^1.0.0",
+        "fastify-plugin": "^5.0.0"
+      }
+    },
+    "node_modules/@fastify/cookie/node_modules/fastify-plugin": {
+      "version": "5.1.0",
+      "resolved": "https://registry.npmjs.org/fastify-plugin/-/fastify-plugin-5.1.0.tgz",
+      "integrity": "sha512-FAIDA8eovSt5qcDgcBvDuX/v0Cjz0ohGhENZ/wpc3y+oZCY2afZ9Baqql3g/lC+OHRnciQol4ww7tuthOb9idw==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fastify"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fastify"
+        }
+      ],
+      "license": "MIT"
+    },
     "node_modules/@fastify/cors": {
       "version": "10.1.0",
       "resolved": "https://registry.npmjs.org/@fastify/cors/-/cors-10.1.0.tgz",

package.json

@@ -20,6 +20,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@fastify/cookie": "^11.0.2",
     "@fastify/cors": "^10.0.0",
     "@fastify/helmet": "^12.0.0",
     "@fastify/rate-limit": "^10.0.0",

src/app.ts

@@ -1,4 +1,5 @@
 import Fastify, { FastifyInstance } from 'fastify';
+import cookie from '@fastify/cookie';
 import { AppError } from './utils/errors.js';
 import databasePlugin from './plugins/database.js';
 import redisPlugin from './plugins/redis.js';
@@ -9,6 +10,7 @@ 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 { adminQuestionsRoutes } from './routes/admin/questions.js';
 import { env } from './config/env.js';
 import { randomUUID } from 'node:crypto';
 
@@ -73,12 +75,17 @@ export async function buildApp(): Promise<FastifyInstance> {
   await app.register(redisPlugin);
   await app.register(databasePlugin);
   await app.register(securityPlugin);
+  await app.register(cookie, {
+    secret: env.JWT_SECRET,
+    parseOptions: {},
+  });
   await app.register(rateLimitPlugin);
   await app.register(authPlugin);
   await app.register(subscriptionPlugin);
-  await app.register(authRoutes, { prefix: '/auth' });
+  await app.register(authRoutes, { prefix: '/api/v1/auth' });
-  await app.register(profileRoutes, { prefix: '/profile' });
+  await app.register(profileRoutes, { prefix: '/api/v1/profile' });
-  await app.register(testsRoutes, { prefix: '/tests' });
+  await app.register(testsRoutes, { prefix: '/api/v1/tests' });
+  await app.register(adminQuestionsRoutes, { prefix: '/api/v1/admin' });
 
   app.get('/health', async () => ({ status: 'ok', timestamp: new Date().toISOString() }));
 

src/config/env.ts

@@ -22,7 +22,6 @@ const envSchema = z.object({
   LLM_TEMPERATURE: z.coerce.number().min(0).max(2).default(0.7),
   LLM_MAX_TOKENS: z.coerce.number().default(2048),
 
-  RATE_LIMIT_LOGIN: z.coerce.number().default(5),
   RATE_LIMIT_REGISTER: z.coerce.number().default(3),
   RATE_LIMIT_FORGOT_PASSWORD: z.coerce.number().default(3),
   RATE_LIMIT_VERIFY_EMAIL: z.coerce.number().default(5),

src/db/migrations/0001_fluffy_yellowjacket.sql

@@ -0,0 +1,3 @@
+ALTER TABLE "question_cache_meta" ADD COLUMN "valid" boolean DEFAULT true NOT NULL;--> statement-breakpoint
+ALTER TABLE "question_cache_meta" ADD COLUMN "retry_count" integer DEFAULT 0 NOT NULL;--> statement-breakpoint
+ALTER TABLE "question_cache_meta" ADD COLUMN "questions_generated" integer DEFAULT 0 NOT NULL;

src/db/migrations/meta/_journal.json

@@ -8,6 +8,13 @@
       "when": 1772620981431,
       "tag": "0000_fearless_salo",
       "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1772792192122,
+      "tag": "0001_fluffy_yellowjacket",
+      "breakpoints": true
     }
   ]
 }

src/db/schema/questionCacheMeta.ts

@@ -1,4 +1,4 @@
-import { pgTable, uuid, varchar, integer, timestamp } from 'drizzle-orm/pg-core';
+import { pgTable, uuid, varchar, integer, timestamp, boolean } from 'drizzle-orm/pg-core';
 import { jsonb } from 'drizzle-orm/pg-core';
 import { questionBank } from './questionBank.js';
 
@@ -11,6 +11,9 @@ export const questionCacheMeta = pgTable('question_cache_meta', {
   promptHash: varchar('prompt_hash', { length: 64 }).notNull(),
   generationTimeMs: integer('generation_time_ms').notNull(),
   rawResponse: jsonb('raw_response').$type<unknown>(),
+  valid: boolean('valid').notNull().default(true),
+  retryCount: integer('retry_count').notNull().default(0),
+  questionsGenerated: integer('questions_generated').notNull().default(0),
   createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
 });
 

src/plugins/auth.ts

@@ -1,11 +1,14 @@
 import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
 import fp from 'fastify-plugin';
+import { eq } from 'drizzle-orm';
 import { verifyToken, isAccessPayload } from '../utils/jwt.js';
-import { unauthorized } from '../utils/errors.js';
+import { unauthorized, forbidden } from '../utils/errors.js';
+import { users } from '../db/schema/users.js';
 
 declare module 'fastify' {
   interface FastifyInstance {
     authenticate: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
+    authenticateAdmin: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
   }
   interface FastifyRequest {
     user?: { id: string; email: string };
@@ -34,9 +37,22 @@ export async function authenticate(req: FastifyRequest, _reply: FastifyReply): P
   }
 }
 
+export async function authenticateAdmin(req: FastifyRequest, _reply: FastifyReply): Promise<void> {
+  if (!req.user) {
+    throw unauthorized('Authentication required');
+  }
+
+  const [user] = await req.server.db.select({ role: users.role }).from(users).where(eq(users.id, req.user.id));
+
+  if (!user || user.role !== 'admin') {
+    throw forbidden('Admin access required');
+  }
+}
+
 const authPlugin = async (app: FastifyInstance) => {
   app.decorateRequest('user', undefined);
   app.decorate('authenticate', authenticate);
+  app.decorate('authenticateAdmin', authenticateAdmin);
 };
 
-export default fp(authPlugin, { name: 'auth' });
+export default fp(authPlugin, { name: 'auth', dependencies: ['database'] });

src/plugins/rateLimit.ts

@@ -6,7 +6,6 @@ import { env } from '../config/env.js';
 declare module 'fastify' {
   interface FastifyInstance {
     rateLimitOptions: {
-      login: { max: number; timeWindow: string };
       register: { max: number; timeWindow: string };
       forgotPassword: { max: number; timeWindow: string };
       verifyEmail: { max: number; timeWindow: string };
@@ -18,7 +17,6 @@ declare module 'fastify' {
 
 const rateLimitPlugin: FastifyPluginAsync = async (app: FastifyInstance) => {
   const options = {
-    login: { max: env.RATE_LIMIT_LOGIN, timeWindow: '15 minutes' },
     register: { max: env.RATE_LIMIT_REGISTER, timeWindow: '1 hour' },
     forgotPassword: { max: env.RATE_LIMIT_FORGOT_PASSWORD, timeWindow: '1 hour' },
     verifyEmail: { max: env.RATE_LIMIT_VERIFY_EMAIL, timeWindow: '15 minutes' },

src/routes/admin/questions.ts

@@ -0,0 +1,131 @@
+import type { FastifyInstance } from 'fastify';
+import { AdminQuestionService } from '../../services/admin/admin-question.service.js';
+import type { EditQuestionInput } from '../../services/admin/admin-question.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 QUESTION_TYPES = ['single_choice', 'multiple_select', 'true_false', 'short_text'] as const;
+
+const listPendingQuerySchema = {
+  querystring: {
+    type: 'object',
+    properties: {
+      limit: { type: 'integer', minimum: 1, maximum: 100 },
+      offset: { type: 'integer', minimum: 0 },
+    },
+    additionalProperties: false,
+  },
+};
+
+const questionIdParamsSchema = {
+  params: {
+    type: 'object',
+    required: ['questionId'],
+    properties: {
+      questionId: { type: 'string', format: 'uuid' },
+    },
+  },
+};
+
+const editQuestionSchema = {
+  params: {
+    type: 'object',
+    required: ['questionId'],
+    properties: {
+      questionId: { type: 'string', format: 'uuid' },
+    },
+  },
+  body: {
+    type: 'object',
+    properties: {
+      stack: { type: 'string', enum: [...STACKS] },
+      level: { type: 'string', enum: [...LEVELS] },
+      type: { type: 'string', enum: [...QUESTION_TYPES] },
+      questionText: { type: 'string', minLength: 1 },
+      options: {
+        type: 'array',
+        items: {
+          type: 'object',
+          required: ['key', 'text'],
+          properties: {
+            key: { type: 'string' },
+            text: { type: 'string' },
+          },
+        },
+      },
+      correctAnswer: {
+        oneOf: [
+          { type: 'string' },
+          { type: 'array', items: { type: 'string' } },
+        ],
+      },
+      explanation: { type: 'string', minLength: 1 },
+    },
+    additionalProperties: false,
+  },
+};
+
+export async function adminQuestionsRoutes(app: FastifyInstance) {
+  const adminQuestionService = new AdminQuestionService(app.db);
+  const { rateLimitOptions } = app;
+
+  app.get(
+    '/questions/pending',
+    {
+      schema: listPendingQuerySchema,
+      config: { rateLimit: rateLimitOptions.apiAuthed },
+      preHandler: [app.authenticate, app.authenticateAdmin],
+    },
+    async (req, reply) => {
+      const { limit, offset } = (req.query as { limit?: number; offset?: number }) ?? {};
+      const result = await adminQuestionService.listPending(limit, offset);
+      return reply.send(result);
+    },
+  );
+
+  app.post(
+    '/questions/:questionId/approve',
+    {
+      schema: questionIdParamsSchema,
+      config: { rateLimit: rateLimitOptions.apiAuthed },
+      preHandler: [app.authenticate, app.authenticateAdmin],
+    },
+    async (req, reply) => {
+      const adminId = req.user!.id;
+      const { questionId } = req.params as { questionId: string };
+      await adminQuestionService.approve(questionId, adminId);
+      return reply.status(204).send();
+    },
+  );
+
+  app.post(
+    '/questions/:questionId/reject',
+    {
+      schema: questionIdParamsSchema,
+      config: { rateLimit: rateLimitOptions.apiAuthed },
+      preHandler: [app.authenticate, app.authenticateAdmin],
+    },
+    async (req, reply) => {
+      const adminId = req.user!.id;
+      const { questionId } = req.params as { questionId: string };
+      await adminQuestionService.reject(questionId, adminId);
+      return reply.status(204).send();
+    },
+  );
+
+  app.patch(
+    '/questions/:questionId',
+    {
+      schema: editQuestionSchema,
+      config: { rateLimit: rateLimitOptions.apiAuthed },
+      preHandler: [app.authenticate, app.authenticateAdmin],
+    },
+    async (req, reply) => {
+      const adminId = req.user!.id;
+      const { questionId } = req.params as { questionId: string };
+      const body = req.body as EditQuestionInput;
+      const question = await adminQuestionService.edit(questionId, body, adminId);
+      return reply.send(question);
+    },
+  );
+}

src/routes/auth.ts

@@ -1,5 +1,21 @@
 import type { FastifyInstance } from 'fastify';
 import { AuthService } from '../services/auth/auth.service.js';
+import { checkBlocked, clearOnSuccess, recordFailedAttempt } from '../utils/loginLockout.js';
+import { env } from '../config/env.js';
+
+const COOKIE_PATH = '/api/v1/auth';
+const REFRESH_MAX_AGE = 604800; // 7 days
+
+function getRefreshCookieOptions() {
+  return {
+    httpOnly: true,
+    secure: env.NODE_ENV === 'production',
+    sameSite: 'strict' as const,
+    path: COOKIE_PATH,
+    maxAge: REFRESH_MAX_AGE,
+    signed: false,
+  };
+}
 
 const registerSchema = {
   body: {
@@ -24,17 +40,11 @@ const loginSchema = {
   },
 };
 
-const refreshTokenSchema = {
+/** Refresh: empty body, token from cookie */
-  body: {
+const refreshSchema = { body: { type: 'object', properties: {} } };
-    type: 'object',
-    required: ['refreshToken'],
-    properties: {
-      refreshToken: { type: 'string' },
-    },
-  },
-};
 
-const logoutSchema = refreshTokenSchema;
+/** Logout: Bearer + cookie, empty body */
+const logoutSchema = { body: { type: 'object', properties: {} } };
 
 const verifyEmailSchema = {
   body: {
@@ -89,48 +99,83 @@ export async function authRoutes(app: FastifyInstance) {
 
   app.post(
     '/login',
-    { schema: loginSchema, config: { rateLimit: rateLimitOptions.login } },
+    {
+      schema: loginSchema,
+      preValidation: async (req, reply) => {
+        const ip = req.ip ?? 'unknown';
+        const { blocked, retryAfter } = await checkBlocked(app.redis, ip);
+        if (blocked) {
+          if (retryAfter !== undefined) {
+            reply.header('Retry-After', String(retryAfter));
+          }
+          return reply.status(429).send({
+            error: {
+              code: 'RATE_LIMIT_EXCEEDED',
+              message: 'Too many failed login attempts. Please try again later.',
+              retryAfter,
+            },
+          });
+        }
+      },
+    },
     async (req, reply) => {
       const body = req.body as { email: string; password: string };
       const userAgent = req.headers['user-agent'];
-      const ipAddress = req.ip;
+      const ip = req.ip ?? 'unknown';
 
-      const result = await authService.login({
+      try {
-        email: body.email,
+        const result = await authService.login({
-        password: body.password,
+          email: body.email,
-        userAgent,
+          password: body.password,
-        ipAddress,
+          userAgent,
-      });
+          ipAddress: ip,
-
+        });
-      return reply.send(result);
+        await clearOnSuccess(app.redis, ip);
+        reply.setCookie('refreshToken', result.refreshToken, getRefreshCookieOptions());
+        return reply.send(result);
+      } catch (err) {
+        await recordFailedAttempt(app.redis, ip);
+        throw err;
+      }
     },
   );
 
   app.post(
     '/logout',
-    { schema: logoutSchema, config: { rateLimit: rateLimitOptions.apiGuest } },
+    {
+      schema: logoutSchema,
+      config: { rateLimit: rateLimitOptions.apiGuest },
+      preHandler: [app.authenticate],
+    },
     async (req, reply) => {
-      const body = req.body as { refreshToken: string };
+      const refreshToken = req.cookies?.refreshToken;
-      await authService.logout(body.refreshToken);
+      await authService.logout(refreshToken);
-      return reply.status(204).send();
+      reply.clearCookie('refreshToken', {
+        path: COOKIE_PATH,
+        httpOnly: true,
+        secure: env.NODE_ENV === 'production',
+        sameSite: 'strict',
+      });
+      return reply.status(200).send({ message: 'Logged out successfully' });
     },
   );
 
   app.post(
     '/refresh',
-    { schema: refreshTokenSchema, config: { rateLimit: rateLimitOptions.apiGuest } },
+    { schema: refreshSchema, config: { rateLimit: rateLimitOptions.apiGuest } },
     async (req, reply) => {
-      const body = req.body as { refreshToken: string };
+      const refreshToken = req.cookies?.refreshToken;
       const userAgent = req.headers['user-agent'];
       const ipAddress = req.ip;
 
       const result = await authService.refresh({
-        refreshToken: body.refreshToken,
+        refreshToken,
         userAgent,
         ipAddress,
       });
 
-      return reply.send(result);
+      reply.setCookie('refreshToken', result.refreshToken, getRefreshCookieOptions());
+      return reply.send({ accessToken: result.accessToken });
     },
   );
 

src/routes/profile.ts

@@ -38,7 +38,8 @@ export async function profileRoutes(app: FastifyInstance) {
     },
     async (req, reply) => {
       const userId = req.user!.id;
-      const profile = await userService.getPrivateProfile(userId);
+      const plan = req.subscription?.plan ?? 'free';
+      const profile = await userService.getPrivateProfile(userId, plan);
       return reply.send(profile);
     },
   );

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

@@ -0,0 +1,194 @@
+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, auditLogs } 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, adminId: 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');
+    }
+
+    await this.db.insert(auditLogs).values({
+      adminId,
+      action: 'question_approved',
+      targetType: 'question',
+      targetId: questionId,
+    });
+  }
+
+  async reject(questionId: string, adminId: 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');
+    }
+
+    await this.db.insert(auditLogs).values({
+      adminId,
+      action: 'question_rejected',
+      targetType: 'question',
+      targetId: questionId,
+    });
+  }
+
+  async edit(questionId: string, input: EditQuestionInput, adminId: string): 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');
+    }
+
+    await this.db.insert(auditLogs).values({
+      adminId,
+      action: 'question_edited',
+      targetType: 'question',
+      targetId: questionId,
+      details: updates as Record<string, unknown>,
+    });
+
+    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/auth/auth.service.ts

@@ -34,14 +34,24 @@ export interface LoginInput {
   ipAddress?: string;
 }
 
+export interface LoginUser {
+  id: string;
+  email: string;
+  nickname: string;
+  avatarUrl: string | null;
+  role: string;
+  emailVerified: boolean;
+}
+
 export interface LoginResult {
+  user: LoginUser;
   accessToken: string;
   refreshToken: string;
   expiresIn: number;
 }
 
 export interface RefreshInput {
-  refreshToken: string;
+  refreshToken: string | undefined;
   userAgent?: string;
   ipAddress?: string;
 }
@@ -138,18 +148,24 @@ export class AuthService {
     });
 
     return {
+      user: {
+        id: user.id,
+        email: user.email,
+        nickname: user.nickname,
+        avatarUrl: user.avatarUrl ?? null,
+        role: user.role,
+        emailVerified: !!user.emailVerifiedAt,
+      },
       accessToken,
       refreshToken,
       expiresIn: Math.floor(REFRESH_TTL_MS / 1000),
     };
   }
 
-  async logout(refreshToken: string): Promise<void> {
+  async refresh(input: RefreshInput): Promise<{ accessToken: string; refreshToken: string; expiresIn: number }> {
-    const hash = hashToken(refreshToken);
+    if (!input.refreshToken) {
-    await this.db.delete(sessions).where(eq(sessions.refreshTokenHash, hash));
+      throw new AppError(ERROR_CODES.INVALID_REFRESH_TOKEN, 'Refresh token required (cookie)', 401);
-  }
+    }
-
-  async refresh(input: RefreshInput): Promise<LoginResult> {
     const payload = await verifyToken(input.refreshToken);
 
     if (!isRefreshPayload(payload)) {
@@ -199,6 +215,12 @@ export class AuthService {
     };
   }
 
+  async logout(refreshToken: string | undefined): Promise<void> {
+    if (!refreshToken) return;
+    const hash = hashToken(refreshToken);
+    await this.db.delete(sessions).where(eq(sessions.refreshTokenHash, hash));
+  }
+
   async verifyEmail(userId: string, verificationCode: string): Promise<void> {
     const codeUpper = verificationCode.toUpperCase();
     const [record] = await this.db

src/services/llm/llm.service.ts

@@ -64,6 +64,9 @@ export interface LlmGenerationMeta {
   promptHash: string;
   generationTimeMs: number;
   rawResponse: unknown;
+  valid: boolean;
+  retryCount: number;
+  questionsGenerated: number;
 }
 
 export interface GenerateQuestionsResult {
@@ -93,8 +96,10 @@ export class LlmService {
     return content;
   }
 
-  /** Returns content and model used (for logging to question_cache_meta) */
+  /** Returns content, model, and retry count (for logging to question_cache_meta) */
-  async chatWithMeta(messages: ChatMessage[]): Promise<{ content: string; model: string }> {
+  async chatWithMeta(
+    messages: ChatMessage[]
+  ): Promise<{ content: string; model: string; retryCount: number }> {
     let lastError: Error | null = null;
 
     const modelsToTry = [this.config.model];
@@ -106,7 +111,7 @@ export class LlmService {
       for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
         try {
           const content = await this.executeChat(messages, model);
-          return { content, model };
+          return { content, model, retryCount: attempt };
         } catch (err) {
           lastError = err instanceof Error ? err : new Error('LLM request failed');
           if (attempt < this.config.maxRetries) {
@@ -185,7 +190,7 @@ Rules: type must be one of: ${typeList}. For single_choice/multiple_select: opti
     const promptHash = createHash('sha256').update(promptForHash).digest('hex');
 
     const start = Date.now();
-    const { content: raw, model } = await this.chatWithMeta([
+    const { content: raw, model, retryCount } = await this.chatWithMeta([
       { role: 'system', content: systemPrompt },
       { role: 'user', content: userPrompt },
     ]);
@@ -221,6 +226,9 @@ Rules: type must be one of: ${typeList}. For single_choice/multiple_select: opti
         promptHash,
         generationTimeMs,
         rawResponse: parsed,
+        valid: retryCount === 0,
+        retryCount,
+        questionsGenerated: questions.length,
       },
     };
   }

src/services/questions/question.service.ts

@@ -179,6 +179,9 @@ export class QuestionService {
           promptHash: meta.promptHash,
           generationTimeMs: meta.generationTimeMs,
           rawResponse: meta.rawResponse,
+          valid: meta.valid,
+          retryCount: meta.retryCount,
+          questionsGenerated: meta.questionsGenerated,
         });
 
         inserted.push({

src/services/tests/tests.service.ts

@@ -39,6 +39,8 @@ export type TestWithQuestions = {
   mode: string;
   status: string;
   score: number | null;
+  totalQuestions: number;
+  percentage: number | null;
   startedAt: string;
   finishedAt: string | null;
   timeLimitSeconds: number | null;
@@ -236,7 +238,7 @@ export class TestsService {
     }
 
     const correctCount = questions.filter((q) => q.isCorrect === true).length;
-    const score = Math.round((correctCount / questions.length) * 100);
+    const score = correctCount; // score = count of correct answers, not percentage
 
     const [updatedTest] = await this.db
       .update(tests)
@@ -368,6 +370,11 @@ export class TestsService {
     test: (typeof tests.$inferSelect),
     questionsRows: (typeof testQuestions.$inferSelect)[]
   ): TestWithQuestions {
+    const totalQuestions = questionsRows.length;
+    const percentage =
+      test.score !== null && totalQuestions > 0
+        ? (test.score / totalQuestions) * 100
+        : null;
     return {
       id: test.id,
       userId: test.userId,
@@ -377,6 +384,8 @@ export class TestsService {
       mode: test.mode,
       status: test.status,
       score: test.score,
+      totalQuestions,
+      percentage,
       startedAt: test.startedAt.toISOString(),
       finishedAt: test.finishedAt?.toISOString() ?? null,
       timeLimitSeconds: test.timeLimitSeconds,

src/services/user/user.service.ts

@@ -1,7 +1,7 @@
 import { eq } from 'drizzle-orm';
 import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
 import type * as schema from '../../db/schema/index.js';
-import { users, userStats } from '../../db/schema/index.js';
+import { users, userStats, subscriptions } from '../../db/schema/index.js';
 import { notFound, conflict, ERROR_CODES } from '../../utils/errors.js';
 import type { User } from '../../db/schema/users.js';
 import type { SelfLevel } from '../../db/schema/index.js';
@@ -50,6 +50,8 @@ export type PrivateProfile = PublicProfile & {
   emailVerifiedAt: string | null;
   createdAt: string;
   updatedAt: string;
+  role: string;
+  plan: 'free' | 'pro';
 };
 
 async function getStatsForUser(db: Db, userId: string): Promise<ProfileStats> {
@@ -88,13 +90,19 @@ function toPublicProfile(user: User, stats: ProfileStats): PublicProfile {
   };
 }
 
-function toPrivateProfile(user: User, stats: ProfileStats): PrivateProfile {
+function toPrivateProfile(
+  user: User,
+  stats: ProfileStats,
+  plan: 'free' | 'pro' = 'free'
+): PrivateProfile {
   return {
     ...toPublicProfile(user, stats),
     email: user.email,
     emailVerifiedAt: user.emailVerifiedAt?.toISOString() ?? null,
     createdAt: user.createdAt.toISOString(),
     updatedAt: user.updatedAt.toISOString(),
+    role: user.role,
+    plan,
   };
 }
 
@@ -115,12 +123,15 @@ export class UserService {
     return user ?? null;
   }
 
-  async getPrivateProfile(userId: string): Promise<PrivateProfile> {
+  async getPrivateProfile(
+    userId: string,
+    plan: 'free' | 'pro' = 'free'
+  ): Promise<PrivateProfile> {
     const [user, stats] = await Promise.all([this.getById(userId), getStatsForUser(this.db, userId)]);
     if (!user) {
       throw notFound('User not found');
     }
-    return toPrivateProfile(user, stats);
+    return toPrivateProfile(user, stats, plan);
   }
 
   async getPublicProfile(username: string): Promise<PublicProfile> {
@@ -170,6 +181,18 @@ export class UserService {
     }
 
     const stats = await getStatsForUser(this.db, userId);
-    return toPrivateProfile(updated, stats);
+    const plan = await this.getPlanForUser(userId);
+    return toPrivateProfile(updated, stats, plan);
+  }
+
+  async getPlanForUser(userId: string): Promise<'free' | 'pro'> {
+    const [sub] = await this.db
+      .select()
+      .from(subscriptions)
+      .where(eq(subscriptions.userId, userId))
+      .limit(1);
+    if (!sub || (sub.expiresAt && sub.expiresAt < new Date())) return 'free';
+    if (sub.plan === 'pro' && (sub.status === 'active' || sub.status === 'trialing')) return 'pro';
+    return 'free';
   }
 }

src/utils/loginLockout.ts

@@ -0,0 +1,106 @@
+import type { Redis } from 'ioredis';
+
+const WINDOW_15M_SEC = 15 * 60;   // 900
+const WINDOW_1H_SEC = 60 * 60;   // 3600
+const WINDOW_24H_SEC = 24 * 60 * 60; // 86400
+
+const THRESHOLD_15M = 5;
+const THRESHOLD_1H = 10;
+const THRESHOLD_24H = 20;
+
+const BLOCK_15M_SEC = WINDOW_15M_SEC;
+const BLOCK_1H_SEC = WINDOW_1H_SEC;
+const BLOCK_24H_SEC = WINDOW_24H_SEC;
+
+const KEY_PREFIX = 'lockout';
+
+function key15m(ip: string): string {
+  return `${KEY_PREFIX}:15m:${ip}`;
+}
+function key1h(ip: string): string {
+  return `${KEY_PREFIX}:1h:${ip}`;
+}
+function key24h(ip: string): string {
+  return `${KEY_PREFIX}:24h:${ip}`;
+}
+function keyBlocked(ip: string): string {
+  return `${KEY_PREFIX}:blocked:${ip}`;
+}
+
+/**
+ * Check if the IP is currently blocked due to progressive login lockout.
+ * @returns { blocked: true, retryAfter } if blocked, { blocked: false } otherwise
+ */
+export async function checkBlocked(
+  redis: Redis,
+  ip: string
+): Promise<{ blocked: boolean; retryAfter?: number }> {
+  const blockedKey = keyBlocked(ip);
+  const ttl = await redis.ttl(blockedKey);
+  if (ttl > 0) {
+    return { blocked: true, retryAfter: ttl };
+  }
+  return { blocked: false };
+}
+
+const RECORD_SCRIPT = `
+  local c15 = redis.call('INCR', KEYS[1])
+  if redis.call('TTL', KEYS[1]) == -1 then redis.call('EXPIRE', KEYS[1], ARGV[1]) end
+  local c1h = redis.call('INCR', KEYS[2])
+  if redis.call('TTL', KEYS[2]) == -1 then redis.call('EXPIRE', KEYS[2], ARGV[2]) end
+  local c24 = redis.call('INCR', KEYS[3])
+  if redis.call('TTL', KEYS[3]) == -1 then redis.call('EXPIRE', KEYS[3], ARGV[3]) end
+  return {c15, c1h, c24}
+`;
+
+/**
+ * Record a failed login attempt. Increments counters and sets blocked key when thresholds are reached.
+ * Thresholds: 5 in 15m -> 15m block; 10 in 1h -> 1h block; 20 in 24h -> 24h block.
+ */
+export async function recordFailedAttempt(redis: Redis, ip: string): Promise<void> {
+  const k15 = key15m(ip);
+  const k1h = key1h(ip);
+  const k24 = key24h(ip);
+  const kBlocked = keyBlocked(ip);
+
+  const counts = (await redis.eval(
+    RECORD_SCRIPT,
+    3,
+    k15,
+    k1h,
+    k24,
+    String(WINDOW_15M_SEC),
+    String(WINDOW_1H_SEC),
+    String(WINDOW_24H_SEC)
+  )) as number[];
+
+  const count15m = counts[0] ?? 0;
+  const count1h = counts[1] ?? 0;
+  const count24h = counts[2] ?? 0;
+
+  let blockTtl = 0;
+  if (count24h >= THRESHOLD_24H) {
+    blockTtl = BLOCK_24H_SEC;
+  } else if (count1h >= THRESHOLD_1H) {
+    blockTtl = BLOCK_1H_SEC;
+  } else if (count15m >= THRESHOLD_15M) {
+    blockTtl = BLOCK_15M_SEC;
+  }
+
+  if (blockTtl > 0) {
+    await redis.setex(kBlocked, blockTtl, '1');
+  }
+}
+
+/**
+ * Clear all lockout counters and blocked state on successful login.
+ */
+export async function clearOnSuccess(redis: Redis, ip: string): Promise<void> {
+  const keys = [
+    key15m(ip),
+    key1h(ip),
+    key24h(ip),
+    keyBlocked(ip),
+  ];
+  await redis.del(...keys);
+}

tests/helpers/build-admin-test-app.ts

@@ -0,0 +1,51 @@
+import Fastify, { FastifyInstance } from 'fastify';
+import { AppError } from '../../src/utils/errors.js';
+import { adminQuestionsRoutes } from '../../src/routes/admin/questions.js';
+import type { MockDb } from '../test-utils.js';
+import { createMockDb } from '../test-utils.js';
+
+const mockAdminUser = { id: 'admin-1', email: 'admin@test.com' };
+
+/**
+ * Build a minimal Fastify app for admin route integration tests.
+ * Bypasses real auth - preHandlers set req.user to mock admin.
+ */
+export async function buildAdminTestApp(mockDb?: MockDb): Promise<FastifyInstance> {
+  const db = mockDb ?? createMockDb();
+
+  const app = Fastify({
+    logger: false,
+    requestIdHeader: 'x-request-id',
+    requestIdLogLabel: 'requestId',
+  });
+
+  app.setErrorHandler((err: unknown, _request, reply) => {
+    const error = err as Error & { statusCode?: number; validation?: unknown };
+    if (err instanceof AppError) {
+      return reply.status(err.statusCode).send(err.toJSON());
+    }
+    if (error.validation) {
+      return reply.status(422).send({
+        error: { code: 'VALIDATION_ERROR', message: 'Validation failed', details: error.validation },
+      });
+    }
+    return reply.status(500).send({ error: { code: 'INTERNAL_ERROR', message: error.message } });
+  });
+
+  app.decorate('db', db);
+  app.decorate('rateLimitOptions', {
+    apiAuthed: { max: 100, timeWindow: '1 minute' },
+  });
+  app.decorateRequest('user', undefined);
+  app.decorate('authenticate', async (req: { user?: { id: string; email: string } }) => {
+    req.user = mockAdminUser;
+  });
+  app.decorate('authenticateAdmin', async (req: { user?: { id: string; email: string } }) => {
+    if (!req.user) req.user = mockAdminUser;
+    (req.user as { role?: string }).role = 'admin';
+  });
+
+  await app.register(adminQuestionsRoutes, { prefix: '/admin' });
+
+  return app;
+}

tests/helpers/build-test-app.ts

@@ -0,0 +1,76 @@
+import Fastify, { FastifyInstance } from 'fastify';
+import cookie from '@fastify/cookie';
+import fp from 'fastify-plugin';
+import { AppError } from '../../src/utils/errors.js';
+import authPlugin from '../../src/plugins/auth.js';
+import { authRoutes } from '../../src/routes/auth.js';
+import type { MockDb } from '../test-utils.js';
+import { createMockDb } from '../test-utils.js';
+
+const mockDatabasePlugin = (db: MockDb) =>
+  fp(async (app) => {
+    app.decorate('db', db);
+  }, { name: 'database' });
+
+/** Mock Redis for login lockout in auth tests. Implements ttl, setex, del, eval. */
+const mockRedis = {
+  async ttl(_key: string): Promise<number> {
+    return -2; // key does not exist -> not blocked
+  },
+  async setex(_key: string, _ttl: number, _value: string): Promise<'OK'> {
+    return 'OK';
+  },
+  async del(..._keys: string[]): Promise<number> {
+    return 0;
+  },
+  async eval(
+    _script: string,
+    _keysCount: number,
+    ..._keysAndArgs: string[]
+  ): Promise<number[]> {
+    return [0, 0, 0]; // counters below threshold
+  },
+};
+
+/**
+ * Build a minimal Fastify app for auth route integration tests.
+ * Uses mock db, mock Redis for login lockout, and rate limit options (no actual rate limiting).
+ */
+export async function buildAuthTestApp(mockDb?: MockDb): Promise<FastifyInstance> {
+  const db = mockDb ?? createMockDb();
+
+  const app = Fastify({
+    logger: false,
+    requestIdHeader: 'x-request-id',
+    requestIdLogLabel: 'requestId',
+  });
+
+  app.setErrorHandler((err: unknown, request, reply) => {
+    const error = err as Error & { statusCode?: number; validation?: unknown };
+    if (err instanceof AppError) {
+      return reply.status(err.statusCode).send(err.toJSON());
+    }
+    if (error.validation) {
+      return reply.status(422).send({
+        error: { code: 'VALIDATION_ERROR', message: 'Validation failed', details: error.validation },
+      });
+    }
+    return reply.status(500).send({ error: { code: 'INTERNAL_ERROR', message: error.message } });
+  });
+
+  app.decorate('redis', mockRedis);
+  app.decorate('rateLimitOptions', {
+    register: { max: 100, timeWindow: '1 hour' },
+    forgotPassword: { max: 100, timeWindow: '1 hour' },
+    verifyEmail: { max: 100, timeWindow: '15 minutes' },
+    apiAuthed: { max: 100, timeWindow: '1 minute' },
+    apiGuest: { max: 100, timeWindow: '1 minute' },
+  });
+
+  await app.register(mockDatabasePlugin(db));
+  await app.register(cookie, { secret: 'test-secret-at-least-32-characters-long' });
+  await app.register(authPlugin);
+  await app.register(authRoutes, { prefix: '/api/v1/auth' });
+
+  return app;
+}

tests/integration/admin.routes.test.ts

@@ -0,0 +1,140 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { buildAdminTestApp } from '../helpers/build-admin-test-app.js';
+import {
+  createMockDb,
+  selectChainOrderedLimitOffset,
+  selectChainWhere,
+  updateChainReturning,
+  insertChain,
+} from '../test-utils.js';
+
+describe('Admin routes integration', () => {
+  let app: Awaited<ReturnType<typeof buildAdminTestApp>>;
+  let mockDb: ReturnType<typeof createMockDb>;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    mockDb = createMockDb();
+    app = await buildAdminTestApp(mockDb as never);
+  });
+
+  describe('GET /admin/questions/pending', () => {
+    it('returns pending questions list', async () => {
+      const pendingQuestions = [
+        {
+          id: 'q-1',
+          stack: 'js',
+          level: 'beginner',
+          type: 'single_choice',
+          questionText: 'Test question?',
+          options: [{ key: 'a', text: 'A' }],
+          correctAnswer: 'a',
+          explanation: 'Exp',
+          source: 'manual',
+          createdAt: new Date(),
+        },
+      ];
+      (mockDb.select as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(selectChainOrderedLimitOffset(pendingQuestions))
+        .mockReturnValueOnce(selectChainWhere([{ count: 1 }]));
+
+      const res = await app.inject({
+        method: 'GET',
+        url: '/admin/questions/pending',
+        headers: { authorization: 'Bearer any-token' },
+      });
+
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.questions).toHaveLength(1);
+      expect(body.questions[0].questionText).toBe('Test question?');
+      expect(body.total).toBe(1);
+    });
+  });
+
+  describe('POST /admin/questions/:questionId/approve', () => {
+    it('returns 204 on success', async () => {
+      (mockDb.update as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        updateChainReturning([{ id: 'q-1' }])
+      );
+      (mockDb.insert as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        insertChain([])
+      );
+
+      const res = await app.inject({
+        method: 'POST',
+        url: '/admin/questions/11111111-1111-1111-1111-111111111111/approve',
+        headers: { authorization: 'Bearer any-token' },
+      });
+
+      expect(res.statusCode).toBe(204);
+    });
+
+    it('returns 404 when question not found', async () => {
+      (mockDb.update as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        updateChainReturning([])
+      );
+
+      const res = await app.inject({
+        method: 'POST',
+        url: '/admin/questions/11111111-1111-1111-1111-111111111111/approve',
+        headers: { authorization: 'Bearer any-token' },
+      });
+
+      expect(res.statusCode).toBe(404);
+    });
+  });
+
+  describe('POST /admin/questions/:questionId/reject', () => {
+    it('returns 204 on success', async () => {
+      (mockDb.update as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        updateChainReturning([{ id: 'q-1' }])
+      );
+      (mockDb.insert as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        insertChain([])
+      );
+
+      const res = await app.inject({
+        method: 'POST',
+        url: '/admin/questions/11111111-1111-1111-1111-111111111111/reject',
+        headers: { authorization: 'Bearer any-token' },
+      });
+
+      expect(res.statusCode).toBe(204);
+    });
+  });
+
+  describe('PATCH /admin/questions/:questionId', () => {
+    it('returns updated question', async () => {
+      const updatedQuestion = {
+        id: 'q-1',
+        stack: 'js',
+        level: 'intermediate',
+        type: 'single_choice',
+        questionText: 'Updated?',
+        options: [{ key: 'a', text: 'A' }],
+        correctAnswer: 'a',
+        explanation: 'Updated exp',
+        source: 'manual',
+        createdAt: new Date(),
+      };
+      (mockDb.update as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        updateChainReturning([updatedQuestion])
+      );
+      (mockDb.insert as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        insertChain([])
+      );
+
+      const res = await app.inject({
+        method: 'PATCH',
+        url: '/admin/questions/11111111-1111-1111-1111-111111111111',
+        headers: { authorization: 'Bearer any-token' },
+        payload: { questionText: 'Updated?', explanation: 'Updated exp' },
+      });
+
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.questionText).toBe('Updated?');
+    });
+  });
+});

tests/integration/auth.routes.test.ts

@@ -0,0 +1,291 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('../../src/config/env.js', () => ({
+  env: {
+    NODE_ENV: 'test',
+    JWT_SECRET: 'test-secret',
+  },
+}));
+
+import { buildAuthTestApp } from '../helpers/build-test-app.js';
+import {
+  createMockDb,
+  selectChain,
+  insertChain,
+  updateChain,
+  deleteChain,
+} from '../test-utils.js';
+
+vi.mock('../../src/utils/password.js', () => ({
+  hashPassword: vi.fn().mockResolvedValue('hashed-password'),
+  verifyPassword: vi.fn().mockResolvedValue(true),
+}));
+
+vi.mock('../../src/utils/jwt.js', () => ({
+  signAccessToken: vi.fn().mockResolvedValue('access-token'),
+  signRefreshToken: vi.fn().mockResolvedValue('refresh-token'),
+  verifyToken: vi.fn(),
+  isAccessPayload: vi.fn((p: { type?: string }) => p?.type === 'access'),
+  isRefreshPayload: vi.fn(),
+  hashToken: vi.fn((t: string) => `hash-${t}`),
+}));
+
+vi.mock('node:crypto', () => ({
+  randomBytes: vi.fn(() => ({ toString: () => 'abc123' })),
+  randomUUID: vi.fn(() => 'uuid-session-1'),
+}));
+
+import { isRefreshPayload, verifyToken } from '../../src/utils/jwt.js';
+
+describe('Auth routes integration', () => {
+  let app: Awaited<ReturnType<typeof buildAuthTestApp>>;
+  let mockDb: ReturnType<typeof createMockDb>;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    mockDb = createMockDb();
+    app = await buildAuthTestApp(mockDb as never);
+  });
+
+  describe('POST /auth/register', () => {
+    it('returns 201 with userId and verificationCode when registration succeeds', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(selectChain([]))
+        .mockReturnValueOnce(selectChain([]));
+      (mockDb.insert as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(insertChain([{ id: 'user-123' }]))
+        .mockReturnValueOnce(insertChain([]));
+
+      const res = await app.inject({
+        method: 'POST',
+        url: '/api/v1/auth/register',
+        payload: {
+          email: 'test@example.com',
+          password: 'password123',
+          nickname: 'tester',
+        },
+      });
+
+      expect(res.statusCode).toBe(201);
+      const body = JSON.parse(res.body);
+      expect(body.userId).toBe('user-123');
+      expect(body.message).toContain('verify your email');
+      expect(body.verificationCode).toBeDefined();
+    });
+
+    it('returns 409 when email is already taken', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([{ id: 'existing', email: 'test@example.com' }])
+      );
+
+      const res = await app.inject({
+        method: 'POST',
+        url: '/api/v1/auth/register',
+        payload: {
+          email: 'test@example.com',
+          password: 'password123',
+          nickname: 'tester',
+        },
+      });
+
+      expect(res.statusCode).toBe(409);
+      const body = JSON.parse(res.body);
+      expect(body.error?.code).toBe('EMAIL_TAKEN');
+    });
+
+    it('returns 422 when validation fails', async () => {
+      const res = await app.inject({
+        method: 'POST',
+        url: '/api/v1/auth/register',
+        payload: {
+          email: 'short',
+          password: '123', // too short
+          nickname: 'x', // too short
+        },
+      });
+
+      expect([400, 422]).toContain(res.statusCode);
+      const body = JSON.parse(res.body);
+      expect(body.error?.code ?? body.error).toBeDefined();
+    });
+  });
+
+  describe('POST /auth/login', () => {
+    it('returns user and tokens when credentials are valid', async () => {
+      const mockUser = {
+        id: 'user-1',
+        email: 'test@example.com',
+        nickname: 'tester',
+        avatarUrl: null,
+        role: 'free',
+        emailVerifiedAt: null,
+        passwordHash: 'hashed',
+      };
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([mockUser])
+      );
+      (mockDb.insert as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        insertChain([])
+      );
+
+      const res = await app.inject({
+        method: 'POST',
+        url: '/api/v1/auth/login',
+        payload: { email: 'test@example.com', password: 'password123' },
+      });
+
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.user).toBeDefined();
+      expect(body.user.id).toBe('user-1');
+      expect(body.user.email).toBe('test@example.com');
+      expect(body.user.nickname).toBeDefined();
+      expect(body.accessToken).toBe('access-token');
+      expect(body.refreshToken).toBe('refresh-token');
+    });
+
+    it('returns 401 when credentials are invalid', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([])
+      );
+
+      const res = await app.inject({
+        method: 'POST',
+        url: '/api/v1/auth/login',
+        payload: { email: 'unknown@example.com', password: 'wrong' },
+      });
+
+      expect(res.statusCode).toBe(401);
+    });
+  });
+
+  describe('POST /auth/logout', () => {
+    it('returns 200 with message on success (Bearer + cookie)', async () => {
+      vi.mocked(verifyToken).mockResolvedValueOnce({
+        sub: 'user-1',
+        email: 'test@example.com',
+        type: 'access',
+      } as never);
+      (mockDb.delete as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        deleteChain()
+      );
+
+      const res = await app.inject({
+        method: 'POST',
+        url: '/api/v1/auth/logout',
+        headers: { authorization: 'Bearer valid-access-token' },
+        payload: {},
+      });
+
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.message).toBe('Logged out successfully');
+    });
+  });
+
+  describe('POST /auth/refresh', () => {
+    it('returns accessToken when refresh token from cookie is valid', async () => {
+      vi.mocked(verifyToken).mockResolvedValueOnce({
+        sub: 'user-1',
+        sid: 'sid-1',
+        type: 'refresh',
+      } as never);
+      vi.mocked(isRefreshPayload).mockReturnValueOnce(true);
+      (mockDb.select as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(selectChain([{ id: 'sess-1', userId: 'user-1' }]))
+        .mockReturnValueOnce(selectChain([{ id: 'user-1', email: 'test@example.com' }]));
+      (mockDb.delete as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        deleteChain()
+      );
+      (mockDb.insert as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        insertChain([])
+      );
+
+      const res = await app.inject({
+        method: 'POST',
+        url: '/api/v1/auth/refresh',
+        payload: {},
+        headers: { cookie: 'refreshToken=valid-refresh-token' },
+      });
+
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.accessToken).toBe('access-token');
+      expect(body.refreshToken).toBeUndefined();
+    });
+  });
+
+  describe('POST /auth/verify-email', () => {
+    it('returns success when code is valid', async () => {
+      const mockCode = {
+        id: 'code-1',
+        userId: 'user-1',
+        code: 'ABC123',
+        expiresAt: new Date(Date.now() + 60000),
+      };
+      (mockDb.select as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(selectChain([mockCode]))
+        .mockReturnValueOnce(selectChain([{ id: 'user-1', emailVerifiedAt: null }]));
+      (mockDb.update as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        updateChain([{ id: 'user-1' }])
+      );
+      (mockDb.delete as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        deleteChain()
+      );
+
+      const res = await app.inject({
+        method: 'POST',
+        url: '/api/v1/auth/verify-email',
+        payload: { userId: 'user-1', code: 'ABC123' },
+      });
+
+      expect(res.statusCode).toBe(200);
+    });
+  });
+
+  describe('POST /auth/forgot-password', () => {
+    it('returns 200 with generic message', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([{ id: 'user-1', email: 'test@example.com' }])
+      );
+      (mockDb.insert as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        insertChain([])
+      );
+
+      const res = await app.inject({
+        method: 'POST',
+        url: '/api/v1/auth/forgot-password',
+        payload: { email: 'test@example.com' },
+      });
+
+      expect(res.statusCode).toBe(200);
+    });
+  });
+
+  describe('POST /auth/reset-password', () => {
+    it('returns 200 when token is valid', async () => {
+      const mockRecord = {
+        id: 'rec-1',
+        userId: 'user-1',
+        expiresAt: new Date(Date.now() + 60000),
+      };
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([mockRecord])
+      );
+      (mockDb.update as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        updateChain([{ id: 'user-1' }])
+      );
+      (mockDb.delete as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        deleteChain()
+      );
+
+      const res = await app.inject({
+        method: 'POST',
+        url: '/api/v1/auth/reset-password',
+        payload: { token: 'valid-token', newPassword: 'newPassword123' },
+      });
+
+      expect(res.statusCode).toBe(200);
+    });
+  });
+});

tests/services/auth.service.test.ts

@@ -0,0 +1,311 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { AuthService } from '../../src/services/auth/auth.service.js';
+import {
+  createMockDb,
+  selectChain,
+  insertChain,
+  updateChain,
+  deleteChain,
+} from '../test-utils.js';
+
+vi.mock('../../src/utils/password.js', () => ({
+  hashPassword: vi.fn().mockResolvedValue('hashed-password'),
+  verifyPassword: vi.fn().mockResolvedValue(true),
+}));
+
+vi.mock('../../src/utils/jwt.js', () => ({
+  signAccessToken: vi.fn().mockResolvedValue('access-token'),
+  signRefreshToken: vi.fn().mockResolvedValue('refresh-token'),
+  verifyToken: vi.fn(),
+  isRefreshPayload: vi.fn(),
+  hashToken: vi.fn((t: string) => `hash-${t}`),
+}));
+
+vi.mock('node:crypto', () => ({
+  randomBytes: vi.fn(() => ({
+    toString: () => 'abc123',
+  })),
+  randomUUID: vi.fn(() => 'uuid-session-1'),
+}));
+
+import { hashPassword, verifyPassword } from '../../src/utils/password.js';
+import { signAccessToken, signRefreshToken, verifyToken, isRefreshPayload } from '../../src/utils/jwt.js';
+
+describe('AuthService', () => {
+  let mockDb: ReturnType<typeof createMockDb>;
+  let authService: AuthService;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockDb = createMockDb();
+    authService = new AuthService(mockDb as never);
+  });
+
+  describe('register', () => {
+    it('registers a new user when email and nickname are available', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(selectChain([]))
+        .mockReturnValueOnce(selectChain([]));
+      (mockDb.insert as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(insertChain([{ id: 'user-123' }]))
+        .mockReturnValueOnce(insertChain([]));
+
+      const result = await authService.register({
+        email: 'test@example.com',
+        password: 'password123',
+        nickname: 'tester',
+      });
+
+      expect(result.userId).toBe('user-123');
+      expect(result.verificationCode).toBeDefined();
+      expect(hashPassword).toHaveBeenCalledWith('password123');
+    });
+
+    it('throws when email is already taken', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([{ id: 'existing', email: 'test@example.com' }])
+      );
+
+      await expect(
+        authService.register({
+          email: 'test@example.com',
+          password: 'password123',
+          nickname: 'tester',
+        })
+      ).rejects.toMatchObject({ code: 'EMAIL_TAKEN' });
+    });
+
+    it('throws when nickname is already taken', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(selectChain([]))
+        .mockReturnValueOnce(selectChain([{ id: 'existing', nickname: 'tester' }]));
+
+      await expect(
+        authService.register({
+          email: 'test@example.com',
+          password: 'password123',
+          nickname: 'tester',
+        })
+      ).rejects.toMatchObject({ code: 'NICKNAME_TAKEN' });
+    });
+  });
+
+  describe('login', () => {
+    it('returns user and tokens when credentials are valid', async () => {
+      const mockUser = {
+        id: 'user-1',
+        email: 'test@example.com',
+        nickname: 'tester',
+        avatarUrl: null,
+        role: 'free',
+        emailVerifiedAt: null,
+        passwordHash: 'hashed',
+      };
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([mockUser])
+      );
+      (mockDb.insert as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        insertChain([])
+      );
+
+      const result = await authService.login({
+        email: 'test@example.com',
+        password: 'password123',
+      });
+
+      expect(result.user).toBeDefined();
+      expect(result.user.id).toBe('user-1');
+      expect(result.user.email).toBe('test@example.com');
+      expect(result.accessToken).toBe('access-token');
+      expect(result.refreshToken).toBe('refresh-token');
+      expect(verifyPassword).toHaveBeenCalledWith('hashed', 'password123');
+      expect(signAccessToken).toHaveBeenCalled();
+      expect(signRefreshToken).toHaveBeenCalled();
+    });
+
+    it('throws when user not found', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([])
+      );
+
+      await expect(
+        authService.login({ email: 'nonexistent@example.com', password: 'x' })
+      ).rejects.toMatchObject({ code: 'UNAUTHORIZED' });
+    });
+
+    it('throws when password is wrong', async () => {
+      vi.mocked(verifyPassword).mockResolvedValueOnce(false);
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([{ id: 'user-1', email: 'test@example.com', passwordHash: 'hashed' }])
+      );
+
+      await expect(
+        authService.login({ email: 'test@example.com', password: 'wrong' })
+      ).rejects.toMatchObject({ code: 'UNAUTHORIZED' });
+    });
+  });
+
+  describe('logout', () => {
+    it('deletes session by refresh token hash', async () => {
+      (mockDb.delete as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        deleteChain()
+      );
+
+      await authService.logout('some-refresh-token');
+
+      expect(mockDb.delete).toHaveBeenCalled();
+    });
+  });
+
+  describe('refresh', () => {
+    it('returns new tokens when refresh token is valid', async () => {
+      vi.mocked(verifyToken).mockResolvedValueOnce({
+        sub: 'user-1',
+        sid: 'sid-1',
+        type: 'refresh',
+      } as never);
+      vi.mocked(isRefreshPayload).mockReturnValueOnce(true);
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([{ id: 'sess-1', userId: 'user-1' }])
+      );
+      (mockDb.delete as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        deleteChain()
+      );
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([{ id: 'user-1', email: 'test@example.com' }])
+      );
+      (mockDb.insert as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        insertChain([])
+      );
+
+      const result = await authService.refresh({
+        refreshToken: 'valid-refresh-token',
+      });
+
+      expect(result.accessToken).toBe('access-token');
+      expect(result.refreshToken).toBe('refresh-token');
+    });
+
+    it('throws when token is not a refresh payload', async () => {
+      vi.mocked(verifyToken).mockResolvedValueOnce({
+        sub: 'user-1',
+        type: 'access',
+      } as never);
+      vi.mocked(isRefreshPayload).mockReturnValueOnce(false);
+
+      await expect(
+        authService.refresh({ refreshToken: 'access-token' })
+      ).rejects.toMatchObject({ message: expect.stringContaining('Invalid refresh token') });
+    });
+
+    it('throws when session not found', async () => {
+      vi.mocked(verifyToken).mockResolvedValueOnce({
+        sub: 'user-1',
+        sid: 'sid-1',
+        type: 'refresh',
+      } as never);
+      vi.mocked(isRefreshPayload).mockReturnValueOnce(true);
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([])
+      );
+
+      await expect(
+        authService.refresh({ refreshToken: 'invalid-or-expired' })
+      ).rejects.toMatchObject({ code: 'INVALID_REFRESH_TOKEN' });
+    });
+  });
+
+  describe('verifyEmail', () => {
+    it('throws when verification code is invalid', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([])
+      );
+
+      await expect(
+        authService.verifyEmail('user-1', 'WRONG')
+      ).rejects.toMatchObject({ code: 'INVALID_CODE' });
+    });
+
+    it('updates user and deletes code when valid', async () => {
+      const mockCode = {
+        id: 'code-1',
+        userId: 'user-1',
+        code: 'ABC123',
+        expiresAt: new Date(Date.now() + 60000),
+      };
+      (mockDb.select as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(selectChain([mockCode]))
+        .mockReturnValueOnce(selectChain([{ id: 'user-1', emailVerifiedAt: null }]));
+      (mockDb.update as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        updateChain([{ id: 'user-1' }])
+      );
+      (mockDb.delete as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        deleteChain()
+      );
+
+      await authService.verifyEmail('user-1', 'ABC123');
+
+      expect(mockDb.update).toHaveBeenCalled();
+      expect(mockDb.delete).toHaveBeenCalled();
+    });
+  });
+
+  describe('forgotPassword', () => {
+    it('returns empty token when user not found', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([])
+      );
+
+      const result = await authService.forgotPassword('unknown@example.com');
+
+      expect(result.token).toBe('');
+      expect(result.expiresAt).toBeInstanceOf(Date);
+    });
+
+    it('returns token when user exists', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([{ id: 'user-1', email: 'test@example.com' }])
+      );
+      (mockDb.insert as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        insertChain([])
+      );
+
+      const result = await authService.forgotPassword('test@example.com');
+
+      expect(result.token).toBeDefined();
+      expect(result.token).not.toBe('');
+      expect(result.expiresAt).toBeInstanceOf(Date);
+    });
+  });
+
+  describe('resetPassword', () => {
+    it('throws when token is invalid', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([])
+      );
+
+      await expect(
+        authService.resetPassword('invalid-token', 'newPassword123')
+      ).rejects.toMatchObject({ code: 'INVALID_RESET_TOKEN' });
+    });
+
+    it('updates password when token is valid', async () => {
+      const mockRecord = { id: 'rec-1', userId: 'user-1', expiresAt: new Date(Date.now() + 60000) };
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([mockRecord])
+      );
+      (mockDb.update as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        updateChain([{ id: 'user-1' }])
+      );
+      (mockDb.delete as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        deleteChain()
+      );
+
+      await authService.resetPassword('valid-token', 'newPassword123');
+
+      expect(hashPassword).toHaveBeenCalledWith('newPassword123');
+      expect(mockDb.update).toHaveBeenCalled();
+      expect(mockDb.delete).toHaveBeenCalled();
+    });
+  });
+});

tests/services/llm.service.test.ts

@@ -0,0 +1,224 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('../../src/config/env.js', () => ({
+  env: {
+    LLM_BASE_URL: 'http://test',
+    LLM_MODEL: 'test-model',
+    LLM_FALLBACK_MODEL: 'fallback-model',
+    LLM_API_KEY: 'key',
+    LLM_TIMEOUT_MS: 5000,
+    LLM_TEMPERATURE: 0.7,
+    LLM_MAX_TOKENS: 2048,
+    LLM_MAX_RETRIES: 1,
+    LLM_RETRY_DELAY_MS: 10,
+  },
+}));
+
+import { LlmService } from '../../src/services/llm/llm.service.js';
+
+const mockConfig = {
+  baseUrl: 'http://llm.test/v1',
+  model: 'test-model',
+  fallbackModel: 'fallback-model',
+  apiKey: 'test-key',
+  timeoutMs: 5000,
+  temperature: 0.7,
+  maxTokens: 2048,
+  maxRetries: 1,
+  retryDelayMs: 10,
+};
+
+const validQuestionsJson = JSON.stringify({
+  questions: [
+    {
+      questionText: 'What is 2+2?',
+      type: 'single_choice',
+      options: [{ key: 'a', text: '4' }, { key: 'b', text: '3' }],
+      correctAnswer: 'a',
+      explanation: 'Basic math',
+    },
+  ],
+});
+
+describe('LlmService', () => {
+  let mockFetch: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    mockFetch = vi.fn();
+    vi.stubGlobal('fetch', mockFetch);
+  });
+
+  describe('chat', () => {
+    it('returns content from LLM response', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({
+          choices: [{ message: { content: 'Hello!' } }],
+        }),
+      });
+
+      const service = new LlmService(mockConfig);
+      const result = await service.chat([
+        { role: 'user', content: 'Hi' },
+      ]);
+
+      expect(result).toBe('Hello!');
+      expect(mockFetch).toHaveBeenCalledWith(
+        'http://llm.test/v1/chat/completions',
+        expect.objectContaining({
+          method: 'POST',
+          headers: expect.objectContaining({
+            'Content-Type': 'application/json',
+            'Authorization': 'Bearer test-key',
+          }),
+        })
+      );
+    });
+  });
+
+  describe('chatWithMeta', () => {
+    it('returns content and model name', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({
+          choices: [{ message: { content: 'Response' } }],
+        }),
+      });
+
+      const service = new LlmService(mockConfig);
+      const result = await service.chatWithMeta([{ role: 'user', content: 'Q' }]);
+
+      expect(result.content).toBe('Response');
+      expect(result.model).toBe('test-model');
+    });
+
+    it('retries on failure then succeeds', async () => {
+      mockFetch
+        .mockRejectedValueOnce(new Error('Network error'))
+        .mockResolvedValueOnce({
+          ok: true,
+          json: () => Promise.resolve({
+            choices: [{ message: { content: 'Retry OK' } }],
+          }),
+        });
+
+      const service = new LlmService({ ...mockConfig, maxRetries: 1 });
+      const result = await service.chatWithMeta([{ role: 'user', content: 'Q' }]);
+
+      expect(result.content).toBe('Retry OK');
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+    });
+
+    it('falls back to fallbackModel when primary fails', async () => {
+      // Primary model: 2 attempts (initial + 1 retry), both fail
+      mockFetch
+        .mockResolvedValueOnce({ ok: false, status: 500, statusText: 'Error', text: () => Promise.resolve('') })
+        .mockResolvedValueOnce({ ok: false, status: 500, statusText: 'Error', text: () => Promise.resolve('') })
+        .mockResolvedValueOnce({
+          ok: true,
+          json: () => Promise.resolve({
+            choices: [{ message: { content: 'Fallback OK' } }],
+          }),
+        });
+
+      const service = new LlmService(mockConfig);
+      const result = await service.chatWithMeta([{ role: 'user', content: 'Q' }]);
+
+      expect(result.content).toBe('Fallback OK');
+      expect(result.model).toBe('fallback-model');
+    });
+
+    it('throws when all attempts fail', async () => {
+      mockFetch.mockRejectedValue(new Error('Network error'));
+
+      const service = new LlmService({ ...mockConfig, maxRetries: 0 });
+      await expect(
+        service.chatWithMeta([{ role: 'user', content: 'Q' }])
+      ).rejects.toThrow();
+    });
+  });
+
+  describe('generateQuestions', () => {
+    it('returns validated questions with meta', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({
+          choices: [{ message: { content: validQuestionsJson } }],
+        }),
+      });
+
+      const service = new LlmService(mockConfig);
+      const result = await service.generateQuestions({
+        stack: 'js',
+        level: 'beginner',
+        count: 1,
+      });
+
+      expect(result.questions).toHaveLength(1);
+      expect(result.questions[0].questionText).toBe('What is 2+2?');
+      expect(result.questions[0].stack).toBe('js');
+      expect(result.questions[0].level).toBe('beginner');
+      expect(result.meta.llmModel).toBe('test-model');
+      expect(result.meta.promptHash).toBeDefined();
+      expect(result.meta.generationTimeMs).toBeGreaterThanOrEqual(0);
+    });
+
+    it('extracts JSON from markdown code block', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({
+          choices: [{ message: { content: '```json\n' + validQuestionsJson + '\n```' } }],
+        }),
+      });
+
+      const service = new LlmService(mockConfig);
+      const result = await service.generateQuestions({
+        stack: 'ts',
+        level: 'intermediate',
+        count: 1,
+      });
+
+      expect(result.questions).toHaveLength(1);
+      expect(result.questions[0].type).toBe('single_choice');
+    });
+
+    it('throws when response validation fails', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({
+          choices: [{ message: { content: '{"invalid": "response"}' } }],
+        }),
+      });
+
+      const service = new LlmService(mockConfig);
+      await expect(
+        service.generateQuestions({ stack: 'js', level: 'beginner', count: 1 })
+      ).rejects.toThrow('LLM response validation failed');
+    });
+
+    it('throws when single_choice has no options', async () => {
+      const invalidJson = JSON.stringify({
+        questions: [
+          {
+            questionText: 'Q?',
+            type: 'single_choice',
+            options: [],
+            correctAnswer: 'a',
+            explanation: 'e',
+          },
+        ],
+      });
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({
+          choices: [{ message: { content: invalidJson } }],
+        }),
+      });
+
+      const service = new LlmService(mockConfig);
+      await expect(
+        service.generateQuestions({ stack: 'js', level: 'beginner', count: 1 })
+      ).rejects.toThrow('Question validation failed');
+    });
+  });
+});

tests/services/question.service.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { QuestionService } from '../../src/services/questions/question.service.js';
+import {
+  createMockDb,
+  selectChainOrdered,
+  selectChainSimple,
+  insertChain,
+  updateChain,
+} from '../test-utils.js';
+
+const mockLlmQuestions = [
+  {
+    questionBankId: 'qb-new',
+    type: 'single_choice' as const,
+    questionText: 'New question?',
+    options: [{ key: 'a', text: 'A' }, { key: 'b', text: 'B' }],
+    correctAnswer: 'a',
+    explanation: 'Explanation',
+    stack: 'js' as const,
+    level: 'beginner' as const,
+  },
+];
+
+describe('QuestionService', () => {
+  let mockDb: ReturnType<typeof createMockDb>;
+  let mockLlmService: { generateQuestions: ReturnType<typeof vi.fn> };
+  let questionService: QuestionService;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockDb = createMockDb();
+    mockLlmService = {
+      generateQuestions: vi.fn().mockResolvedValue({
+        questions: mockLlmQuestions,
+        meta: {
+          llmModel: 'test-model',
+          promptHash: 'hash',
+          generationTimeMs: 100,
+          rawResponse: {},
+        },
+      }),
+    };
+    questionService = new QuestionService(mockDb as never, mockLlmService as never);
+  });
+
+  describe('getQuestionsForTest', () => {
+    it('returns questions from bank when enough approved exist', async () => {
+      const approvedRows = [
+        {
+          id: 'qb-1',
+          type: 'single_choice',
+          questionText: 'Q1?',
+          options: [{ key: 'a', text: 'A' }],
+          correctAnswer: 'a',
+          explanation: 'e',
+        },
+      ];
+      (mockDb.select as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(selectChainOrdered(approvedRows))
+        .mockReturnValueOnce(selectChainSimple([]));
+      (mockDb.insert as ReturnType<typeof vi.fn>).mockReturnValueOnce(insertChain([]));
+      (mockDb.update as ReturnType<typeof vi.fn>).mockReturnValueOnce(updateChain([]));
+
+      const result = await questionService.getQuestionsForTest(
+        'user-1',
+        'js',
+        'beginner',
+        1
+      );
+
+      expect(result).toHaveLength(1);
+      expect(result[0].questionBankId).toBe('qb-1');
+      expect(mockLlmService.generateQuestions).not.toHaveBeenCalled();
+    });
+
+    it('calls LLM when not enough questions in bank', async () => {
+      const approvedRows: unknown[] = [];
+      const seenIds: unknown[] = [];
+      (mockDb.select as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(selectChainOrdered(approvedRows))
+        .mockReturnValueOnce(selectChainSimple(seenIds));
+      (mockDb.insert as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(insertChain([{ id: 'qb-new', ...mockLlmQuestions[0] }]))
+        .mockReturnValueOnce(insertChain([]))
+        .mockReturnValueOnce(insertChain([]));
+      (mockDb.update as ReturnType<typeof vi.fn>).mockReturnValueOnce(updateChain([]));
+
+      const result = await questionService.getQuestionsForTest(
+        'user-1',
+        'js',
+        'beginner',
+        1
+      );
+
+      expect(result).toHaveLength(1);
+      expect(mockLlmService.generateQuestions).toHaveBeenCalledWith({
+        stack: 'js',
+        level: 'beginner',
+        count: 1,
+      });
+    });
+
+    it('throws when not enough questions available', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(selectChainOrdered([]))
+        .mockReturnValueOnce(selectChainSimple([]));
+      mockLlmService.generateQuestions.mockResolvedValueOnce({
+        questions: [],
+        meta: { llmModel: 'x', promptHash: 'y', generationTimeMs: 0, rawResponse: {} },
+      });
+
+      await expect(
+        questionService.getQuestionsForTest('user-1', 'js', 'beginner', 5)
+      ).rejects.toMatchObject({ code: 'QUESTIONS_UNAVAILABLE' });
+    });
+  });
+});

tests/services/tests.service.test.ts

@@ -0,0 +1,230 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { TestsService } from '../../src/services/tests/tests.service.js';
+import {
+  createMockDb,
+  selectChain,
+  selectChainOrdered,
+  selectChainWhere,
+  insertChain,
+  updateChain,
+  updateChainReturning,
+} from '../test-utils.js';
+
+const mockQuestions = [
+  {
+    questionBankId: 'qb-1',
+    type: 'single_choice' as const,
+    questionText: 'What is 2+2?',
+    options: [{ key: 'a', text: '4' }, { key: 'b', text: '3' }],
+    correctAnswer: 'a',
+    explanation: 'Basic math',
+  },
+];
+
+describe('TestsService', () => {
+  let mockDb: ReturnType<typeof createMockDb>;
+  let mockQuestionService: { getQuestionsForTest: ReturnType<typeof vi.fn> };
+  let testsService: TestsService;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockDb = createMockDb();
+    mockQuestionService = {
+      getQuestionsForTest: vi.fn().mockResolvedValue(mockQuestions),
+    };
+    testsService = new TestsService(mockDb as never, mockQuestionService as never);
+  });
+
+  describe('createTest', () => {
+    it('creates a test with questions from QuestionService', async () => {
+      const mockTest = {
+        id: 'test-1',
+        userId: 'user-1',
+        stack: 'js',
+        level: 'beginner',
+        questionCount: 1,
+        mode: 'fixed',
+        status: 'in_progress',
+        score: null,
+        startedAt: new Date(),
+        finishedAt: null,
+        timeLimitSeconds: null,
+      };
+      const mockTqRows = [
+        {
+          id: 'tq-1',
+          testId: 'test-1',
+          questionBankId: 'qb-1',
+          orderNumber: 1,
+          type: 'single_choice',
+          questionText: 'What is 2+2?',
+          options: [{ key: 'a', text: '4' }],
+          correctAnswer: 'a',
+          explanation: 'Basic math',
+          userAnswer: null,
+          isCorrect: null,
+          answeredAt: null,
+        },
+      ];
+      (mockDb.insert as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(insertChain([mockTest]))
+        .mockReturnValueOnce(insertChain([]));
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChainOrdered(mockTqRows)
+      );
+
+      const result = await testsService.createTest('user-1', {
+        stack: 'js',
+        level: 'beginner',
+        questionCount: 1,
+      });
+
+      expect(result.id).toBe('test-1');
+      expect(result.questions).toHaveLength(1);
+      expect(mockQuestionService.getQuestionsForTest).toHaveBeenCalledWith(
+        'user-1',
+        'js',
+        'beginner',
+        1
+      );
+    });
+
+    it('throws when questionCount is out of range', async () => {
+      await expect(
+        testsService.createTest('user-1', {
+          stack: 'js',
+          level: 'beginner',
+          questionCount: 0,
+        })
+      ).rejects.toMatchObject({ code: 'BAD_REQUEST' });
+
+      await expect(
+        testsService.createTest('user-1', {
+          stack: 'js',
+          level: 'beginner',
+          questionCount: 51,
+        })
+      ).rejects.toMatchObject({ code: 'BAD_REQUEST' });
+    });
+  });
+
+  describe('answerQuestion', () => {
+    it('returns updated question snapshot when answer is correct', async () => {
+      const mockTest = { id: 't-1', userId: 'user-1', status: 'in_progress' };
+      const mockTq = {
+        id: 'tq-1',
+        testId: 't-1',
+        correctAnswer: 'a',
+        userAnswer: null,
+        questionBankId: 'qb-1',
+        orderNumber: 1,
+        type: 'single_choice',
+        questionText: 'Q?',
+        options: [{ key: 'a', text: 'A' }],
+        explanation: 'exp',
+      };
+      const updatedTq = { ...mockTq, userAnswer: 'a', isCorrect: true, answeredAt: new Date() };
+      (mockDb.select as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(selectChain([mockTest]))
+        .mockReturnValueOnce(selectChain([mockTq]));
+      (mockDb.update as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        updateChainReturning([updatedTq])
+      );
+
+      const result = await testsService.answerQuestion('user-1', 't-1', 'tq-1', 'a');
+
+      expect(result.isCorrect).toBe(true);
+      expect(result.userAnswer).toBe('a');
+    });
+
+    it('throws when test not found', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(selectChain([]));
+
+      await expect(
+        testsService.answerQuestion('user-1', 'bad-id', 'tq-1', 'a')
+      ).rejects.toMatchObject({ code: 'NOT_FOUND' });
+    });
+
+    it('throws when test is already finished', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([{ id: 't-1', userId: 'user-1', status: 'completed' }])
+      );
+
+      await expect(
+        testsService.answerQuestion('user-1', 't-1', 'tq-1', 'a')
+      ).rejects.toMatchObject({ code: 'TEST_ALREADY_FINISHED' });
+    });
+  });
+
+  describe('finishTest', () => {
+    it('throws when there are unanswered questions', async () => {
+      const mockTest = { id: 't-1', userId: 'user-1', status: 'in_progress', stack: 'js', level: 'beginner' };
+      const mockQuestionsWithUnanswered = [
+        { id: 'tq-1', testId: 't-1', userAnswer: 'a', isCorrect: true },
+        { id: 'tq-2', testId: 't-1', userAnswer: null, isCorrect: null },
+      ];
+      (mockDb.select as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(selectChain([mockTest]))
+        .mockReturnValueOnce(selectChainWhere(mockQuestionsWithUnanswered));
+
+      await expect(
+        testsService.finishTest('user-1', 't-1')
+      ).rejects.toMatchObject({ code: 'NO_ANSWERS' });
+    });
+  });
+
+  describe('getById', () => {
+    it('returns null when test not found', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(selectChain([]));
+
+      const result = await testsService.getById('user-1', 'bad-id');
+
+      expect(result).toBeNull();
+    });
+
+    it('returns test with questions when found', async () => {
+      const mockTest = {
+        id: 't-1',
+        userId: 'user-1',
+        stack: 'js',
+        level: 'beginner',
+        questionCount: 2,
+        mode: 'fixed',
+        status: 'in_progress',
+        score: null,
+        startedAt: new Date(),
+        finishedAt: null,
+        timeLimitSeconds: null,
+      };
+      const mockTqRows = [
+        { id: 'tq-1', testId: 't-1', orderNumber: 1, questionBankId: 'qb-1', type: 'single_choice', questionText: 'Q1', options: [], correctAnswer: 'a', explanation: 'e', userAnswer: null, isCorrect: null, answeredAt: null },
+      ];
+      (mockDb.select as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(selectChain([mockTest]))
+        .mockReturnValueOnce(selectChainOrdered(mockTqRows));
+
+      const result = await testsService.getById('user-1', 't-1');
+
+      expect(result).not.toBeNull();
+      expect(result!.id).toBe('t-1');
+      expect(result!.questions).toHaveLength(1);
+    });
+  });
+
+  describe('getHistory', () => {
+    it('returns paginated test history', async () => {
+      const mockTests = [
+        { id: 't-1', userId: 'user-1', stack: 'js', level: 'beginner', questionCount: 1, mode: 'fixed', status: 'completed', score: 1, startedAt: new Date(), finishedAt: new Date(), timeLimitSeconds: null },
+      ];
+      const mockTqRows = [];
+      (mockDb.select as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(selectChainOrdered(mockTests))
+        .mockReturnValueOnce(selectChainOrdered(mockTqRows));
+
+      const result = await testsService.getHistory('user-1', { limit: 10, offset: 0 });
+
+      expect(result.tests).toHaveLength(1);
+      expect(result.total).toBe(1);
+    });
+  });
+});

tests/setup.ts

@@ -0,0 +1,11 @@
+import { beforeAll, vi } from 'vitest';
+
+beforeAll(() => {
+  vi.stubEnv('NODE_ENV', 'test');
+  if (!process.env.DATABASE_URL) {
+    process.env.DATABASE_URL = 'postgresql://test:test@localhost:5432/test';
+  }
+  if (!process.env.JWT_SECRET) {
+    process.env.JWT_SECRET = 'test-secret-min-32-chars-long-for-validation';
+  }
+});

tests/smoke.test.ts

@@ -0,0 +1,12 @@
+import { describe, it, expect } from 'vitest';
+import { createMockDb } from './test-utils.js';
+
+describe('test-utils', () => {
+  it('createMockDb returns mock with select, insert, update, delete', () => {
+    const db = createMockDb();
+    expect(db.select).toBeDefined();
+    expect(db.insert).toBeDefined();
+    expect(db.update).toBeDefined();
+    expect(db.delete).toBeDefined();
+  });
+});

tests/test-utils.ts

@@ -0,0 +1,165 @@
+import { vi } from 'vitest';
+import type { FastifyInstance } from 'fastify';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import type * as schema from '../src/db/schema/index.js';
+
+export type MockDb = {
+  select: ReturnType<NodePgDatabase<typeof schema>['select']>;
+  insert: ReturnType<NodePgDatabase<typeof schema>['insert']>;
+  update: ReturnType<NodePgDatabase<typeof schema>['update']>;
+  delete: ReturnType<NodePgDatabase<typeof schema>['delete']>;
+};
+
+/** Build a select chain that resolves to the given rows at .limit(n) */
+export function selectChain(resolveAtLimit: unknown[] = []) {
+  const limitFn = vi.fn().mockResolvedValue(resolveAtLimit);
+  return {
+    from: vi.fn().mockReturnValue({
+      where: vi.fn().mockReturnValue({
+        limit: limitFn,
+        orderBy: vi.fn().mockReturnValue({ limit: limitFn }),
+      }),
+      limit: limitFn,
+    }),
+  };
+}
+
+/** Build a select chain for .from().where().orderBy() - orderBy is terminal */
+export function selectChainOrdered(resolveAtOrderBy: unknown[] = []) {
+  const orderByThenable = {
+    then: (resolve: (v: unknown) => void) => resolve(resolveAtOrderBy),
+  };
+  return {
+    from: vi.fn().mockReturnValue({
+      where: vi.fn().mockReturnValue({
+        orderBy: vi.fn().mockReturnValue(orderByThenable),
+      }),
+    }),
+  };
+}
+
+/** Build a select chain for .from().where() with no orderBy - used by select({...}).from() */
+export function selectChainSimple(resolveRows: unknown[] = []) {
+  const thenable = { then: (resolve: (v: unknown) => void) => resolve(resolveRows) };
+  return {
+    from: vi.fn().mockReturnValue({
+      where: vi.fn().mockReturnValue(thenable),
+    }),
+  };
+}
+
+/** Build a select chain for .from().where() - where is terminal (no orderBy/limit) */
+export function selectChainWhere(resolveAtWhere: unknown[] = []) {
+  const thenable = { then: (resolve: (v: unknown) => void) => resolve(resolveAtWhere) };
+  return {
+    from: vi.fn().mockReturnValue({
+      where: vi.fn().mockReturnValue(thenable),
+    }),
+  };
+}
+
+/** Build a select chain for .from().where().orderBy().limit().offset() */
+export function selectChainOrderedLimitOffset(resolveRows: unknown[] = []) {
+  const offsetFn = vi.fn().mockResolvedValue(resolveRows);
+  return {
+    from: vi.fn().mockReturnValue({
+      where: vi.fn().mockReturnValue({
+        orderBy: vi.fn().mockReturnValue({
+          limit: vi.fn().mockReturnValue({
+            offset: offsetFn,
+          }),
+        }),
+      }),
+    }),
+  };
+}
+
+/** Build an insert chain that resolves at .returning() or .values() */
+export function insertChain(resolveAtReturning: unknown[] = []) {
+  const returningFn = vi.fn().mockResolvedValue(resolveAtReturning);
+  const chainFromValues = {
+    returning: returningFn,
+    then: (resolve: (v?: unknown) => void) => resolve(undefined),
+  };
+  return {
+    values: vi.fn().mockReturnValue(chainFromValues),
+    returning: returningFn,
+  };
+}
+
+/** Build an update chain that resolves at .where() */
+export function updateChain(resolveAtWhere: unknown[] = []) {
+  return {
+    set: vi.fn().mockReturnValue({
+      where: vi.fn().mockResolvedValue(resolveAtWhere),
+    }),
+  };
+}
+
+/** Build an update chain with .where().returning() */
+export function updateChainReturning(resolveAtReturning: unknown[] = []) {
+  const returningFn = vi.fn().mockResolvedValue(resolveAtReturning);
+  return {
+    set: vi.fn().mockReturnValue({
+      where: vi.fn().mockReturnValue({
+        returning: returningFn,
+      }),
+    }),
+  };
+}
+
+/** Build a delete chain that resolves at .where() */
+export function deleteChain() {
+  return {
+    where: vi.fn().mockResolvedValue(undefined),
+  };
+}
+
+/**
+ * Create a chainable mock for Drizzle DB operations.
+ * Use mockReturnValue with selectChain/insertChain/updateChain/deleteChain.
+ */
+export function createMockDb(): MockDb {
+  const chain = {
+    from: vi.fn().mockReturnThis(),
+    where: vi.fn().mockReturnThis(),
+    values: vi.fn().mockReturnThis(),
+    set: vi.fn().mockReturnThis(),
+    orderBy: vi.fn().mockReturnThis(),
+    limit: vi.fn().mockReturnThis(),
+    returning: vi.fn().mockReturnThis(),
+  };
+
+  return {
+    select: vi.fn().mockReturnValue(chain),
+    insert: vi.fn().mockReturnValue(chain),
+    update: vi.fn().mockReturnValue(chain),
+    delete: vi.fn().mockReturnValue(chain),
+  } as unknown as MockDb;
+}
+
+/**
+ * Create a minimal mock Fastify app with db for route/integration tests.
+ * Use buildApp() from app.ts for full integration tests.
+ */
+export function createMockApp(): FastifyInstance & { db: MockDb } {
+  return {
+    db: createMockDb(),
+    log: {
+      child: () => ({
+        debug: () => {},
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        trace: () => {},
+        fatal: () => {},
+      }),
+      debug: () => {},
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      trace: () => {},
+      fatal: () => {},
+    },
+  } as FastifyInstance & { db: MockDb };
+}

vitest.config.ts

@@ -0,0 +1,40 @@
+import { defineConfig } from 'vitest/config';
+import { resolve } from 'path';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.ts', 'tests/**/*.spec.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'lcov'],
+      include: [
+        'src/services/auth/**/*.ts',
+        'src/services/llm/**/*.ts',
+        'src/services/questions/**/*.ts',
+        'src/services/tests/**/*.ts',
+        'src/services/admin/**/*.ts',
+      ],
+      exclude: [
+        'src/services/**/*.d.ts',
+        '**/*.test.ts',
+        '**/*.spec.ts',
+        '**/index.ts',
+      ],
+      thresholds: {
+        lines: 70,
+        functions: 70,
+        branches: 68,
+        statements: 70,
+      },
+    },
+    setupFiles: ['tests/setup.ts'],
+    testTimeout: 10000,
+  },
+  resolve: {
+    alias: {
+      '@': resolve(__dirname, 'src'),
+    },
+  },
+});