@hubex/mcp 0.2.0

package/docs/guides/taskcreate.md

@@ -0,0 +1,260 @@
+---
+topic: taskcreate
+sources:
+  - page: admin/ExampleRequestsAPI.md
+    content_hash: ad3e2bf92fe6a736
+  - page: admin/TicketLifeCycle.md
+    content_hash: 60be5a94c8573779
+---
+
+# Создание заявки
+
+Заявка (Task) — центральная сущность HubEx, живёт в сервисе `WORK`. Порядок вызовов
+ниже повторяет то, что делает веб-приложение HubEx при создании заявки, поэтому агент,
+идущий этим путём, получит заявку, неотличимую от созданной руками в интерфейсе.
+
+Правка уже существующей заявки, смена стадии, удаление и восстановление — в отдельном
+гайде: `hubex_get_guide topic="taskedit"`.
+
+Ключевая особенность: **у `WORK:POST:/Tasks` в swagger нет ни одного обязательного
+поля**, но сервер и бизнес-логика требуют больше, чем схема. Список реально
+обязательных полей отдаёт не swagger, а метаданные формы — `WORK:GET:/Tasks/new/meta`.
+Всегда сверяйся с ними, а не только со схемой.
+
+`POST /Tasks` создаёт саму заявку и этого достаточно — она сразу валидна.
+Исполнитель, контакты, доп. поля, файлы и смена стадии — **отдельные запросы
+по полученному `taskID`, и вызываются они только при наличии соответствующих
+данных**, а не всегда (шаг 4).
+
+## Шаг 0. Метаданные и права
+
+Для `POST /Tasks` нужно полномочие **TaskAdd** (иначе 403), для метаданных —
+**TaskMetadataGet**.
+
+1. `WORK:GET:/Tasks/new/meta` (опц. query `taskTypeID`) — метаданные формы новой заявки.
+   Ответ — словарь по `taskTypeID`; для каждого типа:
+   - `components` — поля формы: `{ "<имя поля>": { permission, capability } }`;
+   - `attributes` — дополнительные (пользовательские) поля: `{ "<attributeID>": { attribute, attributeType, permission, capability, sortOrder } }`.
+
+   `capability` определяет доступность и обязательность поля:
+   | Код | Смысл |
+   | --- | --- |
+   | `RO` | только чтение — не передавай |
+   | `RW` | можно писать, необязательно |
+   | `RWM` | можно писать, **обязательно** (M = mandatory) |
+   | `ROM` | обязательно, но заполняется системой |
+
+   Именно из `capability` берётся обязательность `companyID`, `assetID`, `workTypeID`,
+   `payerCompanyID`, `notes`, `contactPerson`, `contactPhone`, `locationID`,
+   `estimatedCost`, `attachments` и т.д. — она **разная у разных типов заявок и
+   у разных ролей**, зашивать её в код нельзя.
+
+2. `hubex_whoami` — окружение, tenant и от чьего имени идут запросы;
+   `ADM:GET:/Users/this/profile` — профиль текущего пользователя, его `userID`
+   веб-клиент подставляет в `requestedByUserID`.
+
+### Правило: состав полей выясняй динамически, а не по памяти
+
+Набор полей заявки в каждом тенанте свой. Не собирай тело по этому гайду по памяти
+и не придумывай значения за пользователя — действуй так:
+
+1. Возьми `taskTypeID` (если тип не назван — покажи список из `WORK:GET:/TaskTypes`
+   и спроси, какой нужен; если тип в тенанте один, бери его молча).
+2. Запроси `WORK:GET:/Tasks/new/meta` с query `taskTypeID=<выбранный>` **до** сборки тела.
+3. Разбери ответ на три группы:
+   - `capability` = `RWM` в `components` → **обязательное поле**, заявка без него
+     не создастся;
+   - `capability` = `RWM` в `attributes` → **обязательное доп. поле**, его нужно
+     отправить отдельным запросом `WORK:POST:/TaskAttributes` (шаг 4);
+   - `capability` = `RW` → опциональное, заполняй, только если пользователь дал данные;
+   - `capability` = `RO`/`ROM` → **не передавай**, заполняется системой.
+4. Сопоставь обязательные поля с тем, что пользователь уже сказал. Значения, которые
+   можно вывести однозначно (`requestedByUserID` = текущий пользователь,
+   `criticalityID` = запись с `isDefault: true`, `requestMethodID` = 4 для интеграций,
+   `companyID` и адрес = из выбранного объекта), подставляй сам и упомяни это в ответе.
+5. **Одним сообщением спроси только про те обязательные поля, которые остались
+   незакрытыми**, и для каждого справочного поля сразу приложи варианты из
+   соответствующего справочника (шаг 1). Не задавай вопросы по одному
+   и не спрашивай про опциональные поля.
+6. Только после этого вызывай `WORK:POST:/Tasks`.
+
+Тот же цикл повторяется, если пользователь сменил тип заявки: `capability` и состав
+доп. полей у другого типа будут другими — перечитай `Tasks/new/meta` заново.
+
+## Шаг 1. Справочники
+
+Все справочники возвращают словарь `{ "<id>": {...} }`, а не массив.
+
+| № | Запрос | Что даёт | Полезные query-параметры |
+| --- | --- | --- | --- |
+| 1 | `WORK:GET:/TaskTypes` | `taskTypeID` — тип заявки | `isDeleted=false`, `companyID`, `assetID`, `workTypeID`, `districtID` |
+| 2 | `WORK:GET:/RequestMethods` | `requestMethodID` — способ подачи | `fetch`, `offset` |
+| 3 | `SLA:GET:/Criticalities` | `criticalityID` — критичность | `contractID`, `workTypeID` |
+| 4 | `ES:GET:/Companies` | `companyID` (заказчик), `payerCompanyID`, `payeeCompanyID` | `searchText`; веб шлёт ещё `isDeleted=false`, `isOurCompany=true`, `fetch`, `offset` |
+| 5 | `ES:GET:/Assets` | `assetID` — объект обслуживания | `searchText`, `includePath`; веб дополнительно фильтрует `companyID` и `taskTypeID` |
+| 6 | `WORK:GET:/WorkTypes` | `workTypeID` — вид работ | `isPublished=true`, `assetID`, `taskTypeID` |
+| 7 | `ADM:GET:/Users` (или `ADM:GET:/Users/short`) | `requestedByUserID` — заявитель | `searchText`, `isDeleted`, `isCustomer`, `isTechnician`, `companyID`, `fetch`, `offset` |
+| 8 | `SC:GET:/ServiceContract` | `contractID` — договор | `companyID`, `assetID`, `includeUniversalContractsInAssetFilter=true`, `isDeleted=false` |
+| 9 | `ES:GET:/Assets/{assetID}/contacts`, `ES:GET:/Companies/{companyID}/contacts` | контактные лица для привязки к заявке | — |
+
+Параметры `isDeleted`, `companyID`, `taskTypeID`, `isOurCompany` у пунктов 4–5
+отсутствуют в swagger, но реально поддерживаются — веб-клиент шлёт именно их.
+Если фильтр не сработал, отфильтруй ответ на своей стороне.
+
+Порядок важен: `assetID` фильтруется по выбранным `companyID` + `taskTypeID`,
+а `workTypeID` — по `assetID` + `taskTypeID`. Выбрал тип заявки → перезапроси
+объекты; выбрал/сменил объект → перезапроси виды работ и договоры, иначе получишь
+несовместимую комбинацию и ошибку валидации на сервере.
+
+## Шаг 2. Адрес (если нужен)
+
+В теле заявки адрес передаётся как `locationID`, готового адреса у агента обычно нет.
+Веб-клиент подставляет адрес объекта (`asset.location.id`, при его отсутствии —
+`asset.host.location.id`), а если адрес правили руками — создаёт новый:
+
+- `ES:POST:/Locations` — тело **массив**: `[{ address, coordinate, description, isIgnorePossibleDuplication: true }]`.
+  Обязателен только `address`. `coordinate` — строка `"LAT:LNG"`. Ответ — массив id,
+  `locationID` = первый элемент.
+- `ES:PUT:/Locations` — правка существующего адреса (нужен `id` в теле).
+- Готовые адреса: `ES:GET:/Locations`, `ES:GET:/Locations/{id}`.
+
+Проще всего: взять `assetID`, прочитать `ES:GET:/Assets/{assetID}` и использовать
+`location.id` объекта — новый адрес не создавать.
+
+## Шаг 3. Создание заявки
+
+`WORK:POST:/Tasks` — тело **один объект** (не массив, в отличие от большинства
+POST-методов HubEx). Опциональный заголовок `X-Concurrency-Stamp` (Guid) даёт
+идемпотентность: повтор с тем же значением вернёт 409.
+
+Ответ 201: `{ "id": 12345, "number": "T-12345", "concurrencyStamp": "..." }` —
+`id` и есть `taskID` для всех последующих шагов.
+
+### Обязательный минимум
+
+- `taskTypeID` — тип заявки;
+- `requestMethodID` — способ подачи (для интеграций — 4, веб по умолчанию шлёт 1);
+- `criticalityID` — критичность. Берётся из `SLA:GET:/Criticalities`, дефолт —
+  запись с `isDefault: true`. Формально в схеме необязательна, но клиент считает
+  её обязательной всегда, и заявка без критичности не проходит по SLA.
+
+Всё остальное обязательно ровно настолько, насколько это указано в `capability`
+из `Tasks/new/meta` (`RWM`/`ROM`).
+
+### Поля, которые веб-клиент передаёт всегда
+
+| Поле | Значение |
+| --- | --- |
+| `taskTypeID` | выбранный тип |
+| `requestMethodID` | способ подачи, по умолчанию 1 |
+| `criticalityID` | критичность по умолчанию |
+| `requestedByUserID` | текущий пользователь (заявитель) |
+| `faultTimestamp` | момент обнаружения неисправности; по умолчанию сегодня, 12:00, формат **без таймзоны** `YYYY-MM-DDTHH:mm:ss` |
+| `estimatedCostCurrencyID` | всегда `1` |
+| `notes` + `notesHtml` | описание в двух видах, см. подводные камни |
+
+### Остальные поля тела
+
+`assetID`, `companyID`, `workTypeID`, `locationID`, `parentID` (родительская заявка),
+`contractID`, `assetSchemaID`, `payerCompanyID`, `payeeCompanyID`,
+`contactPerson`, `contactPhone`, `contactEmail`, `number`, `erpID`,
+`requestedStartDateTime`, `requestedFinishDateTime`, `deadline`,
+`estimatedTimeConsumptionMinutes` (целое число минут), `estimatedCost`,
+`serviceLevelAgreementID`, `taskTemplateID`.
+
+Форматы дат: `requestedStartDateTime`, `requestedFinishDateTime`, `deadline` —
+ISO 8601 в UTC; `faultTimestamp` — локальное время без таймзоны. `requestedStartDateTime`
+не должен быть позже `requestedFinishDateTime`.
+
+Схему с точными типами всегда бери из `hubex_describe_endpoint` для
+`WORK:POST:/Tasks` — она отражает актуальный контракт, а список обязательных
+полей в ней пустой (это не ошибка, см. шаг 0).
+
+Быстрый путь для тестовых данных: `hubex_create_test_task` — создаёт заявку с
+разумными дефолтами и префиксом `[MCP-TEST]` в описании, чтобы её потом легко
+было найти и удалить.
+
+## Шаг 4. Досоздание частей заявки (по `taskID`) — по необходимости
+
+Всё ниже — **условные шаги**. Каждый вызывается, только если для него есть данные:
+нет исполнителя — не зови `TaskAssignmentHistory`, нет доп. полей — не зови
+`TaskAttributes`, нет файлов — не зови `TaskAttachments`, и т.д. Заявка, созданная
+одним `POST /Tasks`, уже валидна. Порядок ниже — тот, в котором их выполняет
+веб-клиент, если данные есть.
+
+Единственное исключение — доп. поля с `capability: RWM` в `attributes` из
+`Tasks/new/meta`: они обязательны, и `WORK:POST:/TaskAttributes` для них нужно
+вызвать сразу после создания заявки, даже если пользователь про них не вспомнил
+(значения у него нужно спросить заранее — см. правило в шаге 0).
+
+1. **Исполнитель** — `WORK:POST:/TaskAssignmentHistory`, тело массив:
+   `[{ userID, taskID, scheduledStartDateTime, scheduledFinishDateTime }]`.
+   Обязателен `taskID`. `userID: null` — снять назначение. Если задан период,
+   должен быть задан и исполнитель, `scheduledStartDateTime` < `scheduledFinishDateTime`.
+   Подходящих исполнителей ищи через `ADM:GET:/Users/relevance` с `assetID`
+   и `workTypeID` — этот метод ранжирует сотрудников по пригодности к заявке.
+2. **Дополнительные поля (атрибуты)** — `WORK:POST:/TaskAttributes`, тело массив:
+   `[{ taskID, data: [{ attributeID, value, isPublic, sortOrder }] }]`.
+   Состав атрибутов и их обязательность — из `attributes` в `Tasks/new/meta`.
+   `value` всегда строка: для `SELECT`/`MULTISELECT` — id значений через `|`
+   (`"12|15"`), для `ATTACHMENT`/`DRAWING` — id вложений через `|`,
+   для `DATE` — `YYYY-MM-DDTHH:mm:ss`.
+3. **Контакты заявки** — `WORK:POST:/TaskContacts`, тело массив:
+   `[{ taskID, data: [contactID, ...] }]`. Удаление — `WORK:DELETE:/TaskContacts`
+   с тем же форматом. Список контактов — из контактов объекта/компании (шаг 1, п. 9).
+4. **Файлы** — `WORK:POST:/TaskAttachments/upload/fromForm` (multipart: `File`,
+   `taskID`, `IsPublic`, `IsIgnorePossibleDuplication`, `Description`) или
+   `.../upload/fromBody`. Привязать уже загруженное вложение —
+   `WORK:POST:/TaskAttachments`.
+5. **Смена стадии** — только если нужно сразу увести заявку с начальной стадии:
+   - доступные переходы: `WORK:GET:/Tasks/{taskID}/stages/next`;
+   - обычный переход: `WORK:POST:/TaskStagingHistory`,
+     тело объект `{ taskID, taskStageID, criticalityID?, notes? }`;
+   - если целевая стадия финальная (`isFinishStage`): вместо этого
+     `WORK:PUT:/Tasks/{taskID}/complete` с `{ closed, closedBy, accepted, signed, signedBy }`.
+
+   У стадии могут быть требования (`TSTG:GET:/TaskStages/{id}/requirements`),
+   которые сервер проверит: `AssignedToAnyone` (нужен исполнитель),
+   `CheckListsCompleted` (заполнены чек-листы), `SignedByCustomer` (есть подпись).
+   Не выполнил — переход отклонят. Подробности — в гайде `taskedit`.
+
+После смены стадии права на поля меняются: перечитай `WORK:GET:/Tasks/{taskID}/meta`
+(метаданные уже существующей заявки, в отличие от `Tasks/new/meta`).
+
+## Что дальше
+
+Проверить результат: `WORK:GET:/Tasks/{taskID}` (детали), `WORK:GET:/Tasks` (список
+с фильтрами), `WORK:GET:/Tasks/short` (облегчённый список).
+
+Любая правка созданной заявки — правка полей, добавление работ и материалов,
+смена стадии, удаление и восстановление — описана в гайде
+`hubex_get_guide topic="taskedit"`. Не используй этот гайд для редактирования:
+там другой метод (`PATCH` со списком `[{ field, value }]`), другие метаданные
+(`WORK:GET:/Tasks/{taskID}/meta`) и логика вычисления дельты.
+
+## Подводные камни
+
+- **Обязательность полей динамическая.** Единственный источник правды —
+  `capability` из `WORK:GET:/Tasks/new/meta`. Она зависит от типа заявки и роли
+  пользователя, поэтому проверять её нужно после выбора `taskTypeID`, а не заранее.
+- **`POST /Tasks` принимает объект, а не массив.** Соседние методы (`/TaskContacts`,
+  `/TaskAttributes`, `/TaskAssignmentHistory`, `ES:POST:/Locations`) — наоборот,
+  массивы. Перепутать легко, ошибка будет 400.
+- **`notes` и `notesHtml` заполняй оба.** `notes` — текст без разметки, показывается
+  в списке заявок; `notesHtml` — с разметкой, показывается в карточке. Веб-клиент
+  формирует `notes` как plain-text из `notesHtml`. Заполнишь одно — где-то будет пусто.
+  Санитайзер текста/HTML может вернуть 422.
+- **Стадия ≠ статус.** Стадия (`TSTG:GET:/TaskStages`, история —
+  `WORK:POST:/TaskStagingHistory`) — крупная фаза жизненного цикла; статус
+  (`WORK:GET:/TaskStatuses`) — состояние внутри стадии. Переход, не предусмотренный
+  жизненным циклом или не удовлетворяющий требованиям стадии, отклоняется сервером.
+- **Совместимость справочников.** `assetID` должен принадлежать `companyID` и быть
+  доступен для `taskTypeID`; `workTypeID` — существовать для этой пары. Не переиспользуй
+  списки, полученные до смены типа заявки или объекта.
+- **Ответы коллекций — словари `{ "<id>": {...} }`**, а не массивы; ключ словаря —
+  это id, внутри объекта его может не быть.
+- **`faultTimestamp` — без таймзоны**, остальные даты — UTC. Смешаешь форматы —
+  получишь сдвиг на часовой пояс, без ошибки от сервера.
+- **Заявка без объекта и компании создастся**, но будет бесполезна: по ней не
+  подберётся SLA, договор и исполнитель. Для осмысленного теста указывай
+  `companyID` + `assetID` + `workTypeID`.

package/docs/guides/taskedit.md

@@ -0,0 +1,277 @@
+---
+topic: taskedit
+sources:
+  - page: admin/ExampleRequestsAPI.md
+    content_hash: ad3e2bf92fe6a736
+  - page: admin/TicketLifeCycle.md
+    content_hash: 60be5a94c8573779
+---
+
+# Редактирование заявки
+
+Этот гайд описывает карточку уже существующей заявки (`Task`) так, как её
+сохраняет MainApp. Основные поля заявки, исполнитель, контакты, доп. поля,
+файлы, материалы, выполненные работы, чек-листы и стадия — независимые части.
+Не отправляй их одним `PATCH /Tasks/{taskID}`: этот метод меняет только поля
+самой карточки.
+
+Безопасный порядок: сначала прочитать текущие данные и права, затем рассчитать
+дельту, сохранить связанные сущности, и только последним шагом сменить стадию.
+Закрытая заявка может запретить последующие изменения.
+
+## 1. Прочитай заявку и права на её поля
+
+Перед каждой правкой вызови:
+
+1. `WORK:GET:/Tasks/{taskID}` — актуальная карточка;
+2. `WORK:GET:/Tasks/{taskID}/meta` — права и обязательность полей на текущей
+   стадии;
+3. только для тех частей, которые пользователь хочет менять: `GET` их текущего
+   состояния (контакты, атрибуты, файлы, материалы и т. п.).
+
+В `meta` поле находится в `components`, дополнительные поля — в `attributes`.
+`capability` имеет тот же смысл, что и при создании:
+
+| Код | Действие |
+| --- | --- |
+| `RO` | не изменяй поле |
+| `RW` | можно изменить при явном запросе |
+| `RWM` | поле доступно и обязательно; после изменения не оставляй его пустым |
+| `ROM` | обязательное системное поле, не передавай его вручную |
+
+Не используй права, прочитанные до смены стадии: после перехода обязательно
+повтори `WORK:GET:/Tasks/{taskID}/meta`.
+
+Для ссылочных значений не придумывай id. Используй те же справочники, что и в
+гайде `hubex_get_guide topic="taskcreate"`: объекты — `ES:GET:/Assets`, виды
+работ — `WORK:GET:/WorkTypes`, пользователей — `ADM:GET:/Users` или
+`ADM:GET:/Users/relevance`, критичности — `SLA:GET:/Criticalities`, договоры —
+`SC:GET:/ServiceContract`.
+
+## 2. Измени основную карточку
+
+Основной запрос — `WORK:PATCH:/Tasks/{taskID}`. Его тело — **массив** операций
+`{ field, value }`, а не объект:
+
+```json
+[
+  { "field": "notes", "value": "Неисправность подтверждена" },
+  { "field": "notesHtml", "value": "<p>Неисправность подтверждена</p>" },
+  { "field": "criticalityID", "value": 3 },
+  { "field": "deadline", "value": "2026-08-20T09:00:00Z" }
+]
+```
+
+MainApp при сохранении строит такой список для всех полей формы. Для MCP
+безопаснее передавать только значения, которые пользователь действительно
+изменил: так неизвестное или скрытое поле не будет случайно очищено. Перед
+записью запроси точную схему через `hubex_describe_endpoint` для
+`WORK:PATCH:/Tasks/{taskID}`.
+
+Поля, которые MainApp передаёт этим методом:
+
+| Поле | Формат / особенность |
+| --- | --- |
+| `companyID`, `assetID`, `workTypeID`, `parentID`, `contractID`, `assetSchemaID` | id из соответствующего справочника |
+| `criticalityID`, `requestedByUserID`, `payerCompanyID`, `payeeCompanyID` | id; не очищай без прямого указания |
+| `contactPerson`, `contactPhone`, `contactEmail`, `erpID`, `number` | строковые поля; телефон передаётся без форматирующих символов |
+| `locationID` | id адреса; создание и правка локации — отдельные вызовы из шага 3 |
+| `requestedStartDateTime`, `requestedFinishDateTime`, `deadline` | ISO 8601 в UTC; начало не позже окончания |
+| `faultTimestamp` | локальное время **без** таймзоны, `YYYY-MM-DDTHH:mm:ss` |
+| `estimatedTimeConsumptionMinutes`, `actualTimeConsumptionMinutes` | целое число минут |
+| `estimatedCost`, `actualCost` | число; валюты MainApp устанавливает в `estimatedCostCurrencyID` и `actualCostCurrencyID` равными `1` |
+| `notes`, `notesHtml` | передавай вместе: `notes` — plain text из `notesHtml` |
+
+Чтобы сгенерировать новый номер, MainApp добавляет `{ "field": "number",
+"value": null }`. Не делай этого без явной просьбы пользователя: это не
+очистка номера, а команда серверу сгенерировать другой.
+
+## 3. Адрес и контакты
+
+Если меняется адрес, сначала получи или создай `locationID`:
+
+- существующий адрес — `ES:GET:/Locations`;
+- новый — `ES:POST:/Locations` с массивом `[{ address, coordinate?,
+  isIgnorePossibleDuplication: true }]`;
+- правка существующего — `ES:PUT:/Locations` с массивом, содержащим `id`.
+
+После этого передай `locationID` в PATCH заявки. Правка локации влияет на сам
+адрес и может затронуть другие сущности, которые его используют; для нового
+адреса безопаснее создать новую локацию.
+
+Контакт из полей `contactPerson`, `contactPhone`, `contactEmail` — это текст в
+карточке. Привязанные контакты объекта или компании — отдельная связь:
+
+```json
+// WORK:POST:/TaskContacts
+[{ "taskID": 12345, "data": [701, 702] }]
+
+// WORK:DELETE:/TaskContacts
+[{ "taskID": 12345, "data": [699] }]
+```
+
+Сначала прочитай `WORK:GET:/Tasks/{taskID}/contacts` и вычисли `added`/`removed`.
+Не удаляй все контакты ради замены одного. Кандидаты: `ES:GET:/Assets/{assetID}/contacts`
+и `ES:GET:/Companies/{companyID}/contacts`.
+
+## 4. Исполнители, дополнительные поля и файлы
+
+### Исполнители
+
+`WORK:POST:/TaskAssignmentHistory` принимает массив назначений:
+
+```json
+[
+  {
+    "taskID": 12345,
+    "userID": 88,
+    "scheduledStartDateTime": "2026-08-14T06:00:00Z",
+    "scheduledFinishDateTime": "2026-08-14T14:00:00Z"
+  }
+]
+```
+
+MainApp отправляет новое назначение, когда изменился состав исполнителей или
+период. Для снятия всех назначений он передаёт `[{ taskID, userID: null }]`.
+Если указано расписание, указывай и исполнителя; начало должно быть раньше
+окончания. Подбирать исполнителей следует через `ADM:GET:/Users/relevance` с
+`assetID` и `workTypeID`.
+
+### Дополнительные поля
+
+Прочитай `WORK:GET:/Tasks/{taskID}/attributes` и метаданные из шага 1. Меняй
+только отличающиеся от текущих атрибуты через `WORK:POST:/TaskAttributes`:
+
+```json
+[
+  {
+    "taskID": 12345,
+    "data": [
+      { "attributeID": 41, "value": "12|15", "isPublic": true, "sortOrder": 0 }
+    ]
+  }
+]
+```
+
+`value` — строка: для `SELECT`/`MULTISELECT` это id значений через `|`, для
+`DATE` — `YYYY-MM-DDTHH:mm:ss`, для `ATTACHMENT`/`DRAWING` — id вложений через
+`|`. Новые вложения сначала загрузить, затем передать их id. Не стирай
+обязательный (`RWM`) атрибут.
+
+### Файлы заявки
+
+Загрузить новый файл: `WORK:POST:/TaskAttachments/upload/fromForm` как
+`multipart/form-data` с полями `File`, `taskID`, `IsPublic`,
+`IsIgnorePossibleDuplication=true` и, при необходимости, `Description`.
+Связать уже загруженные вложения: `WORK:POST:/TaskAttachments` с телом
+`[{ taskID, data: [attachmentID] }]`. Удалить: `WORK:DELETE:/TaskAttachments`
+с `[{ taskID, data: [attachmentID] }]`.
+
+Для сравнения сначала прочитай `WORK:GET:/Tasks/{taskID}/attachments` (MainApp
+добавляет query-параметр `thumbnailSize=128`). Не удаляй вложение только потому,
+что пользователь не упомянул его в новом запросе.
+
+## 5. Материалы и выполненные работы
+
+Материалы заявки читай через `WORK:GET:/Tasks/{taskID}/materials`, затем
+выполняй только подходящую операцию:
+
+| Операция | Метод |
+| --- | --- |
+| добавить | `WORK:POST:/TaskMaterials` |
+| изменить количество, склад или единицу | `WORK:PUT:/TaskMaterials` |
+| удалить | `WORK:DELETE:/TaskMaterials` |
+| выдать исполнителю | `WORK:PUT:/TaskMaterials/takeOn` |
+| вернуть на склад | `WORK:PUT:/TaskMaterials/takeOff` |
+
+Тела первых трёх методов имеют форму `[{ taskID, data: [...] }]`. При создании
+материала MainApp передаёт `materialID`, `warehouseID`, `measurementUnitID`,
+`quantity` и, если материал выдан, `takenByUserID`. Перед вызовом всегда
+прочитай актуальную схему нужного метода: структуры элементов для добавления и
+обновления различаются.
+
+Выполненные работы — самостоятельная коллекция, не поле PATCH. Прочитай
+`WORK:GET:/Tasks/{taskID}/completedWorks`, после чего используй
+`WORK:POST:/CompletedWorks`, `WORK:PUT:/CompletedWorks` или
+`WORK:DELETE:/CompletedWorks` с телом `[{ taskID, data: [...] }]`. Основные
+поля работы в MainApp: `maintainedAssetID`, `workTypeID`, `started`, `finished`,
+`notes`, `workTypeCost`.
+
+Исполнители, материалы, вложения и атрибуты выполненной работы также имеют
+отдельные методы: `CompletedWorksTechnicians`, `Tasks/completedWorks/materials`,
+`CompletedWorkAttachments/upload/fromForm` и `Tasks/completedWorks/attributes`.
+Используй их только когда пользователь меняет именно эту часть; полные формы
+тел обязательно сверяй через `hubex_describe_endpoint`.
+
+## 6. Чек-листы и стадия
+
+Добавление или снятие шаблона чек-листа с заявки выполняется через
+`WORK:POST:/Tasks/{taskID}/checkLists` и
+`WORK:DELETE:/Tasks/{taskID}/checkLists`. MainApp добавляет объекты
+`{ "CheckListID": id }`, а при удалении передаёт массив `taskCheckListID`.
+Заполнение его пунктов описано отдельно в
+`hubex_get_guide topic="taskchecklists"`.
+
+Стадия и статус не одно и то же. Стадия — переход жизненного цикла, статус —
+состояние внутри неё. Не пытайся изменить `taskStageID` или `taskStatusID`
+через PATCH.
+
+1. Получи доступные переходы: `WORK:GET:/Tasks/{taskID}/stages/next`.
+2. Прочитай требования целевой стадии:
+   `TSTG:GET:/TaskStages/{id}/requirements`, передав id целевой стадии.
+3. Для обычной стадии вызови `WORK:POST:/TaskStagingHistory`:
+
+```json
+{ "taskID": 12345, "taskStageID": 9 }
+```
+
+4. Если `isFinishStage: true`, вместо истории стадий заверши заявку через
+   `WORK:PUT:/Tasks/{taskID}/complete`. MainApp передаёт как минимум `closed`
+   и `closedBy`; дополнительно возможны `accepted`, `acceptedPerson`, `signed`,
+   `signedBy`.
+
+Типовые требования: `AssignedToAnyone` (назначить исполнителя),
+`CheckListsCompleted` (сохранить все обязательные результаты),
+`SignedByCustomer` (загрузить подпись). Сначала выполни их и проверь результаты,
+затем делай переход. После него перечитай карточку и `meta`.
+
+## 7. Удаление и восстановление
+
+Удалить заявку: `WORK:DELETE:/Tasks/{taskID}`. Это отдельное, потенциально
+деструктивное действие — перед вызовом явно подтверди, что пользователь выбрал
+именно эту заявку.
+
+Восстановить: `WORK:PUT:/Tasks/restore` с массивом id, например `[12345]`.
+Затем перечитай `WORK:GET:/Tasks/{taskID}`. Не восстанавливай заявку без
+явного запроса пользователя.
+
+## Проверка и порядок операций
+
+После каждого изменённого блока перечитывай соответствующий ресурс. При
+комплексном сохранении следуй последовательности MainApp:
+
+```text
+PATCH основной карточки
+→ назначение, файлы и контакты
+→ результаты чек-листов и выполненные работы
+→ дополнительные атрибуты
+→ смена стадии
+→ GET заявки и GET /meta для проверки
+```
+
+Не запускай зависимые write-запросы параллельно: ошибка в обязательном
+чек-листе, назначении или атрибуте должна быть видна до попытки финального
+перехода.
+
+## Подводные камни
+
+- Права и обязательность динамические: источник правды —
+  `WORK:GET:/Tasks/{taskID}/meta`, а не swagger и не значения другой заявки.
+- `PATCH /Tasks/{taskID}` принимает массив `{ field, value }`; почти все
+  соседние методы принимают объект либо массив объектов с `taskID` и `data`.
+- Не очищай поля значением `null` по умолчанию. `null` в PATCH — это явная
+  команда снять значение; для `number` это ещё и запрос на регенерацию номера.
+- `notes` и `notesHtml` должны быть согласованы; `faultTimestamp` не UTC, а
+  плановые даты и deadline — UTC.
+- Закрытие и смена стадии выполняются в конце. Если сначала закрыть заявку,
+  последующие изменения могут стать недоступны по правам.