docs(skd-dsl-spec): актуализация под фичи текущей сессии

Откатываем расширение SKILL.md (детальные формы расшифровки — редкая необходимость) и переносим документацию в spec: - selection folder placement (Horizontally/Vertically/...) - groupBy field object-form: periodAdditionType + periodAdditionBegin/End (auto-detect xs:dateTime vs dcscor:Field) - chart multi-series/multi-points (points/series как массив) - template parameters drilldown форма A/B/C - cell object-form { value, drilldown } override - fieldTemplates секция - choiceParameters values native bool/int/double/string - filter valueType работает и для массива value - dataParameters valueType=xs:string как nil-placeholder для use=false
2026-06-12 08:54:57 +03:00 · 2026-05-24 17:33:33 +03:00
parent c230142bf1
commit f34303f9ed
2 changed files with 73 additions and 43 deletions
@@ -344,9 +344,8 @@ Raw XML (`"template": "<...>"`) остаётся как fallback. Детект:

 ### Расшифровка (drilldown) в параметрах шаблона

-Ключ `drilldown` в параметре шаблона управляет генерацией `DetailsAreaTemplateParameter` и привязкой `Расшифровка` в appearance ячеек. Различает три формы по типу значения.
+Ключ `drilldown` в параметре шаблона автоматически генерирует `DetailsAreaTemplateParameter` и привязку `Расшифровка` в appearance ячеек:

-**Форма B (shortcut, строка) — расшифровка через `ИмяРесурса`/`DrillDown`:**
 ```json
 "parameters": [
  { "name": "Сырье", "expression": "ПоступлениеСырья", "drilldown": "ПоступлениеСырья" }
@@ -355,38 +354,6 @@ Raw XML (`"template": "<...>"`) остаётся как fallback. Детект:

 Генерирует: `ExpressionAreaTemplateParameter` (обычный) + `DetailsAreaTemplateParameter` с именем `Расшифровка_ПоступлениеСырья`, `fieldExpression` по полю `ИмяРесурса`, `mainAction=DrillDown`. Ячейки `{Сырье}` автоматически получают appearance `Расшифровка = Расшифровка_ПоступлениеСырья`.

-**Форма C (объект) — произвольный `DetailsAreaTemplateParameter`:**
-```json
-"parameters": [
-  { "name": "Номер", "expression": "МаршрутныйЛист.Номер" },
-  { "name": "Дата",  "expression": "МаршрутныйЛист.Дата" },
-  { "name": "МаршрутныйЛист",
-    "drilldown": { "field": "МаршрутныйЛист", "expression": "МаршрутныйЛист", "action": "OpenValue" } }
-]
-```
-
-Параметр без `expression` и с `drilldown` в виде объекта — это самостоятельный `DetailsAreaTemplateParameter` с именем `name`, `fieldExpression={field, expression}`, `mainAction=action` (по умолчанию `DrillDown`). Используется когда `mainAction=OpenValue` (открытие ссылки на data-параметр), либо когда расшифровка не привязана к `ИмяРесурса`.
-
-**Override расшифровки на уровне ячейки:**
-```json
-"rows": [
-  [ { "value": "{Номер}", "drilldown": "МаршрутныйЛист" },
-    { "value": "{Дата}",  "drilldown": "МаршрутныйЛист" } ]
-]
-```
-
-Object-форма ячейки `{ value, drilldown }`: appearance ячейки получит `Расшифровка → <drilldown>` (без префикса `Расшифровка_`). Используется когда несколько ячеек должны указывать на один и тот же параметр расшифровки, объявленный через форму C. Если в ячейке-строке `{X}` есть param X со shortcut form B — appearance подставляется автоматически, override не нужен.
-
-### Привязка макета к полю — `fieldTemplates`
-
-```json
-"fieldTemplates": [
-  { "field": "МаршрутныйЛист", "template": "Макет1" }
-]
-```
-
-Эквивалент XML-секции `<fieldTemplate><field>X</field><template>Y</template></fieldTemplate>` — при выводе значения поля `X` используется именованный area-template `Y`.
-
 ### Привязки макетов к группировкам

 ```json
@@ -404,7 +404,7 @@ XML-маппинг — по `<group>` на каждый элемент:
 | `use` | `"Always"`, `"Auto"` |
 | `denyIncompleteValues` | `true` — запретить произвольные значения (только из availableValues) |
 | `availableValues` | Массив `[{value, presentation}]` — допустимые значения с представлениями. Типы (bool/int/decimal) сохраняются нативно в JSON |
-| `inputParameters` | Параметры ввода (например `ФорматРедактирования`) — массив `[{parameter, value, valueType?, choiceParameters?, choiceParameterLinks?}]`. `valueType: {uri, name}` сохраняет кастомный xsi:type с локальным xmlns (например `d6p1:FoldersAndItemsUse`) |
+| `inputParameters` | Параметры ввода (например `ФорматРедактирования`) — массив `[{parameter, value, valueType?, choiceParameters?, choiceParameterLinks?}]`. `valueType: {uri, name}` сохраняет кастомный xsi:type с локальным xmlns (например `d6p1:FoldersAndItemsUse`). В `choiceParameters[i].values` элементы — bool/int/double/string; compile эмитит соответствующий xsi:type (`xs:boolean` / `xs:decimal` / `dcscor:DesignTimeValue`) |
 | `nilValue` | `true` — эмитить `<value xsi:nil="true"/>` для параметров с явным типом (decimal/string/dateTime), где XML-сериализатор обычно ставит типизированный default. Bit-perfect round-trip |

 ### availableValues
@@ -552,6 +552,12 @@ decompile эмитит длинные имена (`sourceDataSet` и т.д.); co
 ]
 ```

+Опциональное поле `placement` (`Auto` / `Horizontally` / `Vertically` / `Special`) задаёт расположение элементов внутри группы (по умолчанию `Auto`):
+
+```json
+{"folder": "Экономия ФОТ", "items": ["ЭкономияФОТ", "ЭкономияФОТПроцент"], "placement": "Horizontally"}
+```
+
 ### filter

 #### Shorthand-строка
@@ -598,7 +604,7 @@ decompile эмитит длинные имена (`sourceDataSet` и т.д.); co
 | `field` | Имя поля |
 | `op` | Оператор (см. таблицу) |
 | `value` | Правая часть (опц.). См. формы ниже |
-| `valueType` | xsi:type для значения (опц.). `"dcscor:Field"` = field-to-field comparison (значение — имя другого поля) |
+| `valueType` | xsi:type для значения (опц.). `"dcscor:Field"` = field-to-field comparison (значение — имя другого поля). Для массива `value: [...]` применяется ко всем элементам — нужен когда auto-detect ошибается (например `Перечисление.X.Y` должно остаться `xs:string`, а не `dcscor:DesignTimeValue`) |
 | `use` | Включён (`true` по умолчанию) |
 | `presentation` | Текст подсказки |
 | `viewMode` | `"Normal"`, `"QuickAccess"`, `"Inaccessible"` |
@@ -794,7 +800,7 @@ Wrapper эмитится только при наличии extra-полей; п
 |------|----------|
 | `parameter` | Имя параметра |
 | `value` | Значение (объект `{ "variant": "LastMonth" }` для StandardPeriod, или скаляр) |
-| `valueType` | Полный xsi:type если кастомный (например `dcsset:DataCompositionGroupUseVariant`) |
+| `valueType` | Полный xsi:type если кастомный (например `dcsset:DataCompositionGroupUseVariant`). Для пустого значения с `use: false` — `"xs:string"` эмитит `<value xsi:type="xs:string"/>` (placeholder отключённого параметра типа DateTime, бит-перфектный аналог `xsi:nil`) |
 | `use` | Включён (`true` по умолчанию) |
 | `viewMode` | `"Normal"`, `"QuickAccess"`, `"Inaccessible"` |
 | `userSettingID` | `"auto"` → генерировать GUID |
@@ -848,7 +854,7 @@ Platform-pattern: `startDate`/`endDate`/`date` эмитятся ТОЛЬКО д
 |------|----------|
 | `type` | `"group"` |
 | `name` | Имя группировки (опц.) |
-| `groupBy` | Массив полей. Пусто/опущено = детальные записи |
+| `groupBy` | Массив полей. Каждый элемент — строка (имя поля) или объект `{ field, groupType?, periodAdditionType?, periodAdditionBegin?, periodAdditionEnd? }`. Пусто/опущено = детальные записи. Object-форма нужна когда `groupType ≠ "Items"`, `periodAdditionType ≠ "None"` или задана `periodAdditionBegin/End` (см. ниже) |
 | `groupType` | `"Items"` (умолч.), `"Hierarchy"`, `"HierarchyOnly"` |
 | `selection` | Выборка (умолч. `["Auto"]`) |
 | `filter` | Отборы (как в settings) |
@@ -864,6 +870,14 @@ Platform-pattern: `startDate`/`endDate`/`date` эмитятся ТОЛЬКО д

 Пустой `groupBy` (или `[]`) = детальные записи (без `groupItems` в XML).

+**`periodAdditionBegin` / `periodAdditionEnd`** на field-объекте — даты добавочного периода (`<dcsset:periodAdditionBegin>`/`<dcsset:periodAdditionEnd>`). Compile auto-определяет xsi:type значения: строка вида `2025-01-01T00:00:00` → `xs:dateTime`, иначе (путь к параметру, например `ПараметрыДанных.ДатаНачала`) → `dcscor:Field`.
+
+```json
+{ "field": "ПериодМесяц",
+  "periodAdditionBegin": "ПараметрыДанных.ДатаНачала",
+  "periodAdditionEnd":   "ПараметрыДанных.ДатаОкончания" }
+```
+
 #### Таблица (table)

 ```json
@@ -907,6 +921,23 @@ Platform-pattern: `startDate`/`endDate`/`date` эмитятся ТОЛЬКО д

 `points` и `series` принимают те же поля что table column/row (включая `name` и user-settings).

+**Multi-series / multi-points** — `points` и `series` могут быть массивом объектов, тогда генерируется несколько `<dcsset:point>` или `<dcsset:series>` подряд (каждый со своими `groupBy`, `filter`, user-settings). Используется например для разделения данных диаграммы на несколько серий по разным фильтрам:
+
+```json
+{
+  "type": "chart",
+  "points": { "groupBy": ["Период"] },
+  "series": [
+    { "groupBy": ["Стадия"], "filter": ["Стадия = ЗНАЧЕНИЕ(Перечисление.X.A)"],
+      "viewMode": "Normal", "userSettingID": "auto",
+      "userSettingPresentation": { "ru": "Серия A" } },
+    { "groupBy": ["Стадия"], "filter": ["Стадия = ЗНАЧЕНИЕ(Перечисление.X.B)"],
+      "viewMode": "Normal", "userSettingID": "auto",
+      "userSettingPresentation": { "ru": "Серия B" } }
+  ]
+}
+```
+
 ### userFields (пользовательские вычисляемые поля)

 Дополнительные поля, которые пользователь может задать в режиме «Изменить вариант» через UI. Хранятся в settings варианта. Два подтипа определяются по содержимому объекта:
@@ -1151,13 +1182,45 @@ Shorthand-флаги `@inaccessible`, `@quickAccess` доступны для `fi

 #### Расшифровка (drilldown) в параметрах шаблона

-Ключ `drilldown` в параметре шаблона автоматически генерирует:
-1. `DetailsAreaTemplateParameter` с именем `Расшифровка_<значение>`, `fieldExpression` по полю `ИмяРесурса`, `mainAction=DrillDown`
-2. Привязку `Расшифровка` в appearance ячеек, ссылающихся на этот параметр через `{Имя}`
+Ключ `drilldown` в параметре шаблона — три формы по типу значения:
+
+**Форма A (без drilldown)** — обычный `ExpressionAreaTemplateParameter`:
+```json
+{ "name": "Дата", "expression": "Документ.Дата" }
+```
+
+**Форма B (строка, shortcut)** — `ExpressionAreaTemplateParameter` + автоматический `DetailsAreaTemplateParameter` с именем `Расшифровка_<value>`, `fieldExpression` по полю `ИмяРесурса` (`expression="<value>"`), `mainAction=DrillDown`. Ячейки `{name}` получают appearance `Расшифровка → Расшифровка_<value>` автоматически:
+```json
+{ "name": "Сырье", "expression": "ПоступлениеСырья", "drilldown": "ПоступлениеСырья" }
+```
+
+**Форма C (объект)** — самостоятельный `DetailsAreaTemplateParameter` с именем `name`, без `ExpressionAreaTemplateParameter`. Используется когда расшифровка ссылается на data-параметр (а не на ИмяРесурса) и/или нужен другой `mainAction` (например `OpenValue`):
+```json
+{ "name": "МаршрутныйЛист",
+  "drilldown": { "field": "МаршрутныйЛист",
+                 "expression": "МаршрутныйЛист",
+                 "action": "OpenValue" } }
+```
+`action` по умолчанию `DrillDown`.
+
+**Override на уровне ячейки** — object-форма `{ value, drilldown }`. Используется когда несколько ячеек должны указывать на один и тот же параметр-расшифровку (объявленный формой C):

 ```json
-"parameters": [
-  { "name": "Сырье", "expression": "ПоступлениеСырья", "drilldown": "ПоступлениеСырья" }
+"rows": [
+  [ { "value": "{Номер}", "drilldown": "МаршрутныйЛист" },
+    { "value": "{Дата}",  "drilldown": "МаршрутныйЛист" } ]
+]
+```
+
+Значение `drilldown` в ячейке — это полное имя параметра-расшифровки (как объявлено в `parameters`). Для shortcut form B override не нужен — appearance подставляется автоматически.
+
+### fieldTemplates
+
+Привязка именованного area-template к полю — `<fieldTemplate><field>X</field><template>Y</template></fieldTemplate>`. Когда платформа выводит значение поля `X`, используется макет `Y`:
+
+```json
+"fieldTemplates": [
+  { "field": "МаршрутныйЛист", "template": "Макет1" }
 ]
 ```