Auto-build: opencode (powershell) from f522d29

.opencode/skills/xdto-compile/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: xdto-compile
+description: Создание пакета XDTO 1С из XML-схемы (XSD). Используй когда нужно добавить в конфигурацию пакет XDTO — под обмен, интеграцию, веб-сервис или внешний XML-формат
+argument-hint: -XsdPath <файл.xsd>|-Xsd <схема> -OutputDir <каталог-исходников> [-Name <имя>] [-Synonym <синоним>] [-Comment <текст>] [-Force]
+allowed-tools:
+  - Bash
+  - Read
+  - Glob
+---
+
+# /xdto-compile — Создание пакета XDTO из XML-схемы
+
+Собирает пакет XDTO по XML-схеме: `XDTOPackages/<Имя>.xml`,
+`XDTOPackages/<Имя>/Ext/Package.bin` и регистрацию в `Configuration.xml`.
+
+Вход — обычная XML-схема, писать её нужно так же, как для любого другого инструмента.
+
+## Параметры
+
+| Параметр | Обязательный | Описание |
+|----------|--------------|----------|
+| `XsdPath` | один из двух | Путь к файлу XML-схемы. Псевдоним — `-Path` |
+| `Xsd` | один из двух | Схема строкой, вместо `-XsdPath` |
+| `OutputDir` | да | Каталог исходников конфигурации или расширения — там, где лежит `Configuration.xml` |
+| `Name` | нет | Имя объекта метаданных. По умолчанию — из `xs:appinfo`, иначе имя файла XSD, санированное под идентификатор 1С |
+| `Synonym` | нет | Синоним (строка). По умолчанию — из `xs:appinfo`, иначе имя пакета. Для нескольких языков задавай синоним в схеме, блоком `xs:appinfo` |
+| `Comment` | нет | Комментарий. По умолчанию — из `xs:appinfo` |
+| `Force` | нет | Перезаписать существующий пакет. Без него навык откажется затирать уже собранный пакет |
+
+```powershell
+powershell.exe -NoProfile -File ".opencode/skills/xdto-compile/scripts/xdto-compile.ps1" -XsdPath "<схема.xsd>" -OutputDir "<каталог-исходников>"
+```
+
+Примеры:
+```powershell
+... -XsdPath bank.xsd -OutputDir src -Name ОбменСБанком -Synonym "Обмен с банком"
+... -XsdPath fss.xsd  -OutputDir src -Force
+```
+
+## Читай предупреждения
+
+XSD выразительнее модели XDTO. Всё, что не переносится один в один, навык переносит
+приближённо и **пишет об этом**:
+
+```
+Предупреждения (2) — конструкции XSD без точного соответствия в модели XDTO:
+  ! Документ : вложенная xs:choice уплощена в последовательность — выбор одного из вариантов не сохранён
+  ! Документ : кратность на вложенной частице (<xs:sequence minOccurs/maxOccurs>) не выражается в модели XDTO
+```
+
+Такое сообщение означает, что пакет собран, но схема упрощена. Если упрощение
+недопустимо — меняй схему (например, разноси варианты `xs:choice` по разным типам),
+а не игнорируй.
+
+Что переносится приближённо: вложенные `xs:sequence`/`xs:choice` (уплощаются в плоский
+список свойств), `xs:all` (становится последовательностью), кратность на частице,
+`substitutionGroup`, `xs:key`/`keyref`/`unique`, `xs:redefine`.
+
+`xs:group` и `xs:attributeGroup` раскрываются по ссылке — их содержимое попадает в тип.
+`xs:include` игнорируется: зависимости в XDTO разрешаются только по namespace,
+поэтому включаемую схему нужно собрать отдельным пакетом и заменить `include` на `import`.
+
+## Посмотреть, что получилось
+
+Модель пакета лежит в `Ext/Package.bin`. Несмотря на расширение, это текстовый XML,
+но читать его напрямую обычно незачем: состав собранного пакета показывает
+`/xdto-info`, а полную схему — `/xdto-decompile`.
+
+## Зависимости между пакетами
+
+`<xs:import namespace="…"/>` разрешается по namespace среди пакетов конфигурации
+или расширения. Если пакета с таким пространством имён нет, платформа при загрузке
+молча подменит тип на `xs:anyType` — без ошибки. Собирай сначала зависимости, потом
+зависящий пакет, и проверяй результат через `/xdto-validate`.
+
+Какие пакеты уже собраны, видно в `ChildObjects` файла `Configuration.xml`.
+
+## Что XSD выразить не может
+
+Две вещи модель XDTO умеет, а XML Schema — нет: `nillable` у атрибута и `qualified`
+у отдельного свойства. Они пишутся атрибутами из пространства имён модели:
+
+```xml
+<xs:attribute name="Представление" type="xs:string"
+              xmlns:xdto="http://v8.1c.ru/8.1/xdto" xdto:nillable="true"/>
+```
+
+Схема остаётся валидной — валидаторы такие атрибуты игнорируют. Полный список
+и таблица соответствий XSD ↔ XDTO — в [xsd-reference.md](xsd-reference.md).
+
+Свойства объекта метаданных можно задать прямо в схеме:
+
+```xml
+<xs:annotation>
+    <xs:appinfo>
+        <xdto:package xmlns:xdto="http://v8.1c.ru/8.1/xdto">
+            <xdto:name>ОбменСБанком</xdto:name>
+            <xdto:synonym lang="ru">Обмен с банком</xdto:synonym>
+        </xdto:package>
+    </xs:appinfo>
+</xs:annotation>
+```
+
+## Типичный workflow
+
+1. Получить XSD от контрагента (или выгрузить схему существующего пакета: `/xdto-decompile`)
+2. `/xdto-compile -XsdPath <файл> -OutputDir <каталог-исходников>` — прочитать предупреждения
+3. `/xdto-validate <каталог-исходников>/XDTOPackages/<Имя>` — убедиться, что типы разрешились
+4. `/db-load-xml` + `/db-update`
+
+Правка существующего пакета: точечно — `/xdto-edit`; переработать схему целиком —
+`/xdto-decompile` → правка XSD → `/xdto-compile -Force`.

.opencode/skills/xdto-compile/xsd-reference.md

@@ -0,0 +1,88 @@
+# XSD ↔ XDTO — справочник
+
+## Соответствия
+
+| XML Schema | Модель XDTO |
+|---|---|
+| `xs:schema/@targetNamespace` | пространство имён пакета |
+| `elementFormDefault` / `attributeFormDefault` | `elementFormQualified` / `attributeFormQualified` |
+| `xs:import/@namespace` | зависимость от другого пакета (разрешается по namespace) |
+| `xs:complexType` | объектный тип |
+| `xs:simpleType` | тип значения |
+| `xs:element` / `xs:attribute` на верхнем уровне | глобальное свойство пакета |
+| `xs:element` / `xs:attribute` внутри типа | свойство типа |
+| `@minOccurs` / `@maxOccurs="unbounded"` | `lowerBound` / `upperBound="-1"` |
+| `@nillable`, `@default`, `@fixed`, `@ref` | те же по смыслу |
+| анонимный `xs:simpleType`/`xs:complexType` в объявлении | встроенный тип свойства |
+| `xs:complexContent/xs:extension/@base` | наследование типа |
+| `@abstract`, `@mixed` | те же |
+| `xs:choice` | тип-выбор одного из вариантов |
+| `xs:any` + `xs:anyAttribute` | открытый тип |
+| `xs:simpleContent/xs:extension/@base` | свойство собственного значения элемента |
+| `xs:restriction` + фасеты | базовый тип + ограничения |
+| `xs:pattern`, `xs:enumeration` | те же |
+| `xs:list/@itemType` | список |
+| `xs:union/@memberTypes` | объединение |
+
+Порядок объявлений верхнего уровня в XSD произвольный — навык сам расставит их
+в порядке, который требует модель.
+
+## Аннотации `xdto:`
+
+Пространство имён — `http://v8.1c.ru/8.1/xdto`. Нужны только там, где XML Schema
+не может выразить то, что умеет модель. В большинстве схем не нужны вовсе.
+
+Правило: **чего XSD сказать не может — пиши атрибутом `xdto:` с тем же именем,
+что и в модели**.
+
+| Аннотация | Где | Назначение |
+|---|---|---|
+| `xdto:nillable` | `xs:attribute` | `nillable` у свойства-атрибута (XSD допускает только у элементов) |
+| `xdto:lowerBound`, `xdto:upperBound` | `xs:attribute` | кратность свойства-атрибута |
+| `xdto:qualified` | объявление | переопределение `*FormQualified` для одного свойства |
+| `xdto:name` | объявление | имя свойства, если XML-имя не годится как идентификатор 1С; XML-имя уйдёт в `localName` |
+| `xdto:form` | `xs:element` | записать `form` явно |
+| `xdto:variety` | `xs:restriction`, `xs:list`, `xs:union` | записать разновидность типа явно |
+| `xdto:open`, `xdto:abstract`, `xdto:mixed`, `xdto:ordered`, `xdto:sequenced` | `xs:complexType` | флаги типа, не выводимые из модели содержимого |
+| `xdto:order` | `xs:complexType` | исходный порядок свойств, если он не «атрибуты первыми»; имена через `\|` |
+| `xdto:textName`, `xdto:textlowerBound`, `xdto:textupperBound`, `xdto:textnillable` | `xs:extension` в `xs:simpleContent` | параметры свойства собственного значения |
+| `xdto:type` | `xs:enumeration` | тип литерала перечисления |
+| `xdto:prefix` | объявление | осмысленный префикс пространства имён вместо генерируемого |
+| `xdto:memberTypesForm="prefixed"` | `xs:union` | записать состав объединения префиксами, а не `{ns}имя` |
+| `xdto:declareNs` | `xs:union` | объявить префикс пространства имён на узле |
+| `xdto:elementFormQualified`, `xdto:attributeFormQualified` | `xs:schema` | записать флаги явно |
+
+Пример:
+
+```xml
+<xs:complexType name="КонтактнаяИнформация" xdto:sequenced="true">
+    <xs:sequence>
+        <xs:element name="Комментарий" type="xs:string" minOccurs="0"/>
+        <xs:element name="Адрес по документу" type="xs:string"
+                    xdto:name="Адрес_по_документу" minOccurs="0"/>
+    </xs:sequence>
+    <xs:attribute name="Представление" type="xs:string"
+                  xdto:nillable="true" xdto:lowerBound="0"/>
+</xs:complexType>
+```
+
+Аннотации, которые проставляет `/xdto-decompile` при выгрузке существующего пакета,
+писать вручную не нужно — они нужны, чтобы обратная сборка вернула ровно тот же файл.
+
+## Свойства объекта метаданных
+
+```xml
+<xs:annotation>
+    <xs:appinfo>
+        <xdto:package xmlns:xdto="http://v8.1c.ru/8.1/xdto">
+            <xdto:name>ОбменСБанком</xdto:name>
+            <xdto:synonym lang="ru">Обмен с банком</xdto:synonym>
+            <xdto:synonym lang="en">Bank exchange</xdto:synonym>
+            <xdto:comment>Формат 1С:Предприятие — Клиент банка</xdto:comment>
+        </xdto:package>
+    </xs:appinfo>
+</xs:annotation>
+```
+
+Пространство имён пакета берётся из `targetNamespace` и здесь не дублируется.
+Параметры `-Name`, `-Synonym`, `-Comment` имеют приоритет над этим блоком.