1С — маппинг сущностей и метаданных¶

Обзор¶

Документ описывает архитектуру маппинга между сущностями 1С:Предприятие и 1Формы: как платформа извлекает метаданные из конфигурации 1С, как строит соответствия объектов и реквизитов, какие типы поддерживает.

Операционные аспекты (retry, очередь, диагностика ошибок) -- в data-flow.md и runbook-1c-connect-auth.md. Полный справочник XML-тегов -- в support-guide-1c.md.

1. Модель маппинга¶

Центральная идея: один справочник/документ 1С = одна категория 1Ф, реквизиты 1С = ДП категории.

Сущность 1С	Сущность 1Ф	Связующий ключ
Справочник (Каталог)	Категория (`Subcategories`)	`OneCDocName` ↔ `TCSubcatID`
Документ	Категория	`OneCDocName` ↔ `TCSubcatID`
Элемент справочника / документ	Задача (`Tasks`)	GUID в ДП (`GUIDExtParamID`)
Реквизит (физический)	ДП (`ExtParams`)	`RequisiteName` ↔ `ExtParamID`
Виртуальный реквизит	ДП	`PropertyUse="Виртуальный"`
Табличная часть	ДП "Таблица"	Колонки маппятся аналогично реквизитам
Пользователь 1С	Пользователь 1Ф	`Sync1CUsersMap` (логин ↔ UserID)

GUID -- якорь идентичности. Каждая база 1С требует отдельный ДП для хранения GUID (GUIDExtParamID в SyncSettings). При нескольких задачах с одинаковым GUID обновляется только последняя (max TaskID).

2. Извлечение метаданных из 1С¶

Как Builder получает список объектов¶

Админ открывает Мастер добавления справочников в UI (Sync1CDictionaryComponent).
Фронт вызывает GET /api/admin/sync1c/builder/dictionaries?name={configName}.
Backend (Sync1CConfigBuilderController → Sync1CConfigBuilderService) создаёт SOAP-клиент к OneCAddress из профиля.
SOAP-вызов GetFirstData возвращает список доступных объектов (справочники + документы) с их реквизитами и типами.
Фронт отображает дерево объектов с чекбоксами для выбора.

Что возвращается из 1С¶

Для каждого объекта: системное имя (OneCDocName), синоним (OneCSynonym), список реквизитов с именами, синонимами и типами. Виртуальные реквизиты включаются в выгрузку, если они зарегистрированы в справочнике "Виртуальные реквизиты (Первая Форма)" на стороне 1С.

3. Builder: 4 шага создания маппинга¶

Builder -- конвейер для автоматического создания категорий и ДП на основе метаданных 1С.

Шаг	UI	API	Сервис	Что происходит
1	Выбор справочников из дерева	`GET builder/dictionaries`	`Sync1CConfigBuilderService`	SOAP-запрос в 1С, отображение дерева объектов
2	Monaco Editor с XML	`POST builder/prepare-config`	`Sync1CConfigBuilderService`	Генерация XML-конфига (`Record` + `SyncProperties`) для выбранных объектов. Админ может отредактировать XML
3	Preview: список категорий и ДП	`POST builder/prepare-subcategories`	`Sync1CConfigBuilderService`	Парсинг XML → список категорий/ДП для создания, preview с warnings
4	Результат: ID или ошибки	`POST builder/create-subcategories` + `POST builder/apply`	`Sync1CConfigBuilderService`	Создание категорий и ДП в БД. Если ДП с таким именем и типом уже есть -- переиспользуется. `ExtParamID` подставляется автоматически

Флаги шага 4 (checkboxes в UI): - addInSyncSettings -- добавить Record в конфиг - saveInDB -- сохранить конфиг в SyncSettings1C - sendTo1C -- отправить обновлённый конфиг в 1С - getFirstData -- выполнить первичную выгрузку данных

Preconditions¶

Перед запуском: создан или выбран профиль настроек (SyncSettings).
Лучше запускать, когда справочники есть в 1С, но не настроены в 1Ф -- тогда маппинг ДП строится автоматически.
При добавлении уже существующей категории -- рекомендуется заранее удалить из неё ДП, не участвующие в обмене.

4. XML-конфиг: структура маппинга¶

Конфиг хранится в SyncSettings1C.XmlContent. Структура:

SyncSettings                          -- корневой: credentials, GUIDExtParamID
  └─ SyncRecords
       └─ Record                      -- один справочник/документ 1С ↔ категория 1Ф
            ├─ SyncProperties
            │    └─ Property           -- один реквизит 1С ↔ один ДП 1Ф
            │         ├─ AllowedValues -- допустимые значения (для Combobox/Select)
            │         ├─ TableColumns  -- колонки (для ДП "Таблица")
            │         └─ Links         -- ссылки на справочники (для Lookup)
            ├─ Files                   -- маппинг вложенных файлов
            ├─ SyncEvents1С            -- события из 1С (Create, Modify, Post...)
            └─ SyncEventsTC            -- события из 1Ф (ChangeTask, MakeStep...)

Ключевые атрибуты Record¶

Атрибут	Назначение
`OneCDocName`	Системное имя объекта 1С (`Справочник.Контрагенты`)
`TCSubcatID`	ID категории 1Ф
`SyncSource`	Кто источник: `_1C`, `_TC`, `Both`
`SyncDirections`	Направление: `TwoSided`, `From1CtoTC`, `FromTCto1C`
`DefaultActionOnError`	При ошибке: `AddToQuery`, `ForceAddToQuery`, `Cancel`, `Ignore`
`SmartFilterID`	Фильтр задач для выгрузки (0 = всё)
`InboxQueueFlowId`	Flow для обработки входящих через очередь

Ключевые атрибуты Property¶

Атрибут	Назначение
`ExtParamID`	ID ДП в 1Ф
`RequisiteName`	Имя реквизита в 1С
`Type`	Тип ДП (см. маппинг типов ниже)
`PropertyUse`	`ДляГруппыИЭлемента`, `ДляГруппы`, `ДляЭлемента`, `Виртуальный`
`RepresentAsReadonlyText`	`true` -- ссылочный тип передаётся как текст, без выгрузки связанного справочника
`TCLookupGUIDEPID`	ID скрытого текстового ДП для хранения GUID (только для Lookup)
`OneCEvents`	При каких событиях 1С передавать реквизит
`TcEvents`	При каких событиях 1Ф передавать реквизит

5. Маппинг типов¶

Тип ДП 1Ф (`Type`)	Что в 1С	Особенности
`Text`	Строка	Основной тип
`TextArea`	Строка (длинная)	Большой текст
`TextareaWOFormat`	Строка	Без форматирования
`Numerator`, `NumericValue`	Число
`Money`	Число (денежное)
`Date`	Дата
`DateTime`	Дата + время
`Checkbox`	Булево	Да/нет
`Combobox`, `Select`	Перечисление	Допустимые значения в `AllowedValues`
`LookUpField`	Ссылка (на справочник)	Требует пару ДП: сам Lookup + скрытый текстовый для GUID (`TCLookupGUIDEPID`). Целевой справочник указывается в `Links`
`Table`	Табличная часть	Колонки маппятся в `TableColumns`, каждая со своим типом
`URL`	Строка-ссылка	Нетипизированная URL

Особый случай: Lookup¶

Для каждого ДП Lookup, участвующего в обмене, создаётся дополнительный скрытый текстовый ДП для хранения GUID задачи-ссылки. Соглашение по именованию: {имя Lookup}_link (например, Контрагент → Контрагент_link).

ID этого ДП указывается в атрибуте TCLookupGUIDEPID тега Property.

При глобальном поиске по GUID, если найдено более одной задачи -- ошибка. В этом случае нужно явно указать имя справочника через Links.

Особый случай: RepresentAsReadonlyText¶

Если из 1С нужно получить ссылочный объект, но в 1Ф достаточно текстового представления (без синхронизации подчинённого справочника): RepresentAsReadonlyText="true", тип ДП -- Text.

Особый случай: ДП "Таблица"¶

При синхронизации таблиц скрытые и readonly-колонки игнорируются, что вызывает несовпадение числа колонок. Решение: DefaultActionOnError="ForceAddToQuery" (обработка через очередь).

Альтернативный паттерн: скрытый текстовый ДП с JSON-представлением таблицы + SmartAction для обновления основного ДП "Таблица".

6. Виртуальные реквизиты¶

Виртуальный реквизит -- вычисляемое поле на стороне 1С, которому в 1Ф соответствует реальный ДП. Значение не хранится в БД 1С, а формируется "на лету" при обмене.

Назначение: расширить список данных для синхронизации без изменения типовой конфигурации 1С.

Структура¶

Справочник "Виртуальные реквизиты (Первая Форма)" в 1С:

Поле	Назначение
Имя	Системное имя (не должно совпадать с реальными реквизитами)
Синоним	Отображаемое имя
Тип	Тип ДП в 1Ф (Строка, Число, Лукап и др.)
Алгоритм вычисления	Код 1С для получения значения. Результат → `ЗначениеРеквизита`
Алгоритм записи	Код 1С при получении значения из 1Ф. Входное значение → `ЗначениеИз1Ф`

В XML-конфиге¶

PropertyUse="Виртуальный" в теге Property.

При RefreshExtParams=false виртуальные реквизиты всё равно обновляются (вместе с изменёнными реквизитами и табличными частями).

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

В справочнике виртуальных реквизитов 1С есть кнопки: - Проверить алгоритмы вычисления -- вычисляет значения для выбранного объекта - Проверить алгоритмы записи -- выполняет запись в транзакции с откатом (данные не сохраняются)

Подробнее: support-guide-1c.md

7. Виртуальные документы¶

Виртуальный документ -- данные, формируемые в 1С по алгоритму и передаваемые в 1Ф. Два типа:

Алгоритм (файл)¶

Формирует табличный документ 1С → сохраняет как файл (pdf, xls, txt, docx, html, ods) → отправляет в 1Ф.

Конфиг: OneCDocName="ВиртуальныйДокумент.{ИмяВСправочнике}", выходной формат задаётся в Files.BinFileProperty.

Запрос (таблица)¶

Формирует таблицу данных из запроса 1С → выгружает указанные реквизиты → передаёт как ДП "Таблица" в 1Ф.

Общее¶

Виртуальные документы можно совмещать с обычной передачей реквизитов в одном Record
Справочник "Виртуальные документы (Первая Форма)" на стороне 1С хранит алгоритмы
Property из конфига передаются как параметры алгоритма (через ПараметрыАлгоритма)

Подробнее: support-guide-1c.md

Виртуальные документы как отчёты (Query-тип)¶

Начиная с версии модуля 1С от 2026-04, доступен новый тип виртуальных реквизитов — виртуальные документы (отчёты). Они позволяют получать агрегированные данные из 1С: P&L, расчётные листки, остатки отпусков, ФОТ и другие бизнес-отчёты.

В справочнике rgВиртуальныеДокументы (Первая Форма) создаются элементы с видом Query — в отличие от стандартных виртуальных реквизитов (вид Attribute), Query-тип возвращает таблицу данных вместо скалярного значения.

Методы веб-сервиса для работы с виртуальными документами:

Метод	Назначение
`GetReportDefinition`	Получение структуры отчёта (колонки, типы данных)
`ExecuteQuery`	Выполнение отчёта с параметрами, возврат `DataTable`

Требования к настройке в 1С:

Элемент справочника rgВиртуальныеДокументы с видом Query
Алгоритм вычисления — запрос на языке 1С, возвращающий таблицу
Синхронный возврат результата (без обратного синка)

8. Гранулярный маппинг по событиям¶

По умолчанию при любом событии передаются все реквизиты из конфига. Атрибуты OneCEvents и TcEvents тега Property позволяют передавать только часть реквизитов для конкретных событий.

События 1С (`OneCEvents`)¶

Событие	Что происходит
`Create`	Создание документа/элемента
`Modify`	Изменение реквизитов
`Post`	Проведение документа
`ClearPost`	Отмена проведения
`Repost`	Перепроведение
`MarkDelete`	Пометка на удаление

События 1Ф (`TcEvents`)¶

Событие	Что происходит
`ChangeTask`	Изменение ДП задачи
`MakeStep{id}`	Выполнение шага (id слитно)
`ChangeToStatus{id}`	Переход в статус
`CustomEvent{id}`	Произвольное событие

Если событие не указано ни в одном из Property, для него передаются все реквизиты.

Подробнее: support-guide-1c.md

9. Ручное добавление ДП в существующий маппинг¶

Когда Builder не подходит (категория уже настроена, нужно добавить отдельный реквизит):

Запустить Мастер для нужного типа документа, на шаге 2 найти описание реквизита в XML
Скопировать блок <Property>
Вручную создать ДП нужного типа в 1Ф (для Lookup -- два ДП)
Прописать правильный ExtParamID (и TCLookupGUIDEPID для ссылочных)
В профиле синхронизации: Получить настройки → вставить <Property> в XML → Записать → Отправить XML в 1С

10. Первичная выгрузка данных¶

После создания категорий через Builder они пустые. Наполнение:

Путь: Синхронизация с 1С → Получить настройки по имени → Произвести первичную выгрузку → выбрать категории.

Порядок выгрузки (критично)¶

Если категория А содержит Lookup на категорию В, то сначала выгружается В, потом А. Иначе Lookup-поля не заполнятся.

При нарушении порядка -- двойная выгрузка: первый раз создаёт задачи (Lookup пустые), второй раз заполняет ссылки по GUID.

ImportStrategy¶

Значение	Поведение
`0`	Только создание новых
`1`	Только обновление существующих
`2` (по умолчанию)	Создание + обновление

Хранение маппинга¶

Таблица БД	Что хранит
`SyncSettings1C`	XML-конфиг целиком (поле `XmlContent`)
`Sync1CUsersMap`	Маппинг пользователей (логин 1С → UserID 1Ф)
`Sync1CEventQueues`	Очередь событий обмена
`Sync1CLog`	Лог операций синхронизации

Профили конфигурации также зеркалятся на стороне 1С в справочнике "Настройки обмена".

1С — маппинг сущностей и метаданных¶

Обзор¶

1. Модель маппинга¶

2. Извлечение метаданных из 1С¶

Как Builder получает список объектов¶

Что возвращается из 1С¶

3. Builder: 4 шага создания маппинга¶

Preconditions¶

4. XML-конфиг: структура маппинга¶

Ключевые атрибуты Record¶

Ключевые атрибуты Property¶

5. Маппинг типов¶

Особый случай: Lookup¶

Особый случай: RepresentAsReadonlyText¶

Особый случай: ДП "Таблица"¶

6. Виртуальные реквизиты¶

Структура¶

В XML-конфиге¶

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

7. Виртуальные документы¶

Алгоритм (файл)¶

Запрос (таблица)¶

Общее¶

Виртуальные документы как отчёты (Query-тип)¶

8. Гранулярный маппинг по событиям¶

События 1С (OneCEvents)¶

События 1Ф (TcEvents)¶

9. Ручное добавление ДП в существующий маппинг¶

10. Первичная выгрузка данных¶

Порядок выгрузки (критично)¶

ImportStrategy¶

Хранение маппинга¶

События 1С (`OneCEvents`)¶

События 1Ф (`TcEvents`)¶