@hubex/mcp 0.2.0

package/docs/guides/roles.md

@@ -0,0 +1,125 @@
+---
+topic: roles
+sources:
+  - page: adminapp/src/modules/RolesPage/saga.js
+    content_hash: dd2943597b30a21c
+  - page: adminapp/src/services/requests.js
+    content_hash: 54c3d95d85bb0ce0
+  - page: adminapp/src/locales/ru/app.json
+    content_hash: 22b22046c9336c1a
+---
+
+# Роли и полномочия
+
+Роль — набор прав, определяющий уровень доступа пользователя: какие разделы
+видны, какие действия доступны, какие приложения (веб, приложение инженера,
+приложение заказчика) можно открыть. Роль назначается пользователю отдельным
+запросом (`hubex_get_guide topic="users"`).
+
+Полномочия делятся на четыре независимых набора, и у каждого свой эндпоинт:
+
+| Набор | Справочник | Привязка к роли |
+| --- | --- | --- |
+| API-полномочия (доступ к методам) | `ADM:GET:/PermissionsApi` | `ADM:POST:/RolePermissionsApi` |
+| UI-полномочия (видимость элементов интерфейса) | `ADM:GET:/PermissionsUi` | `ADM:POST:/RolePermissionsUi` |
+| Расширенные полномочия | `ADM:GET:/PermissionsExt` | `ADM:POST:/RolePermissionsExt` |
+| Приложения | `COMMON:GET:/Applications` | `ADM:POST:/RoleApplications` |
+
+Полномочия сгруппированы тематическими блоками — теги:
+`ADM:GET:/PermissionApiTags`, `ADM:GET:/SystemPermissionUiTags`,
+`ADM:GET:/PermissionExtTags`.
+
+## 1. Создание роли
+
+Веб-клиент делает это в два шага: сначала роль, затем полномочия отдельными
+запросами по каждому набору.
+
+```text
+POST ADM:POST:/Roles                → [roleID]
+POST ADM:POST:/RolePermissionsApi   → API-полномочия
+POST ADM:POST:/RolePermissionsUi    → UI-полномочия
+POST ADM:POST:/RolePermissionsExt   → расширенные полномочия
+POST ADM:POST:/RoleApplications     → доступные приложения
+```
+
+Тело создания роли — массив: `[{ "name": "Диспетчер", "description": "..." }]`,
+ответ `201` — массив идентификаторов. Изменение названия и описания —
+`ADM:PUT:/Roles` (массив с `id`), удаление — `ADM:DELETE:/Roles/{id}`.
+
+Тела привязок — массивы объектов вида `{ roleID, permission...ID }`; точную
+схему бери через `hubex_describe_endpoint`, поля различаются между наборами.
+Снятие полномочия — соответствующий `ADM:DELETE:/RolePermissionsApi`,
+`ADM:DELETE:/RolePermissionsUi`, `ADM:DELETE:/RolePermissionsExt`,
+`ADM:DELETE:/RoleApplications` с тем же телом.
+
+## 2. Роль по шаблону и копирование
+
+- Копия роли целиком: `ADM:POST:/Roles/copy` с телом
+  `[{ "copiedRoleID": 4, "name": "Копия Диспетчер", "description": "..." }]` —
+  создаёт роль вместе со всеми полномочиями одним запросом.
+- Роль «по шаблону» в интерфейсе — это обычное создание: полномочия шаблонной
+  роли читаются через `ADM:GET:/Roles/{roleID}/permissionsApi`,
+  `ADM:GET:/Roles/{roleID}/permissionsUi`, `ADM:GET:/Roles/{roleID}/permissionsExt`,
+  `ADM:GET:/Roles/{roleID}/applications` и затем прописываются новой роли.
+  Все четыре GET принимают `isCheckedPermission=false`, чтобы вернуть полный
+  список с отметкой, что выбрано.
+
+## 3. Плагины (пакеты) роли
+
+- `ADM:GET:/Roles/{roleID}/packages` — список плагинов роли.
+- `ADM:PUT:/Roles/{roleID}/packages/activate` / `.../deactivate` — включение и
+  выключение.
+- Плагины тенанта в целом — `ADM:GET:/Tenants/this/packages`.
+
+## 4. Собственные UI-полномочия
+
+Кроме системных, в тенанте можно завести свои UI-полномочия и привязывать их к
+переходам жизненного цикла (`permissionUiID` у перехода) и к компонентам формы.
+
+```text
+GET    ADM:GET:/PermissionsUi
+POST   ADM:POST:/PermissionsUi
+PUT    ADM:PUT:/PermissionsUi
+DELETE ADM:DELETE:/PermissionsUi
+```
+
+## 5. Доступ роли к полям заявки
+
+Видимость полей формы заявки настраивается по паре «роль + стадия»:
+
+- `TSTG:GET:/TaskStageComponents/availability` с query `roleID`, `taskStageID`,
+  `taskTypeID` — что доступно сейчас (компоненты и дополнительные поля).
+- `TSTG:POST:/TaskStageComponents` — запись доступности:
+  `[{ "taskStageID": 12, "taskTypeID": 5, "components": [{ "id": 3, "roleID": 7, "capabilityID": 2 }], "attributes": [...] }]`.
+- Справочник уровней доступа (только чтение / чтение и запись / скрыто) —
+  `ADM:GET:/Capabilities`.
+- Доступ к дополнительным полям вне контекста стадии —
+  `ADM:GET:/RoleTaskPropertiesAccess/attributes`,
+  `ADM:POST:/RoleTaskPropertiesAccess/attributes`,
+  `ADM:PUT:/RoleTaskPropertiesAccess/attributes`.
+
+## Последовательность MCP-вызовов
+
+```text
+hubex_request_read(endpointId: `ADM:GET:/Roles`)
+hubex_request_write(endpointId: `ADM:POST:/Roles`, body: [{ name, description }])
+→ response[0] = roleID
+hubex_request_read(endpointId: `ADM:GET:/PermissionsUi`)
+hubex_request_write(endpointId: `ADM:POST:/RolePermissionsUi`, body: [{ roleID, ... }])
+hubex_request_read(endpointId: `ADM:GET:/Roles/{roleID}/permissionsUi`, pathParams: { roleID }, query: { isCheckedPermission: false })
+```
+
+## Подводные камни
+
+- Создание роли не даёт ей ни одного полномочия: без последующих
+  `RolePermissions*` пользователь с этой ролью не увидит ничего.
+- Четыре набора полномочий независимы. Выдать API-полномочие и забыть про
+  UI-полномочие — типичная причина «метод работает, но кнопки нет».
+- Для точной копии роли используй `ADM:POST:/Roles/copy`, а не ручной перенос:
+  ручной путь легко теряет расширенные полномочия и приложения.
+- GET-эндпоинты полномочий роли возвращают **все** полномочия с отметкой
+  выбранных при `isCheckedPermission=false`; без этого параметра список
+  сокращённый — не принимай его за полный справочник.
+- Роли и участки — разные измерения доступа: роль определяет, что можно
+  делать, участок (`ADM:POST:/UserDistricts`) — с какими объектами и типами
+  заявок.

package/docs/guides/sla.md

@@ -0,0 +1,130 @@
+---
+topic: sla
+sources:
+  - page: adminapp/src/modules/slaPage/slaCreateForms.js
+    content_hash: d4a1651f41ee8605
+  - page: adminapp/src/services/requests.js
+    content_hash: 54c3d95d85bb0ce0
+  - page: adminapp/src/locales/ru/app.json
+    content_hash: 22b22046c9336c1a
+---
+
+# SLA и графики работ
+
+Правило SLA (`DeadlineRule`) рассчитывает крайний срок закрытия заявки, когда
+он не задан явно в типе заявки (`closeMinutes`) или в виде работ. Правило
+состоит из двух частей:
+
+1. **Само правило** — сколько времени даётся на выполнение и по какому графику
+   работ это время считать.
+2. **Атрибуты правила** — условия, при которых правило применяется
+   (критичность, вид работ, тип заявки, компания, объект).
+
+```text
+POST SLA:POST:/DeadlineRules            → { id }
+POST SLA:POST:/DeadlineRules/attributes → условия применения
+```
+
+## 1. Правило
+
+```json
+[
+  {
+    "name": "Срочные заявки — 4 часа",
+    "scheduleRuleID": 2,
+    "runtime": 4,
+    "isActive": true
+  }
+]
+```
+
+- `runtime` — время выполнения в **часах**, дробное. Веб-клиент переводит
+  введённые минуты в часы: 90 минут → `1.5`.
+- `scheduleRuleID` — график работ (`WSP:GET:/ScheduleRules`), по которому
+  «тикают» часы: в нерабочее время срок не расходуется.
+- `isActive` — правило включено. Отдельные переключатели —
+  `SLA:PUT:/DeadlineRules/{DeadlineRuleID}/activate` и
+  `SLA:PUT:/DeadlineRules/{DeadlineRuleID}/deactivate`.
+
+Ответ POST — объект с `id` (а не массив идентификаторов, как у большинства
+других сущностей). Изменение — `SLA:PUT:/DeadlineRules` (массив с `id`),
+удаление — `SLA:DELETE:/DeadlineRules/{DeadlineRuleID}`, чтение —
+`SLA:GET:/DeadlineRules` и `SLA:GET:/DeadlineRules/{DeadlineRuleID}`.
+
+## 2. Условия применения
+
+Условие — это пара «атрибут SLA + значение». Справочник атрибутов —
+`SLA:GET:/Attributes`; ответ приходит словарём, ключ — идентификатор атрибута.
+В AdminApp используются атрибуты с идентификаторами 1–6, по смыслу:
+критичность, вид работ, тип заявки, компания, объект, объект-исключение.
+Сверяйся с названиями из `SLA:GET:/Attributes`, а не с номерами вслепую.
+
+```json
+[
+  {
+    "deadlineRuleID": 17,
+    "data": [
+      { "attributeID": 1, "attrNumbValue": 3 },
+      { "attributeID": 2, "attrNumbValue": 12 }
+    ]
+  }
+]
+```
+
+`attrNumbValue` — идентификатор значения из соответствующего справочника
+(`SLA:GET:/Criticalities`, `WORK:GET:/WorkTypes`, `WORK:GET:/TaskTypes`,
+`ES:GET:/Companies`, `ES:GET:/Assets`). Несколько компаний или объектов
+передаются несколькими элементами `data` с одним и тем же `attributeID`.
+
+Чтение условий правила — `SLA:GET:/DeadlineRules/{deadlineRuleID}/attributes`,
+удаление — `SLA:DELETE:/DeadlineRules/attributes` с телом того же вида.
+
+## 3. Графики работ
+
+График (`ScheduleRule`, сервис WSP) описывает рабочие смены: период действия,
+правила по cron, учёт праздников и переопределения отдельных дней.
+
+```text
+GET    WSP:GET:/ScheduleRules            список
+GET    WSP:GET:/ScheduleRules/{id}       один график
+GET    WSP:GET:/ScheduleRules/holiday    производственный календарь
+POST   WSP:POST:/ScheduleRules           создать
+POST   WSP:POST:/ScheduleRules/preview   рассчитать смены, ничего не сохраняя
+PUT    WSP:PUT:/ScheduleRules/{id}       изменить
+PUT    WSP:PUT:/ScheduleRules/extend/{id} продлить период действия
+DELETE WSP:DELETE:/ScheduleRules/{id}    удалить
+```
+
+Тело создания — **объект**, а не массив: `from`, `till`, `name`,
+`considerPublicHolidays`, `shortageHoursBeforeHoliday`, массив `rules`
+(`cron` + `occurrenceDuration` + периодичность) и `overridings` для
+исключений. Перед сохранением веб-клиент всегда прогоняет
+`WSP:POST:/ScheduleRules/preview` с тем же телом и показывает получившийся
+календарь — делай так же, прежде чем создавать график.
+
+## Последовательность MCP-вызовов
+
+```text
+hubex_request_read(endpointId: `WSP:GET:/ScheduleRules`)            → scheduleRuleID
+hubex_request_read(endpointId: `SLA:GET:/Attributes`)               → какие условия бывают
+hubex_request_write(endpointId: `SLA:POST:/DeadlineRules`, body: [{ name, scheduleRuleID, runtime, isActive: true }])
+→ response.id = deadlineRuleID
+hubex_request_write(endpointId: `SLA:POST:/DeadlineRules/attributes`, body: [{ deadlineRuleID, data: [{ attributeID, attrNumbValue }] }])
+hubex_request_read(endpointId: `SLA:GET:/DeadlineRules/{deadlineRuleID}/attributes`, pathParams: { deadlineRuleID })
+```
+
+## Подводные камни
+
+- `runtime` — часы (дробные), а не минуты: `closeMinutes` типа заявки задаётся
+  в минутах, легко перепутать.
+- Правило без условий применяется как общее — проверь, что это действительно
+  нужно, прежде чем создавать его в живом тенанте.
+- SLA считает срок только по своему графику работ: без корректного
+  `scheduleRuleID` дедлайны разъедутся с реальными сменами.
+- Приоритет расчёта дедлайна: явный срок типа заявки и вида работ (берётся
+  **меньший**), и только если оба не заданы — правила SLA.
+- Ответ `SLA:POST:/DeadlineRules` — объект `{ id }`; не пытайся читать его как
+  массив, в отличие от большинства POST-эндпоинтов HubEx.
+- Обрати внимание на регистр параметров пути в этом сервисе: у части
+  эндпоинтов он `DeadlineRuleID`, у части — `deadlineRuleID`; сверяйся с
+  `hubex_describe_endpoint`.

package/docs/guides/start.md

@@ -0,0 +1,67 @@
+---
+topic: start
+sources:
+  - page: admin/StartIntegrationAPI.md
+    content_hash: 696caf08f152c57a
+  - page: admin/RESTAPI.md
+    content_hash: 39aca4ceab766e3e
+---
+
+# Начало работы
+
+HubEx REST API организован по сервисам: у каждого сервиса свой базовый URL
+и своя OpenAPI-схема. Этот MCP-сервер работает поверх этих сервисов и
+предоставляет собственный набор инструментов.
+
+## Базовые сведения о протоколе
+
+- Базовый URL сервиса: `https://{env}-api.hubex.ru/fsm/{SERVICE}`, где
+  `env` — окружение (`dev`, `stg`); на проде префикса нет — `https://api.hubex.ru/fsm/{SERVICE}`. `SERVICE` — код сервиса
+  (`WORK`, `ES`, `ADM`, `AUTHZ`, `AUTHN`, `PA`, `SLA` и т.д.).
+- Каждый запрос требует **два** заголовка: `Authorization: Bearer <access_token>`
+  и `X-Application-ID: <id приложения>`. Без второго заголовка сервер вернёт
+  ошибку 403 «Не найден обязательный заголовок [X-Application-ID]».
+- Access-токен — JWT, действует ограниченное время (в вики указано 30 минут)
+  и получается отдельным запросом по сервисному токену; для этого сервера
+  обновление токена уже реализовано отдельным механизмом авторизации — вручную
+  вызывать `AUTHZ:POST:/AccessTokens` не нужно.
+- HTTP-методы соответствуют обычной семантике REST: `GET` — чтение
+  (идемпотентно, не меняет данные), `POST` — создание/действие (не
+  идемпотентно), `PUT` — полная замена записи (идемпотентно, требует
+  **все** поля), `PATCH` — частичное обновление (идемпотентно, только
+  изменяемые поля), `DELETE` — удаление (идемпотентно, обычно помечает
+  запись удалённой, а не стирает физически).
+- Ответы на GET-запросы коллекций приходят **словарём**, а не массивом:
+  `{ "5136": { ...поля }, "5135": { ...поля } }`, где ключ — id записи.
+  Ошибки возвращаются массивом объектов `{ traceIdentifier, code, message }`.
+- Для каждого запроса списка всегда передавай оба query-параметра пагинации:
+  `fetch` (сколько записей) и `offset` (смещение). Один только `fetch`
+  недостаточен — без `offset` запрос может не отработать.
+
+## Порядок работы с этим сервером
+
+1. `hubex_list_scopes` — узнать, какие сервисы и предметные области доступны.
+2. `hubex_search_*_endpoints` (например поиск по сервису или ключевому
+   слову) — найти нужный эндпоинт, не читая весь swagger вручную.
+3. `hubex_describe_endpoint` — получить полную JSON Schema тела и параметров
+   найденного эндпоинта, уже с аннотациями бизнес-полей (описание,
+   обязательность, справочник-подсказка, если поле есть в оверлее).
+4. `hubex_request_*` — выполнить сам HTTP-запрос к HubEx с телом, собранным
+   по схеме из шага 3.
+
+Перед первой работой с конкретной предметной областью (заявки, объекты,
+компании, пользователи) стоит сначала прочитать соответствующий гайд
+(`hubex_get_guide`) — там короткий порядок вызовов, обязательные поля и
+типичные ошибки, собранные из бизнес-документации HubEx.
+
+## Подводные камни
+
+- Забытый `X-Application-ID` — самая частая причина 403 при первом запросе:
+  одного `Authorization: Bearer` недостаточно.
+- Коллекции — словари по id, а не массивы: код, который ожидает `Array`,
+  сломается на `Object.keys()`/итерации по ключам.
+- В запросах списков указывай и `fetch`, и `offset`, даже если нужна первая
+  страница: например, `fetch=100&offset=0`.
+- `PUT` требует полное тело записи (все поля, включая неизменяемые в этом
+  запросе), а не только то, что меняется — для частичного обновления
+  используй `PATCH`, если эндпоинт его поддерживает.

package/docs/guides/taskchecklists.md

@@ -0,0 +1,149 @@
+---
+topic: taskchecklists
+sources:
+  - page: admin/ExampleRequestsAPI.md
+    content_hash: ad3e2bf92fe6a736
+  - page: admin/TicketLifeCycle.md
+    content_hash: 60be5a94c8573779
+---
+
+# Редактирование чек-листов в заявке
+
+Этот гайд описывает заполнение и изменение уже прикреплённых чек-листов на
+вкладке «Чек-листы» в карточке созданной заявки. Он не изменяет шаблон
+чек-листа, его пункты или привязки к объектам и видам работ.
+
+Шаблон чек-листа и его экземпляр в заявке — разные сущности: не смешивай их
+идентификаторы.
+
+| Идентификатор | Что обозначает | Где используется |
+| --- | --- | --- |
+| `checkListID` | шаблон чек-листа | добавить шаблон в заявку |
+| `taskCheckListID` | экземпляр шаблона в конкретной заявке | читать и записывать ответы, удалить из заявки |
+| `id` результата | пункт (результат) внутри экземпляра | поле `id` в теле сохранения |
+
+MainApp не сохраняет ответ при каждом нажатии. Оно держит все ответы в
+`redux-form` формы заявки и отправляет на сервер только при сохранении заявки.
+Порядок для агента безопаснее сделать явным: записать результаты, дождаться
+успеха, затем отдельно перевести заявку на следующую стадию.
+
+## 1. Прочитай чек-листы и их пункты
+
+1. `WORK:GET:/Tasks/{taskID}/checkLists` — экземпляры чек-листов в заявке.
+   Ответ — словарь, где ключ — `taskCheckListID`. Значения содержат шаблон в
+   `checkList`, а также `totalItemsCount` и `completedItemsCount`.
+2. Для каждого ключа вызови
+   `WORK:GET:/Tasks/{taskID}/checkLists/{taskCheckListID}/results/v2`.
+   Это актуальная версия API; старый путь без `/v2` помечен в swagger как
+   устаревший. Ответ тоже словарь, а его ключ — `id` пункта, который нужен при
+   сохранении.
+
+В MainApp загрузка устроена именно так: сначала список экземпляров, затем
+результаты каждого экземпляра. Пункты сортируются по `sortOrder`, а прогресс
+в шапке — `completedItemsCount / totalItemsCount` из первого ответа.
+
+Для работы нужны права `TaskCheckListsList` и `TaskCheckListResultsList`.
+
+## 2. Измени пункт
+
+Каждый пункт отображается как флажок выполнения `isChecked` и, если у него
+есть атрибут кроме `Switch`, как поле значения. Поле выбирается из
+`attributeType.code`:
+
+| Тип | Представление в MainApp | Значение для API v2 |
+| --- | --- | --- |
+| `Switch` | только флажок | `values: []`, состояние в `isChecked` |
+| `String`, `Int`, `Decimal`, `Text` | строка, число или многострочный текст | массив из одной строки |
+| `Date`, `Datetime` | дата или дата-время | массив из одной ISO-строки |
+| `Select` | один вариант | массив с одним id варианта |
+| `MultiSelect` | несколько вариантов | массив id вариантов |
+| `Attachment`, `Drawing` | список файлов | массив id вложений |
+| атрибут с `domain` | справочник домена | один или несколько id из справочника |
+
+Когда пользователь вводит непустое значение, интерфейс отмечает пункт как
+выполненный; очистка значения снимает флажок. Флажок можно переключить и
+отдельно. В API передавай оба поля явно:
+
+```json
+// WORK:PUT:/Tasks/{taskID}/checkLists/{taskCheckListID}/results/v2
+[
+  {
+    "id": 9151,
+    "isChecked": true,
+    "values": ["12.5"]
+  },
+  {
+    "id": 9152,
+    "isChecked": true,
+    "values": ["2026-08-13T12:00:00"]
+  },
+  {
+    "id": 9153,
+    "isChecked": true,
+    "values": []
+  }
+]
+```
+
+Тело — массив изменённых пунктов. MainApp сравнивает форму с последним
+ответом API и не отправляет неизменённые строки. `values`, а не `value`, —
+контракт v2. Не используй устаревший `results`, где было строковое поле
+`value`.
+
+Перед записью проверь точную схему через
+`hubex_describe_endpoint` для
+`WORK:PUT:/Tasks/{taskID}/checkLists/{taskCheckListID}/results/v2`: swagger
+требует только `id`, но для фактического изменения передавай и `isChecked`, и
+`values`.
+
+## 3. Вложения и рисунки
+
+Новый файл MainApp сначала загружает отдельно, а потом сохраняет возвращённые
+идентификаторы вместе с результатом пункта.
+
+1. `WORK:POST:/Tasks/{taskID}/checkLists/{taskCheckListID}/upload/fromForm` —
+   `multipart/form-data`: `TaskCheckListResultID`, а каждый файл —
+   `Attachments.Index`, `Attachments[N].File`,
+   `Attachments[N].IsIgnorePossibleDuplication=true`.
+2. Возьми идентификаторы из `attachments` ответа и передай их строками в
+   `values` через `WORK:PUT:/Tasks/{taskID}/checkLists/{taskCheckListID}/results/v2`.
+
+Для чтения метаданных вложений есть
+`WORK:GET:/Tasks/{taskID}/checkLists/{taskCheckListID}/results/attachments`.
+Для загрузки нужно полномочие `TaskCheckListResultAttachmentUpload`, для
+сохранения — `TaskCheckListResultSet`.
+
+## 4. Сохранение и переход стадии
+
+В MainApp цепочка редактирования такая:
+
+```text
+редактирование полей заявки
+        ↓
+PATCH заявки
+        ↓
+PUT результатов чек-листов v2 (только изменённые пункты)
+        ↓
+запись выполненных работ и дополнительных полей
+        ↓
+переход на новую стадию
+```
+
+Поэтому не меняй стадию параллельно с чек-листом. Если у целевой стадии
+требование `CheckListsCompleted`, сервер не пропустит переход, пока не будут
+заполнены все необходимые пункты. Требования стадии читай через
+`TSTG:GET:/TaskStages/{id}/requirements`; затем выполняй переход способом из
+гайда `hubex_get_guide topic="taskedit"`.
+
+## Подводные камни
+
+- Списки и результаты приходят словарями по id, не массивами. Сохраняй ключи:
+  UI нормализует их только для отображения.
+- `Switch` не хранит булево значение в `values`: единственный источник его
+  состояния — `isChecked`.
+- Пустой `values` означает отсутствие значения. При очистке уже заполненного
+  пункта передай `isChecked: false` и `values: []`.
+- Для `Attachment`/`Drawing` не посылай объекты файлов, URL или локальные
+  имена. Сервер ожидает только id уже загруженных вложений.
+- MainApp перезагружает результаты после записи. Делай то же, если нужно
+  вернуть пользователю новый прогресс или удостовериться в сохранении.