# Работа с пакетами 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

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

```powershell
# известны namespace и тип (например, из строки ФабрикаXDTO.Тип(...) в чужом коде)
/xdto-info src -Namespace "urn:1C.ru:ClientBankExchange" -Name ПлатежныйДокумент -Depth 2

# только обязательное — скелет для заполнения
/xdto-info src -Namespace "urn:1C.ru:ClientBankExchange" -Name ПлатежныйДокумент -RequiredOnly
```

Вывод даёт типы уже в нотации 1С (`Строка(6)`, `Число(18,2)`), помечает обязательные
свойства и коллекции, перечисляет допустимые значения и подсказывает вызовы фабрики.
Читать `Package.bin` при этом не нужно.

Если имя пакета неизвестно, а тип известен — `-Name` по корню исходников найдёт его
по всем пакетам конфигурации.

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

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

```powershell
/xdto-info src -Namespace "urn:partner:orders"
```

Дальше по имени типа — состав свойств, как в предыдущем сценарии.

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

```powershell
/xdto-compile -XsdPath partner.xsd -OutputDir src -Name ЗаказыКонтрагента
/xdto-validate src/XDTOPackages/ЗаказыКонтрагента
```

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

Схема ссылается на чужой namespace через `<xs:import>` — сначала собери пакет-зависимость.
Иначе платформа при загрузке молча подменит тип на `xs:anyType`, и обнаружится это
только в рантайме.

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

Точечно — `/xdto-edit`, схему целиком читать не нужно:

```powershell
/xdto-edit src/XDTOPackages/ОбменСБанком -Operation add-property -Target "ПлатежныйДокумент" `
           -Value '<xs:element name="Комментарий" type="xs:string" minOccurs="0"/>'
```

Многострочный фрагмент передавай файлом: `-Value "@frag.xsd"`.

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

```powershell
/xdto-info src -Mode used-by -Name СуммаТип
```

Если переработка широкая или сначала надо разобраться в схеме — выгрузи её целиком:

```powershell
/xdto-decompile src/XDTOPackages/ОбменСБанком -OutFile bank.xsd
# правка bank.xsd
/xdto-compile -XsdPath bank.xsd -OutputDir src -Name ОбменСБанком -Force
```

Пара замыкается без потерь, включая имя, синоним и комментарий объекта метаданных.

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

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

```powershell
/xdto-decompile src/XDTOPackages/Обмен_1_0 -OutFile v2.xsd
# правка targetNamespace и содержимого в v2.xsd
/xdto-compile -XsdPath v2.xsd -OutputDir src -Name Обмен_2_0
```

Если же нужно сменить namespace **у существующего** пакета — `/xdto-edit -Operation
set-namespace`. Он перепишет все внутренние ссылки и перечислит пакеты, которые
импортируют старый namespace, но менять их не станет.

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

```powershell
/xdto-decompile src/XDTOPackages/ОбменСБанком -OutFile bank.xsd
```

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

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

Симптом «свойство возвращает что-то бесструктурное» почти всегда означает, что тип
не разрешился и стал `xs:anyType`:

```powershell
/xdto-validate src/XDTOPackages/ПодозрительныйПакет -Detailed
```

Платформа такие вещи не диагностирует: при импорте XML-схемы неразрешённый чужой тип
заменяется молча, пакет выглядит загруженным. Валидатор называет и симптом, и причину —
объявленный, но неиспользуемый `<import>`.

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

```
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` — применить

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

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