1c Metadata

1c-metadata — структурные правки метаданных 1С

Локализация (сначала, если есть)

Если в скилле есть каталог references/local/ — прочитай его ПЕРЕД работой: version-stack.md (версии платформы/библиотек, режим совместимости, префиксы ТВОЕЙ компании) и остальные карты. При противоречии локальное побеждает generic. Контракт — docs/SKILL_LOCALIZATION.md toolkit.

Ядро: onec_metadata/ (Python, lxml). CLI: bin/1c-meta. Каталог покрытия: onec_metadata/catalog.py — операции вне каталога делает человек в IDE.

Железные правила

1. Только тест-база. Загрузка изменений — исключительно в тестовую ИБ (напр. localhost\<testbase>). В прод — человек, после приёмки.
2. Round-trip обязателен. После загрузки: повторная выгрузка → diff с эталоном == строго целевые файлы (apply.dumpload.roundtrip_verify). Без чистого round-trip правка не считается выполненной.
3. Минимальный дифф. Формат-слой (formats/configurator.py) даёт byte-perfect round-trip (BOM/CRLF/табы); операции меняют только целевые узлы. Никогда не переформатируй XML вручную/другими инструментами.
4. BSL после правки кода — если задет *.bsl, прогони BSL Language Server.
5. Смок-валидатор СКД (ENFORCED, офлайн) — после любой правки схемы компоновки: 1c-meta scd validate <Schema.xml> (exit 1 = поломка: пропал набор, поле без dataPath, дубль поля, битая связь наборов, невалидный XML). До загрузки в 1С.
6. Класс поля СКД перед добавлением в группировку. Поле выводится в выбранных полях группировки, только если оно: поле группировки | реквизит поля группировки (dataPath через точку — Номенклатура.Артикул) | ресурс (totalField). Иначе — Поле ... не может быть использовано в группировке .... Для обычного (неагрегатного) атрибута правильный класс — реквизит, не ресурс: в структуре «Таблица» ресурсы уходят в ячейки на пересечении строк и колонок, а не в колонку строки. Перед правкой посмотреть, как объявлены уже работающие неагрегатные поля этой же группировки, и повторить их класс. Проверить РасположениеРеквизитов (умолчание «Вместе с владельцем» → колонки склеиваются с владельцем; для отдельных колонок нужно Отдельно). Подробно — references/skd-fields-in-groupings.md.
7. Объект расширения в типовом интерфейсе — через ПодключаемыеОтчетыИОбработки. СведенияОВнешнейОбработке() работает ТОЛЬКО для внешних файлов .erf/.epf в справочнике ДополнительныеОтчетыИОбработки (БСП поднимает их из ХранилищеОбработки через ВнешниеОтчеты.Создать). Для отчёта/обработки ВНУТРИ расширения она не вызывается никогда. Штатный путь: заимствовать подсистему ПодключаемыеОтчетыИОбработки, включить в её состав свой объект, в модуле менеджера определить ПриОпределенииНастроек + парную процедуру (ДобавитьКомандыПечати / ДобавитьКомандыОтчетов / НастроитьВариантыОтчета / ДобавитьКомандыЗаполнения / ДобавитьКомандыСозданияНаОсновании). Подробно, включая рецепт печатной формы с макетом Word — references/bsp-extension-attachable-objects.md.
8. Scope-guard «не тронул незатронутое» (ENFORCED, офлайн) — property-level diff onec_metadata/apply/scope_guard.assert_in_scope(before, after, scope) БЕЗ тест-базы блокирует дрейф свойств у объектов, которые правка менять не должна была (дополняет файловый roundtrip_verify до уровня свойств).

Форматы

Оба формата исходников: Конфигуратор (Объект.xml, Rights.xml, Template.xml, Form.xml) и EDT (Объект.mdo, Rights.rights, Template.mxlx, Form.form, .dcs) — диспетчеризация по расширению, стиль файла (BOM/EOL/табы) сохраняется. EDT-нюансы: .mdo опускает свойства со значением по умолчанию EMF-модели EDT (проверено эмпирически на выгрузке ERP: свойство отсутствует ⇔ дефолт; дефолт EDT ≠ дефолт UI Конфигуратора — пример fullTextSearch) — поэтому set-property на отсутствующем свойстве отказывает предусловием; тип реквизита формы в EDT-нотации (String, CatalogRef.Имя), а не xs:/cfg:. Бинарный Template.bin вне scope.

Порядок операции

1c-meta detect <root>                  # формат дерева: CONFIGURATOR | EDT
cp -r <src> <src>_before               # эталон для verify
1c-meta template add-column <Макет.xml> --after "<ЗаголовокЯкоря>" \
    --header "<НовыйЗаголовок>" --parameter <ИмяПараметра>
1c-meta scd add-field <Schema.xml> --dataset <ИмяНабора> \
    --field X --data-path X --title "..."
1c-meta scd get-query|set-query ... --from-file q.sql
1c-meta attr add <Объект.xml> --name X --type xs:string --synonym "..."
# затем python: onec_metadata.apply — upload_tree → load_extension →
# dump_extension → fetch_tree → roundtrip_verify(before, after, {целевые файлы})

Exit 2 = ошибка предусловия (якорь не найден / дубль) — файлы не изменены.

Смоук-сценарии (боевые уроки)

Сценарий выполняется через Выполнить() — нельзя объявлять Функция/Процедура, только операторы инлайном. Не называть переменные и псевдоним таблиц зарезервированными словами (И, НЕ, ИЛИ). Состав полей незнакомого объекта проверять по выгрузке/Метаданные ДО написания запроса, а не по памяти. ВнешниеОтчеты.Подключить на базе без маски DisableUnsafeActionProtection вешает пакетный сеанс насмерть — проверять объект расширения через Отчеты.<Имя>.Создать() либо поднимать схему из XML через СериализаторXDTO. Мутации — только в транзакции с откатом и контрольным запросом после. Подробно — references/smoke-runner-gotchas.md.

Известные ловушки инструментов (читать до правки)

references/edt-mcp-known-issues.md — EDT MCP (модальное окно вместо «таймаута», форматы типа, заимствование перед ссылочным типом, чего MCP не умеет вовсе), EDT + git (метаданные молча откатываются мержами, коллизия id в форме), пакетный деплой расширения (безопасный режим гасит перехваты, «ошибка формата потока», сборка из файлов). Все пункты — про операции, которые возвращают успех при неверном результате.

Транспорт и доступ (боевые уроки)

• Кириллические имена Windows→Mac: только chcp 65001 + tar (не zip).
• SSH-алиас с пробелом в имени пользователя: User "<Имя С Пробелом>" в кавычках.
• Пароль ИБ не хранить в коде/логах (runner.mask_password).

Ссылки

Перед работой посмотреть, нет ли уже готового ответа (сначала искать, потом писать своё):

• docs/testing-ladder.md — какой ступенью что проверять (статика → batch → компоновка → интерфейс → фреймворки);
• docs/create-object-in-extension.md — создание нового объекта/копии объекта в расширении;
• docs/setup-actions-required.md — предпосылки окружения, в т.ч. защита от опасных действий (вешает пакетные сеансы);
• docs/data-access-architecture.md — чтение ДАННЫХ живой базы (другая ось, чем проверка поведения);
• docs/onec-work-mechanisms.md — механизмы платформы.

Документация модуля: onec_metadata/README.md (архитектура, CLI, настройки, дорожная карта Фаз 2–5, известные ограничения). Кейсы конкретных организаций и их настройки — в приватных репозиториях настроек, не в этом (публичном) toolkit.