2f45a0b851
- 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 символов
158 lines
6.1 KiB
Markdown
158 lines
6.1 KiB
Markdown
# Задача: Синхронизация документации с реализацией
|
||
|
||
## Контекст
|
||
|
||
По итогам аудита документация должна быть приведена в соответствие с текущей реализацией 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
|