Browse Source
- 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>master
Aleksey Razorvin
1 week ago
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] Выбрать технологический стек |
||||
- [ ] Составить план спринтов |
||||
Loading…
Reference in new issue