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
- Обновлены тесты

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