From 20d86ae10fc188b5b19e0c001a1a95c3ff86b5a0 Mon Sep 17 00:00:00 2001 From: Nick Shirokov Date: Sun, 26 Jul 2026 15:48:29 +0300 Subject: [PATCH] =?UTF-8?q?docs(xdto-guide):=20=D0=BF=D1=80=D0=B8=D0=BC?= =?UTF-8?q?=D0=B5=D1=80=D1=8B=20=D1=81=20=D0=BD=D0=B0=D0=B7=D0=B2=D0=B0?= =?UTF-8?q?=D0=BD=D0=BD=D1=8B=D0=BC=20=D0=BE=D0=B1=D1=8A=D0=B5=D0=BA=D1=82?= =?UTF-8?q?=D0=BE=D0=BC=20=D1=80=D0=B0=D0=B1=D0=BE=D1=82=D1=8B,=20=D1=82?= =?UTF-8?q?=D1=80=D0=B8=20=D0=BD=D0=BE=D0=B2=D1=8B=D1=85=20=D1=81=D1=86?= =?UTF-8?q?=D0=B5=D0=BD=D0=B0=D1=80=D0=B8=D1=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Формулировка задачи может быть общей, но объект работы нужно назвать: без пути к файлу или имени пакета агент останавливается и просит уточнений вместо работы. Проверено прогоном триггеров: тот же запрос без якоря и с якорем даёт разный исход. Отсюда абзац «что стоит назвать в задаче» и переформулировка примеров, где объект не назывался. Сняты два неудачных примера: «создай по нему документы» (вторая половина не про XDTO) и симптом без якоря, дублирующий соседний сильный пример. Добавлены сценарии, которых не было: инвентаризация незнакомой конфигурации, обратные ссылки перед правкой (в прозе упоминались, примера не было) и проверка перед загрузкой — у навыка проверки не было ни одного примера. Уточнения по тексту: - импорт пространств имён самой платформы пакетами объявлять не нужно; - штатный экспорт XML-схемы даёт невалидную XSD и для неквалифицированной формы элементов, не только теряет nillable; - обещание round-trip подкреплено измерением на корпусе. Co-Authored-By: Claude Opus 5 (1M context) --- docs/xdto-guide.md | 73 ++++++++++++++++++++++++++++++++++------------ 1 file changed, 55 insertions(+), 18 deletions(-) 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-схемы неразрешённый чужой тип заменяется