# Сервис DockindStructure Сервис предназначен для управления структурой информационных объектов (DocKind) в системе. Он позволяет настраивать атрибуты типов документов: основные свойства, статусы, реквизиты, функции, действия, права доступа, а также переименовывать документы определённого типа. ## Зависимости - **`QueriesHelper`** — выполнение SQL-запросов и вызов хранимых процедур. - **`OraLongTransactions`** — управление длительными транзакциями. - **`SysProcesses`** — запуск фоновых процессов бизнес-логики (используется для отложенного обновления имён документов). ## События - **`onChanged`** — генерируется при любом изменении структуры информационного объекта. Полезно для сброса кэшей или оповещения других компонентов системы. ## Запросы Все запросы выполняются через HTTP POST (если в схеме указано `"http": "POST"`), либо доступны только внутренне (если `"http": null`). Почти все запросы требуют авторизации (`"anonymous": false`), административные методы отмечены флагом `"needAdmin": true`. ### `getInfo` Получить идентификатор и описание типа документа по его системному имени. **Параметры запроса:** | Поле | Тип | Обязательное | Описание | |----------|--------|--------------|------------------------------| | `docKind` | string | да | Системное имя типа документа | **Ответ:** | Поле | Тип | Описание | |---------------|--------|--------------------------| | `id` | number | Идентификатор типа (DOCKIND_ID) | | `description` | string | Человекочитаемое описание | **Ошибки:** - `ComplexError("Не найден тип документа ...")` — если указанный тип не существует. --- ### `setMain` Обновить основные атрибуты типа документа: описание, родительскую папку. Переименование (изменение `oldDocKind` на `newDocKind`) запрещено. **Параметры запроса:** | Поле | Тип | Обязательное | Описание | |---------------|--------|--------------|--------------------------------------------------------------------------| | `oldDocKind` | string | нет | Текущее системное имя (должно совпадать с `newDocKind`, если указано) | | `newDocKind` | string | да | Новое системное имя (не может отличаться от `oldDocKind`) | | `description` | string | нет | Новое описание | | `parentId` | number | нет | ID родительской папки (категории) | **Примечания:** - Требует прав администратора (`needAdmin: true`). - Выполняется в рамках сессии (`session` передаётся из контекста). --- ### `getStatuses` Получить список всех статусов (событий) для заданного типа документа. **Параметры запроса:** | Поле | Тип | Обязательное | Описание | |-------------|--------|--------------|--------------------------------------------------------------------------| | `docKind` | string | условно | Системное имя типа. Используется, если не передан `docKindId`. | | `docKindId` | number | условно | ID типа. Если указан, `docKind` игнорируется. | | `session` | object | нет | Сессия пользователя (автоматически подставляется при HTTP-вызове). | **Ответ:** Массив объектов со следующими полями: | Поле | Тип | Описание | |--------------|--------|---------------------------------------------| | `EVENT_ID` | number | Уникальный идентификатор статуса | | `EVENT_NAME` | string | Системное имя статуса | | `EVENT_DESCR`| string | Отображаемое описание | | `COLOR_NAME` | string | Название цвета (может быть `null`) | | `COLOR_CODE` | string | Код цвета в формате Delphi (например, `$00D6FED6`) | --- ### `setStatuses` Изменить набор статусов типа документа: удалить, обновить существующие, добавить новые, установить порядок. Операция обёрнута в транзакцию. **Параметры запроса:** | Поле | Тип | Обязательное | Описание | |-------------|--------|--------------|--------------------------------------------------------------------------| | `docKind` | string | условно | Системное имя типа (если не указан `docKindId`). | | `docKindId` | number | условно | ID типа. | | `deleteIds` | array of number | нет | Список ID статусов, которые необходимо удалить. | | `statuses` | array | нет | Массив статусов для добавления/обновления. Каждый объект содержит: | | | | | · `EVENT_ID` (number, <0 для новых), | | | | | · `EVENT_NAME` (string), | | | | | · `EVENT_DESCR` (string), | | | | | · `COLOR_NAME` (string), | | | | | · `COLOR_CODE` (string). | | `newOrder` | array of number | нет | Новый порядок ID статусов (включая только что созданные). | | `session` | object | нет | Сессия пользователя. | | `trxId` | string | нет | Идентификатор внешней транзакции (для встраивания в более крупные операции). | **Требования:** `needAdmin: true`. --- ### `getProps` Получить все реквизиты (свойства) типа документа. **Параметры запроса:** | Поле | Тип | Обязательное | Описание | |-------------|--------|--------------|--------------------------| | `docKind` | string | условно | Системное имя типа. | | `docKindId` | number | условно | ID типа. | | `session` | object | нет | Сессия пользователя. | **Ответ:** массив объектов реквизитов (структура зависит от БД). --- ### `setProps` Массовое изменение реквизитов типа документа: удаление, создание/обновление, установка порядка. Внутри транзакции последовательно обрабатываются все переданные свойства. **Параметры запроса:** | Поле | Тип | Обязательное | Описание | |-------------|--------|--------------|--------------------------------------------------------------------------| | `docKind` | string | да | Системное имя типа. | | `props` | array | нет | Массив объектов свойств для вставки/обновления. Каждый объект должен содержать поля согласно `PKG_KIND_PROPERTIES_CS.UPDATE_PROPERTY` (см. описание отдельных полей в `setProperty`). Если у свойства указаны `Statuses`, они также обновляются. | | `deleteIds` | array of number | нет | ID реквизитов, подлежащих удалению. | | `statuses` | | | (Не используется в текущей реализации, оставлен для совместимости) | | `session` | object | нет | Сессия. | | `trxId` | string | нет | Внешняя транзакция. | **Детали полей объекта свойства (property):** - `DOCPROP_KIND` — тип реквизита (number). - `DOCPROP_ID` — ID реквизита (number, для существующих). - `DOCPROP_FPATH`, `DOCPROP_PRESENTATION`, `DOCPROP_SQL`, `DOCPROP_OBJECT`, `DOCPROP_DESCR`, `DOCPROP_NAME`, `DOCPROP_SCRIPT`, `DEFAULT_VALUE`, `DOCPROP_PRESENTATION_OPTIONS` — строковые атрибуты (CLOB). - `DOCPROP_UNIQUE`, `DOCPROP_MULTI` — булевы флаги (передаются как 1/0). - `DOCPROP_RULE_CHILD`, `DOCPROP_RULE_PARENT`, `DOCPROP_REPEAT`, `DOCPROP_TREE_KIND`, `DOCPROP_RULE`, `DOCPROP_VALID`, `DOC_FORMAT` — числовые поля. - `RefLinks` — опциональный массив объектов `{ DocKindId, XmlFilter }`, перед отправкой сериализуется в JSON. - `Statuses` — массив объектов вида `{ eventId, required, visible, writable }` для настройки доступности реквизита в разных статусах. **Требования:** `needAdmin: true`. --- ### `getFunctions` Получить список функций (триггеров/обработчиков), привязанных к типу документа. **Параметры запроса:** | Поле | Тип | Обязательное | Описание | |-------------|--------|--------------|----------------------| | `docKind` | string | условно | Системное имя типа. | | `docKindId` | number | условно | ID типа. | | `session` | object | нет | Сессия. | | `trxId` | string | нет | Транзакция. | **Ответ:** массив объектов функций. Каждый объект содержит: - `DOCEVENTKIND_IDS`, `DOCPROP_IDS`, `DK_ACTION_IDS` — массивы чисел, полученные парсингом строк с разделителем `,`. - Прочие поля, возвращаемые БД. **Требования:** `needAdmin: true`. --- ### `setFunctions` Обновить перечень функций типа документа. Предварительно для каждой функции вида `schema.name` создаётся заглушка в БД (если ещё не существует). **Параметры запроса:** | Поле | Тип | Обязательное | Описание | |-------------------|--------|--------------|--------------------------------------------------------------------------| | `docKind` | string | условно | Системное имя типа. | | `docKindId` | number | условно | ID типа. | | `funcs` | array | нет | Массив объектов функций (формат определяется БД). Поле `db_function` обязательно должно иметь вид `schema.function_name`. | | `deleteIds` | array of number | нет | ID функций для удаления. | | `notValidateFuncs`| boolean| нет | Если `true`, пропустить проверку формата `db_function`. | | `session` | object | нет | Сессия. | | `trxId` | string | нет | Транзакция. | **Требования:** `needAdmin: true`. --- ### `setActions` Управление действиями (actions), доступными для типа документа. Поддерживает добавление, обновление, удаление и изменение порядка. **Параметры запроса:** | Поле | Тип | Обязательное | Описание | |-------------|--------|--------------|--------------------------------------------------------------------------| | `docKind` | string | условно | Системное имя типа. | | `docKindId` | number | условно | ID типа. | | `deleteIds` | array of number | нет | ID действий для удаления. | | `actions` | array | нет | Массив объектов действий. Каждый объект должен иметь поле `changed` (boolean). Если `changed === true`, объект будет передан в БД для вставки/обновления. Если `false`, используется только его `id` для сохранения порядка. | | `session` | object | нет | Сессия. | | `trxId` | string | нет | Транзакция. | **Требования:** `needAdmin: true`. --- ### `setNames` Запускает процесс обновления имён всех документов заданного типа (например, после изменения правил формирования наименования). Выполняется немедленное сохранение новых правил именования и создание фонового процесса через сервис `SysProcesses`. **Параметры запроса:** | Поле | Тип | Обязательное | Описание | |-------------|--------|--------------|--------------------------------------------------------------------------| | `docKind` | string | условно | Системное имя типа. | | `docKindId` | number | условно | ID типа. | | `names` | object | да | Новые правила формирования имён (структура определяется логикой БД). | | `session` | object | нет | Сессия. | | `trxId` | string | нет | Транзакция. | **Требования:** `needAdmin: true`. --- ### `updateDockindNames` Служебный метод, вызываемый фоновым процессом. Последовательно обновляет описания (`DESCR`) всех документов, принадлежащих указанному типу. Может выполняться долго, поэтому не должен вызываться напрямую из HTTP (хотя endpoint открыт). **Параметры запроса:** | Поле | Тип | Обязательное | Описание | |--------------|--------|--------------|----------------| | `dockindId` | number | нет | ID типа документа. Если не указан, будет ошибка. | **Требования:** `needAdmin: true`. --- ### `setPermissions` Управление правами ролей на тип документа: создание, доступ к статусам и реквизитам. **Параметры запроса:** | Поле | Тип | Обязательное | Описание | |----------------|--------|--------------|--------------------------------------------------------------------------| | `docKind` | string | условно | Системное имя типа. | | `docKindId` | number | условно | ID типа. | | `roles` | array | нет | Массив объектов прав ролей. Каждый объект: `id` (роль), `creation` (0/1), `statuses` (структура прав на статусы), `properties` (права на реквизиты). | | `deleteRoleIds`| array of number | нет | ID ролей, для которых нужно удалить все права на данный тип. | | `session` | object | нет | Сессия. | | `trxId` | string | нет | Транзакция. | **Требования:** `needAdmin: true`. --- ### `getIdByName` Получить числовой идентификатор типа документа по его системному имени. **Параметры запроса:** | Поле | Тип | Обязательное | Описание | |-----------|--------|--------------|-------------------------| | `docKind` | string | да | Системное имя типа. | **Ответ:** число (`RESULT`) — идентификатор. --- ### `getNameById` Получить системное имя типа документа по его ID. **Параметры запроса:** | Поле | Тип | Обязательное | Описание | |-------------|--------|--------------|----------| | `docKindId` | number | да | ID типа. | **Ответ:** строка — системное имя.