cc-1c-skills/docs/xdto-guide.md

# Работа с пакетами XDTO

Пакет XDTO описывает XML-формат: какие есть типы, из каких свойств состоят, что
обязательно. По нему платформа умеет читать и писать XML — через `ФабрикаXDTO`.
Встречается везде, где 1С обменивается данными наружу: ЭДО, ЕГАИС, ВЕТИС, ФСС,
клиент-банк, веб-сервисы, `EnterpriseData`.

Навыки вызываются агентом сами — задачу можно ставить обычными словами. Ниже
примеры формулировок и того, что за ними происходит.

## Навыки

| Навык | Задача |
|---|---|
| [`/xdto-info`](../.claude/skills/xdto-info/SKILL.md) | Что в пакете и как заполнять тип — в терминах 1С |
| [`/xdto-compile`](../.claude/skills/xdto-compile/SKILL.md) | Собрать пакет по XML-схеме |
| [`/xdto-decompile`](../.claude/skills/xdto-decompile/SKILL.md) | Выгрузить пакет в XML-схему |
| [`/xdto-edit`](../.claude/skills/xdto-edit/SKILL.md) | Точечно поправить существующий пакет |
| [`/xdto-validate`](../.claude/skills/xdto-validate/SKILL.md) | Проверить перед загрузкой в базу |

Формат описания — обычная XML-схема, своего DSL нет. Схема в реальных задачах
обычно уже есть: её присылает контрагент или публикует регулятор.

## Сценарии

### Написать код, который заполняет объект XDTO

> «Сформируй платёжное поручение в формате клиент-банка и выгрузи в файл»
>
> «Напиши обработку выгрузки заказов по нашему обмену с маркетплейсом»

Самая частая задача, и обычно она часть большей. Прежде чем писать код, агент
смотрит структуру типа: какой тип значения присваивать каждому свойству, что
обязательно, где нужно создать вложенный объект, какие значения допустимы.

Выводится это уже в терминах 1С — `Строка(6)`, `Число(18,2)`, `[обязательный]`, —
поэтому переводить `xs:decimal` и `lowerBound="0"` в голове не приходится.
Если тип большой, помогает срез только обязательных свойств: получается готовый
скелет заполнения.

### Разобрать входящий XML

> «Разбери входящий файл ЕГАИС и создай по нему документы»
>
> «Какому типу соответствует корень этого XML?»

Чтобы прочитать документ, надо знать, с какого типа начинать. Это **точки входа**
пакета — его глобальные объявления; агент покажет их вместе со списком типов.

### Добавить пакет по схеме контрагента

> «Контрагент прислал схему обмена заказами, добавь её в конфигурацию»
>
> «Нужен пакет XDTO по вот этой XSD от ФСС»

Пакет собирается по схеме и сразу регистрируется в конфигурации.

**Обрати внимание на предупреждения.** XML Schema выразительнее модели XDTO, и часть
конструкций переносится приближённо: вложенный `xs:choice` уплощается (ветки при этом
становятся необязательными), `xs:all` превращается в последовательность, кратность
на частице отбрасывается. Агент об этом сообщит — если упрощение недопустимо,
схему надо менять, а не игнорировать сообщение.

Если схема ссылается на чужое пространство имён через `<xs:import>`, сначала нужен
пакет-зависимость. Иначе платформа откажется принимать конфигурацию либо молча
подменит тип на «произвольный», и всплывёт это уже в рантайме.

### Поправить существующий пакет

> «Добавь в платёжное поручение необязательный комментарий, не длиннее 200 символов»
>
> «Убери из обмена устаревшее поле СтарыйКод»
>
> «Добавь в перечисление видов документов значение Инкассо»

Точечная правка не требует читать схему целиком — для больших пакетов вроде
`EnterpriseData` это единственный практичный путь. После правки автоматически
запускается проверка.

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

Если переработка широкая — «перепиши обмен под новую версию формата» — схема
выгружается целиком, правится и собирается обратно. Пара выгрузка-сборка
замыкается без потерь, включая имя, синоним и комментарий объекта метаданных.

### Новая версия пакета

> «Сделай версию 2.0 нашего обмена, старая должна продолжать работать»

Типовой приём: рядом со старым пакетом появляется новый с другим пространством
имён (`EnterpriseData_1_19` → `_1_20`), а старые потребители продолжают смотреть
на прежний namespace.

Если же надо сменить namespace **у существующего** пакета, агент перепишет все
внутренние ссылки и перечислит пакеты, которые импортируют старый — но менять
их не станет, потому что при версионировании это было бы ошибкой.

### Отдать схему контрагенту

> «Выгрузи схему нашего обмена, отправлю партнёру»

Получается валидная XSD, ничего не теряющая. Штатный «Экспорт XML-схемы»
в Конфигураторе для этого хуже: он теряет признак `nillable` у свойств-атрибутов.

### Разобраться, почему обмен ведёт себя странно

> «Обращение к Смена.Сотрудник возвращает что-то бесструктурное, разберись»
>
> «Пакет вроде загрузился, а обмен не работает»

Такой симптом почти всегда означает, что тип не разрешился и стал «произвольным».
Платформа об этом молчит: при импорте XML-схемы неразрешённый чужой тип заменяется
без единой ошибки, пакет выглядит загруженным. Проверка называет и симптом,
и причину — объявленный, но неиспользуемый импорт.

## Структура файлов

```
XDTOPackages/
├── ОбменСБанком.xml            объект метаданных: Name, Synonym, Comment, Namespace
└── ОбменСБанком/
    └── Ext/
        └── Package.bin         модель пакета (текстовый XML, несмотря на расширение)
```

Плюс регистрация в корневом `Configuration.xml` — без неё платформа пакет не увидит.

## Рабочий цикл

1. Посмотреть, что есть — `/xdto-info`
2. Изменить — `/xdto-compile` или `/xdto-edit`
3. Проверить до загрузки — `/xdto-validate`
4. Применить — `/db-load-xml` + `/db-update`

Точный синтаксис параметров каждого навыка — в его `SKILL.md` по ссылкам выше.

## Спецификации

- Формат исходников — [1c-xdto-spec.md](1c-xdto-spec.md)
- XML Schema как формат описания, таблица соответствий и аннотации `xdto:` —
  [xdto-dsl-spec.md](xdto-dsl-spec.md)