Skip to content

technical.md

Latest commit

 

History

History
285 lines (210 loc) · 18 KB

technical.md

File metadata and controls

285 lines (210 loc) · 18 KB
Raw

Техническая документация gitsync-plugins

Архитектура

Проект gitsync-plugins — набор встроенных плагинов для gitsync, инструмента синхронизации конфигураций 1С с git.

Плагины написаны на OneScript (OScript) — русскоязычном диалекте, совместимом со встроенным языком 1С:Предприятие.

Жизненный цикл плагина

Плагин реализует интерфейс, определённый в src/Классы/plugin.os.template. Хостовое приложение gitsync вызывает хуки плагинов в фиксированной последовательности.

Обязательные экспортные функции

Функция Назначение
Версия() Строка версии плагина
Приоритет() Числовой приоритет (0 — по умолчанию)
Описание() Краткое описание
Справка() Подробная справочная информация с параметрами
Имя() Уникальное имя плагина (используется для включения/отключения)
ИмяЛога() Имя логера, формат oscript.lib.gitsync.plugins.<plugin-name>

Жизненные хуки (в порядке вызова)

Хуки регистрации

Хук Когда вызывается Назначение
ПриАктивизации(СтандартныйОбработчик) При включении плагина Сохранение ссылки на стандартный обработчик, инициализация
ПриРегистрацииКомандыПриложения(ИмяКоманды, КлассРеализации) При парсинге аргументов команды Регистрация опций CLI через КлассРеализации.Опция()
ПриПолученииПараметров(ПараметрыКоманды) После разбора аргументов Чтение значений параметров из ПараметрыКоманды.Параметр()

Хуки синхронизации (для команды sync)

Хук Когда вызывается Назначение
ПередНачаломВыполнения(ПутьКХранилищу, КаталогРабочейКопии) Перед началом основного цикла Чтение контекста, подготовка
ПередВыгрузкойКонфигурациюВИсходники(Конфигуратор, КаталогРабочейКопии, КаталогВыгрузки, ПутьКХранилищу, НомерВерсии, Формат) Перед каждой выгрузкой версии Модификация конфигурации перед выгрузкой
ПриВыгрузкеКонфигурациюВИсходники(Конфигуратор, КаталогВыгрузки, Формат, СтандартнаяОбработка) Вместо штатной выгрузки Переопределение механизма выгрузки
ПослеВыгрузкиКонфигурациюВИсходники(Конфигуратор, КаталогРабочейКопии, КаталогВыгрузки, ПутьКХранилищу, НомерВерсии, Формат) После выгрузки Дополнительная обработка выгруженных файлов
ПередПеремещениемВКаталогРабочейКопии(КаталогВыгрузки, КаталогРабочейКопии) Перед копированием из врем. каталога Преобразование файлов (распаковка форм, EDT)
ПриОчисткеКаталогаРабочейКопии(КаталогРабочейКопии, СтандартнаяОбработка) При очистке рабочей копии Переопределение очистки
ПриПеремещенииВКаталогРабочейКопии(КаталогВыгрузки, КаталогРабочейКопии, СтандартнаяОбработка) При копировании в рабочую копию Переопределение копирования
ПередОбработкойВерсииХранилища(СтрокаВерсии, СледующаяВерсия) Перед обработкой очередной версии Чтение данных версии
ПередНачаломЦиклаОбработкиВерсий(ТаблицаИсторииХранилища, ТекущаяВерсия, СледующаяВерсия, МаксимальнаяВерсияДляРазбора) Перед циклом по версиям Корректировка границ цикла
ПередКоммитом(ГитРепозиторий, КаталогРабочейКопии) Перед git-коммитом Добавление файлов, изменение .gitignore
ПослеКоммита(ГитРепозиторий, КаталогРабочейКопии) После коммита Теги, промежуточный push
ПослеОкончанияВыполнения(ГитРепозиторий, КаталогРабочейКопии) После завершения основного цикла Финальные операции (push, очистка)

Хуки расширенного жизненного цикла

Хук Когда вызывается Назначение
ПриКоммите(ГитРепозиторий, КаталогРабочейКопии) Вместо штатного коммита Переопределение коммита
ПослеПолученияТаблицыАвторов(ПутьКФайлуАвторов, ТаблицаАвторов) После загрузки AUTHORS Проверка/дополнение таблицы авторов
ПослеПолученияТаблицыВерсий(ТаблицаВерсий) После получения списка версий Модификация таблицы версий
ПослеПолученияТаблицыПользователей(ТаблицаПользователей) После получения списка пользователей Дополнение пользователей
ПриЗагрузкеВерсииХранилищаВКонфигурацию(Конфигуратор, ПутьКХранилищу, НомерВерсии) При загрузке версии Переопределение загрузки версии
ПриПолученииТаблицыВерсий(ПутьКХранилищу, НачальнаяВерсия, КонечнаяВерсия, СтандартнаяОбработка) Вместо получения таблицы версий Переопределение чтения истории

Регистрация опций CLI

В хуке ПриРегистрацииКомандыПриложения плагин регистрирует параметры:

// Флаговый параметр с переменной окружения
КлассРеализации.Опция("S skip-exists-tags", Ложь, "[*smart-tags] флаг пропуска ошибок")
                .Флаговый()
                .ВОкружении("GITSYNC_SKIP_EXISTS_TAGS");

// Строковый параметр с переменной окружения
КлассРеализации.Опция("b branch", "master", "[*sync-remote] Имя ветки")
                .ВОкружении("GITSYNC_REMOTE_BRANCH");

// Числовой параметр
КлассРеализации.Опция("min-task-count", 0, "[*check-comments] Минимальное количество задач")
                .ТЧисло();

Сигнатура .Опция(Спецификация, ЗначениеПоУмолчанию, Описание):

  • Спецификация: "короткийФлаг длинноеИмя" или просто "длинноеИмя"
  • ЗначениеПоУмолчанию: определяет тип параметра (булев, строка, число)
  • Описание: текст справки с префиксом категории [*имя-плагина]

Фильтрация команд

Переменная КомандыПлагина (массив строк) определяет, для каких команд плагин регистрирует опции. Устанавливается в Инициализация():

КомандыПлагина = Новый Массив;
КомандыПлагина.Добавить("sync");

Если КомандыПлагина отсутствует — плагин подключается неявно ко всем командам.

Несовместимость плагинов

Некоторые плагины (drop-config-dump, use-ibcmd) отключают несовместимые. Реализуется в ПриАктивизации:

СтандартныйОбработчик.МенеджерПлагинов.ОтключитьПлагин("increment");

Соглашение об именах логов

Формат: oscript.lib.gitsync.plugins.<plugin-name>

Добавление нового плагина

1. Создать файл плагина

Скопировать src/Классы/plugin.os.template в src/Классы/newPlugin.os.

2. Реализовать интерфейс

Обязательные функции:

  • Версия(), Приоритет(), Описание(), Справка(), Имя(), ИмяЛога()

Опционально — хуки, в которых плагин должен участвовать.

3. Зарегистрировать класс

В packagedef добавить:

.ОпределяетКласс("Плагин_НовыйПлагин", "src/Классы/newPlugin.os")

4. Написать BDD-тесты

  • Создать features/new-plugin.feature с Gherkin-сценариями
  • При необходимости добавить шаги в features/step_definitions/new-plugin.os
  • Шаг регистрируется в ПолучитьСписокШагов():
ВсеШаги.Добавить("ИмяНовогоШага");

5. Обновить документацию

  • README.md — добавить описание плагина в список
  • docs/user-guide.md — детальное описание с параметрами

6. Запустить тесты

export GITSYNC_V8VERSION=8.3.24.1691
export EDT_VERSION=2024.2.5
opm install --dev
opm install gitsync
opm run install-gitsync
opm test

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

gitsync-plugins/
├── packagedef            # Манифест пакета opm: версия, зависимости, классы
├── src/
│   └── Классы/
│       ├── *.os          # Плагины (один файл — один плагин)
│       ├── plugin.os.template  # Шаблон для новых плагинов
│       └── internal/     # Вспомогательные библиотеки
│           ├── tool1cd/  # Чтение файловой БД хранилища 1С
│           └── v8unpack/ # Распаковка контейнеров метаданных
├── features/
│   ├── *.feature         # Сценарии BDD (Gherkin)
│   └── step_definitions/
│       ├── shared.os     # Общие шаги для всех тестов
│       └── *.os          # Шаги конкретных плагинов
├── tests/
│   └── fixtures/         # Тестовые данные
│       ├── *.1CD         # Файловые хранилища 1С
│       ├── *.cf          # Файлы конфигураций
│       ├── *.mxl         # Отчёты по версиям
│       └── edtWorkspace/ # Тестовая рабочая область EDT
├── tasks/
│   ├── test.os           # Запуск BDD-тестов
│   ├── coverage.os       # Запуск с покрытием кода
│   ├── install-gitsync.os # Установка gitsync из исходников
│   └── install-plugins.os # Установка плагинов для тестов
├── docs/                 # Документация
│   ├── user-guide.md     # Пользовательская документация
│   └── technical.md      # Техническая документация (этот файл)
└── .github/workflows/    # CI/CD
    ├── testing.yml       # Матрица тестов (Windows/Linux, 1C/EDT версии)
    ├── qa.yml           # SonarQube + покрытие кода
    └── release.yml       # Сборка и публикация .ospx

Внутренние библиотеки

internal/tool1cd/

Библиотека для чтения файловой базы данных хранилища 1С (1cv8ddb.1CD):

  • ЧтениеХранилищаКонфигурации — выгрузка версий конфигурации из хранилища
  • ЧтениеТаблицФайловойБазыДанных — чтение таблиц VERSIONS и USERS
  • СконвертироватьФайлКонфигурации — конвертация между форматами 1C

internal/v8unpack/

Распаковщик контейнеров метаданных обычных форм:

  • Распаковщик.Распаковать() — извлекает содержимое Form.bin

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

Инфраструктура

Тесты построены на BDD-фреймворке 1bdd. Каждый плагин имеет свой .feature-файл. Общие шаги вынесены в features/step_definitions/shared.os.

Требования к окружению

  • Платформа 1С:Предприятие (версия из GITSYNC_V8VERSION)
  • EDT (версия из EDT_VERSION, по умолчанию 2022.2.5)
  • Java 11 (для EDT ≤2023) или Java 17 (для EDT ≥2024)
  • Локаль ru_RU

Запуск

# Все тесты
opm test

# С покрытием кода
opm run coverage

# Отдельный тестовый файл (через oscript напрямую)
oscript ./tasks/test.os

Тестовые фикстуры

  • ТестовыйФайлХранилища1С.1CD — файловое хранилище с несколькими версиями (используется большинством тестов)
  • ТестовыйФайлКонфигурации.cf — выгруженная конфигурация
  • ТестовыйФайлКонфигурации_8_2_17.cf — конфигурация в старом формате
  • edtWorkspace/ — тестовая рабочая область EDT
  • ОтчетПоВерсиямХранилища.mxl — эталонный отчёт по версиям

CI/CD

Тестирование (.github/workflows/testing.yml)

Матрица: OScript [1.9.2, 2.0.0] × 1C [8.3.21, 8.3.24] × EDT [2023.3.6, 2024.2.5] × OS [windows, ubuntu].

Особенности Linux:

  • Требуется libenchant1c2a для 1C 8.3.21
  • Wine для работы tool1CD
  • XVFB для headless-тестов

QA (.github/workflows/qa.yml)

  • Запускается только для репозитория oscript-library/gitsync-plugins
  • Собирает покрытие кода через opm run coverage
  • Отправляет результаты в SonarQube
  • Версия пакета извлекается из packagedef для SonarQube

Релиз (.github/workflows/release.yml)

  • Триггер: GitHub Release (published/edited)
  • Собирает .ospx пакет через opm build
  • Публикует артефакт в релиз и на hub.oscript.io

Процесс выпуска версии

  1. Поднять версию в packagedef (.Версия("X.Y.Z"))
  2. Создать PR, получить аппрув и мёрдж в master
  3. Создать GitHub Release — CI соберёт пакет и опубликует его
  4. Обновить ссылку на версию в репозитории gitsync в файле tasks/get_plugins.os
  5. Выпустить новую версию gitsync

Конвенции кода

  • Язык комментариев и идентификаторов — русский
  • Максимальная длина строки: 150 символов (см. .bsl-language-server.json)
  • Имена логов: oscript.lib.gitsync.plugins.<plugin-name>
  • Приоритет() = 0, если плагину не требуется особый порядок выполнения
  • Файл — один плагин, имя файла совпадает с Имя()
  • Переменная Лог инициализируется в Инициализация() или ПриАктивизации(): 
    Лог = Логирование.ПолучитьЛог(ИмяЛога());