mirror of
https://github.com/Nikolay-Shirokov/cc-1c-skills.git
synced 2026-07-27 07:01:02 +03:00
Nick ShirokovandClaude Opus 5
32455a64b1
Раздел «Новая версия пакета» описывал, что получается, но не как это сделать, и из-за этого выглядел местом, требующим отдельного флага компилятора. Рутины там на самом деле немного: выгрузить схему, поменять в шапке targetNamespace и связанное объявление xmlns, собрать под новым именем — имя и синоним задаются флагами, править их внутри схемы не нужно. Названа острая кромка: заменять все вхождения URI строкой нельзя — пострадает импорт пространства имён, для которого старый URI является префиксом. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
193 lines
14 KiB
Markdown
193 lines
14 KiB
Markdown
# Работа с пакетами 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 есть в конфигурации `src`?»
|
||
>
|
||
> «Что внутри пакета `ОбменСБанком` — какие типы и с чего начинать чтение?»
|
||
|
||
Обычный первый шаг, когда формат чужой или давно не открывался. Список пакетов
|
||
показывает имя, пространство имён и число типов; обзор пакета — типы и точки входа.
|
||
|
||
### Написать код, который заполняет объект XDTO
|
||
|
||
> «Сформируй платёжное поручение по пакету `ОбменСБанком` и запиши в `out.xml`»
|
||
>
|
||
> «Напиши обработку выгрузки заказов по пакету `ОбменМаркетплейс`, начни с типа `Заказ`»
|
||
|
||
Самая частая задача, и обычно она часть большей. Прежде чем писать код, агент
|
||
смотрит структуру типа: какой тип значения присваивать каждому свойству, что
|
||
обязательно, где нужно создать вложенный объект, какие значения допустимы.
|
||
|
||
Выводится это уже в терминах 1С — `Строка(6)`, `Число(18,2)`, `[обязательный]`, —
|
||
поэтому переводить `xs:decimal` и `lowerBound="0"` в голове не приходится.
|
||
Если тип большой, помогает срез только обязательных свойств: получается готовый
|
||
скелет заполнения.
|
||
|
||
### Разобрать входящий XML
|
||
|
||
> «Разбери `in/egais-ttn.xml` по пакету `ЕГАИС3` — с какого типа начинать?»
|
||
>
|
||
> «Какие точки входа у пакета `ЕГАИС3`?»
|
||
|
||
Чтобы прочитать документ, надо знать, с какого типа начинать. Это **точки входа**
|
||
пакета — его глобальные объявления; агент покажет их вместе со списком типов.
|
||
|
||
### Добавить пакет по схеме контрагента
|
||
|
||
> «Контрагент прислал `schemas/orders.xsd` — добавь пакет в конфигурацию, исходники в `src`»
|
||
>
|
||
> «Собери пакет по `schemas/fss-person.xsd`, имя `FSS_Person_01`»
|
||
|
||
Пакет собирается по схеме и сразу регистрируется в конфигурации.
|
||
|
||
**Обрати внимание на предупреждения.** XML Schema выразительнее модели XDTO, и часть
|
||
конструкций переносится приближённо: вложенный `xs:choice` уплощается (ветки при этом
|
||
становятся необязательными), `xs:all` превращается в последовательность, кратность
|
||
на частице отбрасывается. Агент об этом сообщит — если упрощение недопустимо,
|
||
схему надо менять, а не игнорировать сообщение.
|
||
|
||
Если схема ссылается на чужое пространство имён через `<xs:import>`, сначала нужен
|
||
пакет-зависимость: платформа отвергнет конфигурацию, где импортируемого пакета нет.
|
||
Об этом скажут ещё на сборке — чинить дешевле там, чем на `/db-update`. Исключение —
|
||
пространства имён самой платформы (`http://www.w3.org/2001/XMLSchema`,
|
||
`http://v8.1c.ru/8.1/data/core` и подобные): их пакетами объявлять не нужно.
|
||
|
||
### Поправить существующий пакет
|
||
|
||
> «Добавь в платёжное поручение необязательный комментарий, не длиннее 200 символов»
|
||
>
|
||
> «Убери свойство `СтарыйКод` у типа `Документ` в пакете `Обмен`»
|
||
>
|
||
> «Добавь в перечисление видов документов значение Инкассо»
|
||
|
||
Точечная правка не требует читать схему целиком — для больших пакетов вроде
|
||
`EnterpriseData` это единственный практичный путь. После правки автоматически
|
||
запускается проверка.
|
||
|
||
Перед изменением существующего типа полезно узнать, кого оно затронет:
|
||
|
||
> «Кто ссылается на тип `Адрес` из пакета `КонтактнаяИнформация`?»
|
||
|
||
Ответ — список типов и пакетов, включая те, что ссылаются через границу пакета.
|
||
|
||
Если переработка широкая — «перепиши обмен под новую версию формата» — схема
|
||
выгружается целиком, правится и собирается обратно. Пара выгрузка-сборка
|
||
замыкается без потерь, включая имя, синоним и комментарий объекта метаданных:
|
||
проверено на 760 пакетах типовых конфигураций — сборка даёт исходный файл модели
|
||
побайтово.
|
||
|
||
### Новая версия пакета
|
||
|
||
> «Сделай из пакета `Обмен` версию 2: новый пакет `ОбменV2` с namespace `urn:…:v2`,
|
||
> старый не трогай»
|
||
|
||
Типовой приём: рядом со старым пакетом появляется новый с другим пространством
|
||
имён (`EnterpriseData_1_19` → `_1_20`), а старые потребители продолжают смотреть
|
||
на прежний namespace. Копия делается через выгрузку схемы и сборку под новым именем:
|
||
|
||
1. `/xdto-decompile` исходного пакета в файл схемы;
|
||
2. в схеме поменять `targetNamespace` — **и связанное с ним объявление `xmlns`**,
|
||
которым внутренние ссылки пользуются как префиксом;
|
||
3. `/xdto-compile` этой схемы с `-Name` нового пакета (имя и синоним задаются
|
||
флагами, править их внутри схемы не нужно).
|
||
|
||
Внутренние ссылки при этом переводятся на новый namespace целиком, импорты чужих
|
||
пакетов сохраняются, исходный пакет не меняется.
|
||
|
||
Менять `targetNamespace` **заменой всех вхождений строки** — плохая идея: если пакет
|
||
импортирует пространство имён, у которого старый URI является префиксом
|
||
(`urn:example:exchange` и `urn:example:exchange:legacy`), заменится и оно.
|
||
|
||
Если же надо сменить namespace **у существующего** пакета, а не сделать копию, агент
|
||
перепишет все внутренние ссылки и перечислит пакеты, которые импортируют старый — но
|
||
менять их не станет, потому что при версионировании это было бы ошибкой.
|
||
|
||
### Отдать схему контрагенту
|
||
|
||
> «Выгрузи схему пакета `Обмен` в `schemas/exchange.xsd`, отправлю партнёру»
|
||
|
||
Получается валидная XSD, ничего не теряющая. Штатный «Экспорт XML-схемы»
|
||
в Конфигураторе для этого хуже: он теряет признак `nillable` у свойств-атрибутов,
|
||
а для пакетов с неквалифицированной формой элементов выдаёт XSD, которую строгий
|
||
валидатор не принимает.
|
||
|
||
### Проверить перед загрузкой в базу
|
||
|
||
> «Проверь пакет `Обмен` перед загрузкой в базу»
|
||
>
|
||
> «Я правил `Package.bin` руками — проверь, что платформа его примет»
|
||
|
||
Проверка ловит то, на чём `/db-update` отказывается принимать конфигурацию:
|
||
импорт пакета, которого в конфигурации нет; ссылку на несуществующий тип или
|
||
необъявленный префикс; нарушенный порядок элементов верхнего уровня; расхождение
|
||
объекта метаданных с моделью; отсутствие пакета в `Configuration.xml`. Дешевле
|
||
поймать здесь, чем в отказе загрузки. После правки через `/xdto-edit` проверка
|
||
запускается сама.
|
||
|
||
### Разобраться, почему обмен ведёт себя странно
|
||
|
||
> «Пакет `ФСС` загрузился, но обращение к `Смена.Сотрудник` возвращает
|
||
> что-то бесструктурное — разберись»
|
||
|
||
Такой симптом почти всегда означает, что тип не разрешился и стал «произвольным».
|
||
Платформа об этом молчит: при импорте 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`
|
||
|
||
Точный синтаксис параметров каждого навыка — в его `SKILL.md` по ссылкам выше.
|
||
|
||
## Спецификации
|
||
|
||
- Формат исходников — [1c-xdto-spec.md](1c-xdto-spec.md)
|
||
- XML Schema как формат описания, таблица соответствий и аннотации `xdto:` —
|
||
[xdto-dsl-spec.md](xdto-dsl-spec.md)
|