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

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

Механизм используется для передачи бизнес-объектов и 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` | Переопределенный атрибут выборки. Если на исходном контуре переопределение отсутствует, то на целевом контуре переопределение будет удалено. Для указания системного имени используется специальная выборка |
| **Переопределение операций выборки** | Формат: `Выборка;Отображение;Операция` / `Btk_SelOperOverride` | Переопределенная операция выборки (в т.ч. JEXL-операции, добавленные через «Обозреватель проекта»). Если на исходном контуре переопределение отсутствует, то на целевом контуре переопределение будет удалено. Для указания системного имени используется специальная выборка |
| **Все объекты таблицы вариантов** | Системное имя или `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` | Тег комплекта сборки, коммиты и измененные сущности |

## Настройки переноса бизнес объектов

Система позволяет управлять тем, какие классы, коллекции и атрибуты участвуют в переносе. Это необходимо, когда часть данных управляется внешними системами (например, интеграциями с HR или ERP) и не должна перезаписываться при установке конфигурации.

Путь: `Настройки системы > Настройки и сервисы > Управление конфигурацией > Настройки переноса бизнес объектов`.

В интерфейсе отображается дерево бизнес-объектов. Верхний уровень дерева содержит классы шапок бизнес-объектов, последующие уровни — классы их коллекций.

Для поиска используются фильтры **Код**, **Наименование**, **Модуль** и **Класс**. Флаг **Показать удаленные** включает в отображение удаленные классы.

В дереве отображаются следующие колонки:

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

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

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

Для выбранных классов и атрибутов доступно групповое редактирование настроек.

### Настройки переноса атрибутов

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

Для поиска атрибутов используются фильтры **Системное имя атрибута** и **Наименование атрибута**. Флаг **Отображать назначенные к удалению** включает в список атрибуты, назначенные к удалению.

На закладке отображаются следующие колонки:

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

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

После изменения настроек переноса необходимо очистить кэш (`Сервис > Управление решением > Очистить все кэши`).

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

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

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** требуется:
- предварительная настройка доступа к стороннему сервису как с исходного, так и с целевого контура;
- согласование параметров маршрутизации (значения «Наименование целевого контура» должны соответствовать кодам настроек на противоположной стороне);
- создание технических пользователей с минимально необходимыми правами и зашифрованными учётными данными.

Детали настройки пайплайна и репозитория смотрите в разделе [Настройка обмена через репозиторий](https://help.globalerp.ru/books/G3SysAdminDoc/SNAPSHOT/html/070_addition/040_add_contour.html).
```

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

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

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

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

**Отслеживание изменений на уровне класса.** В разделе [Настройки переноса бизнес объектов](#настройки-переноса-бизнес-объектов) выберите нужный класс, установите флаг **Отслеживать изменения для включения в релиз конфигурации**, очистите кэш.

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

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

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

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

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

## Настройка уникального ключа

Уникальный ключ — это набор атрибутов, значения которых однозначно идентифицируют объект класса. Корректная настройка уникального ключа обязательна для переноса объектов: если объект относится к классу без настроенного уникального ключа, выгрузка и установка конфигурации будут заблокированы.

**Способы настройки:**
- **Предпочтительный способ:** разработчики указывают уникальные атрибуты непосредственно в метаданных приложения. Это гарантирует согласованность настройки между исходным и целевым контурами.
- **Ручная настройка:** при необходимости можно включить флаг **Ключевой атрибут** для нужных атрибутов в разделе **Настройки переноса бизнес объектов** на закладке **Настройки переноса атрибутов** или отметить атрибуты как уникальные на закладке **Уникальные атрибуты класса** в карточке класса. Настройка должна быть выполнена идентично на обеих базах. После ручной настройки очистите кэш (`Сервис > Управление решением > Очистить все кэши`) и переоткройте карточку конфигурации.

## Диагностика типовых ошибок

Ниже приведены типовые ошибки, их причины и способы устранения.

### Не настроена уникальность

**Когда возникает.**  
Ошибка появляется при попытке формирования конфигурации на исходном контуре или при её установке на целевом контуре. Процесс блокируется до устранения причины.

**Сообщение.**  
`Не настроена уникальность (класс <Класс>)`  
или  
`Ошибка импорта объекта. Передан не уникальный ключ для объекта класса <Класс>`

**Причина.**  
В конфигурацию включены объекты класса, для которого не определён уникальный ключ. Уникальный ключ — это набор атрибутов, значения которых однозначно идентифицируют объект в пределах класса. Без него система не может:
- найти существующий объект на целевом контуре для обновления;
- отличить новый объект от уже существующего;
- гарантировать, что при установке не будут созданы дубликаты или перезаписаны чужие данные.

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

**Как исправить.**

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

```{attention}
Если уникальный ключ настраивается вручную, убедитесь, что выбранные атрибуты действительно обеспечивают уникальность объектов в вашей предметной области. Слишком общие атрибуты (например, только «Наименование») могут привести к ошибке «Найдено несколько объектов с одинаковым уникальным ключом».
```

### Не найден ссылочный объект

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

**Сообщение.**  
`Не найден объект класса <Класс>, на который ссылается атрибут <Атрибут> класса <Родительский класс>`

**Причина.**  
Переносимый объект содержит ссылку на запись, которой нет на целевом контуре. По умолчанию все ссылочные атрибуты считаются обязательными: система не может создать объект, не зная, на что он ссылается, так как это нарушает целостность данных. Установка прерывается, чтобы избежать создания «битых» ссылок.

**Как исправить.**  
Выберите один из вариантов в зависимости от бизнес-логики и того, должен ли ссылочный объект существовать на целевом контуре независимо от конфигурации.

| Вариант | Действия | Результат |
|---------|----------|-----------|
| **Создать объект вручную** | На целевом контуре создайте недостающий объект с тем же уникальным ключом, что и на исходном контуре. Убедитесь, что значения всех атрибутов, входящих в уникальный ключ, совпадают. | После создания объекта повторно установите конфигурацию. Ссылка будет установлена на существующий объект |
| **Перенести отдельной конфигурацией** | Выгрузить недостающий объект в отдельный пакет конфигурации, установить его на целевой контур, затем повторно установить основную конфигурацию. | Ссылочная целостность восстановится автоматически при второй установке |
| **Изменить порядок задач** | Включить недостающий объект в ту же конфигурацию, но задать ему порядковый номер **меньше**, чем у объекта, ссылающегося на него. Установка выполняется строго по возрастанию порядкового номера. | Установка выполнится в правильном порядке: сначала создаётся ссылочный объект, затем — зависимый |
| **Снять требование ссылочной целостности** | На целевом контуре в разделе **Настройки переноса бизнес объектов** на закладке **Настройки переноса атрибутов** снимите флаг **Требуется наличие объекта по ссылке при переносе входящими релизами конфигурации**. На исходном контуре можно снять флаг **Выгружается в исходящих релизах конфигурации**, чтобы значение ссылки не передавалось в пакете. После изменения настроек очистите кэш. Если флаг снят на исходном контуре, повторно сформируйте конфигурацию перед установкой. | Установка пройдёт без ошибки, но поле ссылки останется пустым. Используйте, если ссылка не критична или будет заполнена позже |

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

### Найдено несколько объектов с одинаковым уникальным ключом

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

**Сообщение.**  
`Найдено несколько объектов с одинаковым уникальным ключом`  
или  
`Ошибка импорта объекта. Передан не уникальный ключ для объекта класса <Класс>`

**Причина.**  
На целевой базе существует несколько записей, у которых совпадают значения всех атрибутов, входящих в уникальный ключ. Это нарушает условие однозначной идентификации: система не может понять, какой из существующих объектов следует обновить, а какой — оставить без изменений. Установка прерывается, чтобы избежать некорректной перезаписи данных.

**Как исправить.**

| Причина дублирования | Решение |
|---------------------|---------|
| **Существуют объекты с одинаковыми комбинациями атрибутов** | Найти и удалить лишние записи на целевом контуре. Для этого выполните поиск по значениям атрибутов, входящих в уникальный ключ. Удалите дубликаты, оставив только актуальную запись. На программном уровне настройте ограничения (например, уникальные индексы в БД), исключающие создание таких дубликатов в будущем. |
| **Уникальный ключ настроен некорректно** | Сбросить пользовательское переопределение ключа в интерфейсе или обратиться к разработчикам для исправления метаданных. Проверьте, что в ключ включены достаточно специфичные атрибуты, которые в совокупности действительно обеспечивают уникальность. Например, для класса «Сотрудник» ключ может включать «Табельный номер», но не только «ФИО». |

### Циклические ссылки между классами

**Когда возникает.**  
При попытке переноса двух взаимно ссылающихся классов: класс `A` содержит ссылку на класс `B`, а класс `B` содержит ссылку на класс `A`. Установка постоянно завершается ошибкой отсутствия ссылочного объекта, независимо от того, какая задача идёт первой.

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

**Как исправить.**  
Выполните перенос в три этапа, временно отключив проверку ссылочной целостности:

1. **Подготовка.**  
   На целевом контуре в разделе **Настройки переноса бизнес объектов** для одного из классов (например, класса `A`) откройте закладку **Настройки переноса атрибутов** и снимите флаг **Требуется наличие объекта по ссылке при переносе входящими релизами конфигурации** для атрибута, ведущего на класс `B`. После изменения настройки очистите кэш.

2. **Перенос.**  
   Перенесите оба класса в составе одной конфигурации. Ошибок ссылочной целостности не возникнет, так как проверка отключена. Поля ссылок временно останутся пустыми, но объекты будут созданы на целевом контуре.

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