docs: add tech stack document and step 004 log

- Create DOC/СТЕК.md: FastAPI + React + PostgreSQL + Docker - Add DOC/ШАГИ/ШАГ_2026-03-21_004.md with decisions log Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-21 11:31:57 +05:00
parent 52c8aff459
commit 15de1e9369
2 changed files with 217 additions and 0 deletions
@@ -0,0 +1,96 @@
+# ШАГ 004 — Выбор технологического стека
+
+**Дата:** 2026-03-21
+**Контекст:** Мастер-класс по разработке системы тестирования сотрудников клиники.
+
+---
+
+## Запрос
+
+> да (переходим к обсуждению стека)
+
+Контекст:
+- Команда: джуниор-разработчики, знают Python
+- Архитектура: отдельный API + SPA
+- Деплой: Docker на своём сервере
+- Frontend фреймворк: React
+
+---
+
+## Ответ
+
+Стек зафиксирован в `DOC/СТЕК.md`.
+
+---
+
+## Принятые решения и обоснование
+
+### Backend: FastAPI
+
+Почему не Django:
+- Django — монолитный фреймворк, заточен под SSR, его DRF (Django REST Framework) добавляет сложность
+- FastAPI чище для чистого API-сервиса, меньше магии, проще читать код
+
+Почему не Flask:
+- Flask слишком минималистичен, джуниор потратит время на сборку инфраструктуры вместо бизнес-логики
+- FastAPI даёт валидацию, документацию и типизацию из коробки
+
+### База данных: PostgreSQL
+
+- SQLite не подходит для многопользовательского доступа (блокировки при записи)
+- PostgreSQL — проверенный выбор для продакшена, отличная поддержка в SQLAlchemy
+
+### ORM: SQLAlchemy 2.0 (async)
+
+- Async-режим важен для FastAPI — приложение не блокируется на запросах к БД
+- Alembic для миграций — джуниор учится правильно управлять схемой БД
+
+### Frontend: React 18 + TypeScript
+
+- React — самый востребованный фреймворк на рынке труда
+- TypeScript добавляет типизацию, ловит ошибки на этапе компиляции
+- Vite — современный и быстрый сборщик (замена устаревшего CRA)
+
+### UI: Ant Design
+
+- Готовые компоненты таблиц, форм, модалок, таймеров — сэкономим 1-2 спринта
+- Хорошо подходит для admin-панелей и внутренних инструментов
+- Встроенная русская локализация
+
+### Серверный стейт: TanStack Query
+
+Обучающий момент для джуниора:
+- Учит разделять серверное состояние (данные с API) и клиентское состояние (UI)
+- Без него джуниоры обычно пишут useEffect + useState везде — это антипаттерн
+- Автоматическое кэширование и перезапросы — меньше кода, больше надёжности
+
+### Инфраструктура: Docker Compose + Nginx
+
+```
+Nginx (80/443)
+ ├── / → React SPA (статика из build)
+ └── /api/ → FastAPI backend (uvicorn)
+
+Docker Compose сервисы:
+ ├── db (PostgreSQL)
+ ├── backend (FastAPI)
+ ├── frontend (React build / Vite в dev)
+ └── nginx
+```
+
+- Один `docker compose up` запускает весь стек
+- Nginx в одном контейнере раздаёт фронтенд и проксирует запросы к API
+- Для 50–200 пользователей этой архитектуры полностью достаточно
+
+---
+
+## Итог
+
+Документ `DOC/СТЕК.md` содержит полное описание стека с версиями и обоснованиями.
+
+### Следующие шаги
+
+- [x] Написать ТЗ
+- [x] Закрыть открытые вопросы ТЗ
+- [x] Выбрать технологический стек
+- [ ] Составить план спринтов