steelmorgan/platform-data-core

Работа с данными платформы 1С (Platform Data Core)

Три операции, которые обычно используются вместе в одном рабочем цикле:

1. Metadata Discovery — найти объект метаданных и его структуру
2. Query Execution — построить и выполнить запрос по найденным именам
3. Nav Link — разобрать входящую навигационную ссылку → запрос → сформировать исходящую ссылку

---

§1 Metadata Discovery (поиск метаданных)

Принцип: Перед работой с бизнес-логикой — исследовать метаданные. Не создавать объекты «наугад», если пользователь не попросил явно.

Инструменты

| Tool | Параметры | Назначение | |------|-----------|------------| | list_metadata_objects | metaType, nameMask, maxItems | Поиск объектов по типу и маске имени | | get_metadata_structure | metaType, name | Структура: реквизиты, ТЧ, измерения, ресурсы | | navigate_symbol | — | Переход к модулям, процедурам найденных объектов | | get_call_graph | — | Анализ цепочек вызовов в модулях |

Алгоритм работы

1. Найти объект: list_metadata_objects(metaType, nameMask) — проверить существование и тип. Для нечёткого поиска: nameMask: "*Номенклатура*".
2. Получить структуру: get_metadata_structure(metaType, name) — реквизиты, ТЧ, измерения, ресурсы. Обязательно перед построением запроса.
3. Анализ кода (при необходимости): navigate_symbol → get_call_graph.
4. Создание нового объекта: агент НЕ создаёт объекты метаданных автоматически. Алгоритм: проверить что не существует → описать пользователю (имя, реквизиты, ТЧ) → пользователь создаёт в Конфигураторе/EDT → get_metadata_structure для верификации.

Типичные ошибки

| Ошибка | Решение | |--------|---------| | Поиск по общему слову даёт много результатов | Сузить nameMask; указать metaType; уменьшить maxItems | | Агент пытается создать объект сам | Протокол: агент описывает, пользователь создаёт в Конфигураторе/EDT |

---

§2 Query Execution (выполнение запросов)

Справочник синтаксиса: references/query-syntax-cheatsheet.md

Workflow

1. Метаданные (если не уверен в именах): list_metadata_objects → get_metadata_structure
2. Построить запрос с точными именами объектов и полей
3. Валидация: validate_query
4. Выполнение: execute_query

Никогда не угадывай имена — конфигурации 1С различаются. Один вызов за метаданными дешевле отладки провалившегося запроса.

---

Критические ограничения MCP

При выполнении запросов через execute_query (HTTP/MCP без параметров) значения задаются явно в тексте запроса. Параметры &Имя могут не поддерживаться.

1. Ограничивать выборку через ПЕРВЫЕ N

Для запросов, возвращающих строки данных, всегда ограничивай количество записей:

ВЫБРАТЬ ПЕРВЫЕ 100
    Документы.Номер,
    Документы.Дата
ИЗ
    Документ.РеализацияТоваровУслуг КАК Документы

Исключения — ПЕРВЫЕ N не нужен и вреден:

| Случай | Почему не нужен | |--------|-----------------| | Агрегатные запросы (КОЛИЧЕСТВО, СУММА, МАКСИМУМ) | Возвращают одну строку; ПЕРВЫЕ 1 избыточен и может дать неверный результат при группировке | | Проверка существования (ВЫБРАТЬ ПЕРВЫЕ 1 Ссылка ИЗ ... ГДЕ ...) | ПЕРВЫЕ 1 здесь уместен и уже ограничивает | | ОБЪЕДИНИТЬ ВСЕ в подзапросах | Ограничение задаётся на внешнем уровне |

2. Параметры — если не поддерживаются

❌ НЕПРАВИЛЬНО (если &Параметр недоступен):

ГДЕ Товар = &Товар

✅ ПРАВИЛЬНО (сравнение через примитивные реквизиты):

ГДЕ Товар.Наименование = "iPhone 17 Pro Max"
ГДЕ Контрагент.ИНН = "7707083893"

3. Сравнение ссылочных полей — только через примитивы

execute_query через HTTP/MCP не поддерживает параметры &Ссылка, поэтому сравнивать ссылочные поля напрямую невозможно — используй примитивные реквизиты объекта.

❌ НЕПРАВИЛЬНО (сравнение ссылок напрямую):

ГДЕ Документ.Контрагент = Справочник.Контрагенты.Ссылка

✅ ПРАВИЛЬНО (сравнение через примитивные реквизиты):

ГДЕ Документ.Контрагент.Наименование = "ООО Ромашка"
ГДЕ Документ.Контрагент.Код = "000001"
ГДЕ Документ.Контрагент.ИНН = "7707083893"

⚠️ Важно — риск неоднозначности. Наименование и Код не гарантируют уникальность:

• Наименование — может повторяться в разных папках или при дублях
• Код — уникален внутри справочника, предпочтительнее
• ИНН, Артикул и другие бизнес-идентификаторы — используй, если они уникальны в этой конфигурации

Когда допустимо: диагностика, анализ данных, разовые запросы где дубли маловероятны. Когда недопустимо: критически важная выборка, где ложное совпадение по имени даст неверный результат — в этом случае уточни у пользователя точный идентификатор или используй ПОДОБНО с предупреждением о возможных дублях.

4. Литеральные значения — даты и строки

Раз параметры &Имя недоступны, значения задаются литералами: даты — через ДАТАВРЕМЯ(Год, Месяц, День[, Час, Минута, Секунда]), строки — в двойных кавычках. Синтаксис и примеры: references/query-syntax-cheatsheet.md §§ «Работа с датами», «Строковые значения».

---

Типичные ошибки запросов

| Ошибка | Решение | |--------|---------| | NULL в вычислениях | ЕСТЬNULL(Поле, ЗначениеПоУмолчанию) при LEFT JOIN | | Медленный запрос с ИЛИ | Заменить на В (...) или ОБЪЕДИНИТЬ ВСЕ | | Медленный запрос к Регистратору | ВЫРАЗИТЬ(Регистратор КАК Документ.Имя) + ССЫЛКА в ГДЕ |

---

§3 Nav Link (навигационные ссылки)

Когда применять

| Триггер | Действие | |---------|----------| | Пользователь даёт ссылку e1cib/data/... | parse_nav_link → тип + ссылка → запросы/анализ | | Нужно сформировать ссылку по данным из запроса | get_nav_link(тип, ссылка) → ссылка для ответа |

Алгоритм

• Входящая ссылка: parse_nav_link → извлечь тип и ref → построить запрос → execute_query.
• Исходящая ссылка: execute_query вернул ссылку → get_nav_link(тип, ссылка) → вернуть пользователю.

Capabilities

| Capability | Назначение | |------------|------------| | parse_nav_link | Разбор e1cib/data/... — извлечение типа объекта и ссылки | | get_nav_link | Формирование навигационной ссылки по типу + ссылке |

---

depends_on: []