Clean

---
name: 1c-bsp-api
description: "Справочник программного интерфейса Библиотеки стандартных подсистем (БСП) 1С - какие общие модули существуют, какие у них экспортные методы, сигнатуры, типы параметров, контексты выполнения и переопределяемые обработчики. Используй когда пишешь код на конфигурации с БСП и нужно узнать имя модуля или метода, его сигнатуру, серверный он или клиентский, какой переопределяемый обработчик реализовать под задачу; а также чтобы ПРОВЕРИТЬ вызов перед тем, как его написать: имя модуля БСП, отсутствующее в библиотеке, по виду не отличается от настоящего, поэтому вызов сверяется со справочником. Работает офлайн, платформа и EDT не нужны. НЕ для API самой платформы (там 1c-platform-docs) и НЕ для прикладных конфигураций ERP, ЗУП, БП"
argument-hint: "find <текст> | show <Модуль.Метод> | check <Модуль.Метод> | module <Имя> | subsystem <Имя> | overrides <текст>"
allowed-tools:
  - Bash
  - Read
---

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

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

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

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

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

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

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

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

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

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

| Суффикс | Где исполняется | Пример |
|---|---|---|
| без суффикса или `Сервер` | сервер, толстый клиент, внешнее соединение | `ОбщегоНазначения` |
| `Клиент` | тонкий и толстый клиент | `ОбщегоНазначенияКлиент` |
| `КлиентСервер` | и там, и там | `ОбщегоНазначенияКлиентСервер` |
| `ВызовСервера` | сервер, вызывается с клиента напрямую | `ОбщегоНазначенияВызовСервера` |

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

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

- **Обычные** - публичный интерфейс, их и вызывают: `ОбщегоНазначения`, `Пользователи`,
  `УправлениеПечатью`.
- **`Переопределяемый`** - точки расширения. Их не вызывают, в них ПИШУТ: обработчик вызывает
  библиотека, а тело пишет внедряющая конфигурация. Таких методов 372.
- **`Служебный`** - внутренняя реализация библиотеки. В программный интерфейс не входит ни один
  служебный метод, и вызывать их нельзя: они меняются между версиями без объявления.

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

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

## Запросы

```bash
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` и обновлять его нужно только при переходе
на новую версию БСП. Пересборка требует двух источников, оба лицензионные и в репозиторий не
входят: скрапа документации с ИТС и дистрибутива библиотеки.

```bash
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-порта нет: сборка нужна редко, а поиск идет по готовому файлу.