# Задача: Синхронизация документации с реализацией

## Контекст

По итогам аудита документация должна быть приведена в соответствие с текущей реализацией 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