From 484ee443878e5bae9776db5c7eadf3c7cf747d49 Mon Sep 17 00:00:00 2001 From: Nick Shirokov Date: Sat, 14 Feb 2026 18:23:03 +0300 Subject: [PATCH] Add subsystem and command interface XML format specification Co-Authored-By: Claude Opus 4.6 --- docs/1c-config-objects-spec.md | 2 + docs/1c-subsystem-spec.md | 659 +++++++++++++++++++++++++++++++++ 2 files changed, 661 insertions(+) create mode 100644 docs/1c-subsystem-spec.md diff --git a/docs/1c-config-objects-spec.md b/docs/1c-config-objects-spec.md index 62386f31..6fc51d91 100644 --- a/docs/1c-config-objects-spec.md +++ b/docs/1c-config-objects-spec.md @@ -5,6 +5,8 @@ Источники: выгрузки ERP 2, Бухгалтерия предприятия (платформы 8.3.20, 8.3.24, 8.3.27). +> **Связанные спецификации**: Подсистемы и командный интерфейс — [1c-subsystem-spec.md](1c-subsystem-spec.md). + --- ## 1. Общая структура выгрузки diff --git a/docs/1c-subsystem-spec.md b/docs/1c-subsystem-spec.md new file mode 100644 index 00000000..706354f0 --- /dev/null +++ b/docs/1c-subsystem-spec.md @@ -0,0 +1,659 @@ +# Спецификация формата XML подсистем и командного интерфейса 1С + +Формат: XML-выгрузка конфигурации 1С:Предприятие 8.3 (Конфигуратор → Конфигурация → Выгрузить конфигурацию в файлы). +Версии формата: `2.17` (платформа 8.3.20–8.3.24), `2.20` (платформа 8.3.27+). + +Источники: выгрузки Бухгалтерия предприятия (платформы 8.3.20, 8.3.24, 8.3.27), ERP 2 (8.3.24). + +--- + +## 1. Структура каталогов + +### 1.1. Подсистемы (Subsystems) + +Подсистемы организуют иерархическое дерево в каталоге `Subsystems/`: + +``` +Subsystems/ +├── ПодсистемаА.xml # Определение подсистемы +├── ПодсистемаА/ # Каталог подсистемы (если есть вложенные или CommandInterface) +│ ├── Ext/ +│ │ └── CommandInterface.xml # Командный интерфейс подсистемы (опционально) +│ └── Subsystems/ # Вложенные подсистемы (опционально) +│ ├── Дочерняя1.xml +│ ├── Дочерняя1/ +│ │ ├── Ext/ +│ │ │ └── CommandInterface.xml +│ │ └── Subsystems/ +│ │ └── Внучатая1.xml # Вложенность до 3+ уровней +│ └── Дочерняя2.xml +├── ПодсистемаБ.xml # Лист — без каталога +└── ... +``` + +**Правила:** +- Каждая подсистема имеет файл `<Имя>.xml` (обязательно) +- Каталог `<Имя>/` создаётся только если есть вложенные подсистемы или файл `Ext/CommandInterface.xml` +- Вложенные подсистемы хранятся в `<Имя>/Subsystems/` — рекурсивно повторяя ту же структуру +- Глубина вложенности не ограничена (на практике до 3–4 уровней) + +### 1.2. Командный интерфейс конфигурации (корневой) + +``` +Ext/ +└── CommandInterface.xml # Глобальный командный интерфейс — порядок разделов +``` + +Корневой `CommandInterface.xml` определяет порядок подсистем верхнего уровня в панели разделов. + +--- + +## 2. Пространства имён XML + +### 2.1. Подсистема (файл метаданных) + +Корневой элемент — ``, стандартный набор деклараций: + +```xml + +``` + +### 2.2. Командный интерфейс (CommandInterface.xml) + +Корневой элемент — ``: + +```xml + +``` + +--- + +## 3. Формат подсистемы + +### 3.1. Общая структура + +```xml + + + + + ИмяПодсистемы + ... + + true + true + false + ... + ... + ... + + + Дочерняя1 + Дочерняя2 + + + +``` + +### 3.2. Свойства (Properties) + +| Свойство | Тип | Обязательно | Описание | +|---|---|---|---| +| `Name` | string | да | Программное имя (CamelCase, без пробелов) | +| `Synonym` | LocalString | да | Отображаемое имя (локализованное) | +| `Comment` | string | да | Комментарий. Обычно пустой тег `` | +| `IncludeHelpInContents` | bool | да | Включать справку в содержание | +| `IncludeInCommandInterface` | bool | да | Отображать в командном интерфейсе (`true` — раздел видим) | +| `UseOneCommand` | bool | да | Использовать единственную команду (подсистема-ярлык). `true` — при открытии сразу выполняется единственная команда из Content | +| `Explanation` | LocalString | да | Подсказка при наведении на раздел. Пустой тег если не задана | +| `Picture` | Picture | да | Иконка раздела. Пустой тег `` если не задана | +| `Content` | Content | да | Список включённых объектов метаданных. Пустой тег `` если нет | + +#### Synonym, Explanation (LocalString) + +Локализованная строка с элементами по языкам: + +```xml + + + ru + Администрирование + + + en + Administration + + +``` + +Может быть пустым тегом: `` + +#### Picture + +Ссылка на общую картинку конфигурации: + +```xml + + CommonPicture.Администрирование + false + +``` + +- `xr:Ref` — ссылка на объект `CommonPicture.<Имя>` +- `xr:LoadTransparent` — загружать с прозрачностью (`true`/`false`) +- Пустой тег `` если иконка не задана + +#### Content + +Список объектов метаданных, включённых в подсистему: + +```xml + + Catalog.Номенклатура + Document.РеализацияТоваровУслуг + Report.Продажи + CommonCommand.Настройки + FunctionalOption.ИспользоватьСклады + Constant.ИспользоватьСклады + CommandGroup.Настройки + Role.ПодсистемаПродажи + +``` + +Каждый элемент `` имеет фиксированный атрибут `xsi:type="xr:MDObjectRef"` и содержит полный путь объекта в формате `<ТипОбъекта>.<Имя>`. + +**Встречающиеся типы объектов в Content:** + +| Тип | Пример | +|---|---| +| `Catalog` | `Catalog.Номенклатура` | +| `Document` | `Document.РеализацияТоваровУслуг` | +| `Report` | `Report.Продажи` | +| `DataProcessor` | `DataProcessor.ПанельАдминистрирования` | +| `CommonModule` | `CommonModule.МодульОбщий` | +| `CommonCommand` | `CommonCommand.Настройки` | +| `CommonForm` | `CommonForm.ФормаОбщая` | +| `CommonPicture` | `CommonPicture.КартинкаОбщая` | +| `CommandGroup` | `CommandGroup.Настройки` | +| `Constant` | `Constant.ИспользоватьСклады` | +| `FunctionalOption` | `FunctionalOption.ИспользоватьСклады` | +| `Enum` | `Enum.ВидыОпераций` | +| `Role` | `Role.ПодсистемаПродажи` | +| `InformationRegister` | `InformationRegister.КурсыВалют` | +| `AccumulationRegister` | `AccumulationRegister.Продажи` | +| `AccountingRegister` | `AccountingRegister.Хозрасчетный` | +| `ChartOfAccounts` | `ChartOfAccounts.Хозрасчетный` | +| `ChartOfCharacteristicTypes` | `ChartOfCharacteristicTypes.Виды` | +| `ExchangePlan` | `ExchangePlan.ОбменДанными` | +| `DocumentJournal` | `DocumentJournal.Журнал` | +| UUID (ссылка по идентификатору) | `cf4e9dea-4052-4a62-8427-0d37e8c47a23` | + +> **UUID-ссылки**: Некоторые элементы Content содержат UUID вместо именованной ссылки. Это ссылки на объекты из расширений или объекты, которые были удалены/переименованы. + +Пустой тег `` — подсистема не содержит объектов (организующая подсистема). + +### 3.3. Дочерние объекты (ChildObjects) + +Список вложенных подсистем: + +```xml + + НастройкиПрограммы + Пользователи + ПроведениеДокументов + +``` + +- Каждый `` содержит только **имя** дочерней подсистемы (не UUID, не путь) +- Порядок элементов значим — определяет порядок в дереве конфигурации +- Пустой тег `` — лист дерева, нет вложенных подсистем +- Определения дочерних подсистем находятся в `<ИмяРодителя>/Subsystems/<ИмяДочерней>.xml` + +### 3.4. Типовые паттерны подсистем + +**Организующая подсистема** — содержит только дочерние, без собственных объектов: +```xml + + + Дочерняя1 + Дочерняя2 + +``` + +**Листовая подсистема** — содержит объекты, без вложенных: +```xml + + Catalog.Товары + + +``` + +**Подсистема-ярлык** (`UseOneCommand=true`) — открывает единственную команду: +```xml +true + + DataProcessor.Помощь + + +``` + +**Смешанная подсистема** — и объекты, и дочерние: +```xml + + CommonModule.Модуль + Report.Отчёт + + + Дочерняя1 + +``` + +--- + +## 4. Формат командного интерфейса (CommandInterface.xml) + +### 4.1. Общая структура + +```xml + + + ... + ... + ... + ... + ... + +``` + +Все 5 дочерних элементов опциональны. Порядок фиксирован: `CommandsVisibility` → `CommandsPlacement` → `CommandsOrder` → `SubsystemsOrder` → `GroupsOrder`. + +### 4.2. Два уровня CommandInterface + +| Уровень | Путь | Типичное содержание | +|---|---|---| +| **Корневой** (конфигурация) | `Ext/CommandInterface.xml` | Только `SubsystemsOrder` — порядок разделов верхнего уровня | +| **Подсистема** | `Subsystems/<Имя>/Ext/CommandInterface.xml` | Любая комбинация из 5 секций | + +#### Корневой командный интерфейс + +Содержит только порядок подсистем верхнего уровня: + +```xml + + + Subsystem.Руководителю + Subsystem.БанкИКасса + Subsystem.Продажи + Subsystem.Покупки + Subsystem.Администрирование + + +``` + +### 4.3. CommandsVisibility — видимость команд + +Управляет видимостью отдельных команд в разделе: + +```xml + + + + false + + + + + true + + + +``` + +**Элемент `Command`:** +- Атрибут `name` — полный путь команды (см. [формат ссылок на команды](#46-формат-ссылок-на-команды)) +- `Visibility` > `xr:Common` — видимость для всех пользователей: `true` (видима) / `false` (скрыта) + +> **Семантика**: Определяет какие команды видимы/скрыты **по умолчанию** для всех пользователей в данном разделе. Перечисляются только команды, чья видимость **отличается** от автоматической. + +### 4.4. CommandsPlacement — размещение команд в группах + +Определяет в какую группу команд помещается команда: + +```xml + + + CommandGroup.Отчеты + Auto + + + NavigationPanelOrdinary + Auto + + +``` + +**Элемент `Command`:** +- `name` — ссылка на команду +- `CommandGroup` — идентификатор группы (см. [стандартные группы](#47-группы-команд)) +- `Placement` — стратегия размещения. Единственное наблюдаемое значение: `Auto` + +### 4.5. CommandsOrder — порядок команд + +Определяет порядок отображения команд внутри групп: + +```xml + + + ActionsPanelCreate + + + ActionsPanelCreate + + + CommandGroup.Отчеты + + +``` + +**Элемент `Command`:** +- `name` — ссылка на команду +- `CommandGroup` — группа, в которой определяется порядок + +Команды отображаются в порядке их перечисления в `CommandsOrder`. + +### 4.6. SubsystemsOrder — порядок вложенных подсистем + +Определяет порядок дочерних подсистем в навигационной панели: + +```xml + + Subsystem.Продажи.Subsystem.ПродажиГлавное + Subsystem.Продажи.Subsystem.РозничныеПродажи + Subsystem.Продажи.Subsystem.РасчетыСКонтрагентами + +``` + +**Формат пути подсистемы:** +- Корневой уровень: `Subsystem.<Имя>` +- Вложенный уровень: `Subsystem.<Родитель>.Subsystem.<Дочерняя>` +- Глубже: `Subsystem..Subsystem..Subsystem.` + +> **В корневом CommandInterface** используются пути `Subsystem.<Имя>` (верхний уровень). +> **В CommandInterface подсистемы** используются полные пути от корня: `Subsystem.<Родитель>.Subsystem.<Дочерняя>`. + +### 4.7. GroupsOrder — порядок групп команд + +Определяет порядок отображения самих групп: + +```xml + + NavigationPanelOrdinary + CommandGroup.НачальноеЗаполнение + NavigationPanelSeeAlso + ActionsPanelTools + CommandGroup.Отчеты + CommandGroup.Сервис + CommandGroup.Информация + +``` + +--- + +## 5. Формат ссылок на команды + +Атрибут `name` в элементах `Command` использует точечную нотацию: + +### 5.1. Стандартные команды (StandardCommand) + +``` +<ТипОбъекта>.<ИмяОбъекта>.StandardCommand.<Операция> +``` + +| Операция | Назначение | +|---|---| +| `OpenList` | Открыть список | +| `Open` | Открыть (для отчётов, обработок, общих форм) | +| `Create` | Создать новый | +| `CreateFolder` | Создать группу (для иерархических справочников) | + +**Примеры:** +- `Catalog.Номенклатура.StandardCommand.OpenList` +- `Document.Реализация.StandardCommand.Create` +- `Report.Продажи.StandardCommand.Open` +- `DataProcessor.Настройки.StandardCommand.Open` +- `CommonForm.ФормаОбщая.StandardCommand.Open` +- `InformationRegister.КурсыВалют.StandardCommand.OpenList` +- `DocumentJournal.ЖурналДокументов.StandardCommand.OpenList` + +### 5.2. Пользовательские команды (Command) + +``` +<ТипОбъекта>.<ИмяОбъекта>.Command.<ИмяКоманды> +``` + +**Примеры:** +- `Report.Продажи.Command.ПродажиПоКонтрагентам` +- `DataProcessor.Панель.Command.ОткрытьНастройки` +- `Catalog.Оборудование.Command.ОткрытьОборудование` +- `InformationRegister.Настройки.Command.ОбменДанными` +- `ExchangePlan.Мобильное.Command.ОткрытьНастройки` + +### 5.3. Общие команды (CommonCommand) + +``` +CommonCommand.<ИмяКоманды> +``` + +**Примеры:** +- `CommonCommand.НастройкиСинхронизацииДанных` +- `CommonCommand.ДополнительныеОбработкиПродажи` +- `CommonCommand.ПерсональныеНастройки` + +### 5.4. UUID-ссылки + +``` +0: +``` + +**Пример:** `0:91941f81-07dd-43a0-9baa-f5969b7472db` + +Формат `0:` используется для команд из расширений или ссылок на объекты, недоступные по имени. + +--- + +## 6. Группы команд (CommandGroup) + +### 6.1. Стандартные группы панелей + +| Идентификатор | Панель | Описание | +|---|---|---| +| `NavigationPanelImportant` | Навигация | Важные команды (верхняя часть) | +| `NavigationPanelOrdinary` | Навигация | Обычные команды | +| `NavigationPanelSeeAlso` | Навигация | Блок «См. также» (нижняя часть) | +| `ActionsPanelCreate` | Действия | Блок «Создать» | +| `ActionsPanelTools` | Действия | Блок «Сервис» | + +### 6.2. Пользовательские группы + +``` +CommandGroup.<ИмяГруппы> +``` + +Ссылаются на объекты метаданных `CommandGroup`, определённые в конфигурации (каталог `CommandGroups/`). + +**Типичные примеры:** +- `CommandGroup.Настройки` +- `CommandGroup.Отчеты` +- `CommandGroup.Сервис` +- `CommandGroup.Информация` +- `CommandGroup.НачальноеЗаполнение` +- `CommandGroup.НДС` + +--- + +## 7. Различия версий формата + +| Аспект | `2.17` (8.3.20–8.3.24) | `2.20` (8.3.27+) | +|---|---|---| +| Атрибут `version` | `2.17` | `2.20` | +| BOM (UTF-8 BOM) | Нет | Да (EF BB BF) | +| Набор элементов | Идентичный | Идентичный | +| Набор свойств подсистемы | Идентичный | Идентичный | +| Секции CommandInterface | Идентичные | Идентичные | + +> Между версиями `2.17` и `2.20` структурных различий в формате подсистем и командного интерфейса не обнаружено. Меняется только атрибут `version` и наличие BOM. + +--- + +## 8. Полный пример + +### 8.1. Подсистема верхнего уровня (Продажи.xml) + +```xml + + + + + Продажи + + + ru + Продажи + + + + true + true + false + + + CommonPicture.Продажи + false + + + Report.Продажи + Report.ВаловаяПрибыль + CommonCommand.ДополнительныеОбработкиПродажи + CommonCommand.ДополнительныеОтчетыПродажи + Role.ПодсистемаПродажи + + + + ПродажиГлавное + РозничныеПродажи + РасчетыСКонтрагентами + + + +``` + +### 8.2. CommandInterface подсистемы (Продажи/Ext/CommandInterface.xml) + +```xml + + + + + + true + + + + + true + + + + + true + + + + + + CommandGroup.Отчеты + Auto + + + CommandGroup.Сервис + Auto + + + + + CommandGroup.Отчеты + + + CommandGroup.Отчеты + + + CommandGroup.Сервис + + + + Subsystem.Продажи.Subsystem.ПродажиГлавное + Subsystem.Продажи.Subsystem.РозничныеПродажи + Subsystem.Продажи.Subsystem.РасчетыСКонтрагентами + + + ActionsPanelTools + CommandGroup.Отчеты + CommandGroup.Сервис + + +``` + +### 8.3. Корневой CommandInterface (Ext/CommandInterface.xml) + +```xml + + + + Subsystem.Руководителю + Subsystem.БанкИКасса + Subsystem.Продажи + Subsystem.Покупки + Subsystem.Администрирование + + +```