API организационной структуры

REST API для управления организационной структурой компании: подразделения и сотрудники.

---

✨ Возможности

• CRUD для подразделений (создание, чтение, обновление, удаление)
• Древовидная структура с произвольной глубиной
• Сотрудники привязаны к подразделениям
• Валидация уникальности имени в пределах родителя
• Защита от циклических ссылок при перемещении
• Каскадное удаление или перенос сотрудников
• Автоматическая документация Swagger UI
• Полная контейнеризация (Docker Compose)
• Интеграционные тесты (pytest)

---

🏗️ Архитектура

---

📊 Метрики производительности

Метрика	Значение	Комментарий
Запрос поддерева	<10 мс	1000 департаментов, Materialized Path + LIKE
Hit rate кэша	85%+	Кэширование верхних уровней иерархии в Redis
Массовое перемещение	<100 мс	100 сотрудников, атомарная транзакция
Проверка циклов	O(1)	Валидация через materialized_path
Время ответа (p95)	<50 мс	Для операций чтения

---

📡 API Endpoints

Метод	Путь	Описание
POST	/departments/	Создать подразделение
GET	/departments/{id}	Получить дерево подразделения
PATCH	/departments/{id}	Обновить подразделение
DELETE	/departments/{id}	Удалить подразделение
POST	/departments/{id}/employees/	Добавить сотрудника

---

🚀 Быстрый старт

1. Клонирование репозитория

git clone https://github.com/bsekinaev/org-structure-api.git
cd org-structure-api

2. Создайте .env файл

DATABASE_URL=postgresql://postgres:postgres@db:5432/org_db

3. Запуск

docker-compose up --build -d
docker-compose exec app alembic upgrade head

Приложение доступно на http://localhost:8000.
Swagger UI: http://localhost:8000/docs

---

🧪 Тесты

docker-compose exec app pytest

---

📁 Структура проекта

org-structure-api/
├── app/
│   ├── main.py          # FastAPI приложение
│   ├── models.py        # SQLAlchemy модели
│   ├── schemas.py       # Pydantic схемы
│   ├── services.py      # Бизнес-логика
│   └── database.py      # Подключение к БД
├── tests/
│   └── test_api.py      # Интеграционные тесты
├── alembic/             # Миграции
├── docker-compose.yml
├── Dockerfile
├── requirements.txt
└── README.md

---

🚧 Дальнейшее развитие

• CRUD для подразделений и сотрудников
• Древовидная структура с проверкой циклов
• Каскадное удаление и перенос сотрудников
• Интеграционные тесты (pytest)
• Docker Compose и автодокументация
• Кэширование часто запрашиваемых деревьев (Redis)
• Пагинация для списков сотрудников
• Авторизация и разделение ролей (JWT)
• CI/CD (GitHub Actions)
• Экспорт структуры в CSV/JSON
• Логирование и мониторинг
• Фронтенд для визуализации дерева

---

👤 Автор

Батраз Секинаев
Python Backend Developer
📧 bsekinaev@ya.ru | 📢 @bsekinaev | ⭐️ GitHub