Dcs Edit

/dcs-edit — точечное редактирование СКД (Template.xml)

MCP routing

• Preferred path: use MCP unica tool unica.apply с операциями СКД; адрес цели — логический, файлового селектора у поверхности нет.
• Не зови внутренние адаптеры напрямую: они спрятаны за MCP unica.
• Всегда сначала dryRun: true; dryRun: false — только по явной просьбе пользователя и только с ifRev из превью.
• Словарь операций узла даёт unica.view {at} в секции can: что не названо там, того поверхность не пишет.

Атомарные правки существующей схемы компоновки данных: поля, итоги, фильтры, параметры, настройки варианта, структура, текст запроса.

Адрес и операции

Цель — узел макета-схемы: <набор>:<Вид>.<Имя>.Template.<Макет>. Набор данных и вариант, когда их несколько, называются продолжением адреса.

Двадцать операций словаря: field.add, field.set, field.remove, fieldRole.set, calculatedField.add, total.add, parameter.add, parameter.set, parameter.remove, filter.add, filter.clear, selection.add, selection.clear, order.clear, conditionalAppearance.clear, query.set, query.patch, variant.add, structure.set, structure.patch.

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.apply",
    "arguments": {
      "at": "main:Report.Продажи.Template.ОсновнаяСхема",
      "ops": [
        {"op": "field.add", "args": {"items": [{"dataPath": "Номенклатура", "title": "Товар"}]}}
      ],
      "dryRun": true
    }
  }
}

Несколько правок идут одним ops: план собирается целиком и применяется атомарно — отказ любой операции отменяет весь вызов.

Применение — тот же вызов с dryRun: false и ifRev, который вернуло превью:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.apply",
    "arguments": {
      "at": "main:Report.Продажи.Template.ОсновнаяСхема",
      "ops": [
        {"op": "field.add", "args": {"items": [{"dataPath": "Номенклатура", "title": "Товар"}]}}
      ],
      "dryRun": false,
      "ifRev": "<rev из превью>"
    }
  }
}

Изменившаяся схема отвечает stale_revision и называет обе ревизии: перечитай превью и повтори.

Чего словарь не пишет

Поверхность правит существующую схему двадцатью операциями выше. Остальное из прежнего DSL канонической операции не имеет:

• наборы данных и их связи (add-dataSet, add-dataSetLink);
• параметры данных варианта (add-dataParameter, modify-dataParameter);
• добавление сортировки (add-order — есть только order.clear);
• добавление условного оформления (add-conditionalAppearance — есть только conditionalAppearance.clear);
• расшифровку ресурсов (add-drilldown);
• параметры вывода (set-outputParameter);
• переименование и перестановку параметров (rename-parameter, reorder-parameters);
• удаление итога, вычисляемого поля и отдельного фильтра (remove-total, remove-calculated-field, remove-filter).

Если задача требует одного из них — сообщи это как пробел контракта Unica MCP и не подменяй его соседней операцией: filter.clear вместо удаления одного фильтра сотрёт все.

Операции

Заголовки ниже названы операциями словаря там, где операция есть; прежние имена DSL, у которых канонической операции нет, помечены прямо в заголовке — их значения остаются описанием формата, а не вызовом. Само значение (values, items) в разделах описано в том же shorthand, что принимает операция.

field.add — добавить поле в набор данных

Shorthand: "Имя [Заголовок]: тип @роль #ограничение".

"Цена: decimal(15,2)"
"Организация [Орг-ция]: CatalogRef.Организации @dimension"
"Служебное: string #noFilter #noOrder"

Поле добавляется в набор и в selection варианта (если нет -NoSelection). Дубликат dataPath — предупреждение, пропуск.

total.add — добавить итог

"Цена: Среднее"
"Стоимость: Сумма(Кол * Цена)"

calculatedField.add — добавить вычисляемое поле

Shorthand: "Имя [Заголовок]: тип = Выражение #noFilter #noOrder #noGroup".

"Маржа = Продажа - Закупка"
"Наценка [Наценка, %]: decimal(10,2) = Маржа / Закупка * 100"
"Служебное: string = \"\" #noFilter #noOrder #noGroup"

#noFilter, #noOrder, #noGroup, #noField → <useRestriction> (аналогично field.add).

Также добавляется в selection варианта.

parameter.add — добавить параметр

"Период [Отчетный период]: StandardPeriod = LastMonth @autoDates"
"Организация: CatalogRef.Организации"

Shorthand: "Имя [Заголовок]: тип = значение [availableValue=список] [@флаги]". [Заголовок] опциональный — добавляет <title>.

Флаги:

• @autoDates генерирует пару скрытых параметров ДатаНачала/ДатаОкончания для StandardPeriod-параметра — для БСП-отчётов, чтобы получить пару полей «Начало/Конец» в панели быстрых настроек.
• @hidden скрывает параметр от пользовательских настроек, например для параметров-констант в запросе.
• @always всегда подставляет параметр в запрос. Часто используется вместе с @hidden, но подходит и для видимых обязательных параметров.
• @valueList разрешает передавать список значений. При значении-списке флаг подразумевается автоматически.

Значение-список задаётся несколькими значениями через запятую; если запятая входит в само значение, оборачивай его в одинарные кавычки.

"Виды [Виды субконто]: ChartOfCharacteristicTypesRef.ВидыСубконтоХозрасчетные = ПланВидовХарактеристик.ВидыСубконтоХозрасчетные.Контрагенты, ПланВидовХарактеристик.ВидыСубконтоХозрасчетные.Договоры"
"ПС: CatalogRef.Контрагенты = Справочник.Контрагенты.ПустаяСсылка @hidden"
"Период: StandardPeriod = LastMonth @always"
"ПСчет: ChartOfAccountsRef.Хозрасчетный = ПланСчетов.Хозрасчетный.X @hidden @always"
"Округление: EnumRef.Округления = Окр1 availableValue=Перечисление.Округления.Окр1: руб., Перечисление.Округления.Окр1000: тыс."

availableValue= задаёт начальный список допустимых значений. Формат списка: v1[: p1], v2[: p2], ...; представление после : опционально. Если в значении или представлении встречается , или :, оборачивай элемент в одинарные кавычки:

"Округление: EnumRef.Округления = Окр1 availableValue=Окр1_00: 'руб., коп.', Окр1: руб."

parameter.set — изменить существующий параметр

Shorthand: "ИмяПараметра [Заголовок] [ключ=значение]... [@флаги]". Находит параметр по имени, обновляет указанные свойства.

"ПорядокОкругления use=Always"
"ПорядокОкругления [Округление сумм] denyIncompleteValues=true"
"ПериодОтчета [Отчетный период]"                                  # только title
"ПорядокОкругления availableValue=Перечисление.Округления.Окр1: руб., Перечисление.Округления.Окр1000: тыс."
"СчетПС value=ПланСчетов.Хозрасчетный.КассаПредприятия"
"Виды value=ПланВидовХарактеристик.ВидыСубконтоХозрасчетные.Контрагенты, ПланВидовХарактеристик.ВидыСубконтоХозрасчетные.Договоры"
"Контрагент @hidden @always"

[Заголовок] опциональный — устанавливает или заменяет <title>. Можно вызывать без других kv-пар, чтобы только обновить title.

availableValue= заменяет весь список допустимых значений; старые элементы удаляются. Формат и кавычки такие же, как в parameter.add.

value= заменяет значение параметра. Несколько значений через запятую дают список значений и заменяют все прежние значения; для запятой внутри значения используй одинарные кавычки.

Флаги @hidden и @always работают так же, как в parameter.add, и идемпотентны.

rename-parameter — переименовать параметр — канонической операции нет

Shorthand: "OldName => NewName". Атомарно обновляет имя параметра, ссылки &Имя в выражениях других параметров (только полные совпадения, &ПериодX не задевается), и записи в dataParameters всех вариантов. Текст запроса не трогает — переименование строго в области параметров.

"Период => ПериодОтчета"

reorder-parameters — переставить параметры в указанном порядке — канонической операции нет

Shorthand: "Имя1, Имя2, Имя3". Частичный список — указанные параметры идут первыми в заданном порядке, остальные сохраняют исходный порядок и идут в конце. Параметры из списка, которых нет в схеме — warning, пропуск.

"ПериодОтчета, НачалоПериода, КонецПериода"

filter.add — добавить фильтр в вариант

Shorthand: "Поле оператор значение @флаги". Флаги: @off (use=false), @user (userSettingID=auto), @quickAccess, @normal, @inaccessible.

"Номенклатура = _ @off @user"
"Дата >= 2024-01-01T00:00:00"
"Статус filled"

add-dataParameter — добавить параметр данных в вариант — канонической операции нет

Shorthand: "Имя [= значение] @флаги".

"Период = LastMonth @user"
"Организация @off @user"

add-order — добавить сортировку — канонической операции нет

Shorthand: "Поле [desc]". По умолчанию asc. Auto — авто-элемент.

"Количество desc"
"Auto"

selection.add — добавить элемент выборки

"Номенклатура"
"Auto"
"Folder(Поступление: ПолеА, ПолеБ, ПолеВ)"

Folder(Название: поле1, поле2) — группа полей (SelectedItemFolder) с заголовком и placement=Auto.

@group=ИмяГруппировки — добавить в selection именованной группировки (вместо уровня варианта):

"Folder(Поступление: ПолеА, ПолеБ) @group=ДанныеОтчета"

add-dataSetLink — добавить связь наборов данных — канонической операции нет

Shorthand: "Источник > Приёмник on ВырИсточника = ВырПриёмника [param Имя]".

"Набор1 > Набор2 on Поле1 = Поле2"
"Набор1 > Набор2 on Поле1 = Поле2 [param Связь]"

add-dataSet — добавить набор данных — канонической операции нет

Shorthand: "Имя: ТЕКСТ_ЗАПРОСА" или "ТЕКСТ_ЗАПРОСА" (авто-имя НаборДанныхN).

"Доп: ВЫБРАТЬ 1 КАК Тест"
"ВЫБРАТЬ Ссылка ИЗ Справочник.Номенклатура"
"Продажи: @queries/sales.sql"

dataSource берётся из первого существующего. Дубликат имени — предупреждение, пропуск. Не поддерживает пакетный режим (запрос может содержать ;;).

variant.add — добавить вариант настроек

Shorthand: "Имя [Представление]". Представление опционально, по умолчанию = имя.

"Детальный"
"Детальный [Детальный отчёт]"

Создаёт вариант с Auto selection + detail group. Дубликат имени — предупреждение, пропуск.

add-conditionalAppearance — добавить условное оформление — канонической операции нет

Shorthand: "Параметр = значение [when условие] [for Поле1, Поле2]". Блок when — синтаксис filter.add (Поле оператор значение).

"ЦветТекста = web:Red when Сумма < 0"
"ЦветФона = web:LightGreen when Статус = Одобрен for Статус"
"МинимальнаяШирина = 50 for Организация"
"Формат = ЧДЦ=2 for Цена, Сумма"

Типы значений appearance (автодетект): web:*/style:*/win:* → Color, true/false → Boolean, параметр Формат/Текст/Заголовок → LocalStringType, иначе String.

Типы значений фильтра (автодетект): Перечисление.*/Справочник.*/ПланСчетов.*/Документ.* → DesignTimeValue, true/false → Boolean, дата → DateTime, числа → Decimal, иначе String.

OrGroup: несколько условий через or в when объединяются в FilterItemGroup/OrGroup:

"Формат = ЧЦ=15; ЧДЦ=0 when ПараметрыДанных.Округление = Перечисление.Округления.Окр1 or ПараметрыДанных.Округление = Перечисление.Округления.Окр1000"

Важно: для параметров данных используйте префикс ПараметрыДанных. в поле фильтра.

add-drilldown — подключить расшифровку к ресурсам в шаблонах — канонической операции нет

Value — имена ресурсов (как в полях/вычисляемых полях СКД) через запятую.

"ПоступлениеИзПроизводства, ВыбытиеПрочее"
"Сумма_Дт83, Сумма_Дт99, Сумма_68, Сумма_84"

Подключает DrillDown по ИмяРесурса ко всем шаблонам, содержащим указанные ресурсы. Идемпотентно.

query.set — заменить текст запроса

Не поддерживает пакетный режим. Value — полный текст запроса или @path/to/file.sql (ссылка на внешний файл). Путь разрешается относительно Template.xml, затем CWD.

Когда что: существенная переработка запроса (добавить поля, соединения, переписать пакет) -> получи запрос через unica.view on the schema node и возьми data.dataSets[].query; отредактируй текст и передай его в query.set как значение. query отдаёт сырой текст запроса целиком, с отступами строк продолжения |, поэтому передача точна, включая многопакетные запросы. Точечная замена идентификатора или подстроки не требует выгрузки: используй query.patch.

query.patch — точечная замена в тексте запроса

Shorthand: "старое => новое [@once]". По умолчанию заменяет все вхождения подстроки. Поддерживает пакетный режим и DataSet.

"СубконтоДт1) В => СубконтоКт1) В"
"ЛЕВОЕ СОЕДИНЕНИЕ => ВНУТРЕННЕЕ СОЕДИНЕНИЕ"
"КАК ВТ_СтароеИмя => КАК ВТ_НовоеИмя @once"

@once падает с ошибкой, если найдено не ровно одно вхождение. Используй его для опасных переименований, чтобы не заменить однотипные идентификаторы или комментарии.

set-outputParameter — установить параметр вывода — канонической операции нет

"Заголовок = Мой отчёт"
"ВыводитьЗаголовок = true"

Если параметр уже существует — заменяет значение.

structure.set — установить структуру варианта

Shorthand: "Поле1 > Поле2 > details". details/детали — детальные записи. Заменяет всю структуру. Не поддерживает пакетный режим.

"Организация > Номенклатура > details"
"details"
"СчетМеждународногоУчета @name=ДанныеОтчета"

@name=Имя — присваивает имя группировке (<dcsset:name>). Используется для привязки шаблонов через groupName.

field.set — изменить существующее поле

Тот же shorthand что и field.add. Находит по dataPath, объединяет свойства (непустые переопределяют), сохраняет позицию.

"Цена [Цена USD]: decimal(10,4) @dimension"

modify-filter — изменить существующий фильтр — канонической операции нет

Тот же shorthand что и filter.add. Находит по полю, обновляет оператор/значение/флаги. См. правило для <use> ниже.

modify-dataParameter — изменить параметр данных — канонической операции нет

Тот же shorthand что и add-dataParameter. Находит по имени, обновляет значение/флаги. См. правило для <use> ниже.

Правило <use> для modify-filter / modify-dataParameter

В отличие от add-*, в modify-* поле <use> обновляется только если флаг задан явно:

• @off — установить <use>false</use>
• @on — убрать существующий <use>false</use> (включить параметр)
• ни @off, ни @on не задано — <use> не трогается, существующее значение сохраняется (важно: это значит, что отключённый параметр останется отключённым после модификации других свойств)

remove-* и clear-*

Верификация

Валидация структуры после редактирования

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.check",
    "arguments": {
      "at": "<sourceSet>:<Kind>.<Name>.Template.<Template>"
    }
  }
}

Сводка схемы

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.view",
    "arguments": {
      "cwd": "<workspace>",
      "at": "<набор>:Report.<Отчёт>.Template.<Макет>"
    }
  }
}