steelmorgan/ssl-patterns

Паттерны работы с БСП (Библиотека стандартных подсистем)

Код БСП проверен на миллионах установок, обновляется централизованно, знаком другим разработчикам. Дублирование БСП — антипаттерн.

Сигнатуры функций БСП — через get_signature_help. У функций ОбщегоНазначения и прочих модулей БСП много параметров и перегрузок; не угадывайте порядок и состав аргументов. В точке вызова get_signature_help(uri, line, character) показывает параметры и перегрузки вызываемого метода прямо по месту — без открытия определения модуля БСП. Применяйте при вызове любой функции из каталога ниже, если не уверены в сигнатуре.

Версионированная карта БСП 3.1.11

Этот навык содержит заимствованный справочный слой по БСП 3.1.11:

• references/bsp-3.1.11/*.md — сценарные справочники по подсистемам БСП: модуль, метод, сигнатура, регион API, пример, нюансы и анти-паттерны.
• scripts/bsp_api.py — локальный поиск метода/модуля в выгрузке конфигурации src/cf с определением региона #Область.
• references/bsp-borrowings.md — таблица заимствований: upstream-версия, связь с нашими навыками и вес добавочного знания.

Если задача касается конкретной подсистемы БСП, сначала откройте соответствующий reference из таблицы ниже. Если reference и текущая конфигурация расходятся, приоритет у исходников конфигурации и проверки через get_signature_help / scripts/bsp_api.py.

Версия БСП проекта

Справочный слой соответствует БСП 3.1.11. Версия БСП в конкретном проекте может отличаться.

• Перед использованием метода из справочника определи версию БСП проекта: Описание.Версия заполняется в процедуре ПриДобавленииПодсистемы(Описание) модуля ОбновлениеИнформационнойБазыБСП (или посмотри grep'ом по vendored-исходникам конфигурации, обычно src/xml/CommonModules/).
• Если версия ниже 3.1.11 — сверь существование метода grep'ом по CommonModules проекта, прежде чем писать код.
• Для БСП поколения 2.x справочник использовать только как концептуальный ориентир (какая подсистема за что отвечает); имена и сигнатуры методов сверять по исходникам проекта обязательно. Пример реальной дельты: УправлениеДоступом.ВключитьПрофильПользователю есть в 3.1.x, отсутствует в 2.3.5.

| Задача / подсистема | Reference | |---|---| | Суффиксы модулей, stable/service/deprecated, хуки *Переопределяемый, карта подсистем | references/bsp-3.1.11/fundamentals.md | | ОбщегоНазначения*, строки, даты, реквизиты по ссылке, XML/JSON, безопасное хранилище | references/bsp-3.1.11/base-common.md | | Длительные операции, фоновые и регламентные задания | references/bsp-3.1.11/longs-and-jobs.md | | Пользователи, RLS, профили групп доступа, внешние пользователи | references/bsp-3.1.11/users-access.md | | Подключаемые команды, дополнительные отчеты и обработки | references/bsp-3.1.11/commands-external.md | | Печать, менеджер печати, варианты отчетов, СКД | references/bsp-3.1.11/print-reports.md | | Свойства, запрет редактирования, даты запрета изменения | references/bsp-3.1.11/forms-validation.md | | Файлы, тома, версии объектов, выгрузка объектов в файлы | references/bsp-3.1.11/files-and-versions.md | | Обмен данными, планы обмена, синхронизация, SaaS-области | references/bsp-3.1.11/data-exchange.md | | Почта, SMS, шаблоны сообщений, обсуждения, взаимодействия | references/bsp-3.1.11/comms.md | | Контактная информация, адреса, адресный классификатор | references/bsp-3.1.11/contact-info.md | | Валюты, курсы, банки, графики и календари работы | references/bsp-3.1.11/currencies-banks.md | | Префиксы номеров/кодов и префикс ИБ | references/bsp-3.1.11/prefixes.md | | Обновление версии ИБ и обработчики обновления | references/bsp-3.1.11/update.md | | ЭП, МЧД, криптография, DSS | references/bsp-3.1.11/esign-mcd.md | | Администрирование, резервное копирование, мониторинг, ПДн, дубли, классификаторы, внешние компоненты | см. остальные references/bsp-3.1.11/*.md |

---

Правило 1: Стратегия поиска функций БСП

Алгоритм: LSP -> grep -> AI

1. LSP (если доступен): navigate_symbol("ЗначенияРеквизитовОбъекта")
2. Поиск по тексту: grep -r "Функция.*КурсВалюты" src/CommonModules/
3. AI-ассистент: «Есть ли в БСП функция для получения курса валюты на дату?»

Когда писать своё vs использовать БСП

| Ситуация | Решение | |----------|---------| | В БСП есть подходящая функция | Используй БСП | | В БСП есть похожая, но с лишним функционалом | Используй БСП — лишнее не мешает | | Нужной функции нет в БСП | Пиши своё в стиле БСП | | Конфигурация без БСП | Пиши своё |

Суффиксы модулей (Клиент / КлиентСервер / ПовтИсп / Служебный* и комбинации) — references/bsp-3.1.11/fundamentals.md. Практически: клиентский код формы — искать сначала в *КлиентСервер, потом в *Клиент; серверный — в модуле без суффикса; *ПовтИсп — часто запрашиваемые справочные данные (кэш на сеансе).

---

Правило 2: Каталог готовых механизмов — не дублируй БСП

Прежде чем писать свою реализацию, проверь каталог. Детальные сигнатуры, примеры и анти-паттерны — в reference подсистемы (см. карту выше).

ОбщегоНазначения (сервер):

| Функция | Когда использовать | |---------|-------------------| | ЗначениеРеквизитаОбъекта() | Вместо Ссылка.Реквизит (избегаем точечную нотацию) | | ЗначенияРеквизитовОбъекта() | Несколько реквизитов одним обращением к БД ("Наименование, ИНН, ОсновнойМенеджер") | | СообщитьПользователю() | Сообщение с привязкой к полю и флагом Отказ (вместо Сообщить()) | | МенеджерОбъектаПоСсылке() | Вместо Выполнить("Справочники." + Имя) | | ПодсистемаСуществует() / ОбщийМодуль() | Условный/динамический вызов модулей | | ЭтоСсылка() / СсылкаСуществует() | Валидация параметров / проверка перед обращением |

СтроковыеФункцииКлиентСервер:

| Функция | Когда использовать | |---------|-------------------| | ПодставитьПараметрыВСтроку() | Аналог СтрШаблон(), с дополнительными проверками | | СтрокаСЧисломПредметов() | Склонение: НСтр("ru = 'документ, документа, документов'") → «1 документ», «5 документов» | | ЕстьНедопустимыеСимволы() / ТолькоЦифрыВСтроке() | Валидация ввода (ИНН, КПП) | | РазложитьСтрокуВМассивПодстрок() | Парсинг по разделителю |

ОбщегоНазначенияКлиентСервер (&НаКлиентеНаСервереБезКонтекста — обе среды): ДополнитьМассив(), ДополнитьСтруктуру(), СвойствоСтруктуры() (безопасное чтение со значением по умолчанию), ПроверитьПараметр() (валидация типа), УдалитьЗначениеИзМассива().

Подсистемы вместо самодельного:

| Что часто пишут сами | Что есть в БСП | Reference | |----------------------|----------------|-----------| | Отправка почты | РаботаСПочтовымиСообщениями | comms.md | | Курс валюты | РаботаСКурсамиВалют.ПолучитьКурсВалюты() | currencies-banks.md | | Длительная операция в фоне | ДлительныеОперации.ВыполнитьФункцию() | longs-and-jobs.md | | Хранение секретов / паролей | Регистр сведений БезопасноеХранилищеДанных (только через обёртки ОбщегоНазначения.*ДанныеВБезопасноеХранилище*) | base-common.md | | Профили прав доступа | ГруппыДоступаПользователей / ПрофилиГруппДоступа | users-access.md | | Регистрация внешней обработки | СведенияОВнешнейОбработке() | commands-external.md | | Работа с файлами / временные файлы | РаботаСФайлами, ПолучитьИмяВременногоФайла() + явный УдалитьФайлы() | files-and-versions.md | | Проверка заполнения | ОбработкаПроверкиЗаполнения + СообщитьПользователю(..., Отказ); условное исключение реквизита — УдалитьЗначениеИзМассива(ПроверяемыеРеквизиты, ...) | forms-validation.md | | Печать | УправлениеПечатью.НужноПечататьМакет() / ВывестиТабличныйДокументВКоллекцию() | print-reports.md | | Журнал регистрации | см. error-handling, правило 7 | — |

---

Правило 3: Обязательные нюансы подсистем (MUST)

Полные примеры кода — в reference подсистемы; здесь только нормы, нарушение которых даёт дефект.

ДлительныеОперации — для любой серверной работы дольше ~3 сек; не блокируй UI самодельным циклом ожидания. Прогресс — через ДлительныеОперации.СообщитьПрогресс(); состояние между шагами — в параметрах задания, не в глобальных переменных; перезапуск идемпотентен (повторный вызов с теми же параметрами — тот же результат). Ошибку фонового задания на клиенте обрабатывай через СтандартныеПодсистемыКлиент.ОбработатьОшибкуФоновогоЗадания().

Безопасное хранилище (регистр БезопасноеХранилищеДанных) — никогда не храни пароли/токены/секреты в реквизитах метаданных, константах, журнале регистрации, системе контроля версий; доступ к регистру — только через обёртки ОбщегоНазначения.ЗаписатьДанныеВБезопасноеХранилище/ПрочитатьДанныеИзБезопасногоХранилища/УдалитьДанныеИзБезопасногоХранилища. В ПередУдалением объекта-владельца всегда удаляй его записи из хранилища — иначе накапливаются «осиротевшие» секреты.

ПрофилиГруппДоступа — при ролевом доступе используй профили БСП (УправлениеДоступом.НовоеОписаниеПрофиляГруппДоступа(), ВключитьПрофильПользователю()), не прямое назначение ролей. Идентификатор профиля — фиксированный UUID, не меняется при переименовании. ПривилегированныйРежим() — строго локально, снимай сразу после операции. Проверка прав — УправлениеДоступом.ЕстьПраво()/ЕстьРоль() (или ЧтениеРазрешено()/ИзменениеРазрешено() для RLS-проверок), не РольДоступна() (последнее не учитывает RLS).

Внешние обработки — регистрация в БСП-базе требует функции СведенияОВнешнейОбработке() в основном модуле (Вид, Наименование, Версия, БезопасныйРежим = Истина, команды) и точки входа ВыполнитьКоманду(Идентификатор, ...).

---

Поиск аналогов через Напарника

Если search_ssl_functions не дал результата — ask_ai_assistant (шаблон VALIDATE_BSL из buddy-prompting): передать фрагмент кода, получить рекомендации по замене на методы БСП. Также SEARCH_DOCS для документации по конкретному методу БСП.

---

depends_on: []