1c Metadata

---
name: 1c-metadata
description: Программное редактирование метаданных/форм/СКД 1С (оба формата — Конфигуратор-XML и EDT .mdo/.form/.rights/.mxlx/.dcs) с гарантией round-trip. ОБЯЗАТЕЛЬНО используй, когда нужно программно добавить колонку в печатную форму (макет), поле/запрос в СКД отчёта, реквизит справочника/документа — вместо ручной правки XML или отказа «только человек в IDE». Активируйся на «добавь колонку в печатную форму», «добавь поле в СКД/прайс», «добавь реквизит», «поправь макет». НЕ для BSL-кода (1c-dev) и НЕ для операций вне каталога покрытия.
---

# 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.