mirror of
https://github.com/Nikolay-Shirokov/cc-1c-skills.git
synced 2026-07-27 07:01:02 +03:00
Nick ShirokovandClaude Opus 5
05856abe25
Предыдущая правка гайда изложила копирование пакета пошагово в повелительном наклонении, и стало неясно, кому эти шаги адресованы: гайд построен на том, что задачу ставят словами, а шаги делает агент. Пользователь мог прочитать это как работу, которую надо сделать самому. В гайде теперь сказано, что происходит и чего достаточно назвать в задаче. Сами шаги и острая кромка (менять targetNamespace вместе с объявлением xmlns, не заменять все вхождения строки) — в SKILL.md навыка выгрузки, там же, где описан путь «выгрузить → поправить → собрать». Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
186 lines
13 KiB
Markdown
186 lines
13 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.
|
||
|
||
Отдельной команды для этого нет: агент выгружает схему исходного пакета, меняет в ней
|
||
пространство имён и собирает под новым именем. Дополнительных действий это не требует —
|
||
достаточно назвать в задаче исходный пакет, новое имя и новый namespace. Внутренние
|
||
ссылки переводятся на него целиком, импорты чужих пакетов сохраняются, исходный пакет
|
||
остаётся как был.
|
||
|
||
Если же надо сменить 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)
|