samreshu_backend/AGENT_TASKS.md

# Распределение задач по агентам (MVP 0)

Документ для параллельной работы нескольких агентов. Каждый агент работает в **отдельной сессии Cursor** (отдельное окно чата). После выполнения **каждой задачи** — отдельный коммит по conventional commits.

## Как запустить агента

1. Открыть **новую сессию чата** (новое окно Composer/Chat в Cursor)
2. Скопировать промпт для нужного агента из раздела ниже
3. Агент выполнит свои задачи и сделает коммиты
4. Повторить для следующего агента

### Промпты для запуска агентов

**Agent A (Infrastructure):**

```text
Implement Agent A tasks from AGENT_TASKS.md. Work in branch feat/infra-core. 
Do tasks A1–A9 in order. After EACH task, run: git add -A && git commit -m "<message from table>".
Use conventional commits. Do not touch schema or auth/tests/profile/llm/admin code.
```

**Agent B (DB Schema):**

```text
Implement Agent B tasks from AGENT_TASKS.md. Work in branch feat/db-schema. 
Do tasks B1–B7. After EACH task, commit with the message from the table.
Assume Agent A has created plugins. Generate migrations with npm run db:generate.
```

**Agent C (Auth):**

```text
Implement Agent C tasks from AGENT_TASKS.md. Work in branch feat/auth. 
Merge or rebase from dev first. Do tasks C1–C7, commit after each.
```

**Agent D (Profile):**

```text
Implement Agent D tasks from AGENT_TASKS.md. Work in branch feat/profile-subscription.
Merge dev first. Do tasks D1–D5, commit after each.
```

**Agent E (Tests & Questions):**

```text
Implement Agent E tasks from AGENT_TASKS.md. Work in branch feat/tests-questions.
Requires Auth, Profile, LLM done. Do E1–E5, commit after each.
```

**Agent F (LLM):**

```text
Implement Agent F tasks from AGENT_TASKS.md. Work in branch feat/llm-service.
Do F1–F5, commit after each. Export LlmService interface for QuestionService.
```

**Agent G (Admin):**

```text
Implement Agent G tasks from AGENT_TASKS.md. Work in branch feat/admin-qa.
Do G1–G4, commit after each.
```

**Agent H (Testing):**

```text
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.
```

## Текущее состояние репозитория

Часть работы уже выполнена одним агентом:

- **Infra (A):** package.json, config, plugins (database, redis, security, rateLimit), app.ts, server.ts, utils/errors, utils/uuid, docker-compose, .env.example
- **Schema (B):** все схемы в src/db/schema, drizzle.config, migrate.ts. Миграции ещё не сгенерированы (нужен `npm run db:generate`)

Агентам B–H при старте: проверить, что уже есть, и дописать недостающее. Не дублировать сделанное. Коммитить только свои изменения.

---

## Формат коммитов

Использовать [conventional commits](samreshu_docs/principles/git-workflow.md):

- `feat:` — новый функционал
- `fix:` — исправление бага
- `refactor:` — рефакторинг
- `chore:` — инфраструктура, зависимости, конфиг
- `test:` — тесты

Примеры: `feat: add auth register endpoint`, `chore: add database plugin`, `test: add auth service unit tests`.

---

## Волны запуска и зависимости

```text
Волна 1 (старт сразу, параллельно):
  Agent A ────────────────────────────►
  Agent B ────────────────────────────►

Волна 2 (после завершения A + B):
  Agent C ────────────────────────────►
  Agent D ────────────────────────────►
  Agent F ────────────────────────────►

Волна 3 (после C, D, F):
  Agent E ────────────────────────────►
  Agent G ────────────────────────────►
  Agent H ────────────────────────────► (может стартовать частично после C)
```

---

## Agent A: Infrastructure & Core Backend

**Зависимости:** нет (запускать первым)

**Ветка:** `feat/infra-core` (создать от `main`/`dev`)

**Задачи и коммиты:**

| # | Задача | Коммит |
| - | - | - |
| A1 | package.json, tsconfig, .nvmrc, .gitignore | `chore: init project with Fastify and TypeScript` |
| A2 | src/config/env.ts с Zod-валидацией | `chore: add env config with validation` |
| A3 | src/plugins/redis.ts | `feat: add Redis plugin` |
| A4 | src/plugins/database.ts | `feat: add database plugin with Drizzle` |
| A5 | src/plugins/security.ts (helmet + cors) | `feat: add security plugin` |
| A6 | src/plugins/rateLimit.ts | `feat: add rate limit plugin with Redis` |
| A7 | src/utils/errors.ts, src/utils/uuid.ts | `chore: add error utils and uuid7 helper` |
| A8 | src/app.ts — error handler, логирование | `feat: add Fastify app with error handler` |
| A9 | src/server.ts, docker-compose.dev.yml, .env.example | `chore: add server entry and dev docker compose` |

**Итого:** 9 коммитов. После завершения — PR в `dev`.

---

## 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.

**Ветка:** `feat/db-schema`

**Задачи и коммиты:**

| # | Задача | Коммит |
| - | - | - |
| B1 | src/db/schema/enums.ts | `feat: add Drizzle enums for schema` |
| B2 | src/db/schema/users.ts, sessions.ts, subscriptions.ts | `feat: add users and auth tables schema` |
| B3 | src/db/schema/tests.ts, testQuestions.ts | `feat: add tests and test_questions schema` |
| B4 | src/db/schema/questionBank.ts, questionCacheMeta.ts, questionReports.ts | `feat: add question bank schema` |
| B5 | src/db/schema/userStats.ts, auditLogs.ts, userQuestionLog.ts, verificationTokens.ts | `feat: add user_stats, audit_logs and verification tokens schema` |
| B6 | src/db/schema/index.ts, drizzle.config.ts, migrate.ts | `chore: wire schema and migrations` |
| B7 | Генерация миграций (npm run db:generate), seed скрипт | `chore: add initial migration and seed script` |

**Итого:** 7 коммитов. После завершения — PR в `dev`.

---

## Agent C: Auth & Sessions Service

**Зависимости:** A, B завершены.

**Ветка:** `feat/auth`

**Задачи и коммиты:**

| # | Задача | Коммит |
| - | - | - |
| C1 | src/utils/password.ts (argon2id), src/utils/jwt.ts | `feat: add password hashing and JWT utils` |
| C2 | src/services/auth/auth.service.ts | `feat: add AuthService` |
| C3 | src/plugins/auth.ts (JWT verify, request.user) | `feat: add auth plugin` |
| C4 | src/routes/auth.ts — register, login, logout, refresh | `feat: add auth routes` |
| C5 | verify-email, forgot-password, reset-password | `feat: add email verification and password reset` |
| C6 | Rate limiting на auth-роуты | `feat: add rate limiting to auth endpoints` |
| C7 | Регистрация auth routes в app | `feat: register auth routes in app` |

**Итого:** 7 коммитов. После завершения — PR в `dev`.

---

## Agent D: Profile & Subscription Middleware

**Зависимости:** A, B, C.

**Ветка:** `feat/profile-subscription`

**Задачи и коммиты:**

| # | Задача | Коммит |
| - | - | - |
| D1 | src/plugins/subscription.ts | `feat: add subscription middleware` |
| D2 | src/services/user/user.service.ts | `feat: add UserService` |
| D3 | src/routes/profile.ts — GET, PATCH, GET :username | `feat: add profile routes` |
| D4 | Интеграция user_stats в профиль | `feat: add stats to profile response` |
| D5 | Регистрация profile routes в app | `feat: register profile routes` |

**Итого:** 5 коммитов. После завершения — PR в `dev`.

---

## Agent E: Question Bank & Tests Service

**Зависимости:** A, B, C, D, F (контракт LlmService).

**Ветка:** `feat/tests-questions`

**Задачи и коммиты:**

| # | Задача | Коммит |
| - | - | - |
| E1 | src/services/questions/question.service.ts | `feat: add QuestionService` |
| E2 | src/services/tests/tests.service.ts — создание теста, снепшот | `feat: add TestsService create flow` |
| E3 | tests.service — answer, finish, history | `feat: add test answer and finish flow` |
| E4 | src/routes/tests.ts | `feat: add tests routes` |
| E5 | Регистрация tests routes | `feat: register tests routes` |

**Итого:** 5 коммитов. После завершения — PR в `dev`.

---

## Agent F: LLM Service & Fallback Logic

**Зависимости:** A, B.

**Ветка:** `feat/llm-service`

**Задачи и коммиты:**

| # | Задача | Коммит |
| - | - | - |
| F1 | src/services/llm/llm.service.ts — конфиг, HTTP client | `feat: add LlmService base` |
| F2 | generateQuestions с JSON Schema валидацией | `feat: add LLM question generation` |
| F3 | Retry и fallback логика | `feat: add LLM retry and fallback` |
| F4 | Интеграция question_cache_meta | `feat: log LLM metadata to question_cache_meta` |
| F5 | Экспорт интерфейса для QuestionService | `feat: export LlmService interface` |

**Итого:** 5 коммитов. После завершения — PR в `dev`.

---

## Agent G: Admin QA for Questions

**Зависимости:** A, B, C, E (модель question_bank).

**Ветка:** `feat/admin-qa`

**Задачи и коммиты:**

| # | Задача | Коммит |
| - | - | - |
| G1 | src/services/admin/admin-question.service.ts | `feat: add AdminQuestionService` |
| G2 | src/routes/admin/questions.ts | `feat: add admin questions routes` |
| G3 | audit_logs при approve/reject/edit | `feat: add audit logging to admin actions` |
| G4 | Регистрация admin routes | `feat: register admin routes` |

**Итого:** 4 коммита. После завершения — PR в `dev`.

---

## Agent H: Tests & Quality

**Зависимости:** Может стартовать после C (auth), наращивать по мере готовности других агентов.

**Ветка:** `feat/testing`

**Задачи и коммиты:**

| # | Задача | Коммит |
| - | - | - |
| H1 | Vitest config, test-utils | `test: add Vitest config and test utils` |
| H2 | AuthService unit tests | `test: add auth service tests` |
| H3 | Auth routes integration tests | `test: add auth routes integration tests` |
| H4 | TestsService и QuestionService tests | `test: add tests and questions service tests` |
| H5 | LlmService unit tests (с моком) | `test: add LLM service tests` |
| H6 | Admin routes integration tests | `test: add admin routes tests` |
| H7 | Coverage ≥70%, npm script | `test: add coverage config` |

**Итого:** 7 коммитов. После завершения — PR в `dev`.

---

## Рекомендуемый порядок запуска

1. **Сразу:** Agent A и Agent B (в двух отдельных сессиях Cursor)
2. **После A и B:** Agent C, D, F (три сессии)
3. **После C, D, F:** Agent E, G (две сессии)
4. **Параллельно волне 2–3:** Agent H (тесты по мере готовности API)

---

## Чеклист для каждого агента

Перед каждым коммитом:

- [ ] `npm run typecheck` проходит
- [ ] Сообщение коммита по conventional commits
- [ ] Нет `console.log`, только `logger`
- [ ] Нет `any` без необходимости

После завершения всех задач агента:

- [ ] Создать PR в `dev`
- [ ] Проверить, что не сломаны существующие тесты (если есть)