desko77/cursor-1c-skills/1c-bsp-api

Справочник API БСП

Офлайн-справочник по программному интерфейсу БСП: 2624 метода в 284 модулях, 71 подсистема, версии 3.1.11 и 3.2.1. Собран из двух источников одновременно - структура и сигнатуры из документации, модули и экспортность из самой библиотеки. Каждая версия документации сведена со своим дистрибутивом, поэтому различия между версиями видны, а не усреднены.

Назначение написано нами: одна строка у каждого из 284 модулей и у 440 методов ядра. Описательный текст документации ИТС в справочник не переносится.

Справочник больше мегабайта, в контекст целиком не грузится. Он спрашивается по месту.

Главное правило

Не пиши вызов метода БСП, не проверив его. Имена в БСП длинные и составные, поэтому правдоподобная выдумка выглядит как настоящее имя. Классические несуществующие: ФайловаяСистемаКлиентСервер, JSONСтрокой, Пользователи.СсылкаТекущегоПользователя.

python skills/1c-bsp-api/scripts/bsp-api.py check ФайловаяСистемаКлиентСервер.ПолучитьФайл

Код возврата 1, если вызова нет. При промахе инструмент подсказывает похожие имена - и по модулю, и по методу.

Как устроена библиотека

Суффикс имени модуля - это контекст выполнения, а не тематика. Один механизм разложен по нескольким модулям, и выбор между ними определяется тем, откуда идет вызов:

Отсюда частая ошибка: серверный метод вызывают из клиентского кода. Контекст каждого метода есть в справочнике, отбор - ключом --av (S сервер, T тонкий, F толстый, E внешнее соединение, C вызов сервера).

Три вида модулей по назначению:

• Обычные - публичный интерфейс, их и вызывают: ОбщегоНазначения, Пользователи,

УправлениеПечатью.

• `Переопределяемый` - точки расширения. Их не вызывают, в них ПИШУТ: обработчик вызывает

библиотека, а тело пишет внедряющая конфигурация. Таких методов 372.

• `Служебный` - внутренняя реализация библиотеки. В программный интерфейс не входит ни один

служебный метод, и вызывать их нельзя: они меняются между версиями без объявления.

Еще два суффикса встречаются реже: ПовтИсп - модуль с повторным использованием возвращаемых значений, Локализация - национальная специфика.

Часть интерфейса объявлена не в общих модулях. Обмен данными опубликован модулями объектов обработок (Обработка.УниверсальныйОбменДаннымиXML, Обработка.КонвертацияОбъектовXDTO). В справочнике они есть наравне с общими модулями.

Запросы

B=skills/1c-bsp-api/scripts/bsp-api.py
 
python $B find печать # поиск по имени, модулю, подсистеме, назначению
python $B find "реквизит объект" # ищутся все слова запроса сразу, не подстрока
python $B find файл --av T # только то, что доступно на тонком клиенте
python $B show ОбщегоНазначения.ЗначениеРеквизитаОбъекта # карточка метода
python $B show ЗначениеРеквизитаОбъекта # все модули, где есть метод с таким именем
python $B module Пользователи # состав модуля целиком
python $B modules контакт # какие вообще есть модули
python $B subsystem печать # модули и механизмы подсистемы
python $B overrides обновлен # переопределяемые обработчики под задачу
python $B check Пользователи.ТекущийПользователь
python $B stats # что вообще в справочнике

Общие ключи отбора: --av, --sub <подсистема>, --version 3.2.1, --limit N.

Как читать выдачу

Строка вида ОбщегоНазначения.ЗначениеРеквизитаОбъекта SFE - это модуль, метод и контексты.

Пометка `[?]` означает, что модуль выведен, а не подтвержден. Документация БСП называет механизм, а не модуль, поэтому у части методов модуль восстановлен по примеру вызова или по совпадению контекстов. В карточке (show) последняя строка всегда говорит, откуда взято имя модуля. Метод с пометкой перед использованием стоит сверить с конфигурацией проекта.

Пометка стоит у 117 методов из 2624, это около четырех процентов. Еще у 37 модуль определить не удалось вовсе - они собраны под именем ?. Это не значит, что метода нет: значит, одно и то же имя объявлено в нескольких модулях, и документация не говорит, о каком из них статья.

Пометка `[!]` означает, что между версиями метод изменился. Карточка тогда содержит строку "ВНИМАНИЕ, в <версия> иначе" с прежней сигнатурой. Таких методов 27, и часть изменений ломающие: ОбщегоНазначения.ВыполнитьМетодКонфигурации из процедуры стал функцией, а у ДобавитьПоказатель новый параметр вставлен не в конец, а первым. Код, написанный по новой сигнатуре, на старой версии передаст аргументы не туда и об этом не сообщит.

Частые ошибки

• Выдуманный модуль. Проверять check, а не полагаться на память.
• Серверный метод в клиентском коде. Смотреть контексты; для клиента почти всегда есть

парный модуль с суффиксом Клиент.

• Вызов служебного модуля. Если в имени есть Служебный - это не интерфейс.
• Попытка вызвать переопределяемый обработчик. В него пишут тело, а не вызывают его.
• Метод из другой версии. У каждой записи указано, в каких версиях БСП она есть. Метод,

помеченный только 3.2.1, на 3.1.11 не существует. А метод с пометкой [!] существует в обеих, но вызывается по-разному - смотреть карточку до того, как писать вызов.

• Расчет на то, что у метода тот же набор параметров, что был раньше. Сигнатура в

справочнике полная, включая значения по умолчанию - брать оттуда.

Границы

Справочник знает ИМЕНА, СИГНАТУРЫ и КОНТЕКСТЫ, а назначение - строкой, написанной нами. Развернутого описания в нем нет: текст документации ИТС лицензионный и сюда не переносится. Строка назначения есть у каждого модуля, но у методов пока только у ядра - базовых модулей ОбщегоНазначения*, длительных операций, пользователей, строковых функций, файловой системы и журнала регистрации. Когда нужно понять механизм глубже, а не форму вызова - идти в документацию ИТС по подсистеме, которую покажет subsystem.

Не покрыты: HTTP-сервисы и веб-сервисы библиотеки, макеты, роли, права, состав метаданных подсистем. Только программный интерфейс кода.

Сборка справочника

Готовый справочник лежит в references/bsp-api.jsonl и обновлять его нужно только при переходе на новую версию БСП. Пересборка требует двух источников, оба лицензионные и в репозиторий не входят: скрапа документации с ИТС и дистрибутива библиотеки.

python -m v8unpack -E 1Cv8.cf E:\bsp\3_2_1 --temp E:\bsp\_tmp # распаковать дистрибутив
python skills/1c-bsp-api/scripts/bsp-build.py \
 --docs "3.1.11=E:\scrape\bsp3111doc" --docs "3.2.1=E:\scrape\bsp321doc" \
 --lib "3.1.11=E:\bsp\3_1_11" --lib "3.2.1=E:\bsp\3_2_1" \
 --purposes skills/1c-bsp-api/references/purposes.json \
 --out skills/1c-bsp-api/references/bsp-api.jsonl \
 --map skills/1c-bsp-api/references/subsystem-map.md

Формулировки назначения ведутся отдельно, в references/purposes.json: раздел modules и раздел methods с ключами вида Модуль.Метод. При сборке они подмешиваются в справочник, а имена, которых в нем нет, генератор называет в отчете - это ловит и опечатку, и формулировку к методу, которого в этой версии уже не существует.

Ключи --docs и --lib указываются по одному на версию и связываются префиксом. Связывать обязательно: если сшивать документацию 3.1.11 с библиотекой 3.2.1, методы, убранные в новой версии, будут объявлены несуществующими. Библиотека без префикса версии берется для всех.

Брать надо 1Cv8.cf - чистую библиотеку, а не 1Cv8_demo.cf: демонстрационная конфигурация несет объекты, которых в поставке нет. Распаковка идет без платформы и Конфигуратора.

Скрипты на Python, PowerShell-порта нет: сборка нужна редко, а поиск идет по готовому файлу.