Работа с метаданными

Repo script: ./scripts/python/run-python.sh

Использовать существующий scripts/python/run-python.sh metadata; на Windows — scripts/python/run-python.ps1 metadata. Нужны Python 3.12+ и пакеты lxml и jsonschema; без них команда завершается ошибкой импорта. Этот CLI заменяет импортированные навыки meta-*, form-* (кроме form-patterns) и cfe-borrow. Не запускать их как обход отказа нового инструмента. Регистрация и удаление макетов (template-add/template-remove) и MXL (mxl-*) остаются вне этого маршрута; содержимое уже зарегистрированного табличного макета правится здесь.

Применение

1. Уточнить корень исходников, логический путь объекта и требуемое изменение. metadata capabilities сообщает доступные операции и схему запроса; metadata inspect --root ROOT --object Catalog.Имя показывает текущий объект. Для формы использовать Catalog.Имя.Form.Форма или CommonForm.Форма, а не файловый путь к Form.xml.
2. Составить явный запрос с schemaVersion: 1 и последовательностью operations. Каждая операция содержит op, target, parameters. Не выводить соответствие объектов и размещение элементов из сходства имён. Неизвестные возможности проверять по схеме и реализации, а не угадывать параметры.
3. Выполнить metadata plan --root ROOT --request REQUEST --out PLAN. Новый файл плана хранить вне участвующих деревьев исходников. Просмотреть весь diff, список чтения и записи, удаления и UUID-связи. Убедиться, что изменения ограничены запросом пользователя. Для просмотра использовать готовое поле diff плана; большие планы фильтровать по списку writes, не выводить Base64-содержимое файлов. Не пересобирать diff внутренними Python-функциями: это дублирует уже выполненную работу CLI.
4. Применить именно просмотренный план: metadata apply --root ROOT --plan PLAN. При изменении исходников или редактора заново построить и просмотреть план; не править хеши, предусловия и служебный журнал для обхода конфликта.
5. Выполнить metadata verify --root ROOT --object LOGICAL для затронутых объектов (--object можно повторять). Для заимствованных форм указать точный --base-root BASE. Ошибки и предупреждения разобрать до заявления готовности. Проверка XML не заменяет компиляцию, объединение расширения и открытие формы в точной целевой платформе через штатные наблюдаемые обёртки.

Если пользователь запретил проверки, не запускать их: оставить результат непроверенным и явно указать, какие подтверждения отсутствуют.

Пример добавления поля к существующему реквизиту общей формы:

{
  "schemaVersion": 1,
  "operations": [{
    "op": "form.add-input",
    "target": "CommonForm.Форма",
    "parameters": {
      "name": "НовоеПоле",
      "attribute": "Текст",
      "title": "Текст",
      "parent": "Группа",
      "after": "СуществующееПоле"
    }
  }]
}

parent и after проверить по текущему дереву; без after поле добавляется в конец контейнера. form.add-input не создаёт реквизит и не отменяет ReadOnly родителя. BSL-обработчики разрабатывать и проверять отдельно.

Для работы с заимствованной формой сначала включить в тот же запрос form.borrow с её логическим путём и parameters.baseRoot, указывающим точную базовую выгрузку. Эта операция обеспечивает проверяемую связь с базой; не копировать XML формы вручную и не заменять UUID. У plan и apply нет общего аргумента --base-root.

Для уже заимствованной формы, созданной прежней версией CLI, доступны точечные исправления form.borrow: repairNativeCommandProjection: true восстанавливает нативную сериализацию унаследованных стандартных команд; repairNativeMainAttributeProjection: true меняет ID основного реквизита Объект с 1 на 1000001 по проверенному образцу платформы 8.3.27. Использовать их только при совпадении с исследованным нативным случаем. CLI отклоняет неизвестное состояние BaseForm, изменённые свойства реквизита и коллизии ID. Для последующих form.borrow этой формы сохранять явный параметр проекции основного реквизита; он не включён по умолчанию.

Если форма базы ссылается на команды или контекст, которых нет в расширении (стандартные команды регистров, отборы владельца), заимствовать её с nativeProjection: true: как Конфигуратор 8.3.27, CLI сохраняет только дерево элементов, без путей данных (включая TitleDataPath и FooterDataPath), реквизитов, команд и командного интерфейса. Связи параметров выбора переводятся в ID реквизита формы или <ID основного>/0:<UUID реквизита объекта>; другие пути и условное оформление останавливают план. Параметр нельзя сочетать с moduleOnly и проекциями выше; повторять его в каждом последующем form.borrow этой формы. Для полей расширения добавить основной реквизит Объект типа <Вид>Object.<Имя> владельца через form.edit (main: true); другой тип или форма базы с основным реквизитом отклоняются.

Общую команду расширения создавать object.create с type: CommonCommand: group — имя стандартной группы платформы (например, FormCommandBarCreateBasedOn) или CommandGroup.<Имя>, parameterTypes — список типов параметра, а также representation, parameterUseMode, modifiesData. CLI создаёт пустой CommandModule.bsl; обработчик ОбработкаКоманды писать и проверять отдельно. Для заимствованного документа платформа не сохраняет BasedOn в расширении, поэтому ввод на основании делать собственной командой в группе FormCommandBarCreateBasedOn с типом параметра ссылки документа-основания.

Раздел (подсистему верхнего уровня) расширения создавать object.create с type: Subsystem: content — ссылки Вид.Имя, picture — CommonPicture.<Имя>, также explanation, includeInCommandInterface, useOneCommand. Объекты состава и картинка должны быть зарегистрированы в расширении: типовые предварительно заимствовать object.borrow в том же запросе, иначе план отклоняется. Вложенные подсистемы CLI не создаёт.

Для object.edit заимствованного объекта также включать в тот же запрос object.borrow с точным parameters.baseRoot перед редактированием, даже если объект уже есть в расширении. Наличие объекта не заменяет базовый контекст; отказ Exact base context required исправлять запросом, а не ослаблением проверки.

Предопределённые счета и виды субконто создавать операцией predefined.create для ChartOfAccounts и ChartOfCharacteristicTypes; точные параметры брать из metadata capabilities. parameters.baseRoot должен указывать базовую конфигурацию целевого расширения. CLI заимствует необходимые свойства и цепочку родителей счёта, проверяет коллизии имён/кодов и сохраняет UUID при повторении. После загрузки и обратной выгрузки применять inspect и verify с --base-root BASE: платформа может записать ссылки на виды субконто как UUID. Сверять также порядок субконто и признаки учёта; успешное создание живой ссылки само по себе не подтверждает сохранение всех свойств предопределённого элемента.

Предопределённые элементы собственного (не заимствованного) справочника создавать той же операцией для Catalog.Имя с параметрами name, description и необязательным code без baseRoot. Формат соответствует выгрузке Конфигуратора 8.3.27 для собственного справочника расширения: без ExtensionState, элемент с тем же именем и содержимым не меняется, конфликт имени или кода отклоняется.

Для исправления вида и признаков учёта уже созданного CLI собственного счёта использовать predefined.update с baseRoot, name, accountType и полным accountingFlags. Операция сохраняет код, UUID, родителя, субконто и дочерние элементы; заимствованные и чужие идентификаторы отклоняются. Повторный predefined.create по-прежнему не разрешает перезаписывать конфликтующее определение.

Для повторного импорта выгрузки платформы нормализовать UUID-ссылки субконто операцией predefined.normalize-dimension-refs для ChartOfAccounts.Имя с точным parameters.baseRoot. CLI заменяет только ссылки на логические имена по предопределённым данным базы и расширения; UUID счетов, порядок и признаки учёта сохраняются. Неизвестная или неоднозначная UUID-ссылка останавливает план. После импорта сверить определения через inspect --base-root и обратную выгрузку.

Правка существующей формы

Элементы, реквизиты и команды адресуются по именам из inspect формы (поле elements: имя, вид, родитель, путь к данным).

• form.set-properties — свойства элемента или самой формы (Form или без имени); имена свойств — XML-узлы Designer, null удаляет свойство.
• form.move-element — перенос с into и after/before; допустимость контейнера проверяется, ID сохраняются.
• form.remove-element, form.set-attribute, form.set-command — удаление и изменение; при ссылке на удаляемое (путь к данным, кнопка, условное оформление) план отклоняется с перечнем ссылок. Принудительного удаления нет.
• form.edit добавляет элементы, реквизиты, команды и события, в том числе с before.
• form.remove-event снимает назначение обработчика события формы (name) или элемента (name, element); при нескольких слотах указать callType. Процедура остаётся в модуле, план перечисляет её для ревью.
• Форма с повторяющимися именами элементов отклоняется всеми операциями, кроме form.rename-element (element, id, newName). Повторы чинятся по одному элементу: новое имя должно быть уникальным, прежние повторы могут остаться до своего переименования, новые не допускаются. Все переименования и последующую правку можно передать одним запросом.

Целиком форму удаляет form.remove (target — <Владелец>.Form.<Имя>). План удаляет поддерево формы и ссылку на неё в описании владельца. Справку владельца (Ext/Help.xml и перечисленные в нём страницы) операция пропускает. Любой другой файл владельца вне поддерева формы — модуль объекта, макет, СКД — блокирует удаление, пока он не указан в reviewedDependencies с путём, текущим SHA-256 и причиной, по которой он не ссылается на форму. Схема reviewedDependencies та же, что у object.remove; устаревший SHA-256 отклоняется.

Процедуры модуля эти операции не создают и не удаляют: обработчики, оставшиеся без назначения, план перечисляет как предупреждение. В заимствованной форме узлы BaseForm не изменяются и не удаляются.

Содержимое табличного макета

Цель — Вид.Объект.Template.Имя или CommonTemplate.Имя зарегистрированного макета вида SpreadsheetDocument. inspect показывает области, параметры, шаблоны, параметры расшифровки, размер сетки и настройки печати (строки и колонки с 1). Операции template.set-area, template.set-parameter, template.set-format, template.insert-rows/delete-rows, template.insert-columns/delete-columns, template.merge-cells, template.set-size, template.set-print-settings, template.set-header-footer меняют только затронутые узлы; вставка и удаление сдвигают области и объединения. template.import-xlsx заполняет макет из листа .xlsx (абсолютный путь); непустой макет заменяется только с replace: true, непереносимое перечисляется в notTransferred. Каталог .xlsx не должен содержать --root и файл плана: держите .xlsx в отдельном каталоге вне родителя --root. Пустую заготовку после template-add остальные операции не правят (отказ с кодом 3): сначала template.import-xlsx, в том же плане можно продолжить правкой. Объединение без columnsID относится к набору колонок своей строки; вставка и удаление колонок набора сдвигают только его объединения.

Визуальная проверка

Если подключён MCP one-c-form-viewer, после verify можно посмотреть форму или макет в режиме только просмотра (open_preview, list_form_elements, list_markup). Правку выполнять только через metadata, не инструментами редактирования MCP. Изображение предпросмотра не доказывает готовность: её подтверждает загрузка и открытие в целевой платформе.

Отказы и восстановление

Исходники должны находиться на поддерживаемой локальной файловой системе (на Windows — NTFS); ссылки, UNC и сетевые пути не обходить копированием непроверенных путей. Жёсткие ссылки допустимы только в базовой выгрузке (baseRoot, --base-root), которую CLI лишь читает: так связаны выгрузки между worktree. В целевом дереве они отклоняются. Сохранять полный план и служебное состояние после ошибки применения. Не удалять lock или журнал восстановления как способ повторить операцию: сначала разобрать отказ и принадлежность состояния.

already-applied означает повтор того же результата без новой записи. checks.platform и checks.runtime остаются not-run: сам CLI не запускает 1С. Исторические результаты старого редактора не подтверждают новую реализацию.

Если операции не хватает

При дефекте CLI или отказе платформы после успешного verify использовать metadata-cli-development: получить минимальный образец Конфигуратором и исправить обработчик по его XML.

Сначала проверить scripts/python/metadata_ops.py: каталог, схему и HANDLERS, затем обработчик соответствующего семейства metadata_*. Отличить дефект существующей операции от новой возможности. Расширять ближайший обработчик, используя общий Snapshot, выделение идентификаторов и plan/apply; не добавлять второй механизм записи, произвольные XML-патчи или загрузчик плагинов.

Новую возможность ограничить исходной задачей. При изменении согласованного объёма или поведения сначала согласовать его. Добавить предметную схему, обработчик и проверку сохранности, отказов и повторного применения; не ослаблять валидацию ради одного примера. После разрешённых проверок вернуться к исходной задаче и провести тот же цикл inspect → plan → просмотр → apply → verify. Если пользователь запретил запуск тестов, запрет действует и при расширении инструмента.