Use Bsp

---
name: use-bsp
description: "Паттерны переиспользования БСП (Библиотека стандартных подсистем) - общие модули, работа со строками, утилитарные файловые операции, права, безопасное хранение паролей, длительные операции. Используй перед написанием любого утилитарного кода в конфигурациях на БСП (УТ, ERP, БП, ЗУП) и при работе с расширениями таких конфигураций."
---

# Паттерны работы с БСП

> Нормы кода — в `.claude/rules/1c-rules.md` (единственный источник правил).
> Здесь — развёрнутые паттерны и примеры «как именно».
> БСП = проверенный код на миллионах установок: перед написанием своей функции проверь, есть ли она в БСП.

## Приоритеты

🔴 КРИТИЧНО (нарушение = дублирование кода): ОбщегоНазначения — первое место поиска; не дублируй БСП; стратегия поиска функций.
🟡 ВАЖНО: СтроковыеФункции для строк; КлиентСервер-модули для переиспользования; суффикс модуля определяет среду.
🟢 РЕКОМЕНДУЕТСЯ: ЗаписьЖурналаРегистрации по стандарту; ФайловаяСистема для временных файлов; типовые паттерны для стандартных задач.

---

## ШАБЛОНЫ КОДА (копируй и адаптируй)

### Шаблон 1: Получение реквизитов объекта
```bsl
// ✅ ПРАВИЛЬНО: через БСП - один запрос
РеквизитыКонтрагента = ОбщегоНазначения.ЗначенияРеквизитовОбъекта(
    КонтрагентСсылка,
    "Наименование, ИНН, ОсновнойМенеджер");

Наименование = РеквизитыКонтрагента.Наименование;
ИНН = РеквизитыКонтрагента.ИНН;
Ответственный = РеквизитыКонтрагента.ОсновнойМенеджер;

// ❌ ПЛОХО: точечная нотация - три запроса
Наименование = КонтрагентСсылка.Наименование;
ИНН = КонтрагентСсылка.ИНН;
Ответственный = КонтрагентСсылка.ОсновнойМенеджер;
```

### Шаблон 2: Работа со строками
```bsl
// Подстановка параметров
ТекстСообщения = СтроковыеФункцииКлиентСервер.ПодставитьПараметрыВСтроку(
    НСтр("ru = 'Обработано %1 из %2 документов. Ошибок: %3.'"),
    Формат(Обработано, "ЧГ="),
    Формат(Всего, "ЧГ="),
    Формат(КоличествоОшибок, "ЧГ="));

// Склонение по числу: формы задаются в шаблоне через ";"
ТекстОповещения = СтроковыеФункцииКлиентСервер.СтрокаСЧисломДляЛюбогоЯзыка(
    НСтр("ru = ';%1 документ;;%1 документа;%1 документов;%1 документа'"),
    КоличествоДокументов);
// Результат: "5 документов" или "1 документ"
```

### Шаблон 3: Доступ к необязательному свойству структуры
```bsl
// Для внешней или вариативной структуры: безопасный доступ со значением по умолчанию
ДатаНачала = ОбщегоНазначенияКлиентСервер.СвойствоСтруктуры(
    ПараметрыОтчёта, 
    "ДатаНачала", 
    НачалоГода(ТекущаяДатаСеанса()));

// Ошибка, если по контракту свойство может отсутствовать
Значение = ПараметрыОтчёта.ДатаНачала;
```

### Шаблон 4: Проверка заполнения с сообщением
```bsl
// Модуль объекта
Процедура ОбработкаПроверкиЗаполнения(Отказ, ПроверяемыеРеквизиты)
    
    Если НЕ ЗначениеЗаполнено(Контрагент) Тогда
        ОбщегоНазначения.СообщитьПользователю(
            НСтр("ru = 'Не заполнен контрагент.'"),
            ЭтотОбъект, 
            "Контрагент",, 
            Отказ);
    КонецЕсли;
    
    // Условное исключение реквизитов из проверки
    Если ВидОперации = Перечисления.ВидыОпераций.Услуга Тогда
        ОбщегоНазначенияКлиентСервер.УдалитьЗначениеИзМассива(
            ПроверяемыеРеквизиты, "Склад");
    КонецЕсли;
    
КонецПроцедуры
```

### Шаблон 5: Стратегия поиска функций БСП
```bsl
// 1. Проверь ОбщегоНазначения - там 80% нужных функций
// 2. Проверь СтроковыеФункцииКлиентСервер для работы со строками
// 3. Проверь ОбщегоНазначенияКлиентСервер для клиент-серверных утилит
// 4. Не нашёл по имени модуля — ищи функцию по всем исходникам по приоритету источников из .claude/rules/mcp.md

// Примеры частых функций:
// - ЗначениеРеквизитаОбъекта() - получить один реквизит
// - ЗначенияРеквизитовОбъекта() - получить несколько реквизитов
// - СообщитьПользователю() - сообщение с привязкой к полю
// - МенеджерОбъектаПоСсылке() - менеджер по ссылке
// - ПодставитьПараметрыВСтроку() - подстановка в шаблон
// - СвойствоСтруктуры() - безопасное чтение свойства
```

---

## Подробные паттерны (reference)

**Не загружаются автоматически — открой нужный файл инструментом Read по теме задачи.**

| Тема | Файл |
|---|---|
| Общие модули: ОбщегоНазначения, СтроковыеФункцииКлиентСервер, ОбщегоНазначенияКлиентСервер, стратегия поиска функций, отказ от дублирования БСП, модули «КлиентСервер» | `references/common-modules.md` |
| Подсистемы: журнал регистрации, временные файлы (ФайловаяСистема), безопасное хранилище паролей, ДлительныеОперации, типовые паттерны (проверка заполнения, печать, права доступа) | `references/subsystems.md` |

---

## Чек-лист использования БСП

Дополнение к общему «Чек-листу проверки кода» из `.claude/rules/1c-rules.md` — детализация для работы с БСП:

### Поиск функций БСП
- [ ] Перед написанием новой функции проверил наличие в БСП
- [ ] Проверил модуль `ОбщегоНазначения` (80% нужных функций там)
- [ ] Проверил `СтроковыеФункцииКлиентСервер` для работы со строками
- [ ] Проверил `ОбщегоНазначенияКлиентСервер` для клиент-серверных утилит

### Использование вместо самописного кода
- [ ] Используется `ЗначенияРеквизитовОбъекта()` вместо точечной нотации
- [ ] Используется `СообщитьПользователю()` вместо `Сообщить()`
- [ ] Используется `ПодставитьПараметрыВСтроку()` вместо конкатенации
- [ ] Для необязательных свойств внешних или вариативных структур используется `Свойство()` или `СвойствоСтруктуры()`

### Правильный выбор модуля
- [ ] Для клиента используются модули с суффиксом `КлиентСервер` или `Клиент`
- [ ] Для сервера используются модули без суффикса или с суффиксом `Сервер`
- [ ] Для кэшируемых данных используются модули `ПовтИсп`
- [ ] Не смешиваются серверные и клиентские модули

### Стандартные паттерны
- [ ] Проверка заполнения использует `ОбработкаПроверкиЗаполнения`
- [ ] Логирование следует стандарту БСП (иерархические имена событий)
- [ ] Временные файлы и каталоги удаляются через `ФайловаяСистема.УдалитьВременныйФайл()` / `УдалитьВременныйКаталог()`, в том числе на пути исключения
- [ ] Сохраняемые пароли, токены и закрытые API-ключи размещены в безопасном хранилище паролей, а не в обычных константах и реквизитах
- [ ] Права проверяются платформенной `ПравоДоступа()` — специальной обёртки для проверки права на объект в БСП нет, не изобретай методов вида `ПравоДоступаОбъекта()`

### Отсутствие дублирования
- [ ] Нет самописных функций для получения реквизитов объектов
- [ ] Нет самописных функций для работы со строками
- [ ] Нет самописных функций для склонения слов
- [ ] Нет самописных функций для форматирования дат/чисел

### Документирование
- [ ] Объём и оформление документации своих функций — по нормам `.claude/rules/1c-rules.md` (### Документирование), а не по образцу соседнего кода БСП
- [ ] Структура нового или существенно переработанного модуля соответствует `std#455` из `.claude/rules/1c-rules.md`; неприменимые и пустые области не созданы

---