@hubex/mcp 0.4.0 → 0.5.0

package/dist/guides/field-notes.json

@@ -5,7 +5,7 @@
     "lookup": "WORK:GET:/TaskTypes"
   },
   "requestMethodID": {
-    "description": "Способ подачи заявки. Для интеграций используется значение 4.",
+    "description": "Способ подачи заявки. Значение пер-тенантное — выбери из справочника, не подставляй число из примеров.",
     "required": true,
     "lookup": "WORK:GET:/RequestMethods"
   },

package/dist/http.js

@@ -3,6 +3,18 @@
  * injects auth + `X-Application-ID`, and normalizes responses and errors.
  */
 import { maskPii } from "./pii/mask.js";
+/**
+ * Заголовки, которые клиент проставляет сам. Подмена `Authorization` или
+ * `X-Application-ID` сменила бы того, от чьего имени идёт запрос, поэтому
+ * переопределение отклоняется, а не тихо игнорируется.
+ */
+const RESERVED_HEADERS = new Set(["authorization", "x-application-id"]);
+/**
+ * Заголовки ответа, которые несут данные, а не транспортную обвязку.
+ * `Content-Range` — единственный источник общего числа записей при
+ * постраничной выборке через `Range`, без него цикл по страницам не построить.
+ */
+const EXPOSED_RESPONSE_HEADERS = ["content-range", "accept-ranges"];
 export class HubexApiError extends Error {
     status;
     service;
@@ -65,6 +77,13 @@ export class HubexClient {
             "X-Application-ID": this.config.applicationId,
             Accept: "application/json",
         };
+        for (const [name, value] of Object.entries(req.headers ?? {})) {
+            if (RESERVED_HEADERS.has(name.toLowerCase())) {
+                throw new Error(`Заголовок ${name} подставляет сам сервер и переопределить его нельзя. ` +
+                    `Убери его из headers.`);
+            }
+            headers[name] = String(value);
+        }
         const init = { method: req.method, headers };
         if (req.body !== undefined && req.method !== "GET" && req.method !== "HEAD") {
             headers["Content-Type"] = "application/json";
@@ -85,9 +104,15 @@ export class HubexClient {
         // потребители клиента, включая текст ошибок. Авторизация ходит мимо
         // HubexClient (src/auth.ts), поэтому токены сессии не задеваются.
         const visible = this.config.maskPii ? maskPii(data) : data;
+        const exposed = {};
+        for (const name of EXPOSED_RESPONSE_HEADERS) {
+            const value = res.headers.get(name);
+            if (value !== null)
+                exposed[name] = value;
+        }
         if (!res.ok) {
             throw new HubexApiError(res.status, req.service, req.path, visible ?? text);
         }
-        return { status: res.status, data: visible };
+        return { status: res.status, data: visible, headers: exposed };
     }
 }

package/dist/tools/request.js

@@ -57,6 +57,21 @@ function resolvePath(entry, pathParams) {
     }
     return path;
 }
+/**
+ * Заголовки ответа, которые стоит показать вызывающему. `Content-Range` несёт
+ * общее число записей и нужен всегда; `Accept-Ranges` — только там, где ответ и
+ * так обёрнут (HEAD), чтобы не менять форму обычных ответов.
+ */
+function headerMeta(res, withAcceptRanges = false) {
+    const out = {};
+    const contentRange = res.headers?.["content-range"];
+    if (contentRange)
+        out.contentRange = contentRange;
+    const acceptRanges = res.headers?.["accept-ranges"];
+    if (withAcceptRanges && acceptRanges)
+        out.acceptRanges = acceptRanges;
+    return out;
+}
 function requestTool(group, deps) {
     const isWrite = group === "write";
     // DELETE в HubEx нередко удаляет пачкой и принимает список в теле запроса.
@@ -71,6 +86,15 @@ function requestTool(group, deps) {
             description: "Значения параметров пути, например { \"taskID\": 42 }.",
         },
         query: { type: "object", description: "Query-параметры запроса." },
+        headers: {
+            type: "object",
+            description: "Дополнительные HTTP-заголовки — там, где query-параметр не подходит. " +
+                "`Range: items=0-4999` даёт постраничную выборку больших справочников: " +
+                "общее число записей вернётся в `Content-Range` (`items=1-4999/22721`), " +
+                "он попадёт в результат рядом с data. `X-Concurrency-Stamp` (Guid) даёт " +
+                "идемпотентность создания заявки. Authorization и X-Application-ID " +
+                "подставляет сервер, переопределить их нельзя.",
+        },
     };
     if (acceptsBody) {
         properties.body = {
@@ -141,23 +165,31 @@ function requestTool(group, deps) {
                     path,
                     query,
                     body,
+                    headers: (args.headers ?? undefined),
                 });
+                // HEAD и так отдаёт обёртку — там показываем все собранные заголовки,
+                // включая `Accept-Ranges`: HEAD с `Range` — дешёвый способ узнать размер
+                // коллекции, не выкачивая её.
                 if (group === "head") {
-                    return okResult({ status: res.status, endpointId: entry.id });
+                    return okResult({ status: res.status, endpointId: entry.id, ...headerMeta(res, true) });
                 }
                 if (applied.length > 0) {
                     return okResult({
                         appliedDefaults: applied,
                         status: res.status,
                         data: res.data ?? null,
+                        ...headerMeta(res),
                     });
                 }
                 // Пустое тело ответа (204/200 без содержимого) — валидный успех:
                 // отдаём статус, иначе результат инструмента оказался бы пустым.
                 if (res.data === undefined) {
-                    return okResult({ status: res.status, endpointId: entry.id, data: null });
+                    return okResult({ status: res.status, endpointId: entry.id, data: null, ...headerMeta(res) });
                 }
-                return okResult(res.data);
+                // Обычный ответ отдаём как есть: обёртка появляется только когда пришёл
+                // `Content-Range`, то есть когда вызывающий сам просил страницу.
+                const meta = headerMeta(res);
+                return okResult("contentRange" in meta ? { ...meta, data: res.data } : res.data);
             }
             catch (err) {
                 return failResult(err);

package/docs/guides/attributes.md

@@ -82,7 +82,100 @@ GET    COMMON:GET:/Attributes/{attributeID}/listOfValues
 порядку), `value` — то, что видит пользователь. Запрос заменяет список
 значений целиком: чтобы удалить значение, отправь набор без него.
 
-## 3. Где ещё используются атрибуты
+## 3. Как передаётся значение атрибута
+
+Одно и то же поле в разных сущностях заполняется **по-разному**. Это главный
+источник ошибок с атрибутами: код, отлаженный на заявке, на выполненной работе
+молча не сработает. Общее только одно — значение всегда ссылается на `key` из
+`listOfValues`, а не на отображаемый текст.
+
+| Сущность | Метод записи | Форма `value` | Мультисписок |
+| --- | --- | --- | --- |
+| Заявка | `WORK:POST:/TaskAttributes`, тело `[{ taskID, data: [...] }]` | строка, обязательна | `"12\|15"` |
+| Объект | `ES:POST:/AssetAttributes/v2`, тело `[{ assetID, data: [...] }]` | строка, обязательна | `"12\|15"` |
+| Выполненная работа | `WORK:PUT:/Tasks/{taskID}/completedWorks/{completedWorkID}/attributes`, тело — **плоский** массив | **массив строк**, необязателен | `["12", "15"]` |
+| Пункт чек-листа | `WORK:PUT:/Tasks/{taskID}/checkLists/{taskCheckListID}/results/v2` | **массив строк** в поле `values` | `["12", "15"]` |
+
+Отсюда три следствия:
+
+- **Скаляр в выполненной работе и чек-листе — тоже массив.** Строка, число,
+  дата и одиночный `Select` передаются как массив из одного элемента:
+  `{ "attributeID": 10, "value": ["3"] }`. Отправишь голую строку — получишь
+  ошибку типа, а не молчаливое сохранение.
+- **Ключ элемента разный.** У заявки и объекта элемент адресуется `attributeID`,
+  у чек-листа — `id` **пункта** чек-листа (не атрибута), и рядом обязателен
+  `isChecked`.
+- **Поле чтения тоже разное.** У заявки и объекта заполненное значение приходит
+  в `value` строкой, у выполненной работы и чек-листа — в `values` массивом.
+  Пустое у заявки — отсутствующий ключ, у выполненной работы — пустой массив
+  `values: []`.
+
+### Как выглядит прочитанное значение
+
+Проверено на заявке с заполненными полями всех типов: значение всегда строка
+(в заявке и объекте) или элемент массива строк (в выполненной работе и
+чек-листе) — своих типов у API нет ни для чисел, ни для флажков.
+
+```json
+{ "attributeID": 12, "value": "39|50|67" }   // MultiSelect: ключи по возрастанию
+{ "attributeID": 10, "value": "10" }         // Select: один ключ
+{ "attributeID": 13, "value": "true" }       // Switch: строка, не булево
+{ "attributeID": 16, "value": "123" }        // Int
+{ "attributeID": 9,  "value": "12.3323" }    // Decimal
+{ "attributeID": 7,  "value": "2026-09-09T12:00:00" }       // Date: без таймзоны
+{ "attributeID": 8,  "value": "2026-09-09T20:59:00.000Z" }  // Datetime: UTC с Z и мс
+{ "attributeID": 14, "value": "" }           // незаполненный Drawing
+```
+
+Два подвоха:
+
+- **`Date` и `Datetime` — разные форматы.** Первый без таймзоны, второй в UTC с
+  `Z` и миллисекундами. Обработаешь одинаково — получишь сдвиг на часовой пояс
+  без всякой ошибки от сервера.
+- **Пустое значение приходит по-разному.** Если доп. поля заявки ни разу не
+  сохраняли, ключа `value` в объекте нет вовсе; после сохранения формы
+  незаполненные поля приходят пустой строкой `""`. Проверяй оба случая.
+
+### Как надёжно определить мультисписок
+
+Признак зависит от того, откуда читаешь, и одного универсального нет:
+
+| Источник | Что есть | Признак |
+| --- | --- | --- |
+| `WORK:GET:/Tasks/{taskID}/attributes` | `attributeType.code` | `code === "MultiSelect"` |
+| `WORK:GET:/TaskAttributes` (query `taskID`) | типа нет вообще | только непустой `listOfValues` |
+| `.../completedWorks/{completedWorkID}/attributes` | `attributeType.code` и `selectionMode` | `selectionMode.id === 2` («Мультивыбор») |
+| `WORK:GET:/Tasks/{taskID}/meta` | `attributeType.code` | `code === "MultiSelect"` |
+
+Коды типов — CamelCase, ровно как их отдаёт `COMMON:GET:/AttributeTypes`:
+`String`, `Int`, `Decimal`, `Date`, `Datetime`, `Select`, `MultiSelect`, `Text`,
+`Switch`, `Attachment`, `Drawing`. Сравнение с `"MULTISELECT"` не совпадёт
+никогда и при этом не упадёт. `selectionMode` — самый явный признак, но он есть
+только у доп. полей выполненной работы; там же `Drawing` помечен мультивыбором,
+хотя списком значений не является.
+
+### Атрибуты-справочники (`domain`)
+
+У атрибута может быть `domain` — тогда это не свой список значений, а ссылка на
+сущность системы: `1` — объекты, `2` — компании, `3` — сотрудники, `4` —
+заказчики, `5` — материалы. Отличия от обычного списка:
+
+- ключи `listOfValues` — это id сущностей, а не порядковые номера значений;
+- сами значения приходят **JSON-строками**, а не готовыми подписями:
+  `{"Name": "..."}` у объектов, компаний и материалов, `{"FirstName": "...",
+  "LastName": "...", "MiddleName": "..."}` у сотрудников и заказчиков. Чтобы
+  показать значение пользователю, эту строку надо распарсить;
+- формат записи при этом обычный — те же ключи через `|` или массив, в
+  зависимости от сущности из таблицы выше.
+
+### Очистка значения
+
+Схема `WORK:POST:/TaskAttributes` объявляет `value` обязательной непустой
+строкой, но для снятия значения клиенты передают `null` — пустая строка не
+подходит. У выполненной работы `value` объявлен nullable, у чек-листа очистка —
+это `isChecked: false` вместе с `values: []`.
+
+## 4. Где ещё используются атрибуты
 
 - **Чек-листы**: атрибут задаёт способ ответа на пункт (число, дата, список,
   вложение) — `hubex_get_guide topic="checklisttemplates"`, фильтр
@@ -123,3 +216,10 @@ hubex_request_read(endpointId: `COMMON:GET:/Attributes/{attributeID}/listOfValue
   подтверждению пользователя.
 - В списках атрибутов почти всегда нужен фильтр `isDeleted=false`: удалённые
   поля продолжают возвращаться.
+- Значение списочного поля сервер не валидирует: запись отображаемого текста
+  вместо `key` проходит с `202` и читается обратно как есть, но в интерфейсе
+  поле выглядит пустым. Ключи бери из
+  `COMMON:GET:/Attributes/{attributeID}/listOfValues`.
+- Определять списочный тип по `attributeType.code` можно не везде:
+  `WORK:GET:/TaskAttributes` с query `taskID` не возвращает тип вовсе, только
+  `listOfValues`. Универсальный признак — непустой `listOfValues`.

package/docs/guides/dictionaries.md

@@ -24,7 +24,10 @@ sources:
   жизненного цикла, срок закрытия по умолчанию и разрешённые виды работ.
   Обязателен при создании заявки.
 - **Способ подачи заявки** — `WORK:GET:/RequestMethods`. Обязателен при
-  создании заявки; для интеграций используется значение 4.
+  создании заявки. Числа не значат того, что кажется: в проверенном тенанте
+  `4` — это «Другое», а «Импорт» — `6`; отдельного «интеграции» может не быть
+  вовсе. Выбирай по `name` из живого списка и уточняй у пользователя, а не
+  подставляй число из примеров.
 - **Статус заявки** — `WORK:GET:/TaskStatuses`. Визуальное отображение
   стадии для мобильного приложения заказчика, привязывается к стадии в
   жизненном цикле — не назначается заявке напрямую произвольным значением.
@@ -62,3 +65,42 @@ sources:
   специфичны для тенанта — перед подстановкой ID в тело запроса всегда
   сверяйся с актуальным списком через соответствующий `GET`, а не полагайся
   на значения из документации или прошлых сессий.
+- Большие справочники не выбираются одним запросом. `ES:GET:/Assets` и
+  `WORK:GET:/WorkTypes` поддерживают заголовочную пагинацию — в
+  `hubex_request_read` это параметр `headers`:
+
+  ```text
+  hubex_request_read(endpointId: `ES:GET:/Assets`, headers: { "Range": "items=0-4999" })
+  → { "contentRange": "items=1-4999/22721", "data": { ... } }
+  ```
+
+  **Границы 1-индексные и включают оба конца.** Нумерация начинается с `1`, а
+  не с `0`: `items=1-10` возвращает ровно 10 записей (позиции 1–10), следующая
+  страница — `items=11-20`, без пропусков и повторов. Ноль в начале молча
+  приводится к единице, поэтому `items=0-9` вернёт **9** записей, а не 10, и
+  `Content-Range` честно скажет `items=1-9/70`.
+
+  Отсюда две ошибки, каждая из которых теряет данные молча:
+
+  - **«страница короче запрошенной — значит последняя»** неверно. После
+    `items=0-9` придёт 9 записей из 70; приняв это за конец, потеряешь 61.
+    Единственный признак конца — сравнение правой границы `Content-Range` с
+    числом после дроби.
+  - **следующая страница начинается с `конец + 1`**, а не с `конец`. `items=9-18`
+    после `items=0-9` повторит девятую запись.
+
+  Один большой `Range` на всю коллекцию сервер может обрезать без ошибки и без
+  признака неполноты, поэтому читай страницами и в конце сверяй итог с общим
+  числом — иначе получишь уверенное «такой записи нет» на записи, которая есть.
+
+  И последнее: порядок записей — **лексикографический по ключу-строке**, а не
+  числовой. У справочника с ключами 1…70 позиция 10 — это `"18"`, а позиция 12 —
+  `"2"`. Границы страниц по числовым id не восстанавливаются.
+- `published` у видов работ (`WORK:GET:/WorkTypes`) и объектов
+  (`ES:GET:/Assets`) — это **дата** публикации (`"2024-06-17T12:55:20"`), а не
+  булев флаг. У неопубликованной записи ключа нет вовсе, а не `null` или
+  `false`: проверяй наличие ключа, а не его значение.
+- Ключ словаря — это id, и внутри объекта он есть не всегда. У
+  `WORK:GET:/WorkTypes`, `WORK:GET:/RequestMethods`, `ES:GET:/AssetTypes` и
+  `COMMON:GET:/AttributeTypes` поля `id` в объекте нет — только ключ; у
+  `ES:GET:/Assets`, наоборот, есть. Универсально безопасно брать id из ключа.

package/docs/guides/roles.md

@@ -91,8 +91,11 @@ DELETE ADM:DELETE:/PermissionsUi
   `taskTypeID` — что доступно сейчас (компоненты и дополнительные поля).
 - `TSTG:POST:/TaskStageComponents` — запись доступности:
   `[{ "taskStageID": 12, "taskTypeID": 5, "components": [{ "id": 3, "roleID": 7, "capabilityID": 2 }], "attributes": [...] }]`.
-- Справочник уровней доступа (только чтение / чтение и запись / скрыто) —
-  `ADM:GET:/Capabilities`.
+- Справочник уровней доступа — `ADM:GET:/Capabilities`. Отдаёт пять записей с
+  полем `weightCoefficient`: `RO`=1 (только чтение), `RW`=2 (чтение и запись),
+  `RWM`=3 (обязательная запись), `RWE`=4 (эксклюзивная запись), `RWME`=5
+  (обязательная эксклюзивная). Кода `ROM`, который встречается в метаданных
+  формы, в этом справочнике нет.
 - Доступ к дополнительным полям вне контекста стадии —
   `ADM:GET:/RoleTaskPropertiesAccess/attributes`,
   `ADM:POST:/RoleTaskPropertiesAccess/attributes`,
@@ -123,3 +126,11 @@ hubex_request_read(endpointId: `ADM:GET:/Roles/{roleID}/permissionsUi`, pathPara
 - Роли и участки — разные измерения доступа: роль определяет, что можно
   делать, участок (`ADM:POST:/UserDistricts`) — с какими объектами и типами
   заявок.
+- Права нескольких ролей складываются по **максимуму** веса из
+  `ADM:GET:/Capabilities`, то есть побеждает более строгий уровень: поле,
+  помеченное `RWM` хотя бы в одной роли, обязательно для каждого, у кого эта
+  роль есть.
+- Следствие для тестирования: аккаунт со всеми ролями тенанта видит почти
+  каждое поле обязательным и потому непригоден для проверки обязательности.
+  Нужен узкий тестовый аккаунт — либо одна выделенная роль с `RWM` как чистый
+  однофакторный эксперимент.

package/docs/guides/start.md

@@ -20,7 +20,10 @@ HubEx REST API организован по сервисам: у каждого
   (`WORK`, `ES`, `ADM`, `AUTHZ`, `AUTHN`, `PA`, `SLA` и т.д.).
 - Каждый запрос требует **два** заголовка: `Authorization: Bearer <access_token>`
   и `X-Application-ID: <id приложения>`. Без второго заголовка сервер вернёт
-  ошибку 403 «Не найден обязательный заголовок [X-Application-ID]».
+  ошибку 403 «Не найден обязательный заголовок [X-Application-ID]». Значение
+  различает клиента: `5` — Api/интеграции, `3` — MainWeb. Часть операций
+  доступна не при любом значении, поэтому подставлять произвольное число
+  нельзя.
 - Access-токен — JWT, действует ограниченное время (в вики указано 30 минут)
   и получается отдельным запросом по сервисному токену; для этого сервера
   обновление токена уже реализовано отдельным механизмом авторизации — вручную
@@ -69,3 +72,16 @@ HubEx REST API организован по сервисам: у каждого
 - `PUT` требует полное тело записи (все поля, включая неизменяемые в этом
   запросе), а не только то, что меняется — для частичного обновления
   используй `PATCH`, если эндпоинт его поддерживает.
+- На больших справочниках (`ES:GET:/Assets`, `WORK:GET:/WorkTypes`) вместо
+  `fetch`/`offset` работает заголовочная пагинация: передай
+  `headers: { "Range": "items=1-5000" }`, общее число вернётся в поле
+  `contentRange` (`items=1-5000/22721`) рядом с `data`. Границы **1-индексные и
+  включают оба конца**: начинай с `1` (не с `0`), следующая страница — с
+  `конец + 1`. Признак конца — только правая граница против числа после дроби:
+  короткая страница последней не означает. Подробности — `hubex_get_guide
+  topic="dictionaries"`.
+- Пустое значение почти никогда не приходит как `null`. Чаще всего это
+  **отсутствие ключа**: у неопубликованной записи нет поля `published`, у
+  заявки — нет массива `attribute`. Но не всегда: незаполненный атрибут
+  приходит то без ключа `value`, то пустой строкой `""` — в зависимости от
+  того, сохраняли ли форму. Проверяй и отсутствие ключа, и пустое значение.

package/docs/guides/taskcreate.md

@@ -44,6 +44,13 @@ sources:
    | `RWM` | можно писать, **обязательно** (M = mandatory) |
    | `ROM` | обязательно, но заполняется системой |
 
+   Полный справочник кодов — `ADM:GET:/Capabilities`: кроме перечисленных, он
+   отдаёт `RWE` и `RWME`. Если у пользователя несколько ролей, права
+   складываются по **максимуму** веса (`RO`=1, `RW`=2, `RWM`=3, `RWE`=4,
+   `RWME`=5), то есть побеждает более строгий уровень: поле, помеченное `RWM`
+   хотя бы в одной роли, обязательно для всех её носителей. Подробнее —
+   `hubex_get_guide topic="roles"`.
+
    Именно из `capability` берётся обязательность `companyID`, `assetID`, `workTypeID`,
    `payerCompanyID`, `notes`, `contactPerson`, `contactPhone`, `locationID`,
    `estimatedCost`, `attachments` и т.д. — она **разная у разных типов заявок и
@@ -70,8 +77,10 @@ sources:
    - `capability` = `RO`/`ROM` → **не передавай**, заполняется системой.
 4. Сопоставь обязательные поля с тем, что пользователь уже сказал. Значения, которые
    можно вывести однозначно (`requestedByUserID` = текущий пользователь,
-   `criticalityID` = запись с `isDefault: true`, `requestMethodID` = 4 для интеграций,
-   `companyID` и адрес = из выбранного объекта), подставляй сам и упомяни это в ответе.
+   `criticalityID` = запись с `isDefault: true`, `companyID` и адрес = из выбранного
+   объекта), подставляй сам и упомяни это в ответе. `requestMethodID` так вывести
+   нельзя: способ подачи для интеграций свой в каждом тенанте — бери его из
+   `WORK:GET:/RequestMethods`.
 5. **Одним сообщением спроси только про те обязательные поля, которые остались
    незакрытыми**, и для каждого справочного поля сразу приложи варианты из
    соответствующего справочника (шаг 1). Не задавай вопросы по одному
@@ -125,7 +134,14 @@ sources:
 
 `WORK:POST:/Tasks` — тело **один объект** (не массив, в отличие от большинства
 POST-методов HubEx). Опциональный заголовок `X-Concurrency-Stamp` (Guid) даёт
-идемпотентность: повтор с тем же значением вернёт 409.
+идемпотентность: повтор с тем же значением вернёт 409. В `hubex_request_write`
+он передаётся параметром `headers`:
+`headers: { "X-Concurrency-Stamp": "<guid>" }`.
+
+Если ответ на POST потерялся (таймаут, обрыв соединения), `409 AlreadyExists`
+на повторе означает «сервер уже создал эту заявку», а не «дубликат был раньше».
+Не делай вывод по коду ответа: найди запись по естественному ключу —
+`WORK:GET:/Tasks` с query `taskNumber=…` — и считай непустой ответ успехом.
 
 Ответ 201: `{ "id": 12345, "number": "T-12345", "concurrencyStamp": "..." }` —
 `id` и есть `taskID` для всех последующих шагов.
@@ -133,7 +149,10 @@ POST-методов HubEx). Опциональный заголовок `X-Concu
 ### Обязательный минимум
 
 - `taskTypeID` — тип заявки;
-- `requestMethodID` — способ подачи (для интеграций — 4, веб по умолчанию шлёт 1);
+- `requestMethodID` — способ подачи. Значение пер-тенантное: где-то интеграции
+  идут с `4`, где-то требуется `6` («Импорт»), причём поле обязательно вопреки
+  схеме — без него `409 ParameterOutOfRange`. Выбирай из
+  `WORK:GET:/RequestMethods`, а не по памяти;
 - `criticalityID` — критичность. Берётся из `SLA:GET:/Criticalities`, дефолт —
   запись с `isDefault: true`. Формально в схеме необязательна, но клиент считает
   её обязательной всегда, и заявка без критичности не проходит по SLA.
@@ -146,7 +165,7 @@ POST-методов HubEx). Опциональный заголовок `X-Concu
 | Поле | Значение |
 | --- | --- |
 | `taskTypeID` | выбранный тип |
-| `requestMethodID` | способ подачи, по умолчанию 1 |
+| `requestMethodID` | способ подачи; веб шлёт 1, у интеграций значение своё в каждом тенанте |
 | `criticalityID` | критичность по умолчанию |
 | `requestedByUserID` | текущий пользователь (заявитель) |
 | `faultTimestamp` | момент обнаружения неисправности; по умолчанию сегодня, 12:00, формат **без таймзоны** `YYYY-MM-DDTHH:mm:ss` |
@@ -196,9 +215,13 @@ ISO 8601 в UTC; `faultTimestamp` — локальное время без та
 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`.
+   `value` всегда строка — и у чисел, и у флажков: для `Select`/`MultiSelect` —
+   ключи значений через `|` (`"39|50|67"`), для `Attachment`/`Drawing` — id
+   вложений через `|`, для `Date` — `YYYY-MM-DDTHH:mm:ss` без таймзоны, для
+   `Datetime` — UTC с `Z` (`"2026-09-09T20:59:00.000Z"`), для `Switch` —
+   `"true"`/`"false"`. Коды типов — CamelCase, как их отдаёт
+   `COMMON:GET:/AttributeTypes`. В выполненных работах и чек-листах то же
+   значение передаётся массивом: `hubex_get_guide topic="attributes"`.
 3. **Контакты заявки** — `WORK:POST:/TaskContacts`, тело массив:
    `[{ taskID, data: [contactID, ...] }]`. Удаление — `WORK:DELETE:/TaskContacts`
    с тем же форматом. Список контактов — из контактов объекта/компании (шаг 1, п. 9).
@@ -258,3 +281,7 @@ ISO 8601 в UTC; `faultTimestamp` — локальное время без та
 - **Заявка без объекта и компании создастся**, но будет бесполезна: по ней не
   подберётся SLA, договор и исполнитель. Для осмысленного теста указывай
   `companyID` + `assetID` + `workTypeID`.
+- **Сетевая ошибка ≠ «ничего не создано».** Скрипт, упавший между
+  `POST /Tasks` и `POST /TaskAssignmentHistory`, оставляет заявку созданной, но
+  без исполнителя. Перед повтором любого шага перечитывай фактическое состояние,
+  а не начинай последовательность заново.

package/docs/guides/taskedit.md

@@ -39,6 +39,31 @@ sources:
 | `RWM` | поле доступно и обязательно; после изменения не оставляй его пустым |
 | `ROM` | обязательное системное поле, не передавай его вручную |
 
+Полный справочник кодов — `ADM:GET:/Capabilities`: кроме перечисленных, есть
+`RWE` и `RWME`. Если у пользователя несколько ролей, права складываются по
+**максимуму** веса (`RO`=1, `RW`=2, `RWM`=3, `RWE`=4, `RWME`=5) — обязательность,
+заданная в одной роли, действует на всех её носителей.
+
+`meta` — источник **прав**, но не значений: значения в нём не приходят вовсе
+(поле `value` либо отсутствует, либо `null`), в том числе у заведомо заполненных
+полей. Читать значения оттуда нельзя — каждое поле покажется пустым, ошибка не
+проявится ничем, и агент затрёт чужие данные, «дозаполняя» уже заполненное.
+Заодно не рассчитывай, что `capability` там будет всегда: в части тенантов
+`components` приходит словарём пустых объектов `{}`, и обязательность из `meta`
+не выводится совсем.
+
+Значения дополнительных полей бери из `WORK:GET:/Tasks/{taskID}/attributes` или
+`WORK:GET:/TaskAttributes` с query `taskID`. Оба возвращают **массив** (не
+словарь по id, вопреки общему правилу гайда `start`) и перечисляют все атрибуты
+типа заявки, включая незаполненные. Пустое значение приходит **двумя разными
+способами**: у заявки, где доп. поля ни разу не сохраняли, ключа `value` нет
+вовсе; после сохранения формы незаполненные поля приходят пустой строкой `""`.
+Проверяй оба случая сразу, иначе «пусто» примешь за «заполнено».
+
+Карточка заявки для чтения доп. полей не годится: на проверенном тенанте
+`WORK:GET:/Tasks/{taskID}` не содержит массива `attribute` вообще — ни когда
+значения пустые, ни когда они заполнены. Всегда читай их отдельным запросом.
+
 Не используй права, прочитанные до смены стадии: после перехода обязательно
 повтори `WORK:GET:/Tasks/{taskID}/meta`.
 
@@ -153,10 +178,38 @@ MainApp отправляет новое назначение, когда изм
 ]
 ```
 
-`value` — строка: для `SELECT`/`MULTISELECT` это id значений через `|`, для
-`DATE` — `YYYY-MM-DDTHH:mm:ss`, для `ATTACHMENT`/`DRAWING` — id вложений через
-`|`. Новые вложения сначала загрузить, затем передать их id. Не стирай
-обязательный (`RWM`) атрибут.
+`value` — всегда строка, даже у чисел и флажков:
+
+| Тип | Как выглядит значение |
+| --- | --- |
+| `Select` | один ключ: `"10"` |
+| `MultiSelect` | ключи через `\|` по возрастанию: `"39\|50\|67"` |
+| `Attachment`, `Drawing` | id вложений через `\|` |
+| `Date` | `"2026-09-09T12:00:00"` — **без** таймзоны |
+| `Datetime` | `"2026-09-09T20:59:00.000Z"` — UTC, с `Z` и миллисекундами |
+| `Switch` | строка `"true"` / `"false"`, не булево |
+| `Int`, `Decimal` | `"123"`, `"12.3323"` — строкой |
+
+`Date` и `Datetime` возвращаются в разных форматах: считать их одинаковыми —
+готовый сдвиг на часовой пояс. Новые вложения сначала загрузить, затем передать
+их id. Не стирай обязательный (`RWM`) атрибут. Коды типов пишутся именно так, в
+CamelCase (`COMMON:GET:/AttributeTypes`): сравнение с `"SELECT"` не совпадёт
+никогда. У выполненной работы и чек-листа то же значение передаётся иначе —
+сводная таблица в `hubex_get_guide topic="attributes"`.
+
+Значение `Select`/`MultiSelect` сервер не проверяет: `WORK:POST:/TaskAttributes`
+с отображаемым текстом вместо ключа вернёт `202`, следующий `GET` отдаст этот
+текст обратно без изменений — а в интерфейсе поле будет выглядеть пустым, потому
+что текст не совпал ни с одним ключом. Ошибку видно только сплошной
+перепроверкой постфактум, поэтому ключи бери из `listOfValues`, а не из того,
+что показывает интерфейс.
+
+Как понять, что поле списочное: `WORK:GET:/Tasks/{taskID}/attributes` возвращает
+`attributeType` с `code`, а `WORK:GET:/TaskAttributes` с query `taskID` — не
+возвращает его вовсе, только `attributeName` и `listOfValues`. Надёжный признак,
+работающий на обоих, — **непустой `listOfValues`**; проверка
+`attributeType.code === "Select"` на втором эндпоинте не срабатывает никогда и
+при этом не падает.
 
 ### Файлы заявки
 
@@ -203,6 +256,30 @@ MainApp отправляет новое назначение, когда изм
 Используй их только когда пользователь меняет именно эту часть; полные формы
 тел обязательно сверяй через `hubex_describe_endpoint`.
 
+Выполненные работы нарушают сразу четыре общих правила — каждое отличие легко
+принять за «запись создалась неправильно» на корректных данных:
+
+- `WORK:GET:/Tasks/{taskID}/completedWorks` возвращает **список**, а не словарь
+  по id — единственное известное исключение из правила гайда `start`;
+- исполнителей в нём нет: они в
+  `WORK:GET:/Tasks/{taskID}/completedWorks/{completedWorkID}/technicians` (одна
+  работа) или `WORK:GET:/Tasks/{taskID}/completedWorks/technicians` (все работы
+  заявки, словарём по номеру работы);
+- id выполненной работы нумеруется внутри заявки (1, 2, 3…), а не глобально —
+  именно этот номер ждёт эндпоинт исполнителей;
+- `quantity` и `measurementUnit` HubEx считает сам из `started`/`finished`
+  (13:33→15:15 даёт `quantity: 1.7` и единицу «Час») — отправлять их не нужно;
+- доп. поля работы читаются и пишутся полем `values` (**массив**), а не `value`:
+  `WORK:GET|PUT:/Tasks/{taskID}/completedWorks/{completedWorkID}/attributes`.
+  Там же приходит `selectionMode` (`1` — одно значение, `2` — мультивыбор) —
+  самый явный признак списочности из всех мест. Подробности и сравнение с
+  заявкой — `hubex_get_guide topic="attributes"`.
+
+Естественного ключа у выполненной работы нет: слепой повтор `POST` после
+таймаута молча удваивает строки, и настоящие от дублей потом не отличить. Перед
+повтором прочитай `WORK:GET:/Tasks/{taskID}/completedWorks` и считай непустой
+ответ успехом.
+
 ## 6. Чек-листы и стадия
 
 Добавление или снятие шаблона чек-листа с заявки выполняется через
@@ -235,6 +312,37 @@ MainApp отправляет новое назначение, когда изм
 `SignedByCustomer` (загрузить подпись). Сначала выполни их и проверь результаты,
 затем делай переход. После него перечитай карточку и `meta`.
 
+Для нескольких заявок сразу есть массовый `WORK:GET:/Tasks/stages/next`. Список
+заявок передаётся query-параметром **`id`** (массив); с другим именем параметра
+сервер молча отвечает `204` и пустым телом, а не ошибкой. Живой ответ не
+совпадает со сгенерированной схемой: это не `map<ListStagesResult>`, а список
+групп по типу заявки —
+
+```json
+[
+  {
+    "taskTypeID": 5,
+    "currentStage": { "id": 3, "name": "Новая" },
+    "nextStages": [
+      {
+        "nextStage": { "id": 9, "name": "В работе", "color": "#1E88E5" },
+        "linkName": "Взять в работу",
+        "sortOrder": 1
+      }
+    ],
+    "tasks": [12345, 12346],
+    "error": ""
+  }
+]
+```
+
+Целевой `taskStageID` лежит в `nextStages[i].nextStage.id`. Сопоставлять стадию
+нужно по `nextStage.name`, а не по `linkName`: `linkName` — подпись кнопки
+перехода, и она регулярно отличается от названия стадии назначения (стадия
+«Отказ исполнителя» с кнопкой «Отказаться от заявки», «Исполнитель назначен» с
+кнопкой «Назначение исполнителя»). `sortOrder` внутри `nextStages` не уникален —
+сортировать по нему как по ключу нельзя.
+
 ## 7. Удаление и восстановление
 
 Удалить заявку: `WORK:DELETE:/Tasks/{taskID}`. Это отдельное, потенциально
@@ -263,10 +371,19 @@ PATCH основной карточки
 чек-листе, назначении или атрибуте должна быть видна до попытки финального
 перехода.
 
+Проверяя результат, следи за именами полей: в ответе они не те, которыми поле
+называют в задаче. У карточки заявки нет `criticality`, `deadline` и `stage` на
+верхнем уровне — есть `requestedCriticality` / `actualCriticality`,
+`timesheet.deadline` и `taskStage`. Не делай вывод «не сохранилось», не убедившись,
+что читаешь именно то поле.
+
 ## Подводные камни
 
 - Права и обязательность динамические: источник правды —
   `WORK:GET:/Tasks/{taskID}/meta`, а не swagger и не значения другой заявки.
+- `meta` даёт права, но **не значения**: значений там нет вообще, включая
+  заполненные поля. Значения — только из `WORK:GET:/Tasks/{taskID}/attributes`
+  или `WORK:GET:/TaskAttributes` с query `taskID`.
 - `PATCH /Tasks/{taskID}` принимает массив `{ field, value }`; почти все
   соседние методы принимают объект либо массив объектов с `taskID` и `data`.
 - Не очищай поля значением `null` по умолчанию. `null` в PATCH — это явная

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hubex/mcp",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "MCP server for managing HubEx test data (tasks, assets, companies, users) via the HubEx REST API",
   "author": "HubEx Team",