Підрозділ (Group)¶

Підрозділ (Group) - це організаційна одиниця компанії, яка дозволяє структурувати співробітників за відділами, департаментами або іншими підрозділами. Підрозділи можуть утворювати ієрархічну структуру з батьківськими та дочірніми підрозділами.

API ендпоінти для роботи з підрозділами¶

POST /api/public/v1/group - створити новий підрозділ
GET /api/public/v1/group - отримати список підрозділів
GET /api/public/v1/group/{group_id} - отримати підрозділ за ID
PUT /api/public/v1/group/{group_id} - оновити підрозділ
DELETE /api/public/v1/group/{group_id} - видалити підрозділ

Поля підрозділу¶

Поле	Тип	Опис	Обов'язкове	Можливі значення	За замовчуванням
`id`	UUID	Унікальний ідентифікатор підрозділу	Автоматично	-	-
`name`	string	Назва підрозділу	Так	До 255 символів	-
`leader_id`	UUID \| null	ID співробітника-керівника підрозділу	Ні	Існуючий ID співробітника	null
`parent_id`	UUID \| null	ID батьківського підрозділу	Ні	Існуючий ID підрозділу	null
`type`	enum	Тип підрозділу	Ні	`simple`, `composite`	`simple`
`status`	enum	Статус підрозділу	Ні	`draft`, `parent`, `node`	`draft`
`external_id`	string \| null	Зовнішній ідентифікатор	Ні	До 255 символів	null
`date_created`	datetime	Дата створення	Автоматично	-	-
`date_updated`	datetime	Дата останнього оновлення	Автоматично	-	-

Батьківський підрозділ (`parent_id`)¶

Підрозділ може мати батьківський підрозділ, що дозволяє створювати ієрархію підрозділів. Це поле є необов'язковим, і якщо не вказано, підрозділ буде кореневим.

Приклад ієрархії¶

Компанія (root)
├── IT Департамент (parent_id: null)
│   ├── Frontend (parent_id: IT Департамент ID)
│   ├── Backend (parent_id: IT Департамент ID)
│   └── DevOps (parent_id: IT Департамент ID)
├── HR Департамент (parent_id: null)
└── Фінансовий Департамент (parent_id: null)
    ├── Бухгалтерія (parent_id: Фінансовий Департамент ID)
    └── Аудит (parent_id: Фінансовий Департамент ID)

Лідер підрозділу (`leader_id`)¶

Лідер підрозділу - це співробітник (employee), який відповідає за підрозділ. Це поле є необов'язковим, і якщо не вказано, підрозділ не матиме лідера.

Важливо: Лідер повинен бути співробітником зі статусом working.

Використання лідера підрозділу¶

Лідер підрозділу може використовуватися для: - Автоматичного призначення підписантів у задачах - Контролю за виконанням задач у підрозділі - Отримання звітів по підрозділу

Типи підрозділів (`type`)¶

Тип	Опис	Використання
`simple`	Простий підрозділ	Звичайний відділ або департамент з чітко визначеними співробітниками
`composite`	Композитний підрозділ	Складний підрозділ, який може об'єднувати інші підрозділи за певними критеріями (наприклад, всі технічні відділи)

Простий підрозділ (Simple)¶

Простий підрозділ - це стандартний відділ або департамент, до якого можна призначати співробітників напряму через поле group_id у співробітника.

Приклад: "Відділ розробки", "HR Департамент", "Бухгалтерія"

Композитний підрозділ (Composite)¶

Композитний підрозділ - це віртуальний підрозділ, який може автоматично включати співробітників з декількох інших підрозділів за певними правилами. Використовується для створення логічних групувань без необхідності дублювання призначень.

Приклад: "Всі технічні відділи", "Всі керівники", "Віддалені працівники"

Примітка: Налаштування правил композитних підрозділів доступне лише через веб-інтерфейс Вчасно.Кадри.

Статуси підрозділів (`status`)¶

Статус	Опис	Коли встановлюється
`draft`	Чернетка	За замовчуванням при створенні підрозділу
`parent`	Батьківський	Автоматично, якщо підрозділ має дочірні підрозділи
`node`	Вузол	Автоматично, якщо підрозділ є дочірнім (має `parent_id`)

Важливо: Статуси parent та node встановлюються автоматично системою на основі наявності батьківських та дочірніх підрозділів. Ручна зміна цих статусів може призвести до неконсистентності даних.

Приклади використання¶

Створення кореневого підрозділу¶

Створення головного підрозділу без батьківського підрозділу:

POST /api/public/v1/group
{
  "name": "IT Департамент",
  "type": "simple",
  "status": "draft"
}

Створення дочірнього підрозділу¶

Створення підрозділу з батьківським підрозділом:

POST /api/public/v1/group
{
  "name": "Frontend Team",
  "parent_id": "123e4567-e89b-12d3-a456-426614174000",
  "type": "simple",
  "status": "draft"
}

Після створення: - Дочірній підрозділ "Frontend Team" отримає статус node - Батьківський підрозділ "IT Департамент" автоматично отримає статус parent

Призначення лідера підрозділу¶

Створення підрозділу з керівником:

POST /api/public/v1/group
{
  "name": "Backend Team",
  "parent_id": "123e4567-e89b-12d3-a456-426614174000",
  "leader_id": "987e6543-e21b-12d3-a456-426614174001",
  "type": "simple"
}

Примітка: Співробітник з leader_id повинен мати статус working.

Використання зовнішнього ID¶

Для інтеграції з зовнішніми системами:

POST /api/public/v1/group
{
  "name": "HR Department",
  "external_id": "EXT-HR-001",
  "type": "simple"
}

Оновлення підрозділу¶

Оновлення назви та призначення нового лідера:

PUT /api/public/v1/group/{group_id}
{
  "name": "Відділ розробки та тестування",
  "leader_id": "456e7890-e12b-34c5-d678-426614174003"
}

Створення композитного підрозділу¶

POST /api/public/v1/group
{
  "name": "Всі технічні відділи",
  "type": "composite"
}

Примітка: Правила включення співробітників у композитний підрозділ налаштовуються через веб-інтерфейс.

Отримання списку підрозділів¶

GET /api/public/v1/group?page_size=50&page_num=1

Підтримуються параметри пагінації: - page_size - кількість записів на сторінці (за замовчуванням 100) - page_num - номер сторінки (за замовчуванням 1)

Видалення підрозділу¶

DELETE /api/public/v1/group/{group_id}

Важливо: Перед видаленням підрозділу переконайтеся, що: - У підрозділі немає співробітників (або перенесіть їх в інший підрозділ) - Підрозділ не має дочірніх підрозділів (або перенесіть їх на інший рівень)

Сценарії використання¶

Сценарій 1: Створення організаційної структури компанії¶

Створити головні департаменти:

POST /api/public/v1/group
{
  "name": "IT Департамент"
}

Створити відділи всередині департаментів:

POST /api/public/v1/group
{
  "name": "Frontend Team",
  "parent_id": "{IT_DEPARTMENT_ID}"
}

Призначити лідерів:

PUT /api/public/v1/group/{frontend_team_id}
{
  "leader_id": "{TEAM_LEAD_EMPLOYEE_ID}"
}

Призначити співробітників до підрозділів:

PATCH /api/public/v1/employee/{employee_id}
{
  "group_id": "{FRONTEND_TEAM_ID}"
}

Сценарій 2: Реструктуризація підрозділів¶

Отримати список існуючих підрозділів:
```
GET /api/public/v1/group
```
Перенести дочірній підрозділ до іншого батьківського:
```
PUT /api/public/v1/group/{group_id}
{
  "parent_id": "{NEW_PARENT_ID}"
}
```
Система автоматично оновить статуси:
Старий батьківський підрозділ може змінити статус з parent на draft, якщо це був останній дочірній підрозділ
Новий батьківський підрозділ отримає статус parent

Сценарій 3: Інтеграція з зовнішніми системами¶

Використання external_id для синхронізації з іншими системами:

Створити підрозділ з зовнішнім ID:

POST /api/public/v1/group
{
  "name": "Marketing",
  "external_id": "WORKDAY-MKT-001"
}

Пізніше отримати підрозділ по зовнішньому ID через фільтр:
```
GET /api/public/v1/group?external_id=WORKDAY-MKT-001
```

Як підрозділи впливають на інші сутності¶

Вплив на співробітників¶

Співробітники призначаються до підрозділу через поле group_id
Підрозділ використовується для організації списків співробітників
Лідер підрозділу може автоматично призначатися підписантом у задачах для співробітників цього підрозділу

Вплив на задачі¶

При створенні задач можна використовувати лідера підрозділу як підписанта
Композитні підрозділи дозволяють створювати задачі для групи співробітників з різних відділів

Вплив на звіти¶

Підрозділи використовуються для фільтрації та групування даних у звітах
Ієрархія підрозділів дозволяє отримувати агреговану інформацію на рівні департаменту

Правила валідації¶

Назва підрозділу - обов'язкове поле, мінімум 1 символ
Батьківський підрозділ - повинен існувати в системі та належати до тієї ж компанії
Лідер підрозділу - повинен бути співробітником зі статусом working
Циклічні залежності - заборонені (підрозділ не може бути батьківським для себе через ланцюжок)
Видалення - підрозділ з дочірніми підрозділами або співробітниками не може бути видалений

Помилки та їх вирішення¶

Помилка	Причина	Рішення
`Group not found`	Неправильний `group_id` або `parent_id`	Перевірити ID підрозділу
`Leader must be a working employee`	Лідер не має статус `working`	Використати ID співробітника зі статусом `working`
`Circular dependency detected`	Спроба створити циклічну залежність	Перевірити структуру батьківських підрозділів
`Cannot delete group with children`	Спроба видалити підрозділ з дочірніми підрозділами	Спочатку видалити або перенести дочірні підрозділи
`Cannot delete group with employees`	Спроба видалити підрозділ зі співробітниками	Спочатку перенести співробітників в інший підрозділ
`Group name is required`	Не вказано назву підрозділу	Додати поле `name`

Найкращі практики¶

Планування структури - перед створенням підрозділів продумайте повну ієрархію організації
Використання зовнішніх ID - якщо інтегруєтесь з іншими системами, завжди використовуйте external_id
Призначення лідерів - призначайте лідерів підрозділам для спрощення управління задачами
Композитні підрозділи - використовуйте для створення логічних групувань без дублювання призначень
Регулярний аудит - періодично перевіряйте актуальність структури підрозділів
Обережність при видаленні - перед видаленням підрозділу переконайтеся, що він не використовується

Обмеження¶

Максимальна глибина вкладеності підрозділів не обмежена, але рекомендується не більше 5 рівнів для зручності
Один підрозділ може мати тільки одного лідера
Співробітник може належати тільки до одного простого підрозділу, але може входити в декілька композитних
Композитні підрозділи налаштовуються лише через веб-інтерфейс