mirror of
https://github.com/Nikolay-Shirokov/cc-1c-skills.git
synced 2026-07-27 07:01:02 +03:00
docs(xdto): пользовательский гайд и группа в README
Из семейств гайды есть у cf, cfe, db, epf, form, meta, role, skd, web — у XDTO не было. Гайд построен вокруг задач, а не вокруг навыков: написать код заполнения, разобрать входящий XML, добавить пакет по схеме контрагента, поправить существующий, выпустить новую версию, отдать схему наружу, разобраться с «бесструктурным» свойством. Группа добавлена в таблицу README. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Nick Shirokov
co-authored by
Claude Opus 5
Claude Opus 5
parent
5fd952a796
commit
49d7204385
@@ -0,0 +1,158 @@
|
||||
# Работа с пакетами 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)
|
||||
Reference in New Issue
Block a user