Для разработчиков

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

Исполнение обработчиков: права и режимы

Обработчик потока данных и обработчик пост-обработки подписчика исполняются как внешняя обработка, собранная подсистемой. Права и режимы исполнения распределены так:

Этап	Режим	Почему
`ВнешниеОбработки.Подключить`	привилегированный	подключение в небезопасном режиме требует права «Интерактивное открытие внешних обработок»
`ВнешниеОбработки.Создать`	обычный	прикладной код здесь не исполняется: на уровень модуля попадают только объявления переменных и завершённые блоки процедур
вызов точки входа обработчика	безопасный	прикладной код не должен обращаться к внешним ресурсам

Участок привилегированного режима минимален: он охватывает только сам вызов подключения и снимается на всех путях, включая путь с исключением. Прикладной код обработчика привилегированным режимом не охвачен никогда.

Минимальный набор прав

Для формирования исходящего и обработки входящего сообщения достаточно ролей инт_Администрирование и инт_ИзменениеДанных. Роль полного администратора не требуется.

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

Регламентные и фоновые задания подсистемы работают под тем же набором прав.

События журнала регистрации механизма генерации

Событие	Уровень	Когда
`ПодсистемаИнтеграции.ГенераторОбработок.Компиляция`	Информация	внешняя обработка собрана заново
`ПодсистемаИнтеграции.ГенераторОбработок.Подключение`	Информация	внешняя обработка подключена к сеансу
`ПодсистемаИнтеграции.ГенераторОбработок.ОшибкаКомпиляции`	Ошибка	сборка не удалась
`ПодсистемаИнтеграции.ГенераторОбработок.ОшибкаПодключения`	Ошибка	подключение не удалось
`ПодсистемаИнтеграции.ГенераторОбработок.ОбработчикНеЗаполнен`	Ошибка	у потока данных нет текста обработчика
`ПодсистемаИнтеграции.ГенераторОбработок.ВременныйФайл`	Ошибка	временный файл сборки не удалось удалить

В записи попадают владелец обработчика (в параметрах «данные» и «метаданные»), признак версии текста и длительность этапа в миллисекундах. Текст обработчика в журнал не выгружается.

Число компиляций и суммарную длительность получают выборкой журнала по событию ПодсистемаИнтеграции.ГенераторОбработок.Компиляция: число компиляций равно числу записей, суммарная длительность — сумме значений длительности из них. Отдельной метрики подсистемы мониторинга для этого не заводится.

Записи уровня «Информация» пишутся только при фактической компиляции и подключении, то есть из кэша со временем жизни «В течение сеанса». На каждый серверный вызов они не приходятся.

Ошибки исполнения обработчика журналируют вызывающие стороны своими событиями (ПодсистемаИнтеграции.ПотокиДанных.*, ПодсистемаИнтеграции.Подписчики.ПостОбработкаОтвета), поэтому этапы компиляции, подключения и исполнения различаются по имени события.

Настройка окружения

Требования

Компонент	Версия
Платформа 1С:Предприятие	8.3.24.1548+
OneScript	stable
vrunner	2.6.0+
precommit4onec	latest

Первоначальная настройка

batch

# 1. Клонируйте репозиторий
git clone https://github.com/Segate-ekb/integration_subsystem.git
cd integration_subsystem

# 2. Установите пакеты OneScript
opm install vrunner precommit4onec

# 3. Установите pre-commit hook
precommit4onec install .

# 4. Подключите проверку уникальности идентификаторов к фиксации изменений
install-hooks.cmd

# 5. Скопируйте конфигурацию
copy env.json.example env.json

# 6. Подготовьте базу данных
prepare.cmd

Автоматическая настройка

batch

# Альтернативно — запустите скрипт автонастройки
init-project.cmd

Рабочий процесс

Используем git-flow:

main ─────────────────────────────────────────────────────────
       ↑                                    ↑
develop ──┬─────────┬───────────────────────┼─────────────────
          │         ↑                       ↑
feature/xxx ────────┘      feature/yyy ─────┘

Типичный цикл разработки

batch

# 1. Создайте ветку от develop
git checkout -b feature/my-feature develop

# 2. Синхронизируйте БД с веткой (ОБЯЗАТЕЛЬНО!)
update.cmd

# 3. Напишите тесты (TDD)
# ... разработка тестов ...

# 4. Реализуйте функционал
# ... разработка в Конфигураторе ...

# 5. Убедитесь, что тесты проходят
# Запустите 1С:Предприятие с параметром RunUnitTests

# 6. Выгрузите изменения
decompile.bat

# 7. Зафиксируйте изменения
git add .
git commit -m "feat: описание изменений"

# 8. Создайте Merge Request в develop

Важно!

Всегда запускайте update.cmd после переключения ветки. Иначе возникнут фантомные изменения!

Проверка уникальности идентификаторов

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

Проверка читает только файлы выгрузки src/cf и src/cfe/*: платформа 1С:Предприятие и информационная база ей не нужны, полная выгрузка проверяется примерно за две секунды.

Ручной запуск

batch

check-ids.cmd

Успешная проверка даёт код возврата 0 и сообщение «Столкновений идентификаторов не обнаружено». При столкновении проверка называет значение и по каждому его носителю — путь к файлу, номер строки и имя объекта метаданных:

src/cf: в пространстве «идентификаторы объектов метаданных» значение b2c3d4e5-f6a7-8901-bcde-f23456789012 объявлено более одного раза:
      src/cf/Catalogs/инт_Эндпоинты.xml:219 — Attribute ТаймаутСоединения
      src/cf/CommonModules/инт_ГенераторОбработок.xml:3 — CommonModule инт_ГенераторОбработок

Перед фиксацией изменений

Ловушка pre-commit выполняет ту же проверку по текущему состоянию рабочего каталога, поэтому столкновение, внесённое в подготовленные к фиксации файлы, обнаруживается до записи изменения в репозиторий. Ловушка устанавливается один раз после клонирования:

batch

install-hooks.cmd

Если ловушка pre-commit уже занята другим средством, скрипт сообщит об этом и ничего не изменит — тогда добавьте вызов check-ids.cmd в существующую ловушку вручную.

Ловушка работает на машине разработчика и может быть обойдена, поэтому она не единственное препятствие: то же столкновение остановит сборку и будет замечено на ревью.

Перед сборкой артефактов

Проверка выполняется первым шагом в build.cmd, prepare.cmd и update.cmd — во всех скриптах, которые создают артефакты. При столкновении скрипт завершается с кодом возврата 1, не создавая ни файл конфигурации build/1cv8.cf, ни расширение build/YAXUNIT.cfe.

Что ошибкой не признаётся

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

Структура проекта

integration_subsystem/
├── src/
│   ├── cf/                    # Основная конфигурация
│   │   ├── Catalogs/          # Справочники
│   │   ├── CommonModules/     # Общие модули
│   │   ├── InformationRegisters/  # Регистры сведений
│   │   └── ...
│   └── cfe/
│       └── YAXUnit/           # Расширение с тестами
│
├── tests/
│   ├── uaxunit_config.json    # Конфигурация тестов
│   └── fixtures/              # Тестовые данные
│
├── build/
│   ├── ib/                    # Рабочая БД
│   └── YAXUNIT.cfe            # Собранное расширение
│
├── tools/
│   ├── JSON/                  # Конфиги vrunner, vanessa
│   ├── hooks/                 # Ловушки системы контроля версий
│   └── check-ids.os           # Проверка уникальности идентификаторов
│
├── prepare.cmd                # Подготовка БД
├── update.cmd                 # Обновление БД
├── decompile.bat              # Выгрузка конфигурации
├── build.cmd                  # Сборка CF
├── check-ids.cmd              # Проверка уникальности идентификаторов
├── install-hooks.cmd          # Установка ловушки перед фиксацией
└── test.cmd                   # Запуск тестов

Тестирование

YAXUNIT

Тесты находятся в расширении src/cfe/YAXUnit/CommonModules/.

Соглашения по именованию:

ОМ_* — тесты общих модулей
РС_*_ММ — тесты регистров сведений
СПР_*_ММ — тесты справочников

Структура теста

bsl

// ОМ_инт_ВалидаторПакетов

Процедура ИсполняемыеСценарии() Экспорт
    ЮТТесты.УдалениеТестовыхДанных().ВТранзакции()
        .ДобавитьТестовыйНабор("Валидация")
            .ДобавитьТест("ВалидацияКорректногоСообщения")
            .ДобавитьТест("ВалидацияНекорректногоСообщения");
КонецПроцедуры

Процедура ВалидацияКорректногоСообщения() Экспорт
    // Arrange
    Сообщение = Новый Соответствие;
    Сообщение.Вставить("id", "123");
    Сообщение.Вставить("name", "Test");
    
    Схема = ПолучитьТестовуюСхему();
    
    // Act
    МассивОшибок = инт_ВалидаторПакетов.Валидировать(
        Сообщение, "TestSchema", Схема);
    
    // Assert
    ЮТест.ОжидаетЧто(МассивОшибок).ИмеетДлину(0);
КонецПроцедуры

Генератор тестовых данных

bsl

// Используйте модуль ГенераторТестовыхДанных
ПотокДанных = ГенераторТестовыхДанных.ПотокДанныхИсходящий();
Документ = ГенераторТестовыхДанных.демо_Документ();

Запуск тестов

Откройте Конфигуратор
Сервис → Параметры → Запуск 1С:Предприятия
Параметр запуска: RunUnitTests=<путь>\tests\uaxunit_config.json
Запустите 1С:Предприятие

Соглашения по коду

Регионы модуля

bsl

#Область ПрограммныйИнтерфейс
    // Публичные методы — используются из других модулей
#КонецОбласти

#Область СлужебныйПрограммныйИнтерфейс
    // Внутренние методы подсистемы
#КонецОбласти

#Область СлужебныеПроцедурыИФункции
    // Приватные методы модуля
#КонецОбласти

Префиксы объектов

Префикс	Назначение
`инт_`	Объекты подсистемы интеграции
`пэм`	Объекты мониторинга Prometheus
`ИТКВ_`	Консоль разработчика (вспомогательное)

BSL Language Server

Используйте директивы для отключения проверок:

bsl

// BSLLS:Typo-off
// ... код с техническими терминами ...
// BSLLS:Typo-on

CI/CD

Jenkins Pipeline

Файл Jenkinsfile определяет пайплайн:

Checkout
Подготовка базы
Загрузка расширения
Запуск тестов
SonarQube анализ
Сборка артефактов

SonarQube

Настройки в sonar-project.properties:

properties

sonar.projectKey=integration_subsystem
sonar.sources=src/cf
sonar.sourceEncoding=UTF-8

Для разработчиков ​

Исполнение обработчиков: права и режимы ​

Минимальный набор прав ​

События журнала регистрации механизма генерации ​

Настройка окружения ​

Требования ​

Первоначальная настройка ​

Автоматическая настройка ​

Рабочий процесс ​

Типичный цикл разработки ​

Проверка уникальности идентификаторов ​

Ручной запуск ​

Перед фиксацией изменений ​

Перед сборкой артефактов ​

Что ошибкой не признаётся ​

Структура проекта ​

Тестирование ​

YAXUNIT ​

Структура теста ​

Генератор тестовых данных ​

Запуск тестов ​

Соглашения по коду ​

Регионы модуля ​

Префиксы объектов ​

BSL Language Server ​

CI/CD ​

Jenkins Pipeline ​

SonarQube ​

Полезные ссылки ​

Для разработчиков

Исполнение обработчиков: права и режимы

Минимальный набор прав

События журнала регистрации механизма генерации

Настройка окружения

Требования

Первоначальная настройка

Автоматическая настройка

Рабочий процесс

Типичный цикл разработки

Проверка уникальности идентификаторов

Ручной запуск

Перед фиксацией изменений

Перед сборкой артефактов

Что ошибкой не признаётся

Структура проекта

Тестирование

YAXUNIT

Структура теста

Генератор тестовых данных

Запуск тестов

Соглашения по коду

Регионы модуля

Префиксы объектов

BSL Language Server

CI/CD

Jenkins Pipeline

SonarQube

Полезные ссылки