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

Техническое задание (Go-реализация)

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

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

git clone https://github.com/aaa2ppp/org-tree-api.git
cd org-tree-api

Переменные окружения

Пример всех используемых переменных окружения находится в файле dot.env.example.
Скопируйте его и отредактируйте под свои нужды:

cp dot.env.example .env

# Сгенерировать случайный пароль для базы данных
echo -e "\nDB_PASSWORD='$(head -c16 /dev/urandom | base64)'" >> .env

Локальный запуск

# Загрузить переменные окружения
. dev-env

# Установить зависимости и проверить утилиты (при необходимости будут установлены)
make deps check-tools

# Запустить приложение
make run

Запуск в Docker

# Запустить приложение в контейнере
make docker-run

Swagger

По умолчанию Swagger доступен на http://localhost:8080/swagger/

Уборка

# Удалить контейнеры и том базы данных
make docker-down-volumes

# Удалит локально собранные бинарники и временные файлы
make clean

Управление через Makefile

Все доступные команды make можно посмотреть, выполнив:

make help

Ограничения, особенности и отступления от ТЗ

• Допустимый диапазон идентификаторов:
  1..2147483647

  Особые значения (для внутреннего использования):

  • -1 — Виртуальный корень (содержит все подразделения верхнего уровня)
  • 0 — undefined используется в MoveDepartmentRequest (PATCH /departments/{department_id})

• Вывод подразделений верхнего уровня
  Добавлена ручка GET /departments - возвращает массив подразделений верхнего уровня, в остальном аналогичен GET /departments/{department_id}.

• Parent ID для корневых подразделений.
  ТЗ неявно предполагает для подразделений верхнего уровня parent_id = null (или отсутствие поля).
  Предложение: использовать parent_id = -1 для обозначения корневого узла. Это позволит отказаться от null в API, упростит валидацию запросов и соответствует внутренней модели сервиса.

• Сортировка в GET /departments/{department_id}.
  ТЗ указывает: "если include_employees=true, сортировка по created_at или full_name", но не регламентирует порядок вывода children.

  Добавлен параметр sort_by, который определяет порядок сортировки подотделов и сотрудников.

• Параметр depth в GET /departments/{department_id}.
  ТЗ: "depth: int (по умолчанию 1, максимум 5) — глубина вложенных подразделений в ответе".
  Уточнение определения.
  В реализации используется общепринятое определение:
  Глубина узла — количество ребер (шагов) от корневого узла до рассматриваемого узла.
  При таком подходе depth=1 (значение по умолчанию) означает вывод самого узла и всех его прямых потомков.
  Замечание: возможно, заказчик подразумевал другое поведение (например, depth=1 — только узел, без потомков).

• Перемещение дочених подразделений в DELETE /departments/{department_id}.
  ТЗ: если mode = reassign "сотрудников перевести в reassign_to_department_id", но не указано, что делать с дочерними подразделениями.
  Реализовано перемещение дочерних подразделений в reassign_to_department_id аналогично сотрудникам.

• Хранилище в памяти
  Для целей тестирования реализована возможность хранение данных в памяти. Чтобы получить самодостаточный бинарник, для которого не требуется база данных, сервер должен быть собран с тегом сборки -tags memstor.
  ВАЖНО: Массовые операции не поддерживают откат. При обнаружении конфликта сбойная операция будет выполнена частично с сохранением целостности дерева. В случае паники целостность не гарантируется.