Kd31 Rules

---
name: kd31-rules
description: >
  Программная работа с "Конвертация данных, редакция 3.1" (КД 3.1) через
  MCP-toolkit (HTTP API) к живой ИБ: инспекция и создание Конвертаций, ПКО, ПКС,
  ПКПД, ПОД, теневой модели метаданных (Конфигурации/Объекты/Свойства/Релизы) и
  слоя формата EnterpriseData (ВерсииФормата/ОбъектыФормата); расширение формата
  ED с собственным namespace; генерация модуля менеджера обмена и выгрузка XSD
  штатными обработками КД 3.1; перенос артефактов в расширение конфигурации.
  Содержит схему данных, BSL-шаблоны для execute_code,
  ограничения toolkit. Триггеры: "КД 3.1", "конвертация данных 3.1", "правила обмена
  EnterpriseData", "настроить ПКО ПКС ПКПД ПОД", "расширение формата ED", "модуль
  менеджера обмена", "обмен через универсальный формат", "подключить конфигурацию
  к КД". English: "1C Data Conversion 3.1", "KD 3.1", "EnterpriseData exchange
  rules", "conversion manager module".
---

# KD 3.1 - правила обмена EnterpriseData через MCP-toolkit

Скилл описывает работу с живой ИБ "Конвертация данных, редакция 3.1" (КД 3.1)
через `MCP-toolkit` HTTP API: исследование структуры правил, создание/правка
правил, настройка формата и получение артефактов для расширения формата
EnterpriseData - **модуля менеджера обмена** (общий модуль BSL) и **XDTO-пакета
расширения / версии формата** (XSD).

Относится к сборке КД 3.1.6.14 (платформа 8.5.1.1302).

## Модель данных: КД 3.1 близка к КД 2.0 + слой формата

В этой сборке КД 3.1 по структуре похожа на КД 2.0:
- Теневая модель метаданных: `Релизы` (версия загруженной структуры) -> `Объекты`
  (Владелец=Релизы) -> `Свойства`/`Значения` (Владелец=Объекты). `Конфигурации` -
  топ-контейнер, на который ссылаются Релизы (версии живут в Релизах).
- Правила в справочниках: `ПравилаКонвертацииОбъектов` (ПКО),
  `ПравилаКонвертацииСвойств` (ПКС, Владелец=ПКО - **это справочник**, не регистр),
  `ПравилаКонвертацииПредопределенныхДанных` (ПКПД), `ПравилаОбработкиДанных` (ПОД),
  `ПравилаРегистрацииОбъектов` (ПРО, Владелец=Регистрации). ПКО/ПОД/ПКПД -
  **топ-уровневые** (без Владельца), связь с конвертацией - через `СоставыКонвертаций`.
  ВАЖНО: у ПКО **нет реквизита Наименование** (идентификатор в Коде, искать НайтиПоКоду)
  и ПКО **НЕ иерархичен** (нет ЭтоГруппа); ПКС иерархичен. Паттерн заполнения - **2 ПКО
  на объект** (`<Объект>_Отправка` + `<Объект>_Получение`), эталон в демо. См. bsl-templates.md.
- Дополнительно - слой формата EnterpriseData (цепочка справочников):
  `ВерсииФормата` (`ПространствоИмен`, признак расширения) -> `ОбъектыФормата`
  (Владелец=ВерсииФормата) -> `СвойстваФормата` -> `ЗначенияФормата`; типы - `ТипыФормата`.

Отличие результата от КД 2.0: КД 3.1 генерирует **модуль менеджера обмена** (BSL)
для движка `ОбменДаннымиXDTO` плюс работает с **XDTO-пакетом/версией формата**, а
не выгружает XML-правила для "Универсального обмена". Для КД 2.0 - скилл `kd2-rules`.

## Архитектура работы

```
Claude (агент)  --Bash+curl (payload через jq/python в файл)-->  MCP-toolkit (КД 3.1, СЕРВЕРНЫЙ контекст)
   -> справочники Конвертации/ПКО/ПКС/ПКПД/ПОД + теневая модель + слой формата
   -> штатные обработки (ЗагрузкаСтруктурыКонфигурацииИзФайловXML, НастройкаПравилОбмена, ВыгрузкаМодуля)
   -> артефакты: CommonModule (менеджер обмена) + XDTOPackage/XSD расширения
   -> перенос в расширение конфигурации-приемника (например УНФ)
```

Эндпоинты toolkit (порт по умолчанию 6011):
- `POST /api/execute_query` - запросы к справочникам/состоянию.
- `POST /api/execute_code` - чтение метаданных, создание/правка элементов.
  **Серверный, без `Возврат`** - результат через `Результат = ...`.
- `GET /api/get_metadata?type=Configuration` - метаданные.

## Граница автоматизации

Через toolkit реально:
- Инспекция структуры и состояния (состав справочников, реквизиты, статус Конвертации, есть ли Релиз).
- Создание/правка правил как элементов справочников: Конвертация, ПКО, ПКС, ПКПД, ПОД,
  СоставыКонвертаций (со снятой защитой записи в форме toolkit). ПКО/ПОД/ПКПД -
  топ-уровневые, в конвертацию включаются записью СоставыКонвертаций.
- Точечная правка реквизитов и привязок.
- Загрузка структуры и генерация модуля - тоже программно: у форменных обработок есть
  headless-точки входа (`ВыполнитьЗагрузкуМетаданных`, `ВыполнитьВыгрузкуМодулей`),
  вызываемые через фоновое задание. См. `methods.md`.

Удобнее интерактивно (через формы обработок КД 3.1), но НЕ обязательно:
- Загрузка структуры конфигурации (`ЗагрузкаСтруктурыКонфигурацииИзФайловXML`) -
  заполняет Релиз + Объекты/Свойства. Без нее правила привязывать не к чему.
  Headless - `methods.md` п.1 (для большой конфигурации запускать через фон).
- Создание/расширение версии формата (`ВыгрузкаСтруктурыФормата` / редакторы формата).
- Генерация модуля менеджера (`ВыгрузкаМодуля`). Headless - `methods.md` п.2.

Перед массовой работой проверять, что Релизы загружены:
`ВЫБРАТЬ КОЛИЧЕСТВО(*) ИЗ Справочник.Релизы` (0 -> структура не загружена).

## Карта references

| Документ | Что внутри | Когда читать |
|---|---|---|
| `references/data-schema.md` | проверенные справочники и реквизиты (Конвертации, ПКО, ПКС, ПКПД, ПОД, теневая модель, слой формата), фактические имена обработок | нужны точные имена объектов/реквизитов |
| `references/bsl-templates.md` | BSL для execute_code: инспекция, состояние конвертации, создание ПКО/ПКС, привязка версии формата | конкретная операция через toolkit |
| `references/format-extension.md` | расширение формата ED: версия формата с namespace, привязка к Конвертации, обработчики ПКО, генерация менеджера, перенос в расширение; workflow + контекст проекта | разработка расширения формата и перенос артефактов |
| `references/methods.md` | программный API обработок (headless): загрузка структуры `ВыполнитьЗагрузкуМетаданных`, генерация модуля `ВыполнитьВыгрузкуМодулей`, прием вызова форменной обработки в обход UI, file:line | нужно вызвать обработку КД программно через toolkit |
| `references/troubleshooting.md` | ограничения toolkit :6011 и КД 3.1 (кодировка, Количество(), тип коллекции метаданных, длины реквизитов, имена перечислений) | при ошибке execute_code/execute_query |

## Scripts

- `scripts/kd31_query.sh "<запрос>" [out.json]` - execute_query.
- `scripts/kd31_exec.sh <файл.bsl> [out.json]` - execute_code из BSL-файла.

Оба: payload через jq (fallback python) + `curl --data-binary @файл`, порт через
`KD31_PORT` (по умолчанию 6011). Если указан `out.json` - ответ в файл (читать
через Read: терминал портит кириллицу).

## Демо-база КД 3.1 как эталон (НАСТОЯТЕЛЬНО)

Если доступна демо-база КД 3.1 (типовая поставка содержит готовую конвертацию,
напр. "БП->УП" - сотни ПКО, тысячи ПКС) - использовать ее как ЭТАЛОН заполнения
правил, а не угадывать. Демо идентична рабочей ИБ по структуре метаданных. Перед
созданием своего ПКО/ПКС снять образец аналогичного правила из демо (Код, как
заполнены ОбъектКонфигурации/ОбъектФормата, паттерн _Отправка/_Получение, как
оформлены прямые vs алгоритмические ПКС, ссылочные через ПравилоКонвертацииСвойства).
Порт демо задается при запуске ее toolkit (порт toolkit уточнять по своей
конфигурации). Чтение демо - `KD31_PORT=<порт> bash scripts/kd31_query.sh "..."`.

## Базовая проверка готовности

```bash
curl -s -o /dev/null -w "%{http_code}\n" "http://localhost:6011/api/get_metadata?type=Configuration"   # 200
bash scripts/kd31_query.sh "ВЫБРАТЬ КОЛИЧЕСТВО(*) КАК К ИЗ Справочник.Конвертации"
bash scripts/kd31_query.sh "ВЫБРАТЬ КОЛИЧЕСТВО(*) КАК К ИЗ Справочник.Релизы"
# Релизы=0 -> структура конфигурации не загружена; для расширения проверить ЕстьРасширения
bash scripts/kd31_query.sh "ВЫБРАТЬ Наименование, ЕстьРасширения ИЗ Справочник.Релизы ГДЕ НЕ ЭтоГруппа"
```

## Связанные скиллы

- `1c-mcp-toolkit` - HTTP API к живой ИБ 1С (этот скилл - надстройка).
- `kd2-rules` - аналог для КД 2.0 (та же идея, другой результат - XML-правила).
- `composing-1c-queries` - синтаксис запросов для execute_query.