mirror of
https://github.com/Nikolay-Shirokov/cc-1c-skills.git
synced 2026-07-27 07:01:02 +03:00
Nick ShirokovandClaude Opus 5
49d7204385
Из семейств гайды есть у cf, cfe, db, epf, form, meta, role, skd, web — у XDTO не было. Гайд построен вокруг задач, а не вокруг навыков: написать код заполнения, разобрать входящий XML, добавить пакет по схеме контрагента, поправить существующий, выпустить новую версию, отдать схему наружу, разобраться с «бесструктурным» свойством. Группа добавлена в таблицу README. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
159 lines
8.6 KiB
Markdown
159 lines
8.6 KiB
Markdown
# Работа с пакетами 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)
|