@hubex/mcp 0.2.0

package/docs/guides/tasktypes.md

@@ -0,0 +1,156 @@
+---
+topic: tasktypes
+sources:
+  - page: adminapp/src/modules/taskTypeRightSideBar/taskTypeCreateForms.js
+    content_hash: cd18cabc3f42cf97
+  - page: adminapp/src/services/requests.js
+    content_hash: 54c3d95d85bb0ce0
+  - page: adminapp/src/locales/ru/app.json
+    content_hash: 22b22046c9336c1a
+---
+
+# Типы заявок и связанные справочники
+
+Тип заявки — классификация заявок, которая определяет жизненный цикл
+(последовательность стадий), маску номера, крайний срок закрытия по умолчанию
+и список допустимых видов работ. Настройка жизненного цикла делается **после**
+создания типа заявки — `hubex_get_guide topic="lifecycle"`.
+
+## 1. Создание типа заявки
+
+Порядок вызовов веб-клиента:
+
+```text
+POST WORK:POST:/TaskTypes   query relatedToAnyWorkType=true → taskTypeID
+POST WORK:POST:/TaskTypes/{id}/workTypes            → если виды работ выбраны списком
+POST TSTG:POST:/TaskStageLinks/copy                 → если тип создаётся по шаблону
+PUT  WORK:PUT:/TaskTypeDistrict                     → участки
+```
+
+Тело создания — массив:
+
+```json
+[
+  {
+    "name": "Ремонт электрооборудования",
+    "numberMask": "[{День ДД}][{Месяц ММ}][0-9][0-9][0-9]",
+    "closeMinutes": 1440,
+    "isDefault": false
+  }
+]
+```
+
+- `numberMask` — формат номера заявки. Маска по умолчанию в AdminApp —
+  `[{День ДД}][{Месяц ММ}][0-9][0-9][0-9]`; каждый блок `[0-9]` — один разряд
+  сквозного счётчика, поэтому три блока дают номера до 999 в день.
+- `closeMinutes` — крайний срок закрытия (дедлайн) в **минутах**; веб-клиент
+  собирает его из дней/часов/минут формы. `null` — срок не задан.
+  При создании заявки система берёт **наименьшее** значение из срока типа
+  заявки и срока вида работ; если оба пусты — считает дедлайн по правилам SLA
+  (`hubex_get_guide topic="sla"`).
+- `isDefault` — тип по умолчанию для новых заявок.
+- Query-параметр `relatedToAnyWorkType` (`true`/`false`) — «все виды работ» или
+  «по списку». При `false` сразу после создания привяжи виды работ.
+
+Изменение — `WORK:PUT:/TaskTypes` (массив с `id`, полное тело), удаление —
+`WORK:DELETE:/TaskTypes/{id}`.
+
+## 2. Виды работ типа заявки
+
+```text
+GET    WORK:GET:/TaskTypes/{id}/workTypes    что уже привязано
+POST   WORK:POST:/TaskTypes/{id}/workTypes   тело — массив id видов работ: [12, 18]
+DELETE WORK:DELETE:/TaskTypes/{id}/workTypes отвязать
+```
+
+Зеркальные эндпоинты со стороны вида работ — `WORK:GET:/WorkTypes/{id}/taskTypes`,
+`WORK:POST:/WorkTypes/{id}/taskTypes`, `WORK:DELETE:/WorkTypes/{id}/taskTypes`.
+
+Сам справочник видов работ: `WORK:GET:/WorkTypes`, создание —
+`WORK:POST:/WorkTypes`, изменение — `WORK:PUT:/WorkTypes`. Неопубликованный
+вид работ недоступен пользователям: публикация — `WORK:PUT:/WorkTypes/publish`
+(или `WORK:PUT:/WorkTypes/{id}/publish`), снятие —
+`WORK:PUT:/WorkTypes/unpublish`. Шаблоны чек-листов вида работ —
+`WORK:GET:/WorkTypes/{workTypeID}/checkLists` и
+`WORK:POST:/WorkTypes/{workTypeID}/checkLists`.
+
+## 3. Участки
+
+Участок (`District`) — классификация объектов, типов заявок, сотрудников и
+заказчиков по географическому или функциональному признаку; вместе с ролями
+он разграничивает доступ.
+
+- Справочник: `ES:GET:/Districts`, создание — `ES:POST:/Districts`,
+  изменение — `ES:PUT:/Districts`, иерархия и порядок —
+  `ES:PUT:/Districts/parentAndReorder`, удаление — `ES:DELETE:/Districts/{id}`.
+- Участки типа заявки: чтение `WORK:GET:/TaskTypes/{id}/districts`,
+  запись `WORK:PUT:/TaskTypeDistrict` с телом
+  `[{ "taskTypeID": 5, "data": [1, 2, 3] }]`. Это **замена** списка целиком:
+  переданный `data` становится полным набором участков типа заявки.
+- Участки пользователя — `ADM:POST:/UserDistricts` и `ADM:DELETE:/UserDistricts`.
+
+## 4. Критичности
+
+Критичность визуально разделяет заявки по важности и участвует в расчёте
+дедлайна правилами SLA.
+
+- `SLA:GET:/Criticalities`, `SLA:POST:/Criticalities`, `SLA:PUT:/Criticalities`,
+  `SLA:DELETE:/Criticalities/{id}`.
+- Тело: `[{ "name": "Срочная", "color": "#E03131", "isDefault": false, "sortOrder": 1, "erpID": null }]`.
+  `color` — до 7 символов, `name` — до 128, `erpID` — до 64 символов, внешний
+  идентификатор для интеграций (1С, CRM).
+
+## 5. Актуальности заявки
+
+Актуальность (`TaskActuality`) помечает заявку как устаревающую по времени.
+
+- `WORK:GET:/TaskActualities`, `WORK:POST:/TaskActualities`,
+  `WORK:PUT:/TaskActualities`, `WORK:DELETE:/TaskActualities/{id}`.
+- Тело: `[{ "name": "Просрочена", "color": "#E03131", "toBeExpiredAfterMinutes": 60, "isTillNextDay": false, "sortOrder": 2 }]`.
+
+## 6. Форма заявки для типа
+
+Расположение полей и блоков на форме заявки задаётся шаблоном раскладки:
+
+```text
+GET  UI:GET:/LayoutTemplates            список шаблонов
+GET  UI:GET:/LayoutTemplates/default    шаблон по умолчанию
+GET  UI:GET:/LayoutTemplates/bytype/{id} шаблон, применённый к типу заявки
+POST UI:POST:/LayoutTemplates           создать
+PUT  UI:PUT:/LayoutTemplates/{id}/taskTypes привязать шаблон к типам заявок
+PUT  UI:PUT:/LayoutTemplates/{id}/reset сбросить к исходному
+```
+
+Состав шаблона: `UI:GET:/LayoutTemplates/{id}/Components` (системные блоки и
+поля) и `UI:GET:/LayoutTemplates/{id}/Attributes` (дополнительные поля,
+см. `hubex_get_guide topic="attributes"`).
+
+Видимость полей по ролям и стадиям — это другая настройка, из жизненного
+цикла: `TSTG:GET:/TaskStageComponents/availability` и
+`TSTG:POST:/TaskStageComponents`.
+
+## Последовательность MCP-вызовов
+
+```text
+hubex_request_write(endpointId: `WORK:POST:/TaskTypes`, query: { relatedToAnyWorkType: false }, body: [{ name, numberMask, closeMinutes }])
+→ response[0] = taskTypeID
+hubex_request_write(endpointId: `WORK:POST:/TaskTypes/{id}/workTypes`, pathParams: { id: taskTypeID }, body: [12, 18])
+hubex_request_write(endpointId: `TSTG:POST:/TaskStageLinks/copy`, body: [{ sourceTaskTypeID, targetTaskTypeID: taskTypeID }])
+hubex_request_write(endpointId: `WORK:PUT:/TaskTypeDistrict`, body: [{ taskTypeID, data: [1, 2] }])
+hubex_request_read(endpointId: `WORK:GET:/TaskTypes/{id}`, pathParams: { id: taskTypeID })
+```
+
+## Подводные камни
+
+- Новый тип заявки без жизненного цикла нерабочий: нужен как минимум маршрут
+  (`WORK:POST:/TaskTypeRoutes`) и переходы. Копирование переходов из типа
+  шаблона (`TSTG:POST:/TaskStageLinks/copy`) — самый короткий путь.
+- `relatedToAnyWorkType` задаётся только query-параметром при создании; сам
+  список видов работ передаётся отдельным запросом.
+- `WORK:PUT:/TaskTypeDistrict` заменяет список участков целиком — сначала
+  прочитай текущие через `WORK:GET:/TaskTypes/{id}/districts`.
+- `closeMinutes` — минуты, таймауты переходов в жизненном цикле — секунды.
+- Тип заявки (`WORK:GET:/TaskTypes`) и вид работ (`WORK:GET:/WorkTypes`) —
+  разные справочники: тип задаёт процесс, вид работ — что именно делается.
+- Удаление типа заявки затрагивает все заявки этого типа; в тенанте с данными
+  делай это только по явному подтверждению пользователя.

package/docs/guides/users.md

@@ -0,0 +1,71 @@
+---
+topic: users
+sources:
+  - page: admin/ExampleRequestsAPI.md
+    content_hash: ad3e2bf92fe6a736
+  - page: admin/Roles.md
+    content_hash: 3e67808b47102a51
+  - page: admin/ServiceUsers.md
+    content_hash: 4fb065f9e9d6c93b
+---
+
+# Пользователи
+
+Пользователь (User) — сотрудник (исполнитель, диспетчер, администратор) или
+заказчик в HubEx. Живёт в сервисе ADM. Уровень доступа пользователя задаётся
+ролью (`Role`), а не самим пользователем.
+
+## Создание пользователя: порядок вызовов
+
+1. `ADM:GET:/Roles` → `roleID` — какая роль будет назначена пользователю
+   («Заказчик», «Сервисный специалист», «Диспетчер» и т.п. — конкретные роли
+   заданы в тенанте, справочник не фиксирован).
+2. `ADM:POST:/Users` — создание пользователя. Тело — по схеме из
+   `hubex_describe_endpoint`.
+3. `ADM:POST:/UserRoles` — назначение роли пользователю. Отдельный запрос,
+   без него роль из шага 1 не применится.
+4. `ADM:POST:/UserDistricts` — назначение участков пользователю (какие
+   объекты/заявки будет видеть сотрудник).
+
+## Обязательные и ключевые поля тела
+
+Пример из вики для мобильного сотрудника-исполнителя:
+
+- `firstName`, `lastName` — имя и фамилия.
+- `sexID` — пол.
+- `email` — почта, используется как логин.
+- `isTechnician` — признак «сотрудник» (исполнитель), а не заказчик.
+- `mobilityID` — признак мобильности (мобильный/немобильный сотрудник).
+- `geotrackingModeID` — режим геотрекинга для мобильного приложения.
+
+Точный список обязательных полей и их типы — в схеме `ADM:POST:/Users` через
+`hubex_describe_endpoint`, поля выше — стабильно используемый набор из
+примеров интеграции.
+
+## Чтение, изменение, блокировка
+
+- Список: `ADM:GET:/Users`; облегчённый список: `ADM:GET:/Users/short`.
+- Роли пользователя: `ADM:GET:/Users/{userID}/skills` — навыки исполнителя
+  (используются правилами автоназначения по совпадению вида работ и навыка).
+- Изменение: `ADM:PUT:/Users/{id}` обновляет пользователя **целиком** —
+  нужно передавать все текущие поля плюс изменяемые, включая `oldEmail`, если
+  меняется `email`.
+- Блокировка — это тот же `PUT` с добавленными `banReasonID` и `banTill`
+  (датой, до которой пользователь заблокирован), отдельного endpoint для
+  блокировки нет.
+- Удаление: `ADM:DELETE:/Users` — помечает удалённым, физически не стирает.
+
+## Подводные камни
+
+- Создание пользователя (`ADM:POST:/Users`) не назначает ему роль и участки —
+  это отдельные запросы к `UserRoles` и `UserDistricts`. Без роли пользователь
+  ничего не увидит и не сможет ничего сделать в системе.
+- `isTechnician` отличает сотрудника-исполнителя от заказчика на уровне
+  профиля; тип доступа (что именно видно) при этом всё равно определяется
+  ролью, а не этим флагом.
+- Изменение через `PUT` требует передавать **все** поля пользователя, включая
+  `oldEmail` при смене почты — частичное тело затрёт остальные значения.
+- Служебные пользователи (API-интеграции, анонимный доступ по QR) настраиваются
+  отдельно от обычных сотрудников/заказчиков и имеют свою роль с максимальными
+  полномочиями — их не создают через `ADM:POST:/Users` в обычном порядке, а
+  подключают в консоли администратора.