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,121 @@
+# Технологический стек
+
+**Дата:** 2026-03-21
+**Статус:** Согласовано
+
+---
+
+## Архитектура
+
+```
+┌─────────────────────────────────────────────┐
+│                   Nginx                     │
+│  /         → React SPA (статика)            │
+│  /api/     → FastAPI backend                │
+└────────────────────┬────────────────────────┘
+                     │ Docker network
+          ┌──────────┴──────────┐
+          │                     │
+    ┌─────▼──────┐       ┌──────▼─────┐
+    │  FastAPI   │       │  React SPA │
+    │  (backend) │       │  (frontend)│
+    └─────┬──────┘       └────────────┘
+          │
+    ┌─────▼──────┐
+    │ PostgreSQL │
+    └────────────┘
+```
+
+---
+
+## Backend
+
+| Компонент | Технология | Версия |
+|-----------|-----------|--------|
+| Язык | Python | 3.12+ |
+| Фреймворк | FastAPI | 0.115+ |
+| ORM | SQLAlchemy (async) | 2.0+ |
+| Миграции | Alembic | latest |
+| База данных | PostgreSQL | 16+ |
+| Валидация | Pydantic v2 | 2.x |
+| Аутентификация | JWT (python-jose) | latest |
+| Хэширование паролей | passlib + bcrypt | latest |
+| ASGI-сервер | Uvicorn | latest |
+
+### Почему FastAPI
+- Автоматическая генерация OpenAPI/Swagger документации — джуниор сразу видит API
+- Async из коробки — правильные привычки с первого проекта
+- Pydantic-схемы = валидация + сериализация в одном месте
+- Активное сообщество, отличная документация на русском
+
+---
+
+## Frontend
+
+| Компонент | Технология | Версия |
+|-----------|-----------|--------|
+| Фреймворк | React | 18+ |
+| Язык | TypeScript | 5.x |
+| Сборщик | Vite | 5.x |
+| UI-библиотека | Ant Design (antd) | 5.x |
+| Роутинг | React Router | v6 |
+| Серверный стейт | TanStack Query (React Query) | v5 |
+| HTTP-клиент | Axios | latest |
+
+### Почему Ant Design
+- Готовые компоненты: таблицы, формы, прогрессбары, таймеры — сэкономит спринты
+- Хорошо подходит для административных интерфейсов
+- Поддержка русской локализации
+
+### Почему TanStack Query
+- Учит джуниора правильной работе с серверным состоянием
+- Кэширование, loading/error состояния, инвалидация — всё из коробки
+- Убирает необходимость в Redux для большинства задач
+
+---
+
+## Инфраструктура
+
+| Компонент | Технология |
+|-----------|-----------|
+| Контейнеризация | Docker + Docker Compose |
+| Реверс-прокси | Nginx |
+| ОС сервера | Linux (Ubuntu/Debian) |
+
+### Структура Docker Compose
+
+```yaml
+services:
+  db:        # PostgreSQL
+  backend:   # FastAPI + Uvicorn
+  frontend:  # React (build) / Vite dev server
+  nginx:     # Reverse proxy
+```
+
+---
+
+## Инструменты разработки
+
+| Назначение | Инструмент |
+|-----------|-----------|
+| Линтер Python | Ruff |
+| Форматтер Python | Black |
+| Линтер/форматтер JS | ESLint + Prettier |
+| API-тестирование | Swagger UI (встроен в FastAPI) |
+
+---
+
+## Уведомления (последний спринт)
+
+- Канал: мессенджер **MAX**
+- Реализация: отдельный сервис/модуль в backend
+- Интеграция: MAX API (изучить документацию перед спринтом)
+
+---
+
+## Вне scope (не используем)
+
+- Redis / очереди задач (Celery) — не нужны для данного масштаба
+- GraphQL — REST достаточно
+- Kubernetes — Docker Compose достаточно для 50–200 пользователей
+- SSR (Next.js) — не нужен, SPA достаточно
@@ -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] Выбрать технологический стек
+- [ ] Составить план спринтов