diff --git a/docs/xdto-guide.md b/docs/xdto-guide.md index 58eebf96..4ce8193b 100644 --- a/docs/xdto-guide.md +++ b/docs/xdto-guide.md @@ -8,6 +8,12 @@ Навыки вызываются агентом сами — задачу можно ставить обычными словами. Ниже примеры формулировок и того, что за ними происходит. +**Что стоит назвать в задаче.** Формулировка может быть сколь угодно общей, но +объект работы лучше назвать: каталог исходников конфигурации, имя пакета (а для +точечной правки — и типа), путь к файлу схемы. Чего не назвали — про то агент +спросит, прежде чем что-то делать: «добавь схему от контрагента» без пути к файлу +он не угадает, а искать по всему диску не станет. + ## Навыки | Навык | Задача | @@ -23,11 +29,20 @@ ## Сценарии +### Разобраться, что есть в незнакомой конфигурации + +> «Какие пакеты XDTO есть в конфигурации `src`?» +> +> «Что внутри пакета `ОбменСБанком` — какие типы и с чего начинать чтение?» + +Обычный первый шаг, когда формат чужой или давно не открывался. Список пакетов +показывает имя, пространство имён и число типов; обзор пакета — типы и точки входа. + ### Написать код, который заполняет объект XDTO -> «Сформируй платёжное поручение в формате клиент-банка и выгрузи в файл» +> «Сформируй платёжное поручение по пакету `ОбменСБанком` и запиши в `out.xml`» > -> «Напиши обработку выгрузки заказов по нашему обмену с маркетплейсом» +> «Напиши обработку выгрузки заказов по пакету `ОбменМаркетплейс`, начни с типа `Заказ`» Самая частая задача, и обычно она часть большей. Прежде чем писать код, агент смотрит структуру типа: какой тип значения присваивать каждому свойству, что @@ -40,18 +55,18 @@ ### Разобрать входящий XML -> «Разбери входящий файл ЕГАИС и создай по нему документы» +> «Разбери `in/egais-ttn.xml` по пакету `ЕГАИС3` — с какого типа начинать?» > -> «Какому типу соответствует корень этого XML?» +> «Какие точки входа у пакета `ЕГАИС3`?» Чтобы прочитать документ, надо знать, с какого типа начинать. Это **точки входа** пакета — его глобальные объявления; агент покажет их вместе со списком типов. ### Добавить пакет по схеме контрагента -> «Контрагент прислал схему обмена заказами, добавь её в конфигурацию» +> «Контрагент прислал `schemas/orders.xsd` — добавь пакет в конфигурацию, исходники в `src`» > -> «Нужен пакет XDTO по вот этой XSD от ФСС» +> «Собери пакет по `schemas/fss-person.xsd`, имя `FSS_Person_01`» Пакет собирается по схеме и сразу регистрируется в конфигурации. @@ -62,14 +77,16 @@ схему надо менять, а не игнорировать сообщение. Если схема ссылается на чужое пространство имён через ``, сначала нужен -пакет-зависимость. Иначе платформа откажется принимать конфигурацию либо молча -подменит тип на «произвольный», и всплывёт это уже в рантайме. +пакет-зависимость: платформа отвергнет конфигурацию, где импортируемого пакета нет. +Об этом скажут ещё на сборке — чинить дешевле там, чем на `/db-update`. Исключение — +пространства имён самой платформы (`http://www.w3.org/2001/XMLSchema`, +`http://v8.1c.ru/8.1/data/core` и подобные): их пакетами объявлять не нужно. ### Поправить существующий пакет > «Добавь в платёжное поручение необязательный комментарий, не длиннее 200 символов» > -> «Убери из обмена устаревшее поле СтарыйКод» +> «Убери свойство `СтарыйКод` у типа `Документ` в пакете `Обмен`» > > «Добавь в перечисление видов документов значение Инкассо» @@ -77,16 +94,22 @@ `EnterpriseData` это единственный практичный путь. После правки автоматически запускается проверка. -Перед изменением существующего типа полезно узнать, кого оно затронет: агент -покажет, какие типы и пакеты на него ссылаются. +Перед изменением существующего типа полезно узнать, кого оно затронет: + +> «Кто ссылается на тип `Адрес` из пакета `КонтактнаяИнформация`?» + +Ответ — список типов и пакетов, включая те, что ссылаются через границу пакета. Если переработка широкая — «перепиши обмен под новую версию формата» — схема выгружается целиком, правится и собирается обратно. Пара выгрузка-сборка -замыкается без потерь, включая имя, синоним и комментарий объекта метаданных. +замыкается без потерь, включая имя, синоним и комментарий объекта метаданных: +проверено на 760 пакетах типовых конфигураций — сборка даёт исходный файл модели +побайтово. ### Новая версия пакета -> «Сделай версию 2.0 нашего обмена, старая должна продолжать работать» +> «Сделай из пакета `Обмен` версию 2: новый пакет `ОбменV2` с namespace `urn:…:v2`, +> старый не трогай» Типовой приём: рядом со старым пакетом появляется новый с другим пространством имён (`EnterpriseData_1_19` → `_1_20`), а старые потребители продолжают смотреть @@ -98,16 +121,30 @@ ### Отдать схему контрагенту -> «Выгрузи схему нашего обмена, отправлю партнёру» +> «Выгрузи схему пакета `Обмен` в `schemas/exchange.xsd`, отправлю партнёру» Получается валидная XSD, ничего не теряющая. Штатный «Экспорт XML-схемы» -в Конфигураторе для этого хуже: он теряет признак `nillable` у свойств-атрибутов. +в Конфигураторе для этого хуже: он теряет признак `nillable` у свойств-атрибутов, +а для пакетов с неквалифицированной формой элементов выдаёт XSD, которую строгий +валидатор не принимает. + +### Проверить перед загрузкой в базу + +> «Проверь пакет `Обмен` перед загрузкой в базу» +> +> «Я правил `Package.bin` руками — проверь, что платформа его примет» + +Проверка ловит то, на чём `/db-update` отказывается принимать конфигурацию: +импорт пакета, которого в конфигурации нет; ссылку на несуществующий тип или +необъявленный префикс; нарушенный порядок элементов верхнего уровня; расхождение +объекта метаданных с моделью; отсутствие пакета в `Configuration.xml`. Дешевле +поймать здесь, чем в отказе загрузки. После правки через `/xdto-edit` проверка +запускается сама. ### Разобраться, почему обмен ведёт себя странно -> «Обращение к Смена.Сотрудник возвращает что-то бесструктурное, разберись» -> -> «Пакет вроде загрузился, а обмен не работает» +> «Пакет `ФСС` загрузился, но обращение к `Смена.Сотрудник` возвращает +> что-то бесструктурное — разберись» Такой симптом почти всегда означает, что тип не разрешился и стал «произвольным». Платформа об этом молчит: при импорте XML-схемы неразрешённый чужой тип заменяется