Kd2 Rules

---
name: kd2-rules
description: >
  Программная разработка правил обмена в "Конвертация данных 2.1" (КД 2.0)
  через MCP-toolkit к живой ИБ. Создание/чтение/изменение Конвертаций, ПКО,
  ПКС, ПКЗ, ПВД, ПОД в справочниках КД и выгрузка итогового XML штатными
  обработками КД (ВыгрузкаКонвертации, ВыгрузкаРегистрации, ЗагрузкаКонвертации,
  ЗагрузкаСтруктурыМетаданных). Содержит схему данных, шаблоны BSL для
  execute_code, схему итогового XML, типичные ошибки. Триггеры на русском:
  "работа с КД 2.0", "правила обмена в КД", "создать конвертацию", "настроить
  ПКО ПКС ПКЗ", "выгрузить правила обмена в XML", "конвертация данных 2.1",
  "загрузить метаданные конфигурации в КД", "автонастройка правил конвертации".
  Триггеры на английском: "1C data conversion rules", "KD 2.0", "create
  conversion rule", "PKO PKS PKZ", "export exchange rules XML".
---

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

Скилл описывает, как агент создает/изменяет правила обмена в живой ИБ
"Конвертация данных 2.1" (КД 2.0) через `MCP-toolkit` HTTP API (порт по
умолчанию `6003`, в проектах часто `7003`) и в финале выгружает XML
штатными обработками КД.

## Что такое КД 2.0

- Конфигурация фирмы "1С", v2.1.8.2, обычные формы, режим совместимости
  8.2.13. Программа для разработки правил обмена данными между парами
  конфигураций (например, БП КОРП -> УПП, УТ -> ERP).
- Результат работы в КД - XML с правилами, который грузится в
  "Универсальный обмен данными в формате XML" в конфигурации-источнике.
- Все правила хранятся в справочниках самой КД: `Конвертации`,
  `ПравилаКонвертацииОбъектов`, `ПравилаКонвертацииСвойств`,
  `ПравилаКонвертацииЗначений`, `ПравилаВыгрузкиДанных`,
  `ПравилаОчисткиДанных`, `ПравилаРегистрацииОбъектов`, плюс
  `Конфигурации`/`Объекты`/`Свойства`/`Значения` (теневая модель метаданных
  источника и приемника).

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

```
Claude (агент)
   ↕  MCP-протокол / прямые tool-вызовы
Скилл kd2-rules
   ↕  HTTP POST :6003/api/* (или :7003 если переопределен порт)
MCP-toolkit (обработка MCP_Toolkit.epf в живой ИБ)
   ↕  внутрипроцессно
ИБ КД 2.0
   ↕  через ВыгрузкаКонвертации.ВыполнитьВыгрузкуПравил()
Файл XML с правилами обмена
```

Низкоуровневый транспорт - `MCP-toolkit` (скилл `1c-mcp-toolkit`). Главные
эндпоинты, которые используются здесь:

- `POST /api/execute_query` - читать справочники КД и их связи.
- `POST /api/execute_code` - создавать/изменять элементы справочников,
  запускать экспортные методы обработок.
- `GET /api/health` - проверка живости.

## Предварительные требования

1. Запущенная ИБ КД 2.0 в тонком/толстом клиенте с открытой обработкой
   `MCP_Toolkit.epf` (см. скилл `1c-mcp-toolkit`). HTTP-сервер слушает
   `localhost:6003` (или `:7003` по настройке).
2. В форме toolkit-а проверить и при необходимости снять защиту от записи:
   снять флажки на ключевые слова `Записать`, `Удалить`,
   `УстановитьПривилегированныйРежим`. Без этого работают только
   `execute_query` и read-only вызовы.
3. Желательно тестовая копия ИБ КД, а не production - правила пишутся
   напрямую в справочники.

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

```sh
curl http://localhost:7003/health
# Ожидание: {"status":"healthy", ...}

curl -sS -X POST "http://localhost:7003/api/execute_query" \
  -H "Content-Type: application/json" \
  -d '{"query":"ВЫБРАТЬ КОЛИЧЕСТВО(*) КАК Кол ИЗ Справочник.Конвертации"}'
```

## Карта references

| Документ | Что внутри | Когда читать |
|---|---|---|
| `references/helpers.md` | библиотека готовых BSL-заготовок для `execute_code`: списки ПКО/ПКС/ПКЗ, дамп обработчиков, флаги ПКО, ПКС по ссылке на Свойство, выгрузка комплекта XML, поиск объектов с учетом префикса типа, идиомы передачи значений | нужен запрос или правка объектов КД - СНАЧАЛА сюда, не сочинять скрипт с нуля |
| `references/architecture.md` | объектная модель КД, иерархия Владелец, полные списки реквизитов всех ключевых справочников | проектирование новой операции, нужны типы и связи |
| `references/methods.md` | экспортные методы обработок выгрузки/загрузки + file:line + параметры (реквизиты обработки) | вызов конкретного метода через `execute_code` |
| `references/workflows.md` | end-to-end сценарии: подготовка ИБ, загрузка метаданных, создание правил, выгрузка XML, импорт XML, автонастройка | впервые делаешь полный цикл или сложный сценарий |
| `references/xml-schema.md` | схема итогового XML правил обмена + маппинг полей справочника на XML | надо понять, что КД ожидает увидеть в XML, или сверить результат с эталоном |
| `references/troubleshooting.md` | типичные ошибки и ограничения toolkit-а, особенности КД 2.0 | при ошибке `execute_code`/`execute_query` |

## 5 базовых операций (краткий справочник)

### 1. Найти конвертацию по имени

```bsl
Конв = Справочники.Конвертации.НайтиПоНаименованию("Имя_Конвертации");
Если Конв.Пустая() Тогда
    ВызватьИсключение "Конвертация не найдена";
КонецЕсли;
Результат = XMLСтрока(Конв);
```

### 2. Список ПКО в конвертации

```sh
curl -sS -X POST "http://localhost:7003/api/execute_query" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "ВЫБРАТЬ ПКО.Наименование, ПКО.ТипИсточника, ПКО.ТипПриемника, ПКО.Порядок ИЗ Справочник.ПравилаКонвертацииОбъектов КАК ПКО ГДЕ ПКО.Владелец.Наименование = &Конв И НЕ ПКО.ЭтоГруппа УПОРЯДОЧИТЬ ПО ПКО.Порядок",
    "params": {"Конв": "Имя_Конвертации"}
  }'
```

### 3. Создать ПКО

```bsl
Конв = Справочники.Конвертации.НайтиПоНаименованию("МояКонвертация");
ОбъИст = Справочники.Объекты.НайтиПоНаименованию("Контрагенты", Истина, Конв.Источник);
ОбъПр  = Справочники.Объекты.НайтиПоНаименованию("Контрагенты", Истина, Конв.Приемник);

ПКО = Справочники.ПравилаКонвертацииОбъектов.СоздатьЭлемент();
ПКО.Владелец      = Конв;
ПКО.Наименование  = "Контрагенты";
ПКО.Источник      = ОбъИст;
ПКО.Приемник      = ОбъПр;
ПКО.ТипИсточника  = "СправочникСсылка.Контрагенты";
ПКО.ТипПриемника  = "СправочникСсылка.Контрагенты";
ПКО.Порядок       = 100;
ПКО.Записать();

Результат = Новый Структура("ссылка", XMLСтрока(ПКО.Ссылка));
```

### 4. Создать ПКС внутри ПКО

```bsl
ПКО = Справочники.ПравилаКонвертацииОбъектов.НайтиПоНаименованию("Контрагенты", Истина, Конв);
СвИст = Справочники.Свойства.НайтиПоНаименованию("Наименование", Истина, ПКО.Источник);
СвПр  = Справочники.Свойства.НайтиПоНаименованию("Наименование", Истина, ПКО.Приемник);

ПКС = Справочники.ПравилаКонвертацииСвойств.СоздатьЭлемент();
ПКС.Владелец     = ПКО;
ПКС.Источник     = СвИст;
ПКС.Приемник     = СвПр;
ПКС.ИмяИсточника = "Наименование";
ПКС.ИмяПриемника = "Наименование";
ПКС.ТипИсточника = "Строка";
ПКС.ТипПриемника = "Строка";
ПКС.ВидИсточника = "Свойство";
ПКС.ВидПриемника = "Свойство";
ПКС.Наименование = "Наименование --> Наименование";
ПКС.Порядок      = 100;
ПКС.Записать();
```

### 5. Выгрузить конвертацию в XML

```bsl
Конв = Справочники.Конвертации.НайтиПоНаименованию("МояКонвертация");
Обр = Обработки.ВыгрузкаКонвертации.Создать();
Обр.КонвертацияДляВыгрузки         = Конв;
Обр.ИмяФайлаПравил                 = "C:\Output\rules.xml";
Обр.СжиматьФайлПравил              = Ложь;
Обр.ВыгружатьПравилаКорреспондента = Ложь;
Обр.ВыгружатьПравилаРегистрации    = Ложь;
Обр.ВыполнитьВыгрузкуПравил();

Файл = Новый Файл(Обр.ИмяФайлаПравил);
Результат = Новый Структура("ok,path,size", Истина, Обр.ИмяФайлаПравил, Файл.Размер());
```

## Принципы работы

1. **Все справочники иерархические** "Папки и элементы". ПКО-группы (`ЭтоГруппа=true`)
   используются для логической группировки правил внутри конвертации.

2. **Владелец = главная связь.** ПКО подчинен Конвертации, ПКС/ПКЗ подчинены ПКО,
   Объекты подчинены Конфигурации, Свойства подчинены Объектам, Значения
   подчинены Свойствам.

3. **Денормализованные дубликаты.** Поля типа `ИмяИсточника`/`ТипИсточника` в ПКО и
   ПКС - строковые копии данных из связанной ссылки (для быстрого поиска без
   join-ов). Заполняй их явно при создании.

4. **Поле `Код`** в Конвертациях и ПКО - это "внутренний идентификатор" (UUID-подобная
   строка фиксированной длины 40 символов с trailing-пробелами). Используется в
   итоговом XML как `<Ид>` и `<КодПравилаКонвертации>`.

5. **Имя файла в `ИмяФайлаПравил`** должно быть путем к существующему каталогу.
   `КаталогВременныхФайлов()` - надежный способ получить временную папку клиента.

6. **Гигиена скриптов.** Одноразовые/отладочные BSL-скрипты класть только в
   `tools/_tmp/` рабочего каталога КД и чистить после задачи. Устойчивые
   операции не копить в одноразовых файлах - брать из `references/helpers.md`
   и добавлять новые заготовки туда же.

## Ограничения

- Все ключевые методы КД работают через `execute_code` без явного
  `execution_context` (toolkit живет в клиентском контексте 1С,
  директива `#Если Клиент Тогда` не блокирует).
- В стандартной конфигурации toolkit-а заблокированы ключевые слова
  `Записать`, `Удалить`, `УстановитьПривилегированныйРежим`. Для создания
  правил - отключить защиту в форме toolkit-а.
- Возможны trailing-пробелы в строковых ссылочных полях (`Код` 40 символов
  с пробелами). При сравнениях использовать `СокрЛП(...)`.
- Обработка `ВыгрузкаКонвертации` использует переменную модуля
  `мФормаПрогрессора.Значение` - при программном запуске она остается
  не инициализированной, но падения не происходит.

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

- `1c-mcp-toolkit` - HTTP API к живой ИБ 1С (этот скилл - надстройка
  поверх него).
- `composing-1c-queries` - синтаксис языка запросов 1С для `execute_query`.