diff --git a/DOC/СТЕК.md b/DOC/СТЕК.md new file mode 100644 index 0000000..df30212 --- /dev/null +++ b/DOC/СТЕК.md @@ -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 достаточно diff --git a/DOC/ШАГИ/ШАГ_2026-03-21_004.md b/DOC/ШАГИ/ШАГ_2026-03-21_004.md new file mode 100644 index 0000000..29ccdc8 --- /dev/null +++ b/DOC/ШАГИ/ШАГ_2026-03-21_004.md @@ -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] Выбрать технологический стек +- [ ] Составить план спринтов