Files

Anton 2f45a0b851 docs: приведение документации в соответствие с backend

- Auth: register без токенов до верификации (userId, message, verificationCode)
- Auth: login — 429 RATE_LIMIT_EXCEEDED при lockout, user с avatarUrl
- Auth: verify-email — { userId, code }, без Bearer
- Auth: reset-password — поле newPassword
- Profile: stats — byStack, totalTestsTaken, totalQuestions, correctAnswers, accuracy
- Tests: POST /tests возвращает полный список questions
- Tests: answer — полный snapshot отвеченного вопроса
- Tests: history — offset-пагинация (limit/offset), формат { tests, total }
- Admin: GET /admin/questions/pending, POST approve/reject, PATCH для редактирования
- DB: email_verification_codes, password_reset_tokens; обновлена question_cache_meta
- Security: CORS_ORIGINS из env, CSP/COEP отключены
- LLM: LLM_FALLBACK_MODEL, LLM_RETRY_DELAY_MS
- Onboarding: правило .env.example, JWT_SECRET >= 32 символов

2026-03-06 13:52:24 +03:00

6.1 KiB

Raw Permalink Blame History

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

Контекст

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

Ошибка при блокировке (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

6.1 KiB Raw Permalink Blame History Unescape Escape