From d013a16e98621b1c6de98cf5aa675bd9c405087c Mon Sep 17 00:00:00 2001 From: Aleksey Razorvin <> Date: Sat, 21 Mar 2026 11:39:43 +0500 Subject: [PATCH] docs: add sprint plan and step 005 log MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- DOC/СПРИНТЫ.md | 149 ++++++++++++++++++++++++++ DOC/ШАГИ/ШАГ_2026-03-21_005.md | 45 ++++++++ 2 files changed, 194 insertions(+) create mode 100644 DOC/СПРИНТЫ.md create mode 100644 DOC/ШАГИ/ШАГ_2026-03-21_005.md diff --git a/DOC/СПРИНТЫ.md b/DOC/СПРИНТЫ.md new file mode 100644 index 0000000..ceaf089 --- /dev/null +++ b/DOC/СПРИНТЫ.md @@ -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/ +``` diff --git a/DOC/ШАГИ/ШАГ_2026-03-21_005.md b/DOC/ШАГИ/ШАГ_2026-03-21_005.md new file mode 100644 index 0000000..f2f2bc8 --- /dev/null +++ b/DOC/ШАГИ/ШАГ_2026-03-21_005.md @@ -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