diff --git a/docs/1c-dcs-spec.md b/docs/1c-dcs-spec.md new file mode 100644 index 00000000..6c07c0a3 --- /dev/null +++ b/docs/1c-dcs-spec.md @@ -0,0 +1,957 @@ +# Спецификация XML-формата схемы компоновки данных 1С (DCS) + +Спецификация формата `DataCompositionSchema` — макетов типа «Схема компоновки данных» в конфигурации 1С:Предприятие 8.3. +Составлена на основе анализа 930 схем конфигурации «Бухгалтерия предприятия 3.0.180» (платформа 8.3.24). + +--- + +## 0. Файловая структура + +### Два файла на каждую схему + +``` +<Объект>/Templates/ + ИмяМакета.xml ← метаданные (UUID, имя, TemplateType) + ИмяМакета/ + Ext/ + Template.xml ← тело схемы (DataCompositionSchema) +``` + +Типичные имена макетов: `ОсновнаяСхемаКомпоновкиДанных`, `СхемаКомпоновкиДанных`, произвольные. + +### Метаданные макета — шаблон + +```xml + + + + +``` + +Значение `TemplateType` для DCS всегда: **`DataCompositionSchema`**. + +### Где встречаются DCS-макеты + +| Тип объекта метаданных | Частота | Примечание | +|---|---|---| +| Reports (Отчёты) | ~420 | Основное место — каждый отчёт СКД | +| DataProcessors (Обработки) | ~11 | Обработки с отчётными функциями | +| Enums (Перечисления) | ~20 | Дополнительные ссылки | +| Catalogs (Справочники) | ~5 | Запросы к справочным данным | +| DocumentJournals | ~4 | Журналы документов | +| CommonTemplates | ~3 | Общие макеты | +| InformationRegisters | ~2 | Регистры сведений | +| Documents (Документы) | ~1 | Редко | + +--- + +## 1. Пространства имён + +Корневой элемент — ``. + +```xml + +``` + +| Префикс | URI | Назначение | +|---|---|---| +| *(default)* | `.../data-composition-system/schema` | Элементы схемы (dataSource, dataSet, field, parameter, ...) | +| `dcscom` | `.../data-composition-system/common` | Общие типы СКД (dimension, account, role, ...) | +| `dcscor` | `.../data-composition-system/core` | Ядро СКД (Field, SettingsParameterValue, ChoiceParameterLinks, ...) | +| `dcsset` | `.../data-composition-system/settings` | Настройки варианта (selection, filter, order, group, ...) | +| `v8` | `.../data/core` | Типы данных ядра (LocalStringType, Type, StandardPeriod, ...) | +| `v8ui` | `.../data/ui` | UI-типы (HorizontalAlign, ...) | +| `xs` | `.../XMLSchema` | Стандартные XSD-типы (string, dateTime, boolean, decimal, ...) | +| `xsi` | `.../XMLSchema-instance` | Атрибуты экземпляра (xsi:type, xsi:nil) | + +Дополнительные пространства имён (появляются в `settingsVariant`): + +| Префикс | URI | Где | +|---|---|---| +| `style` | `http://v8.1c.ru/8.1/data/ui/style` | В settings — стили оформления | +| `sys` | `http://v8.1c.ru/8.1/data/ui/fonts/system` | В settings — системные шрифты | +| `web` | `http://v8.1c.ru/8.1/data/ui/colors/web` | В settings — веб-цвета | +| `win` | `http://v8.1c.ru/8.1/data/ui/colors/windows` | В settings — цвета Windows | + +--- + +## 2. Общая структура DataCompositionSchema + +Элементы верхнего уровня (порядок фиксирован): + +``` +DataCompositionSchema +├── dataSource* — источники данных (раздел 3) +├── dataSet* — наборы данных (раздел 4) +├── dataSetLink* — связи между наборами (раздел 5) +├── calculatedField* — вычисляемые поля (раздел 6) +├── totalField* — итоговые поля (раздел 7) +├── parameter* — параметры схемы (раздел 8) +├── template* — макеты областей (раздел 9) +├── groupTemplate* — привязки макетов группировок (раздел 10) +├── settingsVariant* — варианты настроек (раздел 11) +``` + +`*` — 0..N элементов. + +Минимальная DCS содержит: 1 dataSource + 1 dataSet + 1 settingsVariant. + +--- + +## 3. Источники данных (dataSource) + +```xml + + ИсточникДанных1 + Local + +``` + +| Элемент | Обязат. | Описание | +|---|---|---| +| `name` | да | Уникальное имя, на которое ссылаются наборы данных | +| `dataSourceType` | да | Тип: `Local` (текущая информационная база) или `External` (внешний) | + +В подавляющем большинстве случаев — один источник `Local`. Имя произвольное: `ИсточникДанных1`, `ИнформационнаяБаза` и т.п. + +--- + +## 4. Наборы данных (dataSet) + +Тип набора определяется атрибутом `xsi:type`. Три типа: + +### 4.1. DataSetQuery — запрос + +Самый распространённый тип. Содержит SQL-подобный запрос на языке 1С. + +```xml + + НаборДанных1 + ... + ИсточникДанных1 + ВЫБРАТЬ ... ИЗ ... + false + +``` + +| Элемент | Обязат. | Описание | +|---|---|---| +| `name` | да | Уникальное имя набора | +| `field` | нет | Описания полей (раздел 4.4) | +| `dataSource` | да | Ссылка на имя dataSource | +| `query` | да | Текст запроса на языке 1С (XML-экранирование: `&` для `&`, `>` для `>`) | +| `autoFillFields` | нет | `false` — отключить автозаполнение полей из запроса (по умолчанию `true`) | + +#### Особенности запросов в DCS + +- Параметры: `&ИмяПараметра` (в XML: `&ИмяПараметра`) +- Авторазметка полей в фигурных скобках: `{ВЫБРАТЬ ...}`, `{ГДЕ ...}`, `{ЛЕВОЕ СОЕДИНЕНИЕ ...}` — позволяют СКД автоматически модифицировать запрос +- Пакетные запросы: несколько запросов через `; ////////////////` +- Временные таблицы: `ПОМЕСТИТЬ ИмяВТ`, `ИНДЕКСИРОВАТЬ ПО` + +### 4.2. DataSetObject — объект + +Данные берутся из программно заполненной таблицы значений. + +```xml + + НаборДанных1 + ... + ИсточникДанных1 + ТаблицаПроверки + +``` + +| Элемент | Обязат. | Описание | +|---|---|---| +| `objectName` | да | Имя объекта (таблицы значений), передаваемого программно | + +### 4.3. DataSetUnion — объединение + +Объединяет поля из нескольких наборов. Сам не содержит запросов — объединяет подчинённые наборы. + +```xml + + РасчетНалога + ... + + ДанныеПоСтоимости + ... + + + ДанныеПоКадастру + ... + + +``` + +| Элемент | Обязат. | Описание | +|---|---|---| +| `field` | нет | Поля объединения (описывают результирующие колонки) | +| `item` | да | Вложенные наборы (DataSetQuery или другие) | + +### 4.4. Поля набора данных (field) + +Каждое поле — элемент ``: + +```xml + + ОстаточнаяСтоимость + ОстаточнаяСтоимость + + <v8:item> + <v8:lang>ru</v8:lang> + <v8:content>Остаточная стоимость</v8:content> + </v8:item> + + + true + + + true + + + xs:string + + 11 + Variable + + + + + Формат + ЧДЦ=2 + + + ... + ... + +``` + +#### Элементы поля + +| Элемент | Обязат. | Описание | +|---|---|---| +| `dataPath` | да | Путь к данным (имя поля в результате СКД). Через точку — реквизиты: `Номенклатура.Артикул` | +| `field` | да | Имя поля в запросе (может отличаться от dataPath) | +| `title` | нет | Локализованный заголовок (`v8:LocalStringType`) | +| `useRestriction` | нет | Ограничения использования поля (раздел 4.5) | +| `attributeUseRestriction` | нет | Ограничения использования реквизитов поля (раздел 4.5) | +| `role` | нет | Роль поля в СКД (раздел 4.6) | +| `valueType` | нет | Тип значения поля (раздел 4.7) | +| `appearance` | нет | Оформление — список параметров `dcscor:item` (раздел 4.8) | +| `inputParameters` | нет | Параметры ввода / связи параметров выбора (раздел 4.9) | +| `presentationExpression` | нет | Выражение для формирования представления (на языке 1С) | + +### 4.5. Ограничения использования поля (useRestriction / attributeUseRestriction) + +```xml + + true + true + true + true + +``` + +Каждый подэлемент — `true`/`false` (по умолчанию `false` = разрешено). Можно указывать подмножество. + +`attributeUseRestriction` — аналогичная структура, применяется к реквизитам (дочерним полям) поля. + +### 4.6. Роли полей (role) + +```xml + + true + true + Счет.Вид + +``` + +| Подэлемент | Описание | +|---|---| +| `dcscom:dimension` | Поле является измерением (`true`/`false`) | +| `dcscom:account` | Поле является счётом | +| `dcscom:accountTypeExpression` | Выражение для определения типа счёта | +| `dcscom:balance` | Поле является остатком | +| `dcscom:balanceGroup` | Группа остатка | +| `dcscom:period` | Поле — период | + +### 4.7. Тип значения (valueType) + +```xml + + xs:string + + 11 + Variable + + +``` + +Типы: `xs:string`, `xs:dateTime`, `xs:decimal`, `xs:boolean`, ссылочные (`d4p1:CatalogRef.Номенклатура`). + +Квалификаторы: +- `v8:StringQualifiers` → `v8:Length`, `v8:AllowedLength` (Fixed/Variable) +- `v8:DateQualifiers` → `v8:DateFractions` (Date/Time/DateTime) +- `v8:NumberQualifiers` → `v8:Digits`, `v8:FractionDigits`, `v8:AllowedSign` (Any/Nonnegative) + +### 4.8. Оформление полей (appearance) + +Список параметров оформления: + +```xml + + + Формат + ЧДЦ=2 + + + ГоризонтальноеПоложение + Center + + +``` + +Типичные параметры оформления: + +| Параметр | Тип значения | Пример | +|---|---|---| +| `Формат` | `xs:string` | `ЧДЦ=2`, `ЧГ=0`, `ЧН=0`, `ДФ=dd.MM.yyyy`, `Л=ru; ДФ=ММММ` | +| `ГоризонтальноеПоложение` | `v8ui:HorizontalAlign` | `Left`, `Center`, `Right` | + +### 4.9. Параметры ввода (inputParameters) + +Связи параметров выбора для интерактивных полей: + +```xml + + + СвязиПараметровВыбора + + + Отбор.Владелец + Организация + Clear + + + + +``` + +Используется для каскадных зависимостей в пользовательских настройках (например, подразделение зависит от организации). + +--- + +## 5. Связи между наборами данных (dataSetLink) + +Позволяют передавать параметры из одного набора в другой: + +```xml + + Периоды + ДанныеТ13 + НачалоМесяца + Месяц + НачалоМесяца + false + +``` + +| Элемент | Обязат. | Описание | +|---|---|---| +| `sourceDataSet` | да | Имя набора-источника | +| `destinationDataSet` | да | Имя целевого набора | +| `sourceExpression` | да | Выражение из источника (поле или формула) | +| `destinationExpression` | да | Выражение для сопоставления в целевом наборе | +| `parameter` | нет | Имя параметра для передачи значения | +| `parameterListAllowed` | нет | Допустим ли список значений (`true`/`false`) | + +--- + +## 6. Вычисляемые поля (calculatedField) + +Поля, вычисляемые выражением на языке 1С (не из запроса): + +```xml + + УИД + БухгалтерскиеОтчеты.ПолучитьУИДСсылкиСтрокой(Номенклатура) + + <v8:item> + <v8:lang>ru</v8:lang> + <v8:content>Уникальный идентификатор</v8:content> + </v8:item> + + + true + true + true + + +``` + +| Элемент | Обязат. | Описание | +|---|---|---| +| `dataPath` | да | Путь к полю в результате | +| `expression` | да | Выражение на языке 1С (может вызывать методы общих модулей) | +| `title` | нет | Локализованный заголовок | +| `useRestriction` | нет | Ограничения использования (аналогично полям) | +| `valueType` | нет | Тип значения | +| `appearance` | нет | Оформление | + +--- + +## 7. Итоговые поля (totalField) + +Агрегатные функции для подведения итогов: + +```xml + + Количество + Сумма(Количество) + + + Цена + Максимум(Цена) + +``` + +| Элемент | Обязат. | Описание | +|---|---|---| +| `dataPath` | да | Путь к полю | +| `expression` | да | Агрегатная функция: `Сумма(...)`, `Количество(...)`, `Максимум(...)`, `Минимум(...)`, `Среднее(...)` | +| `group` | нет | Для какой группировки считать итоги | + +--- + +## 8. Параметры схемы (parameter) + +Параметры, доступные для задания пользователем или программно: + +```xml + + Период + + <v8:item> + <v8:lang>ru</v8:lang> + <v8:content>Период</v8:content> + </v8:item> + + + v8:StandardPeriod + + + LastMonth + + false + &Период.ДатаНачала + false + Always + +``` + +| Элемент | Обязат. | Описание | +|---|---|---| +| `name` | да | Имя параметра (используется в запросах как `&ИмяПараметра`) | +| `title` | нет | Локализованный заголовок | +| `valueType` | нет | Тип значения (раздел 4.7) | +| `value` | нет | Значение по умолчанию | +| `useRestriction` | нет | `true` — параметр скрыт от пользователя, `false` — доступен | +| `expression` | нет | Выражение для автоматического вычисления (например, `&Период.ДатаНачала`) | +| `availableAsField` | нет | `false` — параметр недоступен как поле в отчёте | +| `use` | нет | Режим: `Always` (всегда), `Auto` (автоматически) | + +### Типы значений параметров + +| Тип | XML-тип | Пример value | +|---|---|---| +| Дата | `xs:dateTime` | `0001-01-01T00:00:00` | +| Строка | `xs:string` | `Т13` | +| Стандартный период | `v8:StandardPeriod` | `LastMonth` | +| Ссылка | `d4p1:CatalogRef.ИмяСправочника` | `xsi:nil="true"` | +| null | — | `xsi:nil="true"` | + +Стандартные варианты периодов (`v8:StandardPeriodVariant`): `Custom`, `Today`, `ThisWeek`, `ThisMonth`, `ThisQuarter`, `ThisYear`, `LastMonth`, `LastQuarter`, `LastYear` и др. + +--- + +## 9. Макеты областей (template) + +Пользовательские шаблоны вывода (макеты ячеек): + +```xml + +``` + +Пространство имён `dcsat`: `http://v8.1c.ru/8.1/data-composition-system/area-template`. + +| Элемент | Описание | +|---|---| +| `name` | Имя макета (ссылаются groupTemplate) | +| `template` (вложенный) | Описание строк/ячеек (`dcsat:AreaTemplate`) | +| `parameter` | Параметры макета (`dcsat:ExpressionAreaTemplateParameter`) — выражения для подстановки | + +--- + +## 10. Привязки макетов группировок (groupTemplate) + +Связывают группировку с пользовательским макетом: + +```xml + + ТипЦен + Header + + +``` + +| Элемент | Описание | +|---|---| +| `groupField` | Имя поля группировки | +| `templateType` | Тип: `Header` (заголовок), `Footer` (подвал), `Overall` (общий) | +| `template` | Ссылка на имя template из раздела 9 | + +--- + +## 11. Варианты настроек (settingsVariant) + +Каждый вариант — именованная конфигурация отчёта. Отчёт может иметь несколько вариантов. + +```xml + + Основной + + + ru + Основной вариант отчёта + + + + + + +``` + +### 11.1. Структура settings + +``` +dcsset:settings +├── dcsset:selection — выбранные поля (раздел 11.2) +├── dcsset:filter — отборы (раздел 11.3) +├── dcsset:order — сортировка (раздел 11.4) +├── dcsset:conditionalAppearance — условное оформление (раздел 11.5) +├── dcsset:outputParameters — параметры вывода (раздел 11.6) +├── dcsset:dataParameters — значения параметров данных (раздел 11.7) +├── dcsset:item* — элементы структуры (раздел 11.8) +``` + +### 11.2. Выборка полей (selection) + +```xml + + + ТипОбъекта + + + ru + Наименование + + + + + +``` + +Типы элементов выборки: +- `dcsset:SelectedItemField` — конкретное поле (элемент `dcsset:field`) +- `dcsset:SelectedItemAuto` — автоматический подбор полей + +### 11.3. Отборы (filter) + +```xml + + + false + Организация + Equal + false + + + ru + Описание фильтра + + + Normal + GUID + + +``` + +Типы элементов фильтра: +- `dcsset:FilterItemComparison` — сравнение поля с значением +- `dcsset:FilterItemGroup` — группа условий (И/ИЛИ) + +Типы сравнения (`comparisonType`): + +| Значение | Описание | +|---|---| +| `Equal` | Равно | +| `NotEqual` | Не равно | +| `Greater` | Больше | +| `GreaterOrEqual` | Больше или равно | +| `Less` | Меньше | +| `LessOrEqual` | Меньше или равно | +| `InList` | В списке | +| `NotInList` | Не в списке | +| `InHierarchy` | В иерархии | +| `InListByHierarchy` | В списке по иерархии | +| `Contains` | Содержит | +| `NotContains` | Не содержит | +| `BeginsWith` | Начинается с | +| `NotBeginsWith` | Не начинается с | +| `Filled` | Заполнено | +| `NotFilled` | Не заполнено | + +Значение правой части (`right`) — может содержать списки: +```xml + + + -1 + +``` + +### 11.4. Сортировка (order) + +```xml + + + РазмерДанных + Desc + + + +``` + +Типы элементов сортировки: +- `dcsset:OrderItemField` — по полю (`dcsset:field` + `dcsset:orderType`: `Asc`/`Desc`) +- `dcsset:OrderItemAuto` — автоматическая сортировка + +### 11.5. Условное оформление (conditionalAppearance) + +```xml + + + + + ИмяПоля + + + + + ИмяПоля + Equal + 0 + + + + + Текст + + + + + +``` + +### 11.6. Параметры вывода (outputParameters) + +```xml + + + false + Заголовок + + + ru + Текст заголовка + + + + +``` + +Типичные параметры вывода: + +| Параметр | Тип значения | Описание | +|---|---|---| +| `Заголовок` | `v8:LocalStringType` | Заголовок отчёта | +| `МакетОформления` | `xs:string` | Имя макета оформления: `ОформлениеОтчетовЧерноБелый`, `Зеленый` и др. | +| `РасположениеПолейГруппировки` | `dcsset:DataCompositionGroupFieldsPlacement` | `Together`, `Separately`, `SeparatelyAndInGroups` | +| `РасположениеРеквизитов` | `dcsset:DataCompositionAttributesPlacement` | `Together`, `Separately`, `SeparatelyAndInGroups` | +| `ГоризонтальноеРасположениеОбщихИтогов` | `dcscor:DataCompositionTotalPlacement` | `None`, `Begin`, `End`, `Auto` | +| `ВертикальноеРасположениеОбщихИтогов` | `dcscor:DataCompositionTotalPlacement` | `None`, `Begin`, `End`, `Auto` | +| `ВыводитьЗаголовок` | `dcsset:DataCompositionTextOutputType` | `Auto`, `DontOutput`, `Output` | +| `ВыводитьПараметрыДанных` | `dcsset:DataCompositionTextOutputType` | То же | +| `ВыводитьОтбор` | `dcsset:DataCompositionTextOutputType` | То же | + +### 11.7. Параметры данных (dataParameters) + +Значения параметров схемы в конкретном варианте: + +```xml + + + false + Период + + LastMonth + + Normal + GUID + + +``` + +| Элемент | Описание | +|---|---| +| `dcscor:use` | `true`/`false` — использовать значение или нет | +| `dcscor:parameter` | Имя параметра из раздела 8 | +| `dcscor:value` | Значение параметра | +| `dcsset:viewMode` | Режим отображения: `Normal`, `QuickAccess`, `Inaccessible` | +| `dcsset:userSettingID` | GUID пользовательской настройки | + +### 11.8. Элементы структуры (structure items) + +Структура отчёта — иерархия группировок, таблиц, диаграмм. + +#### StructureItemGroup — группировка + +```xml + + Группировка + + + Организация + Items + None + 0001-01-01T00:00:00 + 0001-01-01T00:00:00 + + + + + + + + + ... + + ... + + +``` + +Типы группировки (`groupType`): `Items`, `Hierarchy`, `HierarchyOnly`. + +Типы дополнения периодом (`periodAdditionType`): `None`, `Year`, `HalfYear`, `Quarter`, `Month`, `TenDays`, `Week`, `Day`. + +Пустая группировка (без `groupItems`) = детальные записи. + +#### StructureItemTable — таблица (кросс-таблица) + +```xml + + Таблица + + ... + ... + ... + + + Группировка + ... + ... + ... + + +``` + +#### StructureItemChart — диаграмма + +```xml + + + ... + ... + ... + + + ... + ... + + + + РазмерДанных + + + ... + +``` + +--- + +## 12. Типы данных — сводка + +### v8:LocalStringType — локализованная строка + +```xml + + <v8:item> + <v8:lang>ru</v8:lang> + <v8:content>Текст на русском</v8:content> + </v8:item> + +``` + +Также можно задать как простую строку: `xsi:type="xs:string"`. + +### dcscor:SettingsParameterValue — параметр настройки + +```xml + + true + ИмяПараметра + Значение + +``` + +### dcscor:Field — ссылка на поле + +```xml +ИмяПоля +``` + +--- + +## 13. Полный минимальный пример + +Простая DCS: один запрос, два поля, один итог, один вариант: + +```xml + + + + ИсточникДанных1 + Local + + + НаборДанных1 + + Наименование + Наименование + + <v8:item> + <v8:lang>ru</v8:lang> + <v8:content>Наименование</v8:content> + </v8:item> + + + + Количество + Количество + + ИсточникДанных1 + ВЫБРАТЬ + Номенклатура.Наименование КАК Наименование, + КОЛИЧЕСТВО(1) КАК Количество +ИЗ + Справочник.Номенклатура КАК Номенклатура +СГРУППИРОВАТЬ ПО + Номенклатура.Наименование + + + Количество + Сумма(Количество) + + + Основной + + + ru + Основной + + + + + + Наименование + + + Количество + + + + + + + + + + + + + +```