@hubex/mcp 0.10.0 → 0.11.0

package/dist/tools/guides.js

@@ -20,6 +20,7 @@ const TOPIC_GROUPS = [
             taskcreate: "создание заявки: метаданные формы, обязательные поля, справочники, порядок вызовов",
             taskedit: "редактирование заявки: правка полей, стадии и статусы, работы и материалы, удаление",
             taskchecklists: "чек-листы в заявке: заполнение пунктов, вложения, сохранение и переход стадии",
+            plannedtasks: "плановые заявки: шаблон заявки, расписание PMP, активация, точки срабатывания",
         },
     },
     {

package/dist/tools/request.js

@@ -37,23 +37,38 @@ export function applyDefaults(body, defaults) {
     }
     return { body: out, applied };
 }
-function resolvePath(entry, pathParams) {
+/**
+ * Значение параметра без учёта регистра имени: в swagger HubEx объявленное имя
+ * и плейсхолдер в пути расходятся регистром (`taskTemplateID` против
+ * `{taskTemplateId}`), и модель может передать любой из вариантов.
+ */
+function lookupParam(params, name) {
+    if (Object.hasOwn(params, name))
+        return params[name];
+    const lower = name.toLowerCase();
+    const key = Object.keys(params).find((k) => k.toLowerCase() === lower);
+    return key === undefined ? undefined : params[key];
+}
+export function resolvePath(entry, pathParams) {
     const missing = entry.pathParams.filter((name) => {
-        const v = pathParams[name];
+        const v = lookupParam(pathParams, name);
         return v === undefined || v === null || v === "";
     });
     if (missing.length > 0) {
         throw new Error(`Не хватает обязательных path-параметров для ${entry.id}: ${missing.join(", ")}. ` +
             `Передай их в объекте pathParams.`);
     }
-    let path = entry.path;
-    for (const name of entry.pathParams) {
-        path = path.replace(`{${name}}`, encodeURIComponent(String(pathParams[name])));
-    }
+    const declared = new Map(entry.pathParams.map((name) => [name.toLowerCase(), name]));
+    const path = entry.path.replace(/\{([^}]+)\}/g, (placeholder, name) => {
+        const declaredName = declared.get(name.toLowerCase());
+        if (declaredName === undefined)
+            return placeholder;
+        return encodeURIComponent(String(lookupParam(pathParams, declaredName)));
+    });
     const unresolved = path.match(/\{[^}]+\}/g);
     if (unresolved) {
         throw new Error(`Не удалось подставить параметры пути для ${entry.id}: остались незаменённые ${unresolved.join(", ")}. ` +
-            `Объявленные параметры: ${entry.pathParams.join(", ")}. Проверь точное написание имён (регистр может отличаться от текста в пути) через hubex_describe_endpoint.`);
+            `Объявленные параметры: ${entry.pathParams.join(", ")}. В swagger этого эндпоинта плейсхолдер не объявлен — сверь схему через hubex_describe_endpoint.`);
     }
     return path;
 }
@@ -83,7 +98,7 @@ function requestTool(group, deps) {
         },
         pathParams: {
             type: "object",
-            description: "Значения параметров пути, например { \"taskID\": 42 }.",
+            description: "Значения параметров пути, например { \"taskID\": 42 }. Регистр имён не важен.",
         },
         query: { type: "object", description: "Query-параметры запроса." },
         headers: {

package/docs/guides/plannedtasks.md

@@ -0,0 +1,165 @@
+---
+topic: plannedtasks
+sources:
+  - page: mainapp/src/modules/plannedTaskCreateForms.js
+    content_hash: bd3012b5664edf6a
+  - page: mainapp/src/modules/plannedTaskEditForms.js
+    content_hash: a760154e74211900
+  - page: mainapp/src/pages/plannedTaskEditForm/TopBar.jsx
+    content_hash: 5786556ba8917e33
+  - page: mainapp/src/utils/date.js
+    content_hash: 1fe8704c1a74013e
+---
+
+# Плановые заявки: шаблон и расписание
+
+Плановая заявка — это **шаблон заявки** (WORK), к которому привязано
+**расписание** (PMP). Пока расписание активно, HubEx сам создаёт заявки по
+шаблону в точках срабатывания. Расписание хранится в PMP, а привязка к
+шаблону и включение/выключение — в WORK.
+
+Веб-клиент (MainApp) создаёт плановую заявку в таком порядке:
+
+```text
+POST WORK:POST:/TaskTemplates                       → [taskTemplateID]
+POST WORK:POST:/TaskTemplateExcludedAssets          → исключённые объекты (если есть)
+POST WORK:POST:/TaskTemplates/{id}/assignment       → исполнители (если не автоназначение)
+POST PMP:POST:/Schedules                            → [scheduleID]
+POST WORK:POST:/TaskTemplates/{id}/schedules        → привязка расписания к шаблону
+PUT  WORK:PUT:/TaskTemplates/{taskTemplateId}/schedules/{scheduleId}/activate
+```
+
+Последний шаг веб-клиент выполняет только по кнопке «Запланировать»; кнопка
+«Сохранить» оставляет расписание **неактивным** — заявки не создаются.
+
+## 1. Шаблон заявки
+
+`WORK:POST:/TaskTemplates` принимает массив, ответ — массив идентификаторов.
+Поля, которые заполняет веб-клиент:
+
+```json
+[
+  {
+    "name": "Сменный отчёт — день",
+    "taskTypeID": 3,
+    "workTypeID": 12,
+    "criticalityID": 2,
+    "code": "SHIFT-DAY",
+    "notes": "Описание, попадёт в заявку",
+    "estimatedTimeConsumptionMinutes": 60,
+    "estimatedCost": 0,
+    "requestMethodID": 1,
+    "assetFilter": { "assets": [101, 102] }
+  }
+]
+```
+
+- `assetFilter` — по каким объектам создавать заявки: `assets`,
+  `assetTypes`, `assetClasses`, `companies`, `districts`, `responsiblePersons`,
+  `workTypes`, `taskTypes` (массивы id), `warrantyPeriod` (`from`/`till`).
+- Исключить объекты из фильтра — `WORK:POST:/TaskTemplateExcludedAssets`,
+  тело `[{ "taskTemplateID": "<id>", "data": [assetID, ...] }]`.
+- Исполнители — `WORK:POST:/TaskTemplates/{id}/assignment`, тело — массив
+  `userID`. Пустой массив `[]` снимает назначенных ранее исполнителей; так
+  веб-клиент включает автоназначение.
+- Изменение — `WORK:PUT:/TaskTemplates` (массив с `id`), чтение —
+  `WORK:GET:/TaskTemplates/{id}`.
+
+## 2. Расписание
+
+`PMP:POST:/Schedules` создаёт **или обновляет** расписания: элемент без `id`
+создаёт новое, с `id` — перезаписывает существующее. Ответ — массив
+идентификаторов.
+
+```json
+[
+  {
+    "frequencyTypeID": 2,
+    "options": {
+      "Name": "Daily",
+      "DateFrom": "2026-10-20T00:00:00",
+      "DateTill": "2027-10-20T00:00:00",
+      "Frequency": { "AppointmentTimes": ["05:00"], "EachDayNumber": [1] }
+    }
+  }
+]
+```
+
+**Формат `options` бери отсюда, а не из swagger.** В swagger поле объявлено
+строкой с примером `{"interval":1,"timeOfDay":"10:00:00"}`, но веб-клиент
+такой формат не пишет и не читает. Он передаёт объект с ключами в PascalCase:
+
+- `Name` — код частоты: `DuringTheDay`, `Daily`, `Weekly`, `Monthly`
+  (`MonthlyLastDay`, если выбран последний день месяца), `Yearly`.
+- `DateFrom`, `DateTill` — период действия, `YYYY-MM-DDTHH:mm:ss`. Без
+  периода веб-клиент подставляет «сегодня + 1 год».
+- `Frequency.AppointmentTimes` — время срабатывания `HH:mm` **в UTC**
+  (см. «Подводные камни»).
+- `TaskCreationOffset` — необязательно: за сколько до срабатывания создавать
+  заявку, `часы:мм:сс` (`2:00:00`, за двое суток — `48:00:00`).
+- `AppointmentsLimit` — необязательно: сколько раз сработать всего.
+
+Остальные поля `Frequency` зависят от типа частоты
+(`PMP:GET:/FrequencyTypes`):
+
+| `frequencyTypeID` | `Name` | Поля `Frequency` кроме `AppointmentTimes` |
+|---|---|---|
+| 1 | `DuringTheDay` | — (`DateFrom` и `DateTill` — один день, несколько времён) |
+| 2 | `Daily` | `EachDayNumber: [N]` — каждые N дней |
+| 3 | `Weekly` | `EachDayNumber` — дни недели (1 — пн … 7 — вс), `EachWeekNumber: [N]` — каждые N недель |
+| 4 | `Monthly` | `EachDayNumber` — числа месяца (0 — последний день, тогда ещё `EachLastDayNumber: [0]`), `EachMonthNumber: [N]` — каждые N месяцев |
+| 5 | `Yearly` | `EachDayNumber` — числа, `EachMonthNumber` — месяцы (1–12), `EachYearNumber: [N]` — каждые N лет; последний день — как у `Monthly` |
+
+Чтение — `PMP:GET:/Schedules/{id}`: `options` возвращается тем же объектом,
+тип частоты — в поле `frequencyType` объектом `{ id, name }`.
+
+## 3. Привязка, активация, проверка
+
+- `WORK:POST:/TaskTemplates/{id}/schedules` — тело — массив `scheduleID`
+  (ответ `PMP:POST:/Schedules` передаётся как есть), ответ — 202 без тела.
+  При изменении расписания через `PMP:POST:/Schedules` с `id` привязку
+  повторять не нужно.
+- `WORK:GET:/TaskTemplates/{id}/schedules` — привязанные расписания:
+  `state.isActive`, а у активного ещё `appointment.total`/`remaining` и
+  `appointment.next` — ближайшее срабатывание (UTC).
+- Включить — `WORK:PUT:/TaskTemplates/{taskTemplateId}/schedules/{scheduleId}/activate`,
+  выключить — `WORK:PUT:/TaskTemplates/{taskTemplateId}/schedules/{scheduleId}/deactivate`.
+  Тело пустое. `activate` отвечает `{ "isActive": true, "nextAppointment": "..." }`
+  (время в UTC), `deactivate` — 202 без тела. Веб-клиент выключает и включает
+  расписание той же кнопкой.
+- Точки срабатывания — `PMP:GET:/Schedules/{scheduleID}/appointments` с
+  `dateFrom`/`dateTill`, ответ — массив `{ id, appointment }` (UTC); 204 —
+  событий в периоде нет. События появляются только после активации: у
+  неактивного расписания `appointment.total` равно 0.
+- `WORK:POST:/TaskTemplates/{taskTemplateId}/schedules/{scheduleId}/appointments`
+  перегенерирует события. Веб-клиент его не вызывает: активации достаточно.
+
+## Последовательность MCP-вызовов
+
+```text
+hubex_request_read(endpointId: `PMP:GET:/FrequencyTypes`)               → frequencyTypeID
+hubex_request_write(endpointId: `WORK:POST:/TaskTemplates`, body: [{ name, taskTypeID, workTypeID, criticalityID, requestMethodID: 1, assetFilter }])
+→ [taskTemplateID]
+hubex_request_write(endpointId: `PMP:POST:/Schedules`, body: [{ frequencyTypeID, options: { Name, DateFrom, DateTill, Frequency } }])
+→ [scheduleID]
+hubex_request_write(endpointId: `WORK:POST:/TaskTemplates/{id}/schedules`, pathParams: { id: taskTemplateID }, body: [scheduleID])
+hubex_request_write(endpointId: `WORK:PUT:/TaskTemplates/{taskTemplateId}/schedules/{scheduleId}/activate`, pathParams: { taskTemplateId, scheduleId })
+hubex_request_read(endpointId: `PMP:GET:/Schedules/{scheduleID}/appointments`, pathParams: { scheduleID }, query: { dateFrom, dateTill })
+```
+
+## Подводные камни
+
+- **`AppointmentTimes` — в UTC.** Веб-клиент переводит введённое локальное
+  время в UTC перед сохранением и обратно при показе. Заявка в 08:00 по
+  Москве (UTC+3) — это `"05:00"`; записанное буквально `"08:00"` сработает в
+  11:00 по Москве.
+- Созданное, но не активированное расписание заявок не создаёт. После
+  сохранения проверь `state.isActive` и точки срабатывания.
+- Не бери `options` из swagger-примера (`interval`, `timeOfDay`,
+  `daysOfWeek`): веб-клиент не покажет и не отредактирует такое расписание.
+  Используй ключи из раздела 2 и сверь результат по точкам срабатывания.
+- `PMP:POST:/Schedules` с чужим `id` перезапишет чужое расписание: при
+  изменении сначала прочитай его через `PMP:GET:/Schedules/{id}`.
+- Имена параметров пути у `activate`/`deactivate` в swagger расходятся
+  регистром с шаблоном пути (`taskTemplateID` против `{taskTemplateId}`).
+  Сервер MCP принимает любой из вариантов.

package/docs/guides/roles.md

@@ -3,6 +3,12 @@ topic: roles
 sources:
   - page: adminapp/src/modules/RolesPage/saga.js
     content_hash: dd2943597b30a21c
+  - page: adminapp/src/modules/RolesPage/helpers.js
+    content_hash: 5d278fab266691e4
+  - page: adminapp/src/modules/UIPermissionModal/containers/UIPermissionModalContainer.js
+    content_hash: ae0bbd7e29704a68
+  - page: adminapp/src/modules/InterfaceElements/actions.js
+    content_hash: 07877111bb1d1ceb
   - page: adminapp/src/services/requests.js
     content_hash: 54c3d95d85bb0ce0
   - page: adminapp/src/locales/ru/app.json
@@ -46,11 +52,33 @@ POST ADM:POST:/RoleApplications     → доступные приложения
 ответ `201` — массив идентификаторов. Изменение названия и описания —
 `ADM:PUT:/Roles` (массив с `id`), удаление — `ADM:DELETE:/Roles/{id}`.
 
-Тела привязок — массивы объектов вида `{ roleID, permission...ID }`; точную
-схему бери через `hubex_describe_endpoint`, поля различаются между наборами.
+Тела привязок — массивы объектов «роль + список ID» в поле `data`, а не по
+объекту на каждое полномочие:
+
+```text
+// API, расширенные полномочия, приложения
+[{ "roleID": 7, "data": [10, 11] }]
+// UI-полномочия — с уровнем доступа, по объекту на каждый capabilityID
+[{ "roleID": 7, "capabilityID": 1, "data": [10] },
+ { "roleID": 7, "capabilityID": 2, "data": [11, 12] }]
+```
+
 Снятие полномочия — соответствующий `ADM:DELETE:/RolePermissionsApi`,
 `ADM:DELETE:/RolePermissionsUi`, `ADM:DELETE:/RolePermissionsExt`,
-`ADM:DELETE:/RoleApplications` с тем же телом.
+`ADM:DELETE:/RoleApplications` с телом того же вида: `[{ roleID, data: [ids] }]`.
+
+### Изменение полномочий существующей роли
+
+Веб-клиент не перезаписывает набор целиком, а отправляет разницу:
+
+1. Прочитать текущее состояние: `ADM:GET:/Roles/{roleID}/permissionsUi` с
+   `isCheckedPermission=false` (и `isSystemPermission=true`, как в веб-клиенте).
+   Выбранные полномочия — с `isChecked: true`, уровень — в `capabilityID`.
+2. Включённые полномочия — `POST` с `data` только из новых ID.
+3. Выключенные — `DELETE` с `data` только из снимаемых ID.
+4. Смена уровня UI-полномочия (например, RO → RW) — повторный
+   `ADM:POST:/RolePermissionsUi` с новым `capabilityID`; веб-клиент перед этим
+   ничего не удаляет.
 
 ## 2. Роль по шаблону и копирование
 
@@ -83,14 +111,27 @@ PUT    ADM:PUT:/PermissionsUi
 DELETE ADM:DELETE:/PermissionsUi
 ```
 
+`ADM:PUT:/PermissionsUi` принимает массив **полных** записей:
+`[{ "id": 12, "code": "MyPerm", "description": "...", "mustBeAssignedToRole": false, "allowReadonlyOnly": false }]`.
+Поля `id`, `code`, `mustBeAssignedToRole` и `allowReadonlyOnly` обязательны.
+В примере из описания эндпоинта их меньше: тело, собранное по этому примеру,
+сервер отклонит с 400. Удаление — `ADM:DELETE:/PermissionsUi` с массивом ID:
+`[12, 13]`.
+
 ## 5. Доступ роли к полям заявки
 
-Видимость полей формы заявки настраивается по паре «роль + стадия»:
+Видимость полей формы заявки настраивается по паре «роль + стадия». Доступ
+задаётся **роли**, не пользователю: чтобы поменять поле «для пользователя N»,
+сначала узнай его роли через `ADM:GET:/Users/{id}/roles`. Если ролей несколько,
+действует правило максимума (см. «Подводные камни»).
 
-- `TSTG:GET:/TaskStageComponents/availability` с query `roleID`, `taskStageID`,
-  `taskTypeID` — что доступно сейчас (компоненты и дополнительные поля).
+- `UI:GET:/Components` — справочник основных полей формы (`id`, `code`,
+  `description`), например `56` — `companyID`, «Компания-заказчик».
+- `TSTG:GET:/TaskStageComponents/availability` с query `roleID`, `taskStageID`
+  (оба можно повторять) — текущая доступность: массивы `components` и
+  `attributes`, у каждого элемента `availability.capabilityID`.
 - `TSTG:POST:/TaskStageComponents` — запись доступности:
-  `[{ "taskStageID": 12, "taskTypeID": 5, "components": [{ "id": 3, "roleID": 7, "capabilityID": 2 }], "attributes": [...] }]`.
+  `[{ "taskStageID": 27, "components": [{ "id": 56, "roleID": 3, "capabilityID": 2 }, ...], "attributes": [...] }]`.
 - Справочник уровней доступа — `ADM:GET:/Capabilities`. Отдаёт пять записей с
   полем `weightCoefficient`: `RO`=1 (только чтение), `RW`=2 (чтение и запись),
   `RWM`=3 (обязательная запись), `RWE`=4 (эксклюзивная запись), `RWME`=5
@@ -101,6 +142,102 @@ DELETE ADM:DELETE:/PermissionsUi
   `ADM:POST:/RoleTaskPropertiesAccess/attributes`,
   `ADM:PUT:/RoleTaskPropertiesAccess/attributes`.
 
+### Как устроена запись
+
+Под капотом каждое поле стадии — это UI-полномочие с автоматическим кодом, а
+доступ роли к полю — привязка роли к этому полномочию с уровнем `capabilityID`:
+
+- основное поле: `taskForm$<стадия, 5 цифр>@<code компонента>`, например
+  `taskForm$00027@companyID`;
+- дополнительное поле: `taskForm$<стадия>@<attributeID, 5 цифр>`, например
+  `taskForm$00027@00011`;
+- правило для одного типа заявки: `taskForm$00027-007@companyID` (тип 7).
+
+Эти полномочия видны в `ADM:GET:/Roles/{roleID}/permissionsUi` (с
+`isCheckedPermission`) и в `ADM:GET:/Users/this/permissions/ui`.
+
+**POST заменяет список, а не сливает.** Перед записью бэкенд дополняет тело
+всеми компонентами, которые сейчас есть у роли на этой стадии, но не переданы,
+с `capabilityID: null`, а `capabilityID: null` означает «снять доступ у этой
+роли». Итог: переданный массив `components` становится полным списком
+компонентов роли на стадии, остальные поля пропадают из заявки. С `attributes`
+то же самое. Если ключа `attributes` в теле нет вовсе, дополнительные поля не
+трогаются. Другие роли и стадии не затрагиваются.
+
+**`permissionUiID` не передавай.** Бэкенд подбирает полномочие сам по коду
+`taskForm$…` (и создаёт его, если такого нет). Переданный ID лишь проверяется
+на существование — несуществующий даёт ошибку, — после чего заменяется
+найденным по коду; для записей с `taskTypeID` поле отбрасывается сразу.
+Пример в описании эндпоинта с `"permissionUiID": 10` вводит в заблуждение.
+
+**`taskTypeID` не передавай без явной задачи.** Без него правило действует для
+всех типов заявок на стадии — так пишет и веб-клиент («Элементы интерфейса»).
+С `taskTypeID`:
+
+- бэкенд заводит отдельное полномочие `taskForm$<стадия>-<тип>@<code>` и
+  отдельную строку поля для этого типа;
+- для заявок этого типа мета формы берёт **только** эту строку, а общее
+  правило игнорирует — для **всех ролей**. Роль, которой не выдали новое
+  полномочие, теряет поле на заявках этого типа, даже если в общем правиле
+  у неё был доступ;
+- `taskTypeID` вместе с `capabilityID: null` создаёт строку-«заглушку»:
+  поле для типа есть, а полномочие не выдано никому, и поле скрыто у всех на
+  заявках этого типа;
+- повторный POST с тем же `taskTypeID` правило для типа не убирает.
+
+Чтобы снять правило для типа, отправь общий POST **без** `taskTypeID` с полным
+списком компонентов роли: бэкенд снимет привязки роли к полномочиям
+`taskForm$<стадия>-<тип>@…` по тем же полям и удалит строку для типа, если её
+полномочие больше ни у одной роли не осталось. Само полномочие остаётся в
+справочнике `ADM:GET:/PermissionsUi`, но ни на что не влияет.
+
+### Изменение одного поля
+
+1. Снимок до записи: `availability` для нужных `roleID` и `taskStageID` и
+   `ADM:GET:/Roles/{roleID}/permissionsUi` с `isCheckedPermission=true` —
+   строки `taskForm$<стадия>…` с `capabilityID`. Без снимка не пиши: откатить
+   будет не к чему.
+2. Взять **все** компоненты роли из `availability`, поменять `capabilityID` у
+   нужного и отправить полный массив без `taskTypeID` и `permissionUiID`. Если
+   меняются и дополнительные поля, так же отправить полный массив `attributes`.
+3. Проверить результат (см. ниже). Откат — тот же POST с полным списком и
+   `capabilityID` из снимка.
+
+### Проверка результата
+
+`availability` показывает только то, что записано, но не то, что увидит
+пользователь. Проверяй два места:
+
+- `ADM:GET:/Roles/{roleID}/permissionsUi` — у полномочия
+  `taskForm$<стадия>@<code>` стоит `isChecked: true` и нужный `capabilityID`, и
+  нет посторонних `taskForm$<стадия>-<тип>@…`. Это работает для любой роли.
+- `WORK:GET:/Tasks/{taskID}/meta` — в `components` есть нужный `code` с
+  `permission` и `capability`. Мета строится для текущего пользователя, а MCP
+  работает под одной учёткой, поэтому мету для пользователя с другой ролью
+  через MCP не проверить.
+
+Клиенты собирают права поля из двух ответов: мета заявки даёт код полномочия
+компонента, `ADM:GET:/Users/this/permissions/ui` — уровень по этому коду. Если
+компонента нет в мете, поле скрыто. Мобильное приложение перезапрашивает
+UI-права при входе и обновлении токена, поэтому после правки может
+понадобиться перелогин.
+
+### Уровни доступа в мете формы
+
+Мета формы (`WORK:GET:/Tasks/{taskID}/meta`) отдаёт компонент, только если у
+пользователя есть его полномочие хотя бы через одну роль, а уровень берёт
+максимальный по весу. `RWE`/`RWME` бэкенд пересчитывает сам:
+
+- исполнителю заявки (или пользователю с расширенным полномочием
+  «игнорировать эксклюзивные права») — `RW`/`RWM`;
+- остальным, если исполнитель назначен, — `RO`;
+- у заявки без исполнителя код уходит как есть — `RWE`/`RWME`.
+
+Веб-клиент показывает поле только при `RO`, `RW`, `ROM` или `RWM`, поэтому на
+заявке без исполнителя поле с `RWE`/`RWME` скрыто. Чтобы поле было видно и
+редактировалось у всех, ставь `2` (`RW`), чтобы было обязательным — `3`
+(`RWM`).
+
 ## Последовательность MCP-вызовов
 
 ```text
@@ -108,12 +245,31 @@ hubex_request_read(endpointId: `ADM:GET:/Roles`)
 hubex_request_write(endpointId: `ADM:POST:/Roles`, body: [{ name, description }])
 → response[0] = roleID
 hubex_request_read(endpointId: `ADM:GET:/PermissionsUi`)
-hubex_request_write(endpointId: `ADM:POST:/RolePermissionsUi`, body: [{ roleID, ... }])
+hubex_request_write(endpointId: `ADM:POST:/RolePermissionsUi`, body: [{ roleID, capabilityID: 2, data: [permissionUiID, ...] }])
 hubex_request_read(endpointId: `ADM:GET:/Roles/{roleID}/permissionsUi`, pathParams: { roleID }, query: { isCheckedPermission: false })
 ```
 
+Доступ к полю заявки для пользователя:
+
+```text
+hubex_request_read(endpointId: `ADM:GET:/Users/{id}/roles`, pathParams: { id: userID })
+hubex_request_read(endpointId: `UI:GET:/Components`, query: { fetch: 500, offset: 0 })
+hubex_request_read(endpointId: `TSTG:GET:/TaskStageComponents/availability`, query: { roleID, taskStageID })
+hubex_request_read(endpointId: `ADM:GET:/Roles/{roleID}/permissionsUi`, pathParams: { roleID }, query: { isCheckedPermission: true })
+hubex_request_write(endpointId: `TSTG:POST:/TaskStageComponents`, body: [{ taskStageID, components: [<ВСЕ компоненты роли из ответа, одно изменено>] }])
+hubex_request_read(endpointId: `ADM:GET:/Roles/{roleID}/permissionsUi`, pathParams: { roleID }, query: { isCheckedPermission: true })
+hubex_request_read(endpointId: `WORK:GET:/Tasks/{taskID}/meta`, pathParams: { taskID })
+```
+
 ## Подводные камни
 
+- `TSTG:POST:/TaskStageComponents` с одним компонентом в `components` стирает
+  у роли на этой стадии все остальные компоненты: из заявки пропадают все поля,
+  кроме переданного. Всегда отправляй полный список, прочитанный из
+  `availability`.
+- `taskTypeID` в `TSTG:POST:/TaskStageComponents` перекрывает общее правило
+  поля для всех ролей на заявках этого типа: у ролей без нового полномочия поле
+  пропадает. С `capabilityID: null` поле скрывается у всех.
 - Создание роли не даёт ей ни одного полномочия: без последующих
   `RolePermissions*` пользователь с этой ролью не увидит ничего.
 - Четыре набора полномочий независимы. Выдать API-полномочие и забыть про