diff --git a/README.md b/README.md index 9383faf8..7ed82b36 100644 --- a/README.md +++ b/README.md @@ -70,6 +70,7 @@ python tools/cc-1c-skills/scripts/switch.py | Расширения (CFE) | 5 навыков `/cfe-*` | Создание, заимствование, перехват методов, валидация, анализ расширений | [Подробнее](docs/cfe-guide.md) | | Подсистемы (Subsystem) | 4 навыка `/subsystem-*` | Анализ, создание, редактирование, валидация подсистем конфигурации | [Подробнее](docs/subsystem-guide.md) | | Командный интерфейс (CI) | 2 навыка `/interface-*` | Редактирование и валидация CommandInterface.xml подсистем | [Подробнее](docs/subsystem-guide.md) | +| Пакеты XDTO | 5 навыков `/xdto-*` | Анализ, создание из XML-схемы, выгрузка в схему, точечное редактирование, валидация пакетов XDTO | [Подробнее](docs/xdto-guide.md) | | Базы данных (DB) | 9 навыков `/db-*` | Создание баз, загрузка/выгрузка конфигураций, обновление БД, загрузка из Git | [Подробнее](docs/db-guide.md) | | Веб-публикация (Web) | 4 навыка `/web-*` | Публикация баз через Apache, статус, остановка, удаление публикаций | [Подробнее](docs/web-guide.md) | | Тестирование (Web) | `/web-test` | Взаимодействие с веб-клиентом 1С — навигация, формы, таблицы, отчёты, тестирование | [Подробнее](docs/web-test-guide.md) | diff --git a/docs/xdto-guide.md b/docs/xdto-guide.md new file mode 100644 index 00000000..162fab14 --- /dev/null +++ b/docs/xdto-guide.md @@ -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:anyType`, и обнаружится это +только в рантайме. + +### Поправить существующий пакет + +Точечно — `/xdto-edit`, схему целиком читать не нужно: + +```powershell +/xdto-edit src/XDTOPackages/ОбменСБанком -Operation add-property -Target "ПлатежныйДокумент" ` + -Value '' +``` + +Многострочный фрагмент передавай файлом: `-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-схемы неразрешённый чужой тип +заменяется молча, пакет выглядит загруженным. Валидатор называет и симптом, и причину — +объявленный, но неиспользуемый ``. + +## Структура файлов + +``` +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)