diff --git a/docs/xdto-guide.md b/docs/xdto-guide.md index 162fab14..58eebf96 100644 --- a/docs/xdto-guide.md +++ b/docs/xdto-guide.md @@ -5,6 +5,9 @@ Встречается везде, где 1С обменивается данными наружу: ЭДО, ЕГАИС, ВЕТИС, ФСС, клиент-банк, веб-сервисы, `EnterpriseData`. +Навыки вызываются агентом сами — задачу можно ставить обычными словами. Ниже +примеры формулировок и того, что за ними происходит. + ## Навыки | Навык | Задача | @@ -22,115 +25,94 @@ ### Написать код, который заполняет объект 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` по корню исходников найдёт его -по всем пакетам конфигурации. +Выводится это уже в терминах 1С — `Строка(6)`, `Число(18,2)`, `[обязательный]`, — +поэтому переводить `xs:decimal` и `lowerBound="0"` в голове не приходится. +Если тип большой, помогает срез только обязательных свойств: получается готовый +скелет заполнения. ### Разобрать входящий XML -Нужно понять, какому типу соответствует корень документа. Это **точки входа** — -глобальные объявления пакета: +> «Разбери входящий файл ЕГАИС и создай по нему документы» +> +> «Какому типу соответствует корень этого XML?» -```powershell -/xdto-info src -Namespace "urn:partner:orders" -``` - -Дальше по имени типа — состав свойств, как в предыдущем сценарии. +Чтобы прочитать документ, надо знать, с какого типа начинать. Это **точки входа** +пакета — его глобальные объявления; агент покажет их вместе со списком типов. ### Добавить пакет по схеме контрагента -```powershell -/xdto-compile -XsdPath partner.xsd -OutputDir src -Name ЗаказыКонтрагента -/xdto-validate src/XDTOPackages/ЗаказыКонтрагента -``` +> «Контрагент прислал схему обмена заказами, добавь её в конфигурацию» +> +> «Нужен пакет XDTO по вот этой XSD от ФСС» -**Читай предупреждения компилятора.** XML Schema выразительнее модели XDTO, и часть -конструкций переносится приближённо: вложенные `xs:choice` уплощаются, `xs:all` -становится последовательностью, кратность на частице отбрасывается. Навык печатает, -что именно упростилось; если упрощение недопустимо — меняй схему, а не игнорируй. +Пакет собирается по схеме и сразу регистрируется в конфигурации. -Схема ссылается на чужой namespace через `` — сначала собери пакет-зависимость. -Иначе платформа при загрузке молча подменит тип на `xs:anyType`, и обнаружится это -только в рантайме. +**Обрати внимание на предупреждения.** XML Schema выразительнее модели XDTO, и часть +конструкций переносится приближённо: вложенный `xs:choice` уплощается (ветки при этом +становятся необязательными), `xs:all` превращается в последовательность, кратность +на частице отбрасывается. Агент об этом сообщит — если упрощение недопустимо, +схему надо менять, а не игнорировать сообщение. + +Если схема ссылается на чужое пространство имён через ``, сначала нужен +пакет-зависимость. Иначе платформа откажется принимать конфигурацию либо молча +подменит тип на «произвольный», и всплывёт это уже в рантайме. ### Поправить существующий пакет -Точечно — `/xdto-edit`, схему целиком читать не нужно: +> «Добавь в платёжное поручение необязательный комментарий, не длиннее 200 символов» +> +> «Убери из обмена устаревшее поле СтарыйКод» +> +> «Добавь в перечисление видов документов значение Инкассо» -```powershell -/xdto-edit src/XDTOPackages/ОбменСБанком -Operation add-property -Target "ПлатежныйДокумент" ` - -Value '' -``` +Точечная правка не требует читать схему целиком — для больших пакетов вроде +`EnterpriseData` это единственный практичный путь. После правки автоматически +запускается проверка. -Многострочный фрагмент передавай файлом: `-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. +> «Сделай версию 2.0 нашего обмена, старая должна продолжать работать» -```powershell -/xdto-decompile src/XDTOPackages/Обмен_1_0 -OutFile v2.xsd -# правка targetNamespace и содержимого в v2.xsd -/xdto-compile -XsdPath v2.xsd -OutputDir src -Name Обмен_2_0 -``` +Типовой приём: рядом со старым пакетом появляется новый с другим пространством +имён (`EnterpriseData_1_19` → `_1_20`), а старые потребители продолжают смотреть +на прежний namespace. -Если же нужно сменить namespace **у существующего** пакета — `/xdto-edit -Operation -set-namespace`. Он перепишет все внутренние ссылки и перечислит пакеты, которые -импортируют старый namespace, но менять их не станет. +Если же надо сменить namespace **у существующего** пакета, агент перепишет все +внутренние ссылки и перечислит пакеты, которые импортируют старый — но менять +их не станет, потому что при версионировании это было бы ошибкой. ### Отдать схему контрагенту -```powershell -/xdto-decompile src/XDTOPackages/ОбменСБанком -OutFile bank.xsd -``` +> «Выгрузи схему нашего обмена, отправлю партнёру» -Схема валидна и ничего не теряет. Штатный «Экспорт XML-схемы» в Конфигураторе для -этого хуже: он теряет `nillable` у свойств-атрибутов. +Получается валидная XSD, ничего не теряющая. Штатный «Экспорт XML-схемы» +в Конфигураторе для этого хуже: он теряет признак `nillable` у свойств-атрибутов. ### Разобраться, почему обмен ведёт себя странно -Симптом «свойство возвращает что-то бесструктурное» почти всегда означает, что тип -не разрешился и стал `xs:anyType`: +> «Обращение к Смена.Сотрудник возвращает что-то бесструктурное, разберись» +> +> «Пакет вроде загрузился, а обмен не работает» -```powershell -/xdto-validate src/XDTOPackages/ПодозрительныйПакет -Detailed -``` - -Платформа такие вещи не диагностирует: при импорте XML-схемы неразрешённый чужой тип -заменяется молча, пакет выглядит загруженным. Валидатор называет и симптом, и причину — -объявленный, но неиспользуемый ``. +Такой симптом почти всегда означает, что тип не разрешился и стал «произвольным». +Платформа об этом молчит: при импорте XML-схемы неразрешённый чужой тип заменяется +без единой ошибки, пакет выглядит загруженным. Проверка называет и симптом, +и причину — объявленный, но неиспользуемый импорт. ## Структура файлов @@ -146,10 +128,12 @@ XDTOPackages/ ## Рабочий цикл -1. `/xdto-info` — понять, что есть -2. `/xdto-compile` или `/xdto-edit` — изменить -3. `/xdto-validate` — проверить до загрузки -4. `/db-load-xml` + `/db-update` — применить +1. Посмотреть, что есть — `/xdto-info` +2. Изменить — `/xdto-compile` или `/xdto-edit` +3. Проверить до загрузки — `/xdto-validate` +4. Применить — `/db-load-xml` + `/db-update` + +Точный синтаксис параметров каждого навыка — в его `SKILL.md` по ссылкам выше. ## Спецификации