@hubex/mcp 0.2.0

package/docs/guides/dictionaries.md

@@ -0,0 +1,64 @@
+---
+topic: dictionaries
+sources:
+  - page: admin/TicketType.md
+    content_hash: 4166476a7071aae8
+  - page: admin/WorkType.md
+    content_hash: d1fdeca14cd5b5e7
+  - page: admin/StatusType.md
+    content_hash: f9d4863b91cc64bf
+  - page: admin/ObjectsType.md
+    content_hash: 631a7aec138691e5
+---
+
+# Справочники
+
+Почти каждое поле-идентификатор в теле запроса (`...ID`) — это ссылка на
+запись из справочника. Значения справочников настраиваются в консоли
+администратора и различаются между тенантами: не подставляй значения из
+примеров вслепую, всегда сверяйся со списком через API.
+
+## Где брать идентификаторы: порядок вызовов
+
+- **Тип заявки** — `WORK:GET:/TaskTypes`. Определяет допустимые стадии
+  жизненного цикла, срок закрытия по умолчанию и разрешённые виды работ.
+  Обязателен при создании заявки.
+- **Способ подачи заявки** — `WORK:GET:/RequestMethods`. Обязателен при
+  создании заявки; для интеграций используется значение 4.
+- **Статус заявки** — `WORK:GET:/TaskStatuses`. Визуальное отображение
+  стадии для мобильного приложения заказчика, привязывается к стадии в
+  жизненном цикле — не назначается заявке напрямую произвольным значением.
+- **Вид работ** — `WORK:GET:/WorkTypes`. Что за работа выполняется по
+  заявке/объекту/сотруднику.
+- **Тип объекта** — `ES:GET:/AssetTypes`. Функциональное назначение
+  оборудования, определяет обязательность адреса.
+- **Класс объекта** — `ES:GET:/AssetClasses`. Произвольная группировка
+  объектов (по стоимости, производителю и т.п.), не связана с типом.
+- **Навыки исполнителей** — `PA:GET:/Skills`. Используются в правилах
+  автоназначения: система подбирает исполнителя по совпадению вида работ и
+  навыка в его карточке.
+
+## Обязательные поля
+
+У справочных `GET`-эндпоинтов тела запроса нет — все перечисленные вызовы
+принимают только query-параметры (пагинация, фильтры удалённых записей и
+т.п.), значения из ответа подставляются в `...ID`-поля других сущностей.
+
+## Подводные камни
+
+- Тип заявки (`WORK:GET:/TaskTypes`) и вид работ (`WORK:GET:/WorkTypes`) —
+  разные справочники с разной ролью: тип заявки задаёт жизненный цикл и
+  список **допустимых** видов работ, а конкретный вид работ выбирается из
+  этого списка отдельно на самой заявке.
+- Тип объекта (`ES:GET:/AssetTypes`) и класс объекта (`ES:GET:/AssetClasses`)
+  — тоже разные вещи: тип влияет на бизнес-логику (обязательность адреса,
+  автоподстановка видов работ), класс — это ярлык для группировки и
+  фильтрации, бизнес-логики не несёт.
+- Статус заявки (`WORK:GET:/TaskStatuses`) нельзя менять напрямую как
+  независимое поле: он выводится из перехода по стадии в жизненном цикле,
+  настроенном для типа заявки. Смена стадии, не разрешённая жизненным
+  циклом, отклоняется сервером.
+- Значения справочников (какие типы, виды работ, статусы заведены)
+  специфичны для тенанта — перед подстановкой ID в тело запроса всегда
+  сверяйся с актуальным списком через соответствующий `GET`, а не полагайся
+  на значения из документации или прошлых сессий.

package/docs/guides/lifecycle.md

@@ -0,0 +1,263 @@
+---
+topic: lifecycle
+sources:
+  - page: adminapp/src/modules/TaskLifecycle/saga.js
+    content_hash: 7fc865697a504027
+  - page: adminapp/src/modules/TaskStageModal/saga.js
+    content_hash: b24ac8fc352a0f0b
+  - page: adminapp/src/modules/TaskStages/saga.js
+    content_hash: 1d5ecfdf47139340
+  - page: adminapp/src/modules/TaskStatuses/saga.js
+    content_hash: cb2284b9dcdbbbc3
+  - page: adminapp/src/modules/TaskStageLinkModal/components/TaskStageLinkForm/TaskStageLinkForm.js
+    content_hash: bc5ed6671756f00d
+---
+
+# Жизненный цикл заявки
+
+Жизненный цикл — это набор **стадий** и **переходов** между ними, настроенный
+для конкретного **типа заявки**. Стадия (`TaskStage`) — состояние заявки,
+требующее действий пользователя или системы. Переход (`TaskStageLink`) —
+разрешённое движение из одной стадии в другую: именно он превращается в кнопку
+в мобильном приложении.
+
+Три сущности живут в разных сервисах, и их легко перепутать:
+
+| Сущность | Где | Область | Комментарий |
+| --- | --- | --- | --- |
+| Стадия | `TSTG:GET:/TaskStages` | общая для тенанта | справочник, не привязан к типу заявки |
+| Переход | `TSTG:GET:/TaskStageLinks` | **на тип заявки** | ключ — тройка `taskTypeID + fromTaskStageID + toTaskStageID` |
+| Маршрут | `WORK:GET:/TaskTypes/{taskTypeID}/route` | **на тип заявки** | стартовая стадия, стартовый статус, финальная стадия |
+| Статус | `WORK:GET:/TaskStatuses` | общая для тенанта | витрина стадии для приложения заказчика |
+
+Порядок настройки в консоли администратора: сначала тип заявки
+(`hubex_get_guide topic="tasktypes"`) и стадии, затем маршрут, затем переходы.
+
+## 1. Стадии заявки
+
+Список стадий тенанта: `TSTG:GET:/TaskStages`; одна стадия целиком (с
+требованиями и правилом автоназначения) — `TSTG:GET:/TaskStages/{id}`.
+
+Создание — `TSTG:POST:/TaskStages`, тело **массив**, ответ `201` — массив
+идентификаторов:
+
+```json
+[
+  {
+    "name": "Назначена",
+    "description": null,
+    "color": "#464855",
+    "taskViewTemplateID": 1,
+    "actionID": 3,
+    "assigneeSelectionRuleID": null,
+    "assignToRoleID": null,
+    "assignToUserID": null,
+    "isShowTechnicianOnMap": false
+  }
+]
+```
+
+- `color` — до 7 символов (`#RRGGBB`), обязателен: цветом выводится название
+  стадии в списке заявок.
+- `taskViewTemplateID` — веб-клиент всегда шлёт `1` (шаблон по умолчанию);
+  список шаблонов — `UI:GET:/TaskViewTemplate`.
+- `actionID` — действие, которое система выполняет при входе на стадию
+  (закрыть заявку, назначить ближайшего исполнителя и т.п.). Справочник —
+  `TSTG:GET:/Action`. Необязателен.
+- `assigneeSelectionRuleID` — правило автоподбора исполнителя
+  (`TSTG:GET:/AssigneeSelectionRules`). Указывается у той стадии, **на входе
+  в которую** исполнитель должен быть подобран; сам автоподбор запускается
+  автопереходом (см. раздел 4).
+- `assignToRoleID` / `assignToUserID` — жёсткое назначение на роль или
+  пользователя вместо правила.
+
+После создания стадии веб-клиент выполняет ещё два запроса — повтори их,
+иначе стадия будет создана «полупустой»:
+
+1. `TSTG:POST:/TaskStageRequirements` — требования (условия), без которых
+   переход на стадию невозможен: `[{ "taskStageID": 12, "data": [{ "id": 1 }] }]`.
+   Справочник условий — `TSTG:GET:/Requirements/requirements` («назначен
+   исполнитель», «обработаны чек-листы»). Тот же запрос с пустым `data`
+   снимает все требования.
+2. `TSTG:POST:/TaskStageComponents/templates` — наполнение стадии полями формы
+   из шаблона: `[{ "taskStageID": 12, "taskViewTemplateID": 1, "taskTypeID": 5 }]`.
+   Без него на форме заявки на этой стадии не будет полей. AdminApp шлёт только
+   `TaskStageID` и `TaskViewTemplateID`, но в схеме `taskTypeID` обязателен —
+   передавай все три.
+
+Изменение — `TSTG:PUT:/TaskStages` (массив объектов **с `id`**, полное тело),
+удаление — `TSTG:DELETE:/TaskStages` (тело — список id) или
+`TSTG:DELETE:/TaskStages/{id}`.
+
+## 2. Статусы заявки
+
+Статус — визуальное отображение стадии для мобильного приложения заказчика:
+несколько внутренних стадий согласования можно показать заказчику одним
+статусом «В работе». Статус не назначается заявке напрямую — он применяется
+переходом (`applyTaskStatusID`).
+
+- `WORK:GET:/TaskStatuses` — список.
+- `WORK:POST:/TaskStatuses` — тело массив `[{ "name": "В работе", "color": "#2C7BE5", "sortOrder": 3 }]`.
+- `WORK:PUT:/TaskStatuses` — то же тело с `id`; `sortOrder` меняется тем же PUT.
+- `WORK:DELETE:/TaskStatuses/{id}` — удаление.
+
+## 3. Маршрут типа заявки
+
+Маршрут задаёт точку входа и точку выхода жизненного цикла. Без него заявки
+этого типа не создаются.
+
+```text
+GET  WORK:GET:/TaskTypes/{taskTypeID}/route   → { startTaskStage, startTaskStatus, finishTaskStage }
+POST WORK:POST:/TaskTypeRoutes                 → создать, если маршрута ещё нет
+PUT  WORK:PUT:/TaskTypeRoutes                  → изменить существующий
+```
+
+Тело POST/PUT — массив:
+
+```json
+[
+  {
+    "taskTypeID": 5,
+    "startTaskStageID": 10,
+    "startTaskStatusID": 1,
+    "finishTaskStageID": 18
+  }
+]
+```
+
+Выбор между POST и PUT делай по результату GET: если `startTaskStage`,
+`startTaskStatus` и `finishTaskStage` пустые — POST, иначе PUT (так же
+поступает веб-клиент). Удаление — `WORK:DELETE:/TaskTypeRoutes`, тело —
+массив идентификаторов **типов заявок**, а не маршрутов.
+
+## 4. Переходы между стадиями
+
+Переход уникален тройкой `taskTypeID + fromTaskStageID + toTaskStageID`;
+собственного `id` у него нет — все операции адресуют его этой тройкой.
+
+Чтение: `TSTG:GET:/TaskStageLinks` с query `taskTypeID` и `taskStageFromID`
+(исходящие переходы стадии) либо `taskStageToID` (входящие).
+
+Создание — `TSTG:POST:/TaskStageLinks`, изменение — `TSTG:PUT:/TaskStageLinks`,
+тело массив:
+
+```json
+[
+  {
+    "taskTypeID": 5,
+    "fromTaskStageID": 10,
+    "toTaskStageID": 12,
+    "name": "Назначить",
+    "description": null,
+    "branchID": 1,
+    "isPositiveResult": true,
+    "applyTaskStatusID": 2,
+    "timeoutSeconds": 120,
+    "timeoutToDeadlineSeconds": null,
+    "roles": [3, 7],
+    "sortOrder": 0
+  }
+]
+```
+
+Что означают поля:
+
+- `name` — **название кнопки** перехода в мобильном приложении. Обязателен по
+  форме веб-клиента (в схеме помечен необязательным).
+- `branchID` — ветка жизненного цикла, обязателен. Справочник —
+  `TSTG:GET:/Branches`: основная ветка (движение по основным стадиям), ветка
+  согласования (в мобильном приложении такие заявки попадают на отдельную
+  вкладку «Согласование»), ветка действий заказчика.
+- `applyTaskStatusID` — статус, который заявка получит при переходе.
+  Передавай только если статус действительно нужно менять.
+- `timeoutSeconds` — автоматический переход через указанное число **секунд**.
+  Это механизм автоподбора исполнителя: правило висит на целевой стадии, а
+  запускает его таймаут перехода.
+- `timeoutToDeadlineSeconds` — автопереход за указанное время **до дедлайна**
+  заявки (например, вернуть заявку руководителю, если исполнитель так и не
+  назначен).
+- `roles` — если задан, переход доступен только пользователям с этими ролями
+  (`ADM:GET:/Roles`). Пустой список = переход доступен всем.
+- `sortOrder` — порядок кнопок; массовая перестановка — отдельным запросом
+  `TSTG:POST:/TaskStageLinks/reorder` с телом
+  `[{ taskTypeID, fromTaskStageID, toTaskStageID, sortOrder }]`.
+
+Удаление — `TSTG:DELETE:/TaskStageLinks`, тело
+`[{ "taskTypeID": 5, "fromTaskStageID": 10, "toTaskStageID": 12 }]`.
+
+## 5. Переопределения перехода для ролей
+
+Одному и тому же переходу можно задать разное название кнопки для разных
+ролей: для всех — «Назначить», для сервисного специалиста — «Принять заявку».
+
+```text
+GET    TSTG:GET:/TaskStageLinks/overridings    query: taskTypeID, taskStageFromID, taskStageToID
+POST   TSTG:POST:/TaskStageLinks/overridings   создать для ролей, которых ещё нет
+PUT    TSTG:PUT:/TaskStageLinks/overridings    изменить существующие
+DELETE TSTG:DELETE:/TaskStageLinks/overridings снять переопределение с ролей
+```
+
+Тело POST/PUT — массив, **по одному объекту на роль** (веб-клиент кладёт в
+`roles` ровно один id):
+
+```json
+[
+  {
+    "taskTypeID": 5,
+    "fromTaskStageID": 10,
+    "toTaskStageID": 12,
+    "roles": [7],
+    "name": "Принять заявку",
+    "description": null,
+    "isPositiveResult": true
+  }
+]
+```
+
+Тело DELETE — `[{ taskTypeID, fromTaskStageID, toTaskStageID, roles: [7, 9] }]`.
+Порядок как в веб-клиенте: сначала сохранить сам переход, затем POST для новых
+ролей, PUT для изменившихся, DELETE для убранных.
+
+## 6. Копирование жизненного цикла
+
+`TSTG:POST:/TaskStageLinks/copy` с телом
+`[{ "sourceTaskTypeID": 5, "targetTaskTypeID": 9 }]` переносит все переходы из
+одного типа заявки в другой. Именно так работает создание типа заявки «по
+шаблону». Стадии при этом не дублируются — они общие для тенанта.
+Отдельная копия стадии — `TSTG:POST:/TaskStages/copy` с
+`[{ "sourceID": 12, "name": "Копия стадии" }]`.
+
+## Последовательность MCP-вызовов
+
+```text
+hubex_request_read(endpointId: `WORK:GET:/TaskTypes`)                         → taskTypeID
+hubex_request_read(endpointId: `TSTG:GET:/TaskStages`)                        → стадии тенанта
+hubex_request_write(endpointId: `TSTG:POST:/TaskStages`, body: [{...}])       → taskStageID
+hubex_request_write(endpointId: `TSTG:POST:/TaskStageRequirements`, body: [{ taskStageID, data }])
+hubex_request_write(endpointId: `TSTG:POST:/TaskStageComponents/templates`, body: [{ taskStageID, taskTypeID, taskViewTemplateID: 1 }])
+hubex_request_read(endpointId: `WORK:GET:/TaskTypes/{taskTypeID}/route`, pathParams: { taskTypeID })
+hubex_request_write(endpointId: `WORK:POST:/TaskTypeRoutes`, body: [{ taskTypeID, startTaskStageID, startTaskStatusID, finishTaskStageID }])
+hubex_request_read(endpointId: `TSTG:GET:/Branches`)                          → branchID
+hubex_request_write(endpointId: `TSTG:POST:/TaskStageLinks`, body: [{ taskTypeID, fromTaskStageID, toTaskStageID, name, branchID }])
+hubex_request_read(endpointId: `TSTG:GET:/TaskStageLinks`, query: { taskTypeID, taskStageFromID })
+```
+
+## Подводные камни
+
+- Стадии общие для тенанта, переходы — нет. Удаление стадии рвёт переходы во
+  **всех** типах заявок: перед удалением проверь
+  `TSTG:GET:/TaskStageLinks` с `taskStageFromID` и с `taskStageToID` (так
+  делает веб-клиент перед показом предупреждения).
+- У перехода нет `id`. Повторный POST с той же тройкой — это не «второй
+  переход», а конфликт; для изменения используй PUT.
+- Не путай `applyTaskStatusID` (статус, который ставит переход) с
+  `startTaskStatusID` (статус стартовой стадии в маршруте).
+- Таймауты задаются в **секундах**, а срок закрытия типа заявки
+  (`closeMinutes`) — в минутах.
+- Создание стадии без `TSTG:POST:/TaskStageComponents/templates` даёт стадию
+  без полей на форме заявки — визуально «пустую» карточку.
+- Тело всех write-эндпоинтов раздела — массив, кроме `TSTG:POST:/TaskStages/{id}/assign`.
+  Обёртка `{ "data": [...] }` вместо массива приводит к ошибке «Параметр [data]
+  не может быть пустым».
+- DELETE-эндпоинты жизненного цикла требуют тело; `hubex_request_delete`
+  принимает `body` — передавай его так же, как в write-запросах.

package/docs/guides/materials.md

@@ -0,0 +1,135 @@
+---
+topic: materials
+sources:
+  - page: swagger/WH.json
+    content_hash: cff1fe0ebc8a8740
+---
+
+# Материалы
+
+Материал (Material) — номенклатурная позиция склада: то, что списывается в
+заявке как израсходованное. Живёт в сервисе `WH`. Валюта у материала своя
+(поля `costCurrencyID` и `purchaseCostCurrencyID`) и **не подставляется
+сервером по умолчанию** — это главный подводный камень при создании через API.
+
+## Создание материала: порядок вызовов
+
+1. **Валюта тенанта** — `ADM:GET:/TenantSettings`, поле `defaultCurrency.id`.
+   Именно так делает веб-приложение: валюта у материала не выбирается в форме,
+   а берётся из настроек тенанта и подставляется молча. Полный список валют —
+   `COMMON:GET:/Currencies` (словарь по id: `1` — рубль, `2` — доллар,
+   `3` — евро и т.д.), но для материала бери значение из настроек тенанта, а не
+   угадывай.
+2. **Единица измерения** — `COMMON:GET:/MeasurementUnits`. Берём `id` нужной
+   единицы, кладём в `measurementUnitID`. Значение по умолчанию в вебе —
+   `796` («Штука»).
+3. **Создание** — `WH:POST:/Materials`. Тело — **массив** объектов, за один
+   вызов можно создать несколько материалов. `costCurrencyID` и
+   `purchaseCostCurrencyID` заполняем **одним и тем же** id валюты тенанта.
+4. **Проверка** — `WH:GET:/Materials/{id}` или `WH:GET:/Materials/v2`.
+   В ответе должны быть не только `costCurrencyID`, но и раскрытые объекты
+   `costCurrency` / `purchaseCostCurrency` — если их нет, валюта не проставлена.
+
+Изменение — `WH:PUT:/Materials`, тело того же вида, но с `id` у каждого
+элемента. `PUT` заменяет запись целиком: перечисляй все поля, а не только
+изменяемые. Веб при редактировании снова подставляет валюту из настроек
+тенанта — то есть правка материала «чинит» пустую валюту сама собой.
+
+## Обязательные поля
+
+| Поле                     | Обязательность | Комментарий                                                                                        |
+| ------------------------ | -------------- | -------------------------------------------------------------------------------------------------- |
+| `name`                   | да             | до 128 символов, единственное `required` в swagger; в вебе — обязательное поле                     |
+| `measurementUnitID`      | **фактически** | в вебе форма не сохраняется без единицы измерения                                                  |
+| `cost`                   | нет            | цена продажи; если заполнена — попадает в Акт выполненных работ. До 13 цифр, 2 знака после запятой |
+| `costCurrencyID`         | **фактически** | валюта цены продажи = `defaultCurrency.id` тенанта                                                 |
+| `purchaseCost`           | нет            | закупочная цена; веб её не отправляет вообще                                                       |
+| `purchaseCostCurrencyID` | **фактически** | валюта закупочной цены; веб пишет туда **ту же** валюту тенанта                                    |
+| `isMarkable`             | нет            | материал подлежит маркировке (Data Matrix, «Честный ЗНАК»)                                         |
+| `vendorCode`             | нет            | артикул, до 32 символов                                                                            |
+| `erpID`                  | нет            | идентификатор во внешней системе (например, в 1С), до 64 символов                                  |
+| `description`            | нет            | до 2048 символов                                                                                   |
+
+Слово «фактически» означает: swagger помечает поле как `nullable` и запрос без
+него пройдёт с кодом 200, но данные получатся неполными — сервер не валидирует
+то, что валидирует форма в вебе.
+
+## Про валюту: почему без неё материал работает некорректно
+
+`costCurrencyID` и `purchaseCostCurrencyID` объявлены в swagger как
+`nullable`, поэтому сервер принимает материал вообще без валюты и не
+возвращает никакой ошибки. Дальше такой материал ведёт себя как сломанный:
+
+- В ответах `WH:GET:/Materials/v2` и `WH:GET:/Materials/{id}` у него нет ни `costCurrencyID`, ни вложенных
+  объектов `costCurrency` / `purchaseCostCurrency` — только голая `cost`.
+  Клиенты (веб и мобильные приложения), которые читают символ валюты из
+  `costCurrency.asciiCode`, показывают цену без валюты или падают на
+  обращении к полю отсутствующего объекта.
+- Стоимость израсходованных материалов в заявке считается по позициям с
+  разными (или отсутствующими) валютами и не сводится в корректную сумму.
+- Дефолт «рубль» не подставляется ни на уровне тенанта, ни на уровне склада:
+  пустая валюта остаётся пустой, пока материал не отредактируют явно.
+
+**Правило: всегда передавай `costCurrencyID` и `purchaseCostCurrencyID` при
+создании материала**, даже если `cost` равен нулю и закупочной цены нет. Оба
+поля заполняются одним значением — `defaultCurrency.id` из
+`ADM:GET:/TenantSettings`; ровно это делают саги веб-приложения
+`materialCreationForm` и `materialEditForm`. Для рублёвого тенанта это `1`, но
+не хардкодь: у другого тенанта валюта по умолчанию другая, и материал с чужой
+валютой сломает подсчёт стоимости так же, как материал без валюты.
+
+Починка уже созданных материалов — тем же `WH:PUT:/Materials`: читаем текущие
+поля через `WH:GET:/Materials/v2`, добавляем `costCurrencyID` /
+`purchaseCostCurrencyID` и отправляем полный объект обратно.
+
+## Пример тела
+
+`WH:POST:/Materials` (создание) — массив, без `id`:
+
+```json
+[
+  {
+    "name": "Лампа светодиодная",
+    "vendorCode": "LED-9W",
+    "description": "",
+    "measurementUnitID": 796,
+    "cost": 50,
+    "costCurrencyID": 1,
+    "purchaseCost": 35,
+    "purchaseCostCurrencyID": 1,
+    "isMarkable": false
+  }
+]
+```
+
+`WH:PUT:/Materials` (изменение) — то же самое плюс `id` у каждого элемента.
+
+## Подводные камни
+
+- **Тело — массив, а не объект.** И `POST`, и `PUT` принимают массив
+  материалов. Если передать объект или обёртку `{ "data": [...] }`, HubEx
+  ответит `409 ParameterNull: Параметр [data] не может быть пустым` — сервер
+  не смог связать тело с параметром-массивом.
+- **Успешный `PUT` возвращает пустое тело.** Ответ без содержимого — это
+  норма для изменения материалов; результат проверяй отдельным `GET`.
+- `WH:GET:/Materials/v2` и остальные коллекции отдают **словарь по id**, а не
+  массив.
+- Валюта цены продажи и валюта закупки — два независимых поля. Проставив
+  только `costCurrencyID`, получишь материал с наполовину заполненной
+  валютой: `purchaseCostCurrency` в ответе так и не появится.
+- `measurementUnitID` берётся из общего справочника `COMMON`, а не из `WH`:
+  единицы измерения не заводятся на складе.
+- `isMarkable: true` включает работу с кодами маркировки: при списании такого
+  материала в выполненных работах у инженера в мобильном приложении появляется
+  сканирование кода Data Matrix. Не ставь признак «на всякий случай» тестовым
+  материалам — сценарий списания станет другим.
+- Материал — это только номенклатура. Остатки считаются отдельно: тот же
+  `WH:GET:/Materials` с фильтром `warehouseID` отдаёт материалы конкретного
+  склада, а попадают они туда приходными документами (`WH:GET:/Receipts`).
+  Созданный материал сам по себе ни на одном складе не лежит — чтобы списать
+  его в заявке, нужен приход.
+- Удаление материала — мягкое: есть `WH:PUT:/Materials/restore` и
+  `WH:PUT:/Materials/{id}/restore` для восстановления, а список умеет отдавать
+  удалённые через `isDeleted` в `WH:GET:/Materials/v2`.
+- `cost` в вебе ограничена 13 цифрами и двумя знаками после запятой; сервер
+  такой проверки не делает и примет что угодно в пределах `double`.

package/docs/guides/notifications.md

@@ -0,0 +1,184 @@
+---
+topic: notifications
+sources:
+  - page: adminapp/src/modules/Triggers/saga.js
+    content_hash: c7b5460e1cfa0ec7
+  - page: adminapp/src/services/requests.js
+    content_hash: 54c3d95d85bb0ce0
+  - page: adminapp/src/locales/ru/app.json
+    content_hash: 22b22046c9336c1a
+---
+
+# Оповещения: триггеры, шаблоны, получатели
+
+Оповещение в HubEx собирается из трёх независимых сущностей сервиса MSG:
+
+- **Шаблон уведомления** (`MessageTemplate`) — текст и канал доставки.
+- **Правило выбора получателя** (`RecipientSelectionRule`) — кому слать.
+- **Триггер** (`Trigger`) — когда слать: событие и (или) стадии заявки; он
+  связывает шаблон с правилами.
+
+Веб-клиент создаёт их именно в этом порядке — шаблон, затем триггер, затем
+привязки:
+
+```text
+POST MSG:POST:/MessageTemplates          → messageTemplateID
+PUT  MSG:PUT:/MessageTemplates/{id}/validate  → проверка текста на сервере
+POST MSG:POST:/RecipientSelectionRules   → recipientSelectionRuleID
+POST MSG:POST:/Triggers                  → triggerID
+POST MSG:POST:/TriggerRecipientSelectionRules  → правила триггера
+POST MSG:POST:/CriticalityForTriggers    → критичности триггера
+POST TSTG:POST:/TaskStageMessageTriggers → стадии триггера
+```
+
+## 1. Шаблон уведомления
+
+```json
+[
+  {
+    "description": "Заявка назначена на исполнителя",
+    "providerID": 1,
+    "contentTypeID": 2,
+    "subject": "Заявка №@номер заявки",
+    "content": "Вам назначена заявка @номер заявки",
+    "applicationID": null,
+    "navigateToID": null
+  }
+]
+```
+
+- `description` — название шаблона (то, что видно в списке).
+- `providerID` — канал доставки: `MSG:GET:/Providers` (email, push и т.д.).
+- `contentTypeID` — тип контента: `MSG:GET:/ContentTypes` (текст, HTML).
+- `content` — текст с подстановками системных полей. Список доступных полей —
+  `MSG:GET:/Notifications/fields`; в интерфейсе они вводятся как `@имя поля`,
+  а перед отправкой заменяются на системные плейсхолдеры. Через MCP бери
+  корректные имена подстановок из `MSG:GET:/Notifications/fields`, не изобретай
+  их.
+- `navigateToID` — куда открывать по нажатию: `MSG:GET:/NavigateTo`.
+
+После создания или изменения веб-клиент всегда вызывает
+`MSG:PUT:/MessageTemplates/{id}/validate` — серверную проверку текста. Ошибки
+подстановок видны только там.
+
+## 2. Правило выбора получателя
+
+Правило — это набор булевых признаков «кому», а не список пользователей.
+Основные флаги: `isCaller` (автор заявки), `isTaskRequestor`, `isTaskAssignee`
+(текущий исполнитель), `isPreviousTaskAssignee`, `isTaskAssigneeManager`,
+`isTaskContact`, `isTaskAssetResponsiblePerson`, `isTenantPowerUser`,
+`isTaskWatchList` (наблюдатели), `isForRelevantUsers`,
+`isForRelevantUsersByWorkType`. Все они обязательны в теле — передавай явные
+`true`/`false`.
+
+Точечные получатели: `customUserID`, `customRoleID`, `customEmailList`,
+`customPhoneList` (телефоны в формате E.164, через запятую),
+`useUnverifiedContacts`.
+
+```text
+GET    MSG:GET:/RecipientSelectionRules
+POST   MSG:POST:/RecipientSelectionRules
+PUT    MSG:PUT:/RecipientSelectionRules
+DELETE MSG:DELETE:/RecipientSelectionRules
+GET    MSG:GET:/RecipientSelectionRules/recipients  кто попадёт под правило
+```
+
+## 3. Триггер
+
+```json
+[
+  {
+    "messageTemplateID": 41,
+    "eventID": 12,
+    "timeoutSeconds": null,
+    "description": "Уведомление исполнителю о назначении",
+    "isNotifyDuringWorkHours": true,
+    "isNotifyDuringDutyHours": true,
+    "isNotifyDuringOtherHours": false,
+    "isEnabled": true
+  }
+]
+```
+
+- `eventID` — событие системы, справочник `COMMON:GET:/Events`. События с
+  пометкой «отложенное» срабатывают с задержкой в пару минут — так гасится
+  поток уведомлений при ошибочных назначениях.
+- Три флага `isNotifyDuring*` обязательны: рабочее время, дежурное время,
+  остальное время.
+- `timeoutSeconds` — задержка отправки.
+- Включение и выключение без удаления — `MSG:PUT:/Triggers/{triggerID}/activate`
+  и `MSG:PUT:/Triggers/{triggerID}/deactivate`.
+
+Привязки триггера (каждая — отдельный запрос, тело
+`[{ "triggerID": 7, "data": [id, id] }]`):
+
+- критичности заявки — `MSG:POST:/CriticalityForTriggers`
+  (текущие — `MSG:GET:/Triggers/{id}/criticalities`);
+- правила выбора получателей — `MSG:POST:/TriggerRecipientSelectionRules`;
+- стадии заявки — `TSTG:POST:/TaskStageMessageTriggers`
+  (стадии триггера — `TSTG:GET:/TaskStages` с query `triggerID`, триггеры
+  стадии — `TSTG:GET:/TaskStages/{id}/messageTriggers`).
+
+Каждый такой запрос **заменяет** список целиком: чтобы убрать одну стадию,
+отправь оставшиеся.
+
+## 4. Webhooks
+
+Webhook отправляет запрос во внешнюю систему по событиям.
+
+```text
+GET    MSG:GET:/Webhooks
+GET    MSG:GET:/Webhooks/{id}
+POST   MSG:POST:/Webhooks        создание и обновление (id в теле)
+PUT    MSG:PUT:/Webhooks/activate/{id}   PUT MSG:PUT:/Webhooks/deactivate/{id}
+DELETE MSG:DELETE:/Webhooks/{id}
+```
+
+Тело содержит `name`, `uri`, `description`, `isActive` и список `events` —
+идентификаторы из `COMMON:GET:/Events`.
+
+## 5. Приём заявок с почты
+
+```text
+GET    MSG:GET:/MailBoxes                 список ящиков
+GET    MSG:GET:/MailBoxes/{id}            один ящик
+GET    MSG:GET:/MailBoxes/regexactions    действия по regex над письмом
+POST   MSG:POST:/MailBoxes                подключение ящика
+PUT    MSG:PUT:/MailBoxes/activate/{id}   PUT MSG:PUT:/MailBoxes/deactivate/{id}
+DELETE MSG:DELETE:/MailBoxes/{id}
+GET    MSG:GET:/MailBoxes/{id}/errors     ошибки разбора писем
+```
+
+Отправители, письма которых превращаются в заявки, — `MSG:GET:/MailBoxes/{mailBoxID}/senders`,
+удаление отправителя — `MSG:DELETE:/MailBoxes/{mailBoxID}/senders/{id}`.
+
+## Последовательность MCP-вызовов
+
+```text
+hubex_request_read(endpointId: `MSG:GET:/Providers`)
+hubex_request_read(endpointId: `MSG:GET:/ContentTypes`)
+hubex_request_read(endpointId: `MSG:GET:/Notifications/fields`)
+hubex_request_write(endpointId: `MSG:POST:/MessageTemplates`, body: [{ description, providerID, contentTypeID, content }])
+→ response[0] = messageTemplateID
+hubex_request_write(endpointId: `MSG:PUT:/MessageTemplates/{id}/validate`, pathParams: { id: messageTemplateID })
+hubex_request_write(endpointId: `MSG:POST:/RecipientSelectionRules`, body: [{ description, isTaskAssignee: true, ... }])
+hubex_request_write(endpointId: `MSG:POST:/Triggers`, body: [{ messageTemplateID, eventID, isNotifyDuringWorkHours: true, isNotifyDuringDutyHours: true, isNotifyDuringOtherHours: false }])
+→ response[0] = triggerID
+hubex_request_write(endpointId: `MSG:POST:/TriggerRecipientSelectionRules`, body: [{ triggerID, data: [ruleID] }])
+hubex_request_write(endpointId: `TSTG:POST:/TaskStageMessageTriggers`, body: [{ triggerID, data: [taskStageID] }])
+```
+
+## Подводные камни
+
+- Триггер без правил выбора получателя создаётся успешно и молчит — привязка
+  правил обязательна для работы оповещения.
+- Если у триггера заданы и событие, и стадии заявки, пользователь получит
+  **два** уведомления. Выбирай одно основание срабатывания.
+- Выбор конкретного пользователя и отдельно его роли в правилах приводит к
+  дублю письма тому же человеку.
+- Текст шаблона проверяется только `MSG:PUT:/MessageTemplates/{id}/validate` —
+  без этого вызова ошибочная подстановка вылезет на реальном уведомлении.
+- Привязки триггера (критичности, стадии, правила) перезаписывают список
+  целиком, а не добавляют элемент.
+- Телефоны в `customPhoneList` веб-клиент нормализует в E.164 — передавай
+  номера в этом формате.