@hubex/mcp 0.2.0

package/docs/guides/assets.md

@@ -0,0 +1,334 @@
+---
+topic: assets
+sources:
+  - page: admin/ExampleRequestsAPI.md
+    content_hash: ad3e2bf92fe6a736
+  - page: admin/ObjectClass.md
+    content_hash: 77c473001aff5b7e
+  - page: admin/ObjectsType.md
+    content_hash: 631a7aec138691e5
+  - page: admin/PlacesVSObjectsClass.md
+    content_hash: f3a3726398998a1e
+---
+
+# Объекты обслуживания
+
+Объект (Asset) — оборудование или площадка, по которым создают заявки. Он
+принадлежит сервису `ES`, может иметь локацию, участки, виды работ и родителя
+в иерархии.
+
+Гайд состоит из трёх частей: справочники, создание объекта (раздел
+«Создание»), изменение существующего (раздел «Редактирование»). Создание и
+редактирование устроены по-разному: при создании связи добавляются цепочкой,
+при редактировании — вычисляются как дельта.
+
+## Справочники
+
+| Значение | Запрос |
+| --- | --- |
+| объект | `ES:GET:/Assets` или `ES:GET:/Assets/{assetID}` |
+| тип объекта | `ES:GET:/AssetTypes` |
+| класс объекта | `ES:GET:/AssetClasses` |
+| компания-владелец | `ES:GET:/Companies` |
+| локация | `ES:GET:/Locations` |
+| участок | `ES:GET:/Districts` |
+| виды работ | `WORK:GET:/WorkTypes` |
+
+Тип объекта и класс объекта — разные сущности. Тип определяет назначение и
+может требовать собственную локацию; класс служит для классификации и
+фильтрации. Участок (`district`) ограничивает доступ пользователей к объекту
+и заявкам.
+
+# Создание объекта
+
+Этот порядок повторяет короткую форму создания объекта в веб-клиенте HubEx:
+локация → объект → связи с локацией, участками и видами работ → публикация.
+Сам `ES:POST:/Assets` создаёт только основную запись; для объекта, готового к
+работе в заявках, выполни всю цепочку.
+
+Перед записью убедись, что на сервере разрешены `POST` и `PUT`. Не создавай
+тестовый или «примерный» объект без явной просьбы пользователя.
+
+## 1. Собери обязательные значения
+
+Форма веб-клиента требует имя, компанию, адрес и хотя бы один участок. В
+Swagger поля `ES:POST:/Assets` nullable, но для результата, соответствующего
+интерфейсу, собери:
+
+| Значение | Справочник |
+| --- | --- |
+| `name` | запрос пользователя |
+| `companyID` | `ES:GET:/Companies` |
+| `assetTypeID` | `ES:GET:/AssetTypes` |
+| `assetClassID` | `ES:GET:/AssetClasses` |
+| адрес или `locationID` | `ES:GET:/Locations` / запрос пользователя |
+| `districtIDs` | `ES:GET:/Districts` |
+| `workTypeIDs` | `WORK:GET:/WorkTypes` |
+
+`parentID` необязателен. Для дочернего объекта найди родителя через
+`ES:GET:/Assets` с `includePath=true`. Если значение не задано пользователем,
+веб-клиент берёт тип, класс и участок с `isDefault: true`, а также все
+опубликованные виды работ. Используй дефолт только при единственном подходящем
+варианте; иначе уточни выбор.
+
+## 2. Создай или выбери локацию
+
+Если подходящая локация уже существует, используй её `id`. Для нового адреса
+вызови `ES:POST:/Locations`; тело — **массив**:
+
+```json
+[
+  {
+    "address": "Москва, ул. Примерная, 1",
+    "coordinate": "55.7558:37.6173",
+    "isIgnorePossibleDuplication": true
+  }
+]
+```
+
+Обязателен только `address`. Ответ — массив идентификаторов; первый элемент —
+`locationID`. Схему полей страны, временной зоны и описания получай через
+`hubex_describe_endpoint` для `ES:POST:/Locations`.
+
+## 3. Создай основную запись объекта
+
+Вызови `ES:POST:/Assets` с **одним объектом**, не массивом:
+
+```json
+{
+  "name": "Кофемашина 3 этаж",
+  "companyID": 120,
+  "assetTypeID": 4,
+  "assetClassID": 7,
+  "parentID": 501,
+  "isAutoPublish": true
+}
+```
+
+`parentID` опционален. Допустимые дополнительные поля (`serialNumber`, `erpID`,
+`notes`, `responsiblePerson`, `warrantyTill`, `assetTemplateID`) описывает
+`hubex_describe_endpoint` для `ES:POST:/Assets`. Не передавай произвольные
+поля: схема запрещает дополнительные свойства.
+
+Ответ `201` содержит `{ "id", "name" }`; `id` — это `assetID`. Веб-клиент не
+передаёт `locationID` в теле этого запроса: он создаёт отдельную связь на
+следующем шаге.
+
+## 4. Добавь связи
+
+Сначала привяжи локацию через `ES:POST:/AssetLocations`:
+
+```json
+{
+  "assetID": 840,
+  "locationID": 991
+}
+```
+
+Затем добавь виды работ и участки:
+
+```json
+// ES:POST:/AssetWorkTypes
+{
+  "assetID": 840,
+  "data": [12, 18]
+}
+```
+
+```json
+// ES:POST:/AssetDistricts
+{
+  "assetID": 840,
+  "data": [{ "id": 3 }, { "id": 9 }]
+}
+```
+
+Для `AssetWorkTypes.data` нужны числовые id, для `AssetDistricts.data` —
+объекты `{ id }`. Веб-клиент при привязке локации ещё отправляет `dateFrom` и
+`dateTill`, но в Swagger `hubexMCP` для `ES:POST:/AssetLocations` описаны лишь
+`assetID` и `locationID`. Ориентируйся на актуальный результат
+`hubex_describe_endpoint`.
+
+## 5. Опубликуй и проверь
+
+Вызови `ES:PUT:/Assets/{assetID}/publish`, передав id в `pathParams`; тело не
+нужно. Веб-клиент выполняет публикацию явно и безусловно, даже если в создании
+был указан `isAutoPublish: true`.
+
+Затем прочитай `ES:GET:/Assets/{assetID}` и проверь имя, компанию, тип, класс,
+родителя, локацию и публикацию. Связи проверяются через
+`ES:GET:/Assets/{assetID}/districts` и `ES:GET:/Assets/{assetID}/workTypes`.
+
+## Последовательность MCP-вызовов при создании
+
+Перед каждым write-запросом запрашивай его схему через
+`hubex_describe_endpoint`.
+
+```text
+hubex_request_write(endpointId: `ES:POST:/Locations`, body: [{ address, coordinate }])
+→ locationID
+hubex_request_write(endpointId: `ES:POST:/Assets`, body: { name, companyID, assetTypeID, assetClassID, parentID? })
+→ assetID
+hubex_request_write(endpointId: `ES:POST:/AssetLocations`, body: { assetID, locationID })
+hubex_request_write(endpointId: `ES:POST:/AssetWorkTypes`, body: { assetID, data: workTypeIDs })
+hubex_request_write(endpointId: `ES:POST:/AssetDistricts`, body: { assetID, data: districtIDs.map(id => ({ id })) })
+hubex_request_write(endpointId: `ES:PUT:/Assets/{assetID}/publish`, pathParams: { assetID })
+```
+
+Не запускай шаги со связями параллельно: веб-клиент подавляет ошибки дочерних
+вызовов. MCP должен остановиться на первой ошибке и сообщить `assetID` уже
+созданной частичной записи, а не повторять `POST /Assets` и создавать дубликат.
+
+Локация останется в системе, если объект создать не удалось. Не удаляй её
+автоматически: сначала сообщи пользователю её id и запроси разрешение на
+очистку.
+
+# Редактирование объекта
+
+Раздел повторяет форму редактирования объекта в веб-клиенте HubEx. Основные
+поля, участки и локация меняются разными запросами; не пытайся отправить всё в
+`ES:PUT:/Assets/{assetID}`.
+
+Фронтенд выполняет основной `PUT`, затем запускает изменения участков и после
+этого обрабатывает локацию. Для MCP безопаснее дождаться результата каждого
+шага: интерфейс запускает изменения участков в фоне и может показать успех при
+неуспешной привязке участка.
+
+## 1. Прочитай текущее состояние
+
+Перед любым изменением получи:
+
+- `ES:GET:/Assets/{assetID}` — основные поля, компания, тип, класс, родитель,
+  локация и публикация;
+- `ES:GET:/Assets/{assetID}/districts` — текущие участки;
+- `ES:GET:/Assets/{assetID}/workTypes` — текущие виды работ.
+
+Сравни текущее состояние с запросом пользователя. Не передавай `null` или
+пустой массив как замену неизвестного значения: это может снять родителя,
+стереть ссылку или отвязать все элементы. Для справочных значений используй
+`ES:GET:/Companies`, `ES:GET:/AssetTypes`, `ES:GET:/AssetClasses`,
+`ES:GET:/Districts` и `WORK:GET:/WorkTypes`.
+
+## 2. Обнови основную карточку
+
+Вызови `ES:PUT:/Assets/{assetID}` с `assetID` в `pathParams`. Веб-клиент
+передаёт все доступные для формы значения, а не только изменённое поле:
+
+```json
+{
+  "name": "Кофемашина 3 этаж",
+  "companyID": 120,
+  "assetTypeID": 4,
+  "assetClassID": 7,
+  "parentID": 501,
+  "isMobileAsset": false,
+  "isInheritParentDistricts": false,
+  "isSkipForEscalation": false,
+  "isStopEscalation": false,
+  "notes": "Установлена у ресепшена",
+  "serialNumber": "SN-0001"
+}
+```
+
+Перед вызовом получи точную схему через `hubex_describe_endpoint` для
+`ES:PUT:/Assets/{assetID}` и собери тело из прочитанных данных плюс изменения
+пользователя. Дополнительные поддерживаемые поля: `responsiblePerson`, `erpID`,
+`scheduleRuleID`, `warrantyTill`, `positionOnSchema`, `locationID`,
+`useAllWorkTypes` и `isAutoPublish`.
+
+Не используй `ES:PUT:/Assets` для одного объекта: это массовое изменение с
+другим телом (`assets: [id, ...]`) и другой семантикой.
+
+Веб-клиент всегда отправляет `isSkipForEscalation: false` и
+`isStopEscalation: false`, даже если пользователь их не менял. MCP не должен
+копировать это поведение: возьми текущие значения из объекта и меняй их только
+по явной просьбе пользователя.
+
+## 3. Измени участки и виды работ как дельту
+
+Для добавления участков используй `ES:POST:/AssetDistricts`:
+
+```json
+{
+  "assetID": 840,
+  "data": [{ "id": 3 }]
+}
+```
+
+Для удаления — `ES:DELETE:/AssetDistricts`:
+
+```json
+{
+  "assetID": 840,
+  "data": [9]
+}
+```
+
+Виды работ меняются аналогично через `ES:POST:/AssetWorkTypes` и
+`ES:DELETE:/AssetWorkTypes`; в обоих телах `data` — массив числовых id:
+
+```json
+{
+  "assetID": 840,
+  "data": [18]
+}
+```
+
+Сначала вычисли `added` и `removed` относительно прочитанного состояния.
+Отправляй только дельту, не удаляй и не добавляй весь список заново.
+
+Короткая форма редактирования веб-клиента меняет только участки; виды работ в
+ней не редактируются. В MCP вызывай методы `AssetWorkTypes` лишь когда
+пользователь отдельно запросил изменение видов работ.
+
+## 4. Измени локацию осознанно
+
+Есть три разных операции:
+
+1. Привязать к объекту существующую локацию —
+   `ES:POST:/AssetLocations` с телом `{ assetID, locationID }`.
+2. Создать новую локацию — `ES:POST:/Locations` с телом-массивом
+   `[{ address, coordinate, ... }]`, получить `locationID`, затем создать
+   связь через `ES:POST:/AssetLocations`.
+3. Исправить данные уже существующей локации — `ES:PUT:/Locations` с
+   телом-массивом `[{ id, address, coordinate, ... }]`.
+
+Третий вариант меняет саму локацию, а не только объект. Перед ним проверь,
+используется ли она другими объектами; если да, для нового адреса безопаснее
+создать отдельную локацию и привязать её на шагах 1–2.
+
+Веб-клиент при выборе нового адреса добавляет новую связь и не удаляет старую.
+Не предполагай, что предыдущая связь будет снята автоматически: после операции
+перечитай объект и только затем решай, требуется ли дополнительное действие.
+
+Если в выбранном адресе изменилось только `description`, веб-клиент правит
+существующую локацию через `ES:PUT:/Locations`; изменение `address` или
+`coordinate` тоже требует передавать полный объект локации по актуальной схеме.
+Не изменяй общую локацию, пока не проверишь, не используют ли её другие
+объекты.
+
+## 5. Управляй публикацией отдельно
+
+Для публикации используй `ES:PUT:/Assets/{assetID}/publish`, для снятия с
+публикации — `ES:PUT:/Assets/{assetID}/unpublish`. Оба вызова принимают
+`assetID` в `pathParams` и не требуют тело.
+
+## 6. Проверь результат
+
+После каждого успешного шага прочитай `ES:GET:/Assets/{assetID}`; после правки
+участков или видов работ также перечитай соответствующую связь. Если один из
+последующих шагов не выполнился, не откатывай уже выполненные автоматически:
+сообщи пользователю, какие изменения сохранились, и предложи дозапустить только
+неуспешное действие.
+
+## Подводные камни
+
+- Тела `ES:PUT:/Locations` — массивы, а тела связей с объектом — объекты.
+- `parentID: null` снимает родителя. Передавай это значение только по явной
+  просьбе пользователя.
+- Участки и виды работ не обновляются телом `ES:PUT:/Assets/{assetID}`.
+- Изменения участков в интерфейсе выполняются в фоне. В MCP проверяй ответ
+  каждого вызова, иначе объект может сохраниться без нужного участка.
+- При создании связи добавляются цепочкой, при редактировании — только
+  дельтой: не переноси порядок из раздела «Создание» на правку существующего
+  объекта.

package/docs/guides/attributes.md

@@ -0,0 +1,125 @@
+---
+topic: attributes
+sources:
+  - page: adminapp/src/modules/Attributes/saga.js
+    content_hash: 06fc2d7e52a7cf7a
+  - page: adminapp/src/helpers/attributes.js
+    content_hash: b02bb20d39fbd6c5
+  - page: adminapp/src/config/defaultProperties.js
+    content_hash: 280a0b7c004e5820
+---
+
+# Дополнительные поля (атрибуты)
+
+Атрибут — дополнительное поле, которое расширяет карточку заявки, объекта,
+чек-листа, выполненной работы, компании, договора, сотрудника или заказчика.
+Живёт в сервисе COMMON и общий для всего тенанта; к какой сущности он
+относится, задаётся набором флагов `IsRelevantFor*`.
+
+```text
+GET    COMMON:GET:/Attributes                       список
+GET    COMMON:GET:/Attributes/{attributeID}         одно поле
+POST   COMMON:POST:/Attributes                      создать
+PUT    COMMON:PUT:/Attributes                       изменить
+DELETE COMMON:DELETE:/Attributes/{id}               удалить
+POST   COMMON:POST:/AttributeListOfValues           значения списка
+GET    COMMON:GET:/Attributes/{attributeID}/listOfValues
+```
+
+## 1. Создание поля
+
+```json
+[
+  {
+    "name": "Субподрядчик",
+    "attributeTypeID": 5,
+    "measurementUnitID": null,
+    "isPublic": true,
+    "IsRelevantForTask": true,
+    "IsRelevantForAsset": false,
+    "IsRelevantForCheckList": false,
+    "IsRelevantForCompletedWork": false,
+    "IsRelevantForCompany": false,
+    "IsRelevantForContract": false,
+    "IsRelevantForCustomer": false,
+    "IsRelevantForTechnician": false
+  }
+]
+```
+
+- `attributeTypeID` — тип поля: `COMMON:GET:/AttributeTypes` (или
+  `COMMON:GET:/AttributeTypes/v2`). У типа есть `code` — по нему определяется
+  поведение: `Select` и `MultiSelect` требуют списка значений (см. ниже),
+  тип «значение из справочника» связывает поле с одним из справочников
+  (объекты, компании, сотрудники, заказчики, материалы).
+- `measurementUnitID` — единица измерения для числовых полей:
+  `COMMON:GET:/MeasurementUnits`.
+- Флаги `IsRelevantFor*` — для каких сущностей поле доступно. AdminApp всегда
+  отправляет **все восемь** флагов, невыбранные — `false`; частичное тело
+  может обнулить остальные признаки.
+- `isPublic` — поле видно в паспорте объекта (данные, доступные по QR-коду).
+
+Ответ `201` — массив идентификаторов.
+
+## 2. Значения списка
+
+Для типов `Select` и `MultiSelect` сразу после создания или изменения атрибута
+веб-клиент отправляет значения:
+
+```json
+[
+  {
+    "attributeID": 128,
+    "data": [
+      { "key": "1", "value": "Подрядчик А" },
+      { "key": "2", "value": "Подрядчик Б" }
+    ]
+  }
+]
+```
+
+`key` — уникальный идентификатор значения (в интерфейсе заполняется по
+порядку), `value` — то, что видит пользователь. Запрос заменяет список
+значений целиком: чтобы удалить значение, отправь набор без него.
+
+## 3. Где ещё используются атрибуты
+
+- **Чек-листы**: атрибут задаёт способ ответа на пункт (число, дата, список,
+  вложение) — `hubex_get_guide topic="checklisttemplates"`, фильтр
+  `isRelevantForCheckList=true`.
+- **Форма заявки**: дополнительные поля попадают в раскладку
+  (`UI:GET:/LayoutTemplates/{id}/Attributes`) и в настройку доступности по
+  ролям и стадиям (`TSTG:POST:/TaskStageComponents`, секция `attributes`).
+- **Объекты и компании**: значения проставляются своими эндпоинтами —
+  `ES:POST:/AssetAttributes/v2`, `ES:POST:/Companies/{companyID}/attributes`,
+  `ADM:POST:/Users/{userID}/attributes`.
+- **SLA**: атрибуты правил SLA — это другая сущность (`SLA:GET:/Attributes`),
+  не путать с дополнительными полями.
+
+## Последовательность MCP-вызовов
+
+```text
+hubex_request_read(endpointId: `COMMON:GET:/AttributeTypes`)         → attributeTypeID и code
+hubex_request_read(endpointId: `COMMON:GET:/MeasurementUnits`)       → measurementUnitID
+hubex_request_write(endpointId: `COMMON:POST:/Attributes`, body: [{ name, attributeTypeID, IsRelevantForTask: true, ... }])
+→ response[0] = attributeID
+hubex_request_write(endpointId: `COMMON:POST:/AttributeListOfValues`, body: [{ attributeID, data: [{ key, value }] }])
+hubex_request_read(endpointId: `COMMON:GET:/Attributes/{attributeID}/listOfValues`, pathParams: { attributeID })
+```
+
+## Подводные камни
+
+- Флаги `IsRelevantFor*` пишутся с заглавной буквы в теле запроса, а в ответе
+  приходят вложенным объектом `relevantFor` (`task`, `asset`, `checkList`,
+  `completedWork`, `company`, `contract`, `customer`, `technician`) — при
+  копировании поля перекладывай значения между этими формами.
+- Список значений имеет смысл только для типов `Select` и `MultiSelect`; для
+  остальных типов вызов `COMMON:POST:/AttributeListOfValues` бессмысленен.
+- Создание атрибута не размещает его на форме заявки: новое поле появляется
+  внизу основного блока раскладки, а видимость по ролям и стадиям настраивается
+  отдельно.
+- Удаление атрибута (`COMMON:DELETE:/Attributes/{id}`) затрагивает все
+  заполненные значения в заявках и объектах — делай только по явному
+  подтверждению пользователя.
+- В списках атрибутов почти всегда нужен фильтр `isDeleted=false`: удалённые
+  поля продолжают возвращаться.

package/docs/guides/checklisttemplates.md

@@ -0,0 +1,154 @@
+---
+topic: checklisttemplates
+sources:
+  - page: admin/ExampleRequestsAPI.md
+    content_hash: ad3e2bf92fe6a736
+  - page: admin/TicketLifeCycle.md
+    content_hash: 60be5a94c8573779
+---
+
+# Создание шаблона чек-листа
+
+Этот гайд создаёт **шаблон** чек-листа: название, пункты и необязательные
+привязки к объектам обслуживания и видам работ. Это не заполнение чек-листа
+в уже созданной заявке — для него используй
+`hubex_get_guide topic="taskchecklists"`.
+
+MainApp создаёт шаблон тремя последовательными запросами:
+
+```text
+POST /CheckLists → checkListID
+POST /CheckListItems → пункты
+POST /CheckLists/{checkListID}/assign → привязки (при наличии)
+```
+
+Не запускай шаги параллельно: каждый следующий требует `checkListID` из
+предыдущего. Перед каждым write-запросом получай актуальную схему через
+`hubex_describe_endpoint`.
+
+## 1. Собери данные
+
+В форме MainApp обязательны название шаблона и хотя бы один пункт. Описание,
+атрибут пункта, объекты и виды работ необязательны.
+
+| Данные | Ограничение интерфейса | Где взять id |
+| --- | --- | --- |
+| `name` шаблона | 1–60 символов | пользователь |
+| `description` шаблона | до 500 символов | пользователь |
+| `name` пункта | 1–100 символов | пользователь |
+| `description` пункта | до 500 символов | пользователь |
+| `attributeID` | необязателен, один на пункт | `COMMON:GET:/Attributes` с `isDeleted=false`, `isRelevantForCheckList=true` |
+| `assets` | необязательный список объектов | `ES:GET:/Assets` |
+| `workTypes` | необязательный список видов работ | `WORK:GET:/WorkTypes` с `isPublished=true` |
+
+Атрибут задаёт способ ответа на пункт: например, число, дата, текст, список
+значений или вложение. Если для пункта достаточно отметки о выполнении, не
+задавай `attributeID`.
+
+Привязка к объекту и (или) виду работ нужна, чтобы шаблон автоматически
+появлялся в заявке при выборе соответствующих значений. Шаблон без привязок
+создаётся успешно, но в заявки автоматически не добавляется.
+
+## 2. Создай шаблон
+
+`WORK:POST:/CheckLists` принимает **массив**, даже если создаётся один
+шаблон:
+
+```json
+[
+  {
+    "name": "Ежедневный осмотр кофемашины",
+    "description": "Проверки перед началом работы"
+  }
+]
+```
+
+Ответ `201` — массив идентификаторов. Для одного шаблона возьми первый элемент
+как `checkListID`. Право: `CheckListAdd`.
+
+## 3. Добавь пункты
+
+`WORK:POST:/CheckListItems` тоже принимает массив, но его элемент — контейнер
+с `checkListID` и массивом `data`. `sortOrder` начинается с нуля и определяет
+порядок отображения. MainApp отправляет все пункты одним запросом.
+
+```json
+[
+  {
+    "checkListID": 251,
+    "data": [
+      {
+        "name": "Проверить уровень воды",
+        "description": "Не ниже отметки MIN",
+        "attributeID": 42,
+        "sortOrder": 0
+      },
+      {
+        "name": "Очистить поддон",
+        "description": null,
+        "attributeID": null,
+        "sortOrder": 1
+      }
+    ]
+  }
+]
+```
+
+Право: `CheckListItemMerge`. Не передавай `id` для новых пунктов. Если
+создание шаблона прошло, а этот запрос завершился ошибкой, не повторяй
+создание: сохрани пользователю `checkListID` частично созданного шаблона и
+исправь пункты отдельным вызовом.
+
+## 4. Привяжи шаблон — при необходимости
+
+После создания пунктов вызови
+`WORK:POST:/CheckLists/{checkListID}/assign`, передав идентификатор в
+`pathParams`. Тело — **один объект**, не массив:
+
+```json
+{
+  "assets": [840, 841],
+  "workTypes": [12, 18]
+}
+```
+
+Оба массива независимы: можно указать только `assets`, только `workTypes` или
+оба. В MainApp при выборе объекта с дочерними объектами список разворачивается
+до конкретных `assets`; для MCP передавай явные id всех объектов, к которым
+нужна привязка. Право: `CheckListAssign`.
+
+Не вызывай `/assign` с пустыми обоими массивами: веб-клиент в таком случае
+пропускает запрос. При ошибке привязки сам шаблон и его пункты уже существуют;
+не создавай их заново.
+
+## 5. Проверь результат
+
+1. `WORK:GET:/CheckLists/{checkListID}/items` — пункты, их порядок и атрибуты.
+2. `WORK:GET:/CheckLists` с `searchText`, `assetID` или `workTypeID` — шаблон
+   в общем списке и результаты привязки.
+3. При необходимости перечитай `WORK:GET:/CheckLists/{id}` — основное
+   название и описание.
+
+## Последовательность MCP-вызовов
+
+```text
+hubex_request_write(endpointId: `WORK:POST:/CheckLists`, body: [{ name, description? }])
+→ response[0] = checkListID
+hubex_request_write(endpointId: `WORK:POST:/CheckListItems`, body: [{ checkListID, data: items }])
+hubex_request_write(endpointId: `WORK:POST:/CheckLists/{checkListID}/assign`, pathParams: { checkListID }, body: { assets?, workTypes? })
+hubex_request_read(endpointId: `WORK:GET:/CheckLists/{checkListID}/items`, pathParams: { checkListID })
+```
+
+## Подводные камни
+
+- `checkListID` — id шаблона. Не путай его с `taskCheckListID`, который
+  появляется только после добавления шаблона в конкретную заявку.
+- Создание шаблона и создание пунктов — разные операции. Тело первого запроса
+  — массив шаблонов, второго — массив контейнеров `{ checkListID, data }`.
+- Привязки не создают заявку и не добавляют шаблон в уже существующие заявки;
+  они влияют на дальнейший выбор объекта и вида работ.
+- `attributeID` не создаёт атрибут. Если подходящего атрибута нет, нужна его
+  предварительная настройка в консоли администратора, а не произвольный id.
+- Не удаляй частично созданный шаблон автоматически. Удаление — отдельная
+  операция с правом `CheckListDelete` и должно быть явно подтверждено
+  пользователем.

package/docs/guides/companies.md

@@ -0,0 +1,57 @@
+---
+topic: companies
+sources:
+  - page: admin/ExampleRequestsAPI.md
+    content_hash: ad3e2bf92fe6a736
+  - page: admin/CustomerAgreement.md
+    content_hash: a04f9f0fa7b158a4
+---
+
+# Компании
+
+Компания (Company) — заказчик или внутренняя (наша) организация в HubEx.
+Живёт в сервисе ES. К компании привязываются объекты обслуживания и заявки;
+для компаний-заказчиков можно настроить процесс согласования выполненных
+заявок (жизненный цикл с веткой согласования, см. гайд `taskedit`).
+
+## Создание компании: порядок вызовов
+
+1. `ES:GET:/Companies` — посмотреть существующие компании, чтобы не плодить
+   дубликаты (поиск по названию делается на своей стороне, фильтрацией
+   ответа).
+2. `ES:POST:/Companies` — создание. Тело — **массив** объектов компании
+   (можно создавать несколько компаний одним запросом). Тело каждого
+   элемента — по схеме из `hubex_describe_endpoint`.
+
+## Обязательные и ключевые поля тела
+
+- `name` — наименование компании.
+- `isEmployer` — признак типа компании: `true` для собственной/внутренней
+  организации, `false` для заказчика.
+- `registrationTypeID` — тип регистрации компании (см. `ES:GET:/CompanyRegistrationTypes`
+  в swagger сервиса ES).
+
+## Чтение и изменение
+
+- Список: `ES:GET:/Companies`; одна запись — фильтруй ответ по `id`, так как
+  коллекция приходит словарём.
+- Изменение: `ES:PUT:/Companies` — метод обновляет компанию **целиком**,
+  требуется массив с полным набором текущих полей плюс изменяемое значение,
+  иначе остальные поля будут очищены.
+- Удаление: `ES:DELETE:/Companies` — помечает компанию удалённой, физически
+  не стирает.
+
+## Подводные камни
+
+- `ES:POST:/Companies` и `ES:PUT:/Companies` принимают **массив**, а не
+  одиночный объект, даже при создании/изменении одной компании — забытые
+  квадратные скобки дадут ошибку валидации.
+- Ответ на успешное создание — тоже массив, но не эхо тела, а список ID
+  созданных записей (например `[21]`), а не JSON с полями компании.
+- Для компании-заказчика согласование выполненных заявок настраивается не в
+  самой компании, а в жизненном цикле типа заявки (ветка «действий
+  заказчика», см. гайд `taskedit`): к компании это отношения не имеет, но
+  часто путают эти два уровня настройки.
+- Банковские реквизиты (`bankAccounts`), локация (`location`) и контакты
+  (`contacts`) — вложенные структуры внутри тела компании, а не отдельные
+  сущности верхнего уровня для базового сценария создания.