docs: add sprint plan and step 005 log

- Create DOC/СПРИНТЫ.md: 5 sprints, value-first approach - Sprint 1: infra + test creation (no auth) - Sprint 2: taking tests + results - Sprint 3: results tracker - Sprint 4: auth + roles + user management - Sprint 5: MAX notifications - Add DOC/ШАГИ/ШАГ_2026-03-21_005.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-21 11:39:43 +05:00
parent 15de1e9369
commit d013a16e98
2 changed files with 194 additions and 0 deletions
@@ -0,0 +1,149 @@
+# План спринтов
+
+**Дата:** 2026-03-21
+**Статус:** Согласовано
+
+---
+
+## Принцип
+
+Каждый спринт — это готовое работающее приложение (frontend + backend), которое можно запустить локально командой `docker compose up` и протестировать вручную в браузере.
+
+---
+
+## Спринт 1 — Инфраструктура + Создание тестов
+
+**Результат:** Поднят весь стек, можно зайти на страницу и создать тест.
+
+### Инфраструктура
+- [ ] Структура репозитория: `backend/`, `frontend/`, `nginx/`, `docker-compose.yml`
+- [ ] `docker-compose.yml`: сервисы `db`, `backend`, `frontend`, `nginx`
+- [ ] PostgreSQL: контейнер, volume для данных
+- [ ] FastAPI: контейнер, `GET /api/health` → `{"status": "ok"}`
+- [ ] Alembic: инициализирован, первая миграция (пустая схема)
+- [ ] React + Vite: контейнер, базовая страница открывается в браузере
+- [ ] Nginx: `/` → React SPA, `/api/` → FastAPI
+
+### Создание тестов (без авторизации)
+- [ ] Модели БД: `Test`, `Question`, `Answer`
+- [ ] API: `POST /api/tests` — создать тест с вопросами и ответами
+- [ ] API: `GET /api/tests` — список тестов
+- [ ] API: `GET /api/tests/{id}` — детали теста
+- [ ] Фронт: страница создания теста (название, вопросы, варианты, настройки)
+- [ ] Фронт: список тестов
+- [ ] Фронт: страница просмотра теста
+
+**Настройки теста:** порог зачёта (%), таймер (опционально), разрешить возврат к предыдущему вопросу
+
+---
+
+## Спринт 2 — Прохождение теста
+
+**Результат:** Можно выбрать тест из списка и пройти его, увидеть результат и разбор ошибок.
+
+- [ ] Модели БД: `TestAttempt`, `AttemptAnswer`
+- [ ] API: `POST /api/attempts` — начать попытку (фиксируем время начала)
+- [ ] API: `POST /api/attempts/{id}/submit` — завершить попытку, подсчитать результат
+- [ ] API: `GET /api/attempts/{id}/result` — результат с разбором ошибок
+- [ ] Фронт: страница прохождения теста
+  - Случайный порядок вопросов
+  - Таймер с обратным отсчётом (если задан) — автосабмит по истечении
+  - Навигация назад (если разрешена настройкой теста)
+- [ ] Фронт: страница результата
+  - Балл и процент
+  - Сдал / Не сдал (относительно порога)
+  - Разбор ошибок: вопрос, ответ сотрудника, правильный ответ
+
+---
+
+## Спринт 3 — Трекер результатов
+
+**Результат:** Таблица всех попыток прохождения тестов.
+
+- [ ] API: `GET /api/attempts` — все попытки (с фильтрами по тесту, дате)
+- [ ] Фронт: страница трекера
+  - Таблица: сотрудник, тест, № попытки, начало, завершение, результат, зачёт
+  - Фильтрация по тесту и дате
+  - Пагинация
+
+---
+
+## Спринт 4 — Авторизация и управление пользователями
+
+**Результат:** Вход по логину/паролю, роли ограничивают доступ. Можно создавать сотрудников и подразделения.
+
+### Авторизация
+- [ ] Модели БД: `User`, `Department`
+- [ ] API: `POST /api/auth/login` → JWT access token
+- [ ] API: `POST /api/auth/logout`
+- [ ] API: `GET /api/auth/me`
+- [ ] Middleware: проверка JWT на защищённых эндпоинтах
+- [ ] Фронт: страница входа
+- [ ] Фронт: защищённые роуты (редирект на логин если нет токена)
+
+### Роли и права
+
+| Роль | Тесты | Назначение | Трекер |
+|------|-------|-----------|--------|
+| HR-менеджер / Директор | Создаёт, все тесты | Всем сотрудникам | Вся клиника |
+| Руководитель подразделения | Создаёт, свои тесты | Только своему отделу | Только свой отдел |
+| Сотрудник | Только назначенные | — | Только свои |
+
+### Управление пользователями
+- [ ] API: CRUD подразделений
+- [ ] API: CRUD пользователей (создание, редактирование, деактивация)
+- [ ] Фронт: страница управления подразделениями (HR)
+- [ ] Фронт: страница управления сотрудниками (HR / руководитель)
+
+### Назначение тестов
+- [ ] Модели БД: `TestAssignment`
+- [ ] API: `POST /api/assignments` — назначить тест (получатели, дедлайн, кол-во попыток)
+- [ ] Фронт: форма назначения теста
+- [ ] Фронт: дашборд сотрудника — список назначенных тестов со статусами (`Не начат`, `В процессе`, `Завершён`, `Просрочен`)
+
+### Версионирование тестов
+- [ ] При попытке редактировать назначенный тест — создаётся новая версия
+- [ ] Результаты привязаны к конкретной версии теста
+
+---
+
+## Спринт 5 — Уведомления в MAX
+
+**Результат:** Сотрудники получают уведомления в мессенджер MAX.
+
+- [ ] Изучить документацию MAX API
+- [ ] Реализовать сервис уведомлений в backend
+- [ ] Уведомление при назначении теста сотруднику
+- [ ] Уведомление за N дней до дедлайна (настраивается)
+- [ ] Поле `max_user_id` в профиле пользователя
+- [ ] Фронт: в профиле пользователя — поле для MAX ID
+
+---
+
+## Структура репозитория (целевая после Спринта 1)
+
+```
+qa_test_app/
+├── backend/
+│   ├── app/
+│   │   ├── api/          ← роутеры FastAPI
+│   │   ├── models/       ← SQLAlchemy модели
+│   │   ├── schemas/      ← Pydantic схемы
+│   │   ├── services/     ← бизнес-логика
+│   │   └── main.py
+│   ├── alembic/
+│   ├── Dockerfile
+│   └── requirements.txt
+├── frontend/
+│   ├── src/
+│   │   ├── api/          ← Axios + TanStack Query
+│   │   ├── components/   ← переиспользуемые компоненты
+│   │   ├── pages/        ← страницы
+│   │   └── main.tsx
+│   ├── Dockerfile
+│   └── package.json
+├── nginx/
+│   └── nginx.conf
+├── docker-compose.yml
+└── DOC/
+```
@@ -0,0 +1,45 @@
+# ШАГ 005 — План спринтов
+
+**Дата:** 2026-03-21
+**Контекст:** Мастер-класс по разработке системы тестирования сотрудников клиники.
+
+---
+
+## Запрос
+
+> мое предложение такое: давай на первом спринте мы сможем создавать тесты. здесь не нужно никакой авторизации и ролей. главное зашел на страницу создания теста и смог его создать. следующий спринт — можем выполнять тест. следующий спринт — трекер результатов. затем аутентификация и управление пользователями и подразделениями. и потом уведомления
+
+> спринт 0 и спринт 1 соединяем
+
+---
+
+## Ответ
+
+### Ключевое решение по порядку спринтов
+
+Заказчик выбрал подход **"ценность сначала"**: бизнес-логика (создание и прохождение тестов) реализуется в первых спринтах без авторизации. Это даёт несколько преимуществ:
+
+1. **Быстрая обратная связь** — уже после спринта 1 можно потрогать живой продукт
+2. **Мотивация для джуниоров** — видят результат, а не бойлерплейт
+3. **Проще отлаживать** — нет JWT, нет проверки прав, чистая бизнес-логика
+4. **Авторизация добавляется поверх** — в спринте 4 она "накладывается" на уже работающее приложение
+
+Это классический подход Lean/MVP: сначала рабочий продукт, потом безопасность и управление.
+
+### Итоговый план
+
+| Спринт | Что делаем | Результат в браузере |
+|--------|-----------|---------------------|
+| **1** | Инфраструктура + Создание тестов | Создаём тест, видим список тестов |
+| **2** | Прохождение теста | Проходим тест, видим результат и ошибки |
+| **3** | Трекер результатов | Таблица всех попыток |
+| **4** | Авторизация + роли + подразделения + назначение | Вход по логину, разграничение доступа |
+| **5** | Уведомления в MAX | Получаем уведомления в мессенджер |
+
+### Следующие шаги
+
+- [x] Написать ТЗ
+- [x] Закрыть открытые вопросы ТЗ
+- [x] Выбрать технологический стек
+- [x] Составить план спринтов
+- [ ] Начать Спринт 1