Задача
Предоставить API для подразделений и сотрудников, где клиент может получать поддерево, перемещать узлы и удалять подразделения без повреждения иерархии.
Назад к проектам
Org Structure API
REST API для управления подразделениями и сотрудниками. Главная инженерная задача проекта — безопасно изменять дерево произвольной глубины, сохраняя его структурные инварианты.
- Домен
- Организационная иерархия
- Модель
- Подразделения и сотрудники
- Основа
- FastAPI · SQLAlchemy · PostgreSQL
PROBLEM & CONSTRAINTS
CRUD становится сложнее, когда сущности образуют изменяемое дерево.
Создание и чтение узлов просты только до тех пор, пока не появляются перемещение, каскадное удаление и проверка циклов.
Ограничения
- Подразделение нельзя переместить внутрь собственного поддерева.
- Имя должно быть уникальным среди узлов с одним родителем.
- Удаление должно явно определять судьбу дочерних подразделений и сотрудников.
- Изменение структуры должно проходить через бизнес-валидацию, а не напрямую через ORM.
ARCHITECTURE
API-слой отделён от правил целостности дерева.
FastAPI и Pydantic отвечают за контракт, сервисный слой проверяет инварианты, SQLAlchemy управляет данными, а Alembic фиксирует эволюцию схемы.
- cycle prevention
- sibling uniqueness
- explicit deletion mode
- schema migrations
TREE MUTATION FLOW
Перемещение узла начинается с проверки будущего состояния дерева.
Операция рассматривается не как обновление parent_id, а как изменение связанной структуры с набором инвариантов.
Получение команды
FastAPI валидирует идентификаторы, поля подразделения и режим операции через Pydantic-схемы.
Проверка нового родителя
Сервис убеждается, что родитель существует, а перемещаемый узел не станет потомком самого себя.
Проверка уникальности
Имя подразделения проверяется в контексте нового родителя, а не глобально для всей организации.
Транзакционное изменение
После прохождения правил ORM сохраняет новую связь и связанные изменения в PostgreSQL.
Возврат согласованного дерева
API формирует результат только после успешного изменения, чтобы клиент видел актуальную структуру или явную ошибку.
KEY DECISIONS
Инварианты дерева оформлены как бизнес-правила.
Главная ценность проекта — явное моделирование корректных и некорректных изменений иерархии.
Сервисный слой
Проверки перемещения, удаления и работы с сотрудниками не зависят от конкретного HTTP endpoint.
Защита от циклов
Перед сменой родителя сервис проверяет, что новое положение не включает узел в собственное поддерево.
Уникальность внутри родителя
Одинаковые названия допустимы в разных ветках, но не среди соседних подразделений одного уровня.
Alembic для схемы
Изменения структуры базы оформляются миграциями и не зависят от ручного обновления окружения.
QUALITY
Интеграционные тесты проверяют API вместе с бизнес-правилами.
Тесты направлены на наблюдаемое поведение сервиса: CRUD, изменение дерева, сотрудники и ошибочные операции.
Интеграционные сценарии проходят через HTTP-контракт и проверяют результат операций над структурой.
Схема PostgreSQL изменяется воспроизводимо и хранится рядом с исходным кодом.
Приложение и база поднимаются единым окружением, а Swagger UI доступен после запуска.
LIMITS & HONESTY
Кейс показывает реализованное ядро без выдачи roadmap за готовую систему.
Портфолио намеренно отделяет текущий код от функций и показателей, которые ещё требуют реализации или воспроизводимого подтверждения.
JWT и разделение ролей
Авторизация указана в направлении развития репозитория и не представлена здесь как завершённая возможность.
Redis-кэш и пагинация
Кэширование деревьев и пагинация сотрудников остаются следующими шагами, а не частью текущего критического пути.
Производительность без воспроизводимого benchmark
Числа из README не используются как production-гарантии, пока рядом с проектом нет публичной методики и запускаемого benchmark-сценария.
CI, мониторинг и визуализация
Автоматический pipeline, observability и frontend дерева логично добавлять после стабилизации API-контракта.
RESULT
Небольшой API демонстрирует работу с нетривиальными инвариантами данных.
Проект полезен не количеством технологий, а тем, что обычные CRUD-операции рассматриваются через целостность изменяемого дерева.
- Изменение parent_id — это доменная операция, если оно может повредить структуру данных.
- Roadmap и текущая реализация должны быть явно разделены в документации и портфолио.
- Интеграционные тесты особенно ценны там, где ошибка проявляется на границе API, сервиса и базы.
SOURCE CODE
Реализация дерева и тестовые сценарии доступны в репозитории.
README содержит endpoints, Docker-запуск, структуру проекта и список честно обозначенных следующих шагов.