qa_test_app/DOC/ШАГИ/ШАГ_2026-03-21_006.md

ШАГ 006 — Спринт 1: Инфраструктура + Создание тестов

Дата: 2026-03-21 Контекст: Мастер-класс по разработке системы тестирования сотрудников клиники.

---

Запрос

готов. поехали (начинаем Спринт 1)

---

Ответ

Реализован Спринт 1 в полном объёме: инфраструктура + создание тестов без авторизации. Спринт протестирован вручную в браузере, найдены и исправлены 4 бага.

---

Структура проекта после спринта

qa_test_app/
├── docker-compose.yml          ← поднимает весь стек одной командой
├── .env.example
├── nginx/
│   └── nginx.conf              ← / → frontend, /api/ → backend
├── backend/
│   ├── Dockerfile
│   ├── entrypoint.sh           ← ждёт БД, запускает миграции, стартует сервер
│   ├── requirements.txt
│   ├── alembic.ini
│   ├── alembic/
│   │   ├── env.py              ← async alembic, берёт URL из settings
│   │   ├── script.py.mako
│   │   └── versions/
│   │       └── 001_init.py     ← создаёт таблицы tests, questions, answers
│   └── app/
│       ├── config.py           ← настройки через pydantic-settings
│       ├── database.py         ← async SQLAlchemy engine + session
│       ├── main.py             ← FastAPI app, /api/health
│       ├── models/test.py      ← ORM модели: Test, Question, Answer
│       ├── schemas/test.py     ← Pydantic схемы с валидацией
│       └── api/tests.py        ← REST эндпоинты
└── frontend/
    ├── Dockerfile
    ├── package.json
    ├── vite.config.ts
    ├── index.html
    └── src/
        ├── App.tsx             ← роутер + провайдеры
        ├── api/
        │   ├── client.ts       ← axios с baseURL=/api
        │   └── tests.ts        ← типы + функции запросов
        └── pages/
            ├── TestList/       ← список тестов + кнопка создать
            ├── TestCreate/     ← форма создания теста
            └── TestDetail/     ← просмотр теста с вопросами

---

API эндпоинты

Метод	URL	Описание
GET	/api/health	Проверка работы сервера
GET	/api/tests	Список тестов
GET	/api/tests/{id}	Детали теста с вопросами и ответами
POST	/api/tests	Создать тест

---

Схема БД

tests
  id, title, description, passing_score, time_limit,
  allow_navigation_back, is_active, version, created_at

questions
  id, test_id → tests.id, text, order

answers
  id, question_id → questions.id, text, is_correct

---

Валидация

Backend (Pydantic):

• Тест: минимум 7 вопросов, passing_score 0–100
• Вопрос: минимум 3 варианта ответа, хотя бы 1 правильный

Frontend (Ant Design Form):

• Те же правила воспроизведены на клиенте
• Nested Form.List для динамических вопросов и ответов
• Таймер показывается только при включённом переключателе (shouldUpdate)

---

Как запустить

docker compose up --build

Открыть браузер: http://localhost

• Список тестов → кнопка «Создать тест»
• Заполнить форму → нажать «Создать тест»
• Перейти к созданному тесту и увидеть все вопросы и ответы
• http://localhost/api/health → {"status": "ok"}
• http://localhost/api/docs → Swagger UI FastAPI
• http://localhost/api/redoc → ReDoc документация

---

Баги, найденные и исправленные при ручном тестировании

#	Симптом	Причина	Исправление
1	permission denied на entrypoint.sh	docker-compose.yml монтирует ./backend:/app — volume перекрывает файлы образа, включая результат chmod +x из Dockerfile	CMD ["bash", "entrypoint.sh"] вместо CMD ["./entrypoint.sh"]
2	No module named 'app' в Alembic	Python не добавляет WORKDIR в sys.path автоматически	ENV PYTHONPATH=/app в Dockerfile
3	nginx: host not found in upstream "backend"	nginx резолвит upstream-хосты при старте, а backend ещё не поднялся	Docker DNS resolver 127.0.0.11 + set $backend — резолвинг откладывается до момента запроса
4	http://localhost/api/docs → 404	FastAPI по умолчанию отдаёт Swagger по /docs, а через nginx путь становится /api/docs → backend:8000/api/docs (не существует)	Явно указать docs_url="/api/docs", redoc_url="/api/redoc", openapi_url="/api/openapi.json" в FastAPI

Для джуниора: все четыре бага — типичные для первого запуска Docker + FastAPI + nginx. Запомни их, встретишь снова.

---

Ключевые решения для джуниора

Async SQLAlchemy 2.0:

• async_sessionmaker + AsyncSession — не блокируем event loop при запросах к БД
• selectinload для жадной загрузки связей (вместо N+1 запросов)

Alembic async:

• async_engine_from_config + connection.run_sync(do_run_migrations)
• URL берётся из app.config.settings — одно место для конфига

Docker Compose healthcheck:

• db объявляет healthcheck, backend ждёт condition: service_healthy
• Дополнительно entrypoint.sh вызывает pg_isready для надёжности

TanStack Query:

• useQuery для чтения данных — кэш, loading state, error state из коробки
• useMutation для создания — invalidateQueries обновляет список после успеха

---

Следующие шаги

• Спринт 1: Инфраструктура + Создание тестов
• Спринт 2: Прохождение теста + результаты
• Спринт 3: Трекер результатов
• Спринт 4: Авторизация и роли
• Спринт 5: Уведомления в MAX