# Менеджер конфигураций

Менеджер конфигураций — механизм переноса данных и настроек системы между контурами (разработка, тестирование, продуктив). Перенос выполняется через формирование файла конфигурации на исходном контуре и его установку на целевом.

Механизм используется для передачи бизнес-объектов и JEXL-скриптов. Конфигурация формируется из задач, каждая из которых содержит состав объектов для переноса. Порядок применения изменений контролируется через порядковые номера задач и состава.

**Примеры использования.**
- Перенос ролевой модели с тестового контура на продуктивный после согласования прав доступа.
- Доставка новых классов и атрибутов после завершения разработки функционала.
- Синхронизация настроек автонумерации и проектных настроек между контурами.
- Проверка совместимости целевого контура до передачи полного набора данных через метаданные.

**Основная логика работы.**
1. Создание конфигурации и наполнение её задачами с объектами для переноса.
2. Финализация конфигурации и формирование файла.
3. Установка файла на целевом контуре — локально или через удалённое подключение.

## Интерфейс конфигурации

**Доступ к интерфейсу.** Путь: `Настройка системы > Настройки и сервисы > Управление конфигурации > Менеджер конфигурации`.

В разделе отображается список всех доступных конфигураций. 

**Типы конфигураций.**
- Исходящая конфигурация — создана и сформирована на текущем контуре для передачи на другой контур, ещё не установлена на целевой системе.
- Входящая конфигурация — получена из внешнего источника и установлена на текущем контуре.

**Цветовая индикация.**
- Красный значок — установка прошла с ошибками.
- Синий значок — установка выполнена без ошибок.

В верхней части интерфейса расположена кнопка **Дополнительно**, содержащая следующие операции:

- **Сформировать** — формирование файла конфигурации без блокировки редактирования.
- **Сформировать и установить** — формирование файла и его удалённая установка на выбранный контур.
- **Установить** — установка конфигурации из файла на текущий контур.
- **Финализировать** — блокировка конфигурации для любых изменений, обратная операция недоступна.
- **Финализировать и выгрузить** — финализация конфигурации с одновременным формированием файла для передачи.
- **Скачать метаданные** — выгрузка облегчённого файла со структурой конфигурации для предварительной проверки.
- **Проверить метаданные** — проверка совместимости текущего контура по файлу метаданных.
- **Проверить метаданные на удалённом контуре** — отправка метаданных на выбранный удалённый контур для предварительной проверки.
- **Открыть отчёт о валидации** — загрузка и просмотр сформированного отчёта валидации.

### Карточка конфигурации

Открывается при создании или редактировании конфигурации. Содержит вкладки для настройки состава, параметров и контроля переноса.

![conf](/service/img_serv/conf.png)

#### Задача

Основное наполнение конфигурации. Позволяет создавать несколько задач для группировки состава.

**Колонки таблицы задач:**
- **Порядковый номер** — определяет порядок установки задач внутри конфигурации.
- **Системное имя** — наименование задачи, по умолчанию формируется как ФИО и логин создателя.
- **Дата создания** — дата создания записи задачи.
- **Дата последнего изменения** — дата последнего редактирования записи.
- **Описание** — текстовый комментарий к задаче.
- **Создатель** — ФИО и логин пользователя, создавшего задачу.
- **Закрыто** — флаг, блокирующий возможность редактирования задачи. После закрытия задачи, изменения БО в системе не приведёт к обновлению конфигурации.

**Состав задачи.**  
В детализации задачи доступен **Состав задачи**. Здесь задаются конкретные объекты, скрипты или настройки, которые будут перенесены в рамках данной задачи и конфигурации. Для каждой записи указываются:
- **Порядковый номер** — определяет порядок установки внутри задачи.
- **Системное имя** — идентификатор объекта для поиска: системное имя, `gid`, `guid` или мнемокод (зависит от типа).
- **Флаг «Заблокирован»** — если галочка установлена, объект можно изменять, данные в конфигурации обновляются при изменении исходного объекта; если галочка снята, данные зафиксированы на момент снятия флага, изменения в источнике игнорируются.
- **Тип** — определяет, какой объект будет перенесён и какая логика выгрузки применяется.
- **Класс** — класс объекта, заполняется автоматически после проверки, можно задать вручную.
- **Системное имя класса** — системное имя класса объекта, заполняется автоматически.
- **Дополнительная информация** — примечания или контекст для записи, заполняется автоматически после проверки.

**Проверка состава.**  
Операция **Проверить** ищет указанные объекты в текущей системе:
- Если объект найден — автозаполнение класса, системного имени, дополнительной информации.
- Если объект не найден — появляется окно с деталями ошибки.

#### Конфигурация

Вкладка содержит основные параметры конфигурации, которые используются для её идентификации и описания назначения. Здесь отображаются служебные данные (создатель, серийный номер) и поле для текстового комментария, которое помогает различать конфигурации при работе со списком.

**Параметры конфигурации:**
- **Создатель** — ФИО и логин пользователя, создавшего конфигурацию. Заполняется автоматически.
- **Уникальный серийный номер** — идентификатор конфигурации. Заполняется автоматически.
- **Описание** — текстовый комментарий к назначению конфигурации. Заполняется вручную.

#### Пользователи

Список пользователей, которые могут редактировать данную конфигурацию. Если список пуст — редактировать конфигурацию может любой пользователь с соответствующими правами.

#### Зависимость от версии модулей

Вкладка позволяет задать минимальные версии модулей, которые должны быть установлены на целевом контуре для успешной установки конфигурации.

Конфигурация может содержать объекты, которые используют функционал, появившийся в определённой версии модуля. Если на целевом контуре установлена более старая версия, эти объекты не смогут корректно работать. Зависимости позволяют заранее проверить совместимость и получить понятную ошибку до начала установки.

#### Журнал валидации

Отображает логи проверок конфигурации, выполненных через операцию **Открыть отчёт о валидации**.

## Типы составляющих конфигурации

Тип определяет, какой объект будет перенесён и какое значение указывать в поле **Системное имя**.

| Тип     | Что указывается в «Системное имя» | Класс (если применимо) | Что переносится          | Примечание |
|---------|--------------------|---------|--------------------------|-----------|
| **Роль** | Системное имя или `gid` | `Btk_AcRole` | Объект роли + коллекции (права, параметры адм. правила роли) |           |
| **Профиль** | Системное имя или `gid` | `Btk_AcProfile` | Объект профиля + коллекции |           |
| **Печатная форма** | Системное имя или `gid` | `Rpt_Report` | Объект печатной формы + коллекции (шаблоны, параметры) |           |
| **Отчёт** | Системное имя или `gid` | `Rpt_Entity ` | Объект отчетной формы + коллекции + тип документа, создаваемого по отчету (`Wf_RptEntityObjectType`) |           |
| **Профиль печати** | Системное имя или `gid` | `Rpt_Profile` | Объект профиля печати + коллекции |           |
| **Закладка** | Системное имя или `gid` | `Btk_Tab` | Объект закладки интерфейса |           |
| **Тип объекта** | Системное имя или `gid` | `Btk_ObjectType` | Тип объекта + коллекции + настройка расширений типа объекта (`Btk_OTExtensionSetting`), процедуры выполняемые при переводе состояний (`Bts_ObjectProcedure`) |           |
| **JEXL-скрипт** | Не используется    | Не используется | Текстовый файл со скриптом | Поля «Класс» и «Системное имя» игнорируются |
| **Функции JEXL** | Системное имя или `gid` | `Btk_JexlFunctionLib` | Библиотека функций JEXL  |           |
| **Библиотека JEXL** | Системное имя или `gid` | `Btk_JexlScriptLibrary` | Глобальная библиотека JEXL |           |
| **Все состояния класса** | Системное имя класса или `gid` класса | `Btk_Class` | Все состояния класса (`Btk_ClassState`), ссылающиеся на класс и связанные с ними состояния `Btk_State` |           |
| **Состояние класса** | `gid` состояния класса | `Btk_ClassState` | Состояние класса (`Btk_ClassState`) + связанное состояние (`Btk_State`) |           |
| **Объект класса по gid с коллекциями** | `gid` объекта      | Определяется автоматически | Объект + коллекции       | Если найден — обновляется, если нет — создаётся |
| **Объект класса по guid с коллекциями** | `guid` объекта     | Класс объекта | Объект + коллекции       | Если найден — обновляется, если нет — создаётся |
| **Объект класса по мнемокоду с коллекциями** | Мнемокод объекта   | Класс объекта | Объект + коллекции       | Аналогично `guid`, поиск по мнемокоду |
| **Все JSON-атрибуты класса** | Системное имя класса или `gid` класса | `Btk_Class` | Все `Btk_Attribute` указанного класса, добавленные вручную и значения которых хранятся в JSON-поле `jObjectAttrs_dz` |           |
| **JSON-атрибут класса** | Системное имя атрибута | Класс, содержащий атрибут | Атрибут класса (`Btk_Attribute`), добавленный вручную, значения которого хранятся в JSON-поле `jObjectAttrs_dz` |           |
| **Проектные настройки по AVI из обозревателя проекта** | Имя AVI из обозревателя проектов | Не используется | Переопределенные атрибуты выборки (`Btk_SelAttrOverride`), переопределенные операции выборки (`Btk_SelOperOverride`), логические выражения доступности (`Btk_SelCWAExtension`) | Переопределения из обозревателя проекта |
| **Пункт динамического меню (с потомками)** | Системное имя или `gid` | `Btk_MenuTree` | Пункт меню с потомками + соответствующие им вызовы меню |           |
| **Вызов меню** | Системное имя или `gid` | `Btk_MenuCall` | Действие, вызываемое из меню |           |
| **Маршрут документооборота** | Системное имя или `gid` | `Bpm_ProcessSchema` | Схема бизнес-процесса + коллекции |           |
| **Универсальный справочник** | Системное имя или `gid` типа объекта | `Btk_ObjectType` | Тип объекта (`Btk_ObjectType`), записи универсального справочника (`Btk_UniversalReference`), универсальные характеристики (`Btk_UniversalCharacteristic`), настройки универсального справочника (`Btk_UniversalReferenceSetting`), шаблон характеристик (`Btk_AttrTemplateByClassAttrs`) (если есть) |           |
| **Универсальная характеристика** | Системное имя или `gid` | `Btk_UniversalCharacteristic` | Универсальная характеристика и универсальный справочник (если есть) | Универсальный справочник переносится как описано раньше |
| **Все настройки автонумерации для класса(переопределённые)** | Системное имя класса или `gid` класса | `Btk_Class` | Все переопределения автонумерации (`Btk_ClassAunAttrOverride`) настроенные на классе |           |
| **Настройка автонумерации для класса(переопределённые)** | `gid` настройки автонумерации | `Btk_ClassAunAttrOverride` | Настройка автонумерации + коллекции |           |
| **Объектная привилегия** | `gid` объектной привилегии | `Btk_AcObjectPrivilege` | Выгружает объектную привилегию и соответствующий объект администрирования без коллекций |           |
| **Jexl-тест** | Системное имя или `gid` | `Bts_Test` | JEXL-тест                |           |
| **Класс и его окружение** | Системное имя класса или `gid` класса | `Btk_Class` | Класс (`Btk_Class`) и его коллекции, привязанные типы объектов (`Btk_ObjectType`), настройки расширений типов объектов (`Btk_OTExtensionSetting`) |           |
| **Настройки УФ** | Системное имя настройки или `gid` | `Btk_FltSetting` | Настройки универсального фильтра |           |
| **Объекты класса все** | Не используется    | Класс, объекты которого нужно перенести | Все объекты указанного класса |           |
| **Удаление объекта класса** | `gid` объекта для удаления | Не используется | Ищет и удаляет указанный объект на целевой базе |           |
| **Переопределение атрибутов класса** | Системное имя класса или `gid` класса | `Btk_Class` | Переопределенные атрибуты (`Btk_ClassAttrOverride`) класса |           |
| **Схема XML данных (с потомками)** | Системное имя или `gid` | `Bts_XmlSchema` | Схема XML данных + коллекции |           |
| **Идентификаторы внешних систем по gid объекта** | `gid` объекта      | Не используется | Выгружает идентификатор внешней системы по `gid` объекта |           |
| **Динамическое приложение (с пунктами меню)** | `gid` динамического меню | `Btk_DynamicApplication` | Динамическое приложение без коллекций + переопределенные JEXL-операции |           |
| **Переопределение атрибутов выборки** | Формат: `Выборка;Отображение;Атрибут` | `Btk_SelAttrOverride` | Переопределенный атрибут выборки | Если на исходном контуре переопределение отсутствует, то на целевом контуре переопределение будет удалено.<br/>Для указания системного имени используется специальная выборка |
| **Переопределение операций выборки** | Формат: `Выборка;Отображение;Операция` | `Btk_SelOperOverride` | Переопределенная операция выборки | Если на исходном контуре переопределение отсутствует, то на целевом контуре переопределение будет удалено.<br/>Для указания системного имени используется специальная выборка |
| **Все объекты таблицы вариантов** | Системное имя или `gid` | `Btk_Variant` | Объекты таблицы вариантов (`Btk_VariantObjApi`) |           |
| **Таблица вариантов с объектами** | Системное имя или `gid` | `Btk_Variant` | Таблица вариантов (`Btk_Variant`), объекты таблицы вариантов (`Btk_VariantObjApi`), универсальные характеристики (`Btk_UniversalCharacteristic`) |           |
| **Тег модуля с пакетом изменений** | `gid`              | `Vci_GitTag` | Тег, коммиты и измененные сущности вместе с пакетом изменений между версиями тегов |           |
| **Тег модуля** | `gid`              | `Vci_GitTag` | Тег модуля, коммиты и измененные сущности |           |
| **Тег комплекта сборки с пакетом изменений** | `gid`              | `Vci_GitTag` | Тег, коммиты и измененные сущности вместе с пакетом изменений между версиями тегов |           |
| **Тег комплекта сборки** | `gid`              | `Vci_GitTag` | Тег комплекта сборки, коммиты и измененные сущности |           |

## Порядок работы с конфигурацией


1. **Создание и наполнение.** Создайте новую или откройте текущую конфигурацию. На вкладке **Задача** создайте задачу, задайте порядковый номер. В окне **Состав задачи** добавьте объекты для переноса: выберите тип, укажите идентификатор, нажмите **Проверить** для валидации. Сохраните изменения.

2. **Дозаполнение конфигурации.** Если после сохранения и закрытия задачи вы обнаружили, что в конфигурации не все данные, создайте в той же конфигурации новую задачу и заполните её состав недостающими объектами. Закрытие задачи выполняется через установку флага **Закрыто** в карточке задачи.

3. **Финализация.** Когда конфигурация полностью готова, нажмите кнопку **Финализировать**. Конфигурация блокируется для любых изменений, обратной операции нет.

4. **Формирование файла.** Нажмите **Сформировать конфигурацию**. Система скачает файл, содержащий все данные конфигурации. Этот файл можно передать на другой контур для установки.

## Установка конфигурации

В таблице конфигураций нажмите кнопку **Дополнительно** > **Установить**. Выберите файл конфигурации. Система применяет изменения согласно структуре файла.

```{note}
**Поведение при ошибке.** Если в одном из объектов возникает ошибка, система пропускает проблемный объект и фиксирует ошибку в логе, продолжает установку остальных объектов, не затронутых ошибкой.

После установки всегда проверяйте вкладку **Лог установки** на наличие предупреждений и ошибок.
```

**Вкладка «Лог установки».**
Отображается только в установленной конфигурации. Содержит следующие элементы:

- **Порядковый номер** — номер установки в рамках конфигурации.
- **Дата установки** — временная метка выполнения.
- **Кол-во ошибок** — индикатор проблем при установке.
- **Лог БО** — детализация: какие объекты установлены, статус, сообщения.
- **Стек ошибки + JSON** — детальная информация для отладки при возникновении ошибок.
- **Файлы конфигурации**:
  - Резервная копия данных до установки.
  - Файл конфигурации, который был установлен.

## Проверка метаданных

Метаданные содержат только структуру конфигурации (классы, атрибуты, версии модулей), без самих данных объектов. Проверка метаданных выполняется за секунды и позволяет выявить несовместимость целевого контура до передачи тяжёлого файла конфигурации.

**Процесс проверки.**
1. В выбранной конфигурации: **Дополнительно** > **Скачать метаданные**.
2. На целевом контуре: **Дополнительно** > **Проверить метаданные** > загрузить скачанный файл.
3. Откройте отчёт: **Дополнительно** > **Открыть отчёт о валидации** > загрузить сформированный файл.

Структура отчёта валидации:
- Ошибки в структуре класса — отсутствуют классы и атрибуты, которые есть в конфигурации, но отсутствуют на целевом контуре. Такие ошибки требуют обновления модулей или комплектов сборки на удалённом контуре.
- Ошибки в данных — отсутствуют необходимые данные, конфигурация ссылается на объекты, которых нет в целевой системе. Такие ошибки требуют изменения состава конфигурации (добавления недостающих объектов) перед установкой.

Если в отчёте обнаружены отсутствующие связанные объекты их можно добавить через кнопку **Добавить недостающие объекты**. Недостающий объект автоматически добавится в текущую конфигурацию.

## Удалённая установка

В таблице конфигураций: **Дополнительно** > **Сформировать и установить**. Выберите целевой контур из списка. Система отправит файл конфигурации напрямую на выбранный контур. На целевом контуре появится запись в журнале «Установленные конфигурации» с логом выполнения.

Если конфигурация была установлена на удалённый контур с ошибками, можно отправить метаданные на проверку: кнопка **Проверить метаданные на удалённом контуре** отправляет только метаданные на выбранный контур. Результат проверки возвращается в журнал валидации текущего контура.

**Добавление удалённых контуров.** Путь: `Настройка и сервисы > Управление конфигурации > Настройки удалённых контуров`.

```{note}
В данном разделе выполняется только регистрация уже существующего удалённого контура в текущей системе — указываются параметры подключения и авторизации для обмена конфигурациями.
```

| Поле | Описание |
|------|----------|
| **Код** | Уникальный идентификатор контура |
| **Наименование** | Произвольное понятное имя контура (например, `Тестовый контур`) для удобной идентификации в списке |
| **URL** | Полный URL-адрес для доступа к удалённому контуру (например, `https://test-circuit.global-system.ru/`) |
| **База данных** | Наименование базы данных целевого контура |
| **Пользователь** | Логин учётной записи, имеющей права на установку конфигураций на целевом контуре |
| **Пароль** | Идентификатор (GUID) предварительно зашифрованного пароля. Не сам пароль, а ссылка на зашифрованные данные в системном хранилище |
| **Тип передачи** | REST / Git / Artifact Registry |

**Шифрование пароля.**  
Значение в поле **Пароль** должно быть предварительно зашифровано через встроенный сервис системы.

1. Перейдите: `Настройки системы > Настройки и сервисы > Дополнительно > Шифрование данных`.
2. В поле **Исходные данные** введите текстовый пароль.
3. Нажмите **Выполнить шифрование**.
4. Скопируйте полученный идентификатор (GUID) из поля **Результат шифрования**.
5. Вставьте этот идентификатор в поле **Пароль** при настройке удалённого контура.

**Маршрутизация между контурами.**  
Передача конфигураций между изолированными контурами может выполняться тремя способами, которые выбираются в поле **Тип передачи**:

- **REST** — прямое подключение по HTTP/HTTPS. В поле **URL** указывается адрес целевого контура (например, `https://test-circuit.global-system.ru/`). Используется, когда между контурами есть сетевой маршрут и они могут обмениваться данными напрямую.

- **Git** — передача через репозиторий системы контроля версий. В поле **URL** указывается адрес репозитория (например, `https://git.global-system.ru/configs.git`), а не конечного контура. Исходный контур отправляет конфигурацию в репозиторий, после чего CI/CD-пайплайн автоматически выполняет валидацию и установку на целевом контуре, а результаты возвращает обратно. Используется, когда прямой сетевой доступ между контурами отсутствует.

- **Artifact Registry** — передача через корпоративный реестр артефактов (Nexus, Artifactory и аналоги). Логика работы аналогична типу **Git**: конфигурация публикуется как артефакт, пайплайн забирает её, выполняет валидацию и установку.

```{note}
Для типов **Git** и **Artifact Registry** требуется:
 - предварительная настройка доступа к стороннему сервису как с исходного, так и с целевого контура;
 - согласование параметров маршрутизации (значения «Наименование целевого контура» должны соответствовать кодам настроек на противоположной стороне);
 - создание технических пользователей с минимально необходимыми правами и зашифрованными учётными данными.
 
Детали настройки пайплайна и репозитория см. в отдельной инструкции [Настройка обмена через репозиторий](http://helpcenter.gs.local/G3SysAdminDoc/html/070_addition/040_add_contour.html#).
```

## Системные настройки и отслеживание изменений

В этом разделе настраиваются глобальные параметры механизма: ограничение контуров, с которых разрешён приём релизов, и автоматическое отслеживание изменений объектов для включения в конфигурацию.

**Ограничение источников релизов.** Путь: `Настройка и сервисы > Настройки модулей системы > Общие настройки модулей > модуль btk > Релизы конфигурации`.

| Настройка | Описание |
|-----------|----------|
| **Системные имена контуров, с которых разрешён приём конфигураций** | Укажите коды контуров (например, `test`, `dev`), с которых разрешена установка. Значение `*` разрешает приём с любых контуров. Попытка установки с неразрешённого источника завершится ошибкой. |
| **Отслеживать изменения для добавления в релиз конфигурации** | Включает механизм автодобавления изменённых объектов в конфигурацию. После включения необходимо очистить кэш. |

**Отслеживание изменений на уровне класса.** Откройте журнал `Классы`, выберите нужный класс, установите флаг **Отслеживать изменения для включения в релиз конфигурации**, очистите кэш.

После сохранения изменений в классе с активным флагом открывается диалог **Включение в релиз конфигурации**. Можно добавить изменения в существующий черновик (отображаются только конфигурации, созданные текущим пользователем) или создать новый релиз.

## Быстрое добавление объектов в конфигурацию

Используется, когда изменены данные объекта и требуется сразу добавить их в конфигурацию без перехода в интерфейс Менеджера конфигураций — напрямую из карточки объекта.

**Из карточки объекта.** Откройте карточку любого бизнес-объекта, перейдите: `Информация > Информация об объекте`, нажмите **Добавить в конфигурацию объект класса**. Выберите способ идентификации: по `gid`, по мнемокоду, по `guid`.

**Для специализированных типов.** Для сложных объектов (Роль, Профиль, Печатная форма и др.) доступна дополнительная опция: **Добавить для специализированных типов** — добавляет объект с учётом связанных зависимостей (например, для Роли выгружаются также связанные права, ограничения, зависимости).