# Работа с пакетами 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 есть в конфигурации `src`?»
>
> «Что внутри пакета `ОбменСБанком` — какие типы и с чего начинать чтение?»

Обычный первый шаг, когда формат чужой или давно не открывался. Список пакетов
показывает имя, пространство имён и число типов; обзор пакета — типы и точки входа.

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

> «Сформируй платёжное поручение по пакету `ОбменСБанком` и запиши в `out.xml`»
>
> «Напиши обработку выгрузки заказов по пакету `ОбменМаркетплейс`, начни с типа `Заказ`»

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

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

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

> «Разбери `in/egais-ttn.xml` по пакету `ЕГАИС3` — с какого типа начинать?»
>
> «Какие точки входа у пакета `ЕГАИС3`?»

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

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

> «Контрагент прислал `schemas/orders.xsd` — добавь пакет в конфигурацию, исходники в `src`»
>
> «Собери пакет по `schemas/fss-person.xsd`, имя `FSS_Person_01`»

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

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

Если схема ссылается на чужое пространство имён через `<xs:import>`, сначала нужен
пакет-зависимость: платформа отвергнет конфигурацию, где импортируемого пакета нет.
Об этом скажут ещё на сборке — чинить дешевле там, чем на `/db-update`. Исключение —
пространства имён самой платформы (`http://www.w3.org/2001/XMLSchema`,
`http://v8.1c.ru/8.1/data/core` и подобные): их пакетами объявлять не нужно.

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

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

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

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

> «Кто ссылается на тип `Адрес` из пакета `КонтактнаяИнформация`?»

Ответ — список типов и пакетов, включая те, что ссылаются через границу пакета.

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

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

> «Сделай из пакета `Обмен` версию 2: новый пакет `ОбменV2` с namespace `urn:…:v2`,
> старый не трогай»

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

Отдельной команды для этого нет: агент выгружает схему исходного пакета, меняет в ней
пространство имён и собирает под новым именем. Дополнительных действий это не требует —
достаточно назвать в задаче исходный пакет, новое имя и новый namespace. Внутренние
ссылки переводятся на него целиком, импорты чужих пакетов сохраняются, исходный пакет
остаётся как был.

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

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

> «Выгрузи схему пакета `Обмен` в `schemas/exchange.xsd`, отправлю партнёру»

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

### Проверить перед загрузкой в базу

> «Проверь пакет `Обмен` перед загрузкой в базу»
>
> «Я правил `Package.bin` руками — проверь, что платформа его примет»

Проверка ловит то, на чём `/db-update` отказывается принимать конфигурацию:
импорт пакета, которого в конфигурации нет; ссылку на несуществующий тип или
необъявленный префикс; нарушенный порядок элементов верхнего уровня; расхождение
объекта метаданных с моделью; отсутствие пакета в `Configuration.xml`. Дешевле
поймать здесь, чем в отказе загрузки. После правки через `/xdto-edit` проверка
запускается сама.

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

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

Такой симптом почти всегда означает, что тип не разрешился и стал «произвольным».
Платформа об этом молчит: при импорте 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)