{
  "skill_name": "1c-ssl-patterns",
  "evals": [
    {
      "id": "background-op-with-progress",
      "prompt": "Мне нужно запустить долгую операцию пересчета себестоимости в фоне с отображением прогресса пользователю. Как это сделать через БСП?",
      "expected_output": "Использован актуальный API длительных операций: ВыполнитьФункцию либо ВыполнитьПроцедуру с ожиданием на клиенте. Устаревший ВыполнитьВФоне не предлагается.",
      "expectations": [
        "Использован ДлительныеОперации.ВыполнитьФункцию или ВыполнитьПроцедуру",
        "Показан вызов ДлительныеОперацииКлиент.ОжидатьЗавершение",
        "Прогресс передается через ДлительныеОперации.СообщитьПрогресс",
        "Пример включает клиентскую часть и серверную",
        "Устаревший ВыполнитьВФоне не предложен как основной способ"
      ],
      "expect": [
        "ДлительныеОперации\\s*\\.\\s*Выполнить(Функцию|Процедуру)",
        "ОжидатьЗавершение"
      ],
      "forbid": [
        "ФоновыеЗадания\\s*\\.\\s*Выполнить\\s*\\(",
        "ДлительныеОперации\\s*\\.\\s*ВыполнитьВФоне\\s*\\("
      ],
      "checks_bsl": true
    },
    {
      "id": "send-email",
      "prompt": "Нужно отправить письмо пользователю по email после завершения обработки заказа. Какие функции БСП использовать? Покажи пример кода.",
      "expected_output": "Пример использования подсистемы РаботаСПочтовымиСообщениями БСП: создание и отправка письма через стандартные методы библиотеки.",
      "expectations": [
        "Упомянут модуль РаботаСПочтовымиСообщениями как основной для отправки почты через БСП",
        "Показан пример с созданием объекта ИнтернетПочтовоеСообщение или использованием готового метода БСП",
        "Рекомендован поиск через ssl_search перед написанием кастомного кода",
        "Пример содержит указание на необходимость настройки учетной записи электронной почты"
      ],
      "expect": [
        "РаботаСПочтовымиСообщениями"
      ],
      "checks_bsl": true
    },
    {
      "id": "check-user-role",
      "prompt": "Как через БСП получить список ролей текущего пользователя и проверить, есть ли у него конкретная роль?",
      "expected_output": "Пример использования подсистемы Пользователи или ОбщегоНазначения: получение ролей пользователя, проверка наличия роли через РольДоступна().",
      "expectations": [
        "Показан вызов функции РольДоступна() из платформы или аналогичного метода БСП",
        "Упомянут модуль Пользователи БСП как источник API для работы с пользователями и правами",
        "Рекомендовано использовать ssl_search для поиска актуального API в версии БСП проекта",
        "Показан пример проверки прав перед выполнением привилегированной операции"
      ],
      "expect": [
        "Пользователи\\s*\\.\\s*(РолиДоступны|ЭтоПолноправныйПользователь)"
      ],
      "checks_bsl": true
    }
  ],
  "_": "Гоняются через tools/run_skill_evals.py. Поля expect и forbid - регулярные выражения по тексту ответа, checks_bsl включает сверку вызовов BSL со справочником БСП."
}

# Управление доступом

Механизм БСП, ограничивающий доступ на уровне записей и полей: профили групп
доступа, виды доступа, наборы значений доступа. Отвечает на вопрос "какие данные
видит этот пользователь", тогда как роли платформы отвечают на вопрос "какие
действия ему вообще разрешены".

Не путать с механизмом `Пользователи`: там учетные записи и текущий пользователь,
здесь права на данные.

## Модули механизма

| Модуль | Роль | Контексты |
|---|---|---|
| `УправлениеДоступом` | программный интерфейс | сервер, толстый клиент, внешнее соединение |
| `УправлениеДоступомПереопределяемый` | точка расширения: свои виды доступа и наборы значений | сервер, толстый клиент, внешнее соединение |
| `УправлениеДоступомСлужебный` и еще шесть с тем же началом | внутренняя реализация библиотеки | - |

**Публичного клиентского модуля у механизма нет.** `УправлениеДоступомСлужебныйКлиент`
и `УправлениеДоступомСлужебныйКлиентСервер` служебные, как и говорит их имя.
Проверку прав выполняет сервер, и клиент получает уже результат.

## Сценарии

### 1. Проверить право пользователя на конкретный объект

**Задача:** до выполнения действия убедиться, что у пользователя есть право на
ЭТУ запись, а не вообще на вид объекта.

**Функции:**

`УправлениеДоступом.ЕстьПраво(Право, СсылкаНаОбъект, Знач Пользователь = Неопределено) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

`УправлениеДоступом.ИзменениеРазрешено(ОписаниеДанных, Пользователь = Неопределено) Экспорт`
- функция, тот же регион.

**Параметры:**

- `Право` - `Строка`: чтение, изменение и прочие.
- `СсылкаНаОбъект` - ссылка на конкретную запись.
- `Пользователь` - `Неопределено` означает текущего.

**Пример:**

```bsl
&НаСервере
Функция МожноПравитьДокумент(Знач Ссылка)

    Возврат УправлениеДоступом.ЕстьПраво("Изменение", Ссылка);

КонецФункции
```

**Нюансы и антипаттерны:**

- Не подменять эту проверку платформенной `ПравоДоступа`: та отвечает на вопрос о
  виде объекта целиком и про ограничение на уровне записей ничего не знает.
- Не считать отсутствие права ошибкой программы: это штатный ответ, и пользователю
  показывается сообщение, а не исключение.

### 2. Проверить роль пользователя

**Задача:** ветвление логики по роли, а не по конкретному праву.

**Функции:**

`УправлениеДоступом.ЕстьРоль(Знач Роль, Знач СсылкаНаОбъект = Неопределено, Знач Пользователь = Неопределено) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

**Пример:**

```bsl
&НаСервере
Функция ЭтоКладовщик()

    Возврат УправлениеДоступом.ЕстьРоль("ДобавлениеИзменениеСкладскихДокументов");

КонецФункции
```

**Нюансы и антипаттерны:**

- Ветвление по роли - крайняя мера. Право на данные проверяется правом, а не
  ролью: роль может называться иначе во внедрении, а право останется прежним.
- Полноту прав проверяют не ролью, а `Пользователи.ЭтоПолноправныйПользователь`.

### 3. Назначить пользователю профиль группы доступа

**Задача:** при создании пользователя из кода выдать ему набор прав.

**Функции:**

`УправлениеДоступом.ВключитьПрофильПользователю(Пользователь, Профиль) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

`УправлениеДоступом.ВыключитьПрофильПользователю(Пользователь, Профиль = Неопределено) Экспорт`
- процедура, тот же регион. Без профиля выключает все.

`УправлениеДоступом.ГруппаДоступаАдминистраторы() Экспорт` - функция, тот же
регион.

**Пример:**

```bsl
&НаСервере
Процедура ВыдатьПрофильСкладовщика(Знач Пользователь)

    Профиль = Справочники.ПрофилиГруппДоступа.НайтиПоНаименованию("Кладовщик");
    Если ЗначениеЗаполнено(Профиль) Тогда
        УправлениеДоступом.ВключитьПрофильПользователю(Пользователь, Профиль);
    КонецЕсли;

КонецПроцедуры
```

**Нюансы и антипаттерны:**

- Не добавлять пользователя в группу доступа записью справочника напрямую: у
  библиотеки на это своя логика пересчета прав, и запись мимо нее оставит права
  неактуальными.
- Пересчет прав идет фоново. Сразу после назначения профиля новые ограничения
  могут еще не действовать.

### 4. Заполнить наборы значений доступа своего объекта

**Задача:** свой документ должен ограничиваться по тем же видам доступа, что и
типовые.

**Функции:**

Наборы значений доступа заполняются в модуле САМОГО объекта, процедурой
`ЗаполнитьНаборыЗначенийДоступа`, а не в переопределяемом модуле подсистемы. В
`УправлениеДоступомПереопределяемый` метода с таким именем НЕТ - там объявляют
виды доступа и списки с ограничением, а не наборы конкретного объекта.

`УправлениеДоступом.ЗаполнитьНаборыЗначенийДоступа(Знач Объект, Таблица, Знач СсылкаНаПодчиненныйОбъект = Неопределено) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

`УправлениеДоступом.ДобавитьНаборыЗначенийДоступа(Приемник, Знач Источник, Знач Умножение = Ложь, Знач Упростить = Ложь) Экспорт`
- процедура, тот же регион: складывает наборы, в том числе умножением.

`УправлениеДоступомПереопределяемый.ПриЗаполненииСписковСОграничениемДоступа(Списки) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. ХУК: им объявляют, что объект вообще
участвует в ограничении доступа.

`УправлениеДоступомПереопределяемый.ПриЗаполненииВидовДоступа(ВидыДоступа) Экспорт`
- процедура, тот же регион и та же роль: объявляет свой вид доступа.

**Нюансы и антипаттерны:**

- Не вызывать процедуры `УправлениеДоступомПереопределяемый` из прикладного кода:
  их реализуют.
- Объект, не объявленный в `ПриЗаполненииСписковСОграничениемДоступа`, наборы
  значений не получит, и ограничение на него не подействует. Ошибки при этом нет.
- Набор значений доступа пересчитывается при записи объекта. Правка данных мимо
  записи объекта оставит набор старым.

### 5. Запланировать пересчет прав после массовой правки

**Задача:** после загрузки или групповой обработки права должны пересчитаться.

**Функции:**

`УправлениеДоступом.ЗапланироватьОбновлениеДоступа(Таблица) Экспорт` - процедура,
регион `ПрограммныйИнтерфейс`. Сервер.

**Нюансы и антипаттерны:**

- Не пересчитывать права синхронно в цикле по объектам: библиотека делает это
  фоново и пакетно, а поштучный пересчет на больших объемах занимает часы.
- После планирования пересчет идет регламентным заданием. Выключенное задание -
  права не обновятся вовсе.

## Различия версий

Состав модулей в 3.1.11 и 3.2.1 совпадает - сверено по обеим поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check УправлениеДоступом.ЕстьПраво
```

# Контроль ведения учета и рассылка отчетов

Два механизма БСП, работающих в фоне и показывающих результат человеку: проверки
корректности данных с регистрацией найденных проблем и рассылка отчетов по
расписанию.

## Модули

| Модуль | Механизм | Контексты |
|---|---|---|
| `КонтрольВеденияУчета` | запуск проверок, регистрация проблем, отчет по ним | сервер, толстый клиент, внешнее соединение |
| `КонтрольВеденияУчетаПереопределяемый` | точка расширения: свои проверки | сервер, толстый клиент, внешнее соединение |
| `РассылкаОтчетов` | состав рассылки, получатели, формирование и отправка | сервер, толстый клиент, внешнее соединение |
| `РассылкаОтчетовПереопределяемый` | точка расширения рассылки | сервер, толстый клиент, внешнее соединение |

## Сценарии

### 1. Выполнить проверку данных

**Задача:** найти документы, нарушающие правило учета, и показать их
пользователю.

**Функции:**

`КонтрольВеденияУчета.ВыполнитьПроверку(Знач Проверка, Знач ПараметрыВыполненияПроверки = Неопределено, ПроверяемыеОбъекты = Неопределено) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

`КонтрольВеденияУчета.ВыполнитьПроверкиВКонтексте(КонтекстПроверокВеденияУчета) Экспорт`
- процедура, тот же регион.

`КонтрольВеденияУчета.ВидПроверки(Знач ПараметрыВыполненияПроверки, Знач ТолькоПоиск = Ложь) Экспорт`
и `КонтрольВеденияУчета.ВидыПроверок(ВидПроверок, ПоискПоТочномуСоответствию = Истина) Экспорт`
- функции, тот же регион.

**Нюансы и антипаттерны:**

- Не писать свой отчет о нарушениях: библиотека ведет регистр проблем,
  показывает их пользователю и снимает при исправлении.
- Проверка идет по расписанию либо по списку объектов. Полная проверка на большой
  базе долгая, и ее место в регламентном задании.
- Проблема снимается САМА при повторной проверке. Удалять запись вручную не надо.

### 2. Объявить свою проверку

**Задача:** правило учета, специфичное для конфигурации, должно проверяться
наравне с типовыми.

**Функции:**

Процедуры модуля `КонтрольВеденияУчетаПереопределяемый` - регион
`ПрограммныйИнтерфейс`. ХУКИ: библиотека вызывает их сама.

**Нюансы и антипаттерны:**

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

### 3. Выполнить рассылку отчетов

**Задача:** разослать отчет получателям по расписанию либо по команде.

**Функции:**

`РассылкаОтчетов.ВыполнитьРассылкуОтчетов(Рассылка, ПараметрыЖурнала = Неопределено, ДополнительныеНастройки = Неопределено) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

`РассылкаОтчетов.ВыполнитьРассылку(Отчеты, ПараметрыДоставки, НаименованиеРассылки = "", ПараметрыЖурнала = Неопределено) Экспорт`
- функция, тот же регион: разовая рассылка без сохраненной настройки.

`РассылкаОтчетов.ВыполнитьРассылкиВФоновомЗадании(ПараметрыВыполнения, АдресРезультата) Экспорт`
- процедура, тот же регион.

**Нюансы и антипаттерны:**

- Формирование отчетов и отправка долгие. Из формы это делают фоновым заданием, а
  не синхронно.
- Две функции с похожими именами делают разное: одна работает по сохраненной
  настройке рассылки, другая по переданному списку отчетов. Перепутать легко.
- Ошибка доставки одному получателю не отменяет рассылку остальным. Результат
  разбирают по журналу, а не по факту возврата.

### 4. Добавить свой тип получателей

**Задача:** рассылать не только пользователям, но и своим контрагентам.

**Функции:**

`РассылкаОтчетов.ДобавитьЭлементВТаблицуТиповПолучателей(ТаблицаТипов, ДоступныеТипы, Настройки) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер. Вызывается из точки
расширения.

**Нюансы и антипаттерны:**

- Адреса получателей берутся из контактной информации. Свой тип должен уметь ее
  отдавать, иначе рассылка найдет получателей без адресов.

## Различия версий

Состав модулей обоих механизмов в 3.1.11 и 3.2.1 совпадает - сверено по обеим
поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check РассылкаОтчетов.ВыполнитьРассылкуОтчетов
```

# Свойства: дополнительные реквизиты и сведения

Механизм БСП, позволяющий пользователю добавить объекту поля без изменения
конфигурации: дополнительные реквизиты хранятся в самом объекте, дополнительные
сведения - отдельно от него.

Разница между ними существенна. ДопРеквизит принадлежит объекту и записывается
вместе с ним; ДопСведение хранится в регистре и правится независимо, в том числе
когда сам объект править нельзя.

## Модули механизма

| Модуль | Роль | Контексты |
|---|---|---|
| `УправлениеСвойствами` | программный интерфейс сервера | сервер, толстый клиент, внешнее соединение |
| `УправлениеСвойствамиКлиент` | программный интерфейс клиента: правка значений на форме | тонкий и толстый клиент |
| `УправлениеСвойствамиПереопределяемый` | точка расширения: свои наборы свойств | сервер, толстый клиент, внешнее соединение |
| `УправлениеСвойствамиПовтИсп`, `УправлениеСвойствамиСлужебный` | внутренняя реализация библиотеки | - |

**Модуля `Свойства` не существует**, хотя подсистема называется именно так. Все
методы лежат в `УправлениеСвойствами` и его семействе.

## Сценарии

### 1. Прочитать значение дополнительного свойства

**Задача:** в отчете или в проведении использовать поле, добавленное
пользователем.

**Функции:**

`УправлениеСвойствами.ЗначениеСвойства(Объект, Свойство, КодЯзыка = "") Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

`УправлениеСвойствами.ЗначенияСвойств(ОбъектыСоСвойствами, ПолучатьДопРеквизиты = Истина, ПолучатьДопСведения = Истина, Свойства = Неопределено, КодЯзыка = "") Экспорт`
- функция, тот же регион: для нескольких объектов и свойств сразу.

**Пример:**

```bsl
&НаСервере
Функция ЗначениеДопРеквизита(Знач Ссылка, Знач Свойство)

    Возврат УправлениеСвойствами.ЗначениеСвойства(Ссылка, Свойство);

КонецФункции
```

**Нюансы и антипаттерны:**

- Не читать табличную часть дополнительных реквизитов объекта запросом напрямую:
  дополнительные СВЕДЕНИЯ там не лежат, они в отдельном регистре, и запрос их
  пропустит.
- Для списка объектов брать `ЗначенияСвойств`, а не звать одиночную функцию в
  цикле: она читает регистр на каждый вызов.

### 2. Записать значения свойств объекту

**Задача:** загрузка из внешней системы должна заполнять пользовательские поля.

**Функции:**

`УправлениеСвойствами.ЗаписатьСвойстваУОбъекта(ВладелецСвойств, ТаблицаСвойствИЗначений) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

`УправлениеСвойствами.ДобавитьЗначениеСвойства(Знач Владелец, Параметры, Иерархия = Ложь) Экспорт`
и `УправлениеСвойствами.ПараметрыДобавленияЗначенияСвойства() Экспорт`
- функции, тот же регион: добавление нового значения в список значений свойства.

**Нюансы и антипаттерны:**

- Не записывать регистр дополнительных сведений набором записей напрямую: у
  библиотеки своя логика по видам свойств и по иерархии значений.
- Значение должно быть допустимого типа для этого свойства. Библиотека проверяет
  это при записи, а прямая запись в регистр - нет.

### 3. Вывести свойства на форму

**Задача:** на форме своего объекта показать пользовательские поля так же, как в
типовых.

**Функции:**

`УправлениеСвойствами.ЗаполнитьДополнительныеРеквизитыВФорме(Форма, Объект = Неопределено, ПоляНадписей = Ложь, СкрытьУдаленные = Неопределено) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

`УправлениеСвойствами.ПеренестиЗначенияИзРеквизитовФормыВОбъект(Форма, Объект = Неопределено) Экспорт`
- процедура, тот же регион: обратный перенос перед записью.

`УправлениеСвойствамиКлиент.ОбновитьЗависимостиДополнительныхРеквизитов(Форма, Объект = Неопределено) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Клиент.

**Нюансы и антипаттерны:**

- Перенос значений с формы в объект вызывается ПЕРЕД записью. Пропуск этого шага
  выглядит как потеря введенных значений без ошибки.
- Свойства выводятся на форму динамически, элементы создаются библиотекой.
  Обращаться к ним по имени из своего кода нельзя: имена генерируемые.

### 4. Задать свои наборы свойств

**Задача:** у своего документа должны быть отдельные наборы свойств по видам
операции.

**Функции:**

`УправлениеСвойствамиПереопределяемый.ЗаполнитьНаборыСвойствОбъекта(Знач Объект, ТипСсылки, НаборыСвойств, СтандартнаяОбработка, КлючНазначения) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. ХУК.

`УправлениеСвойствамиПереопределяемый.ПриПолученииПредопределенныхНаборовСвойств(Наборы) Экспорт`
- процедура, тот же регион и та же роль.

**Нюансы и антипаттерны:**

- Не вызывать процедуры `УправлениеСвойствамиПереопределяемый` из прикладного
  кода: их реализуют.
- Хук вызывается при каждом открытии формы объекта. Запросы в нем идут на каждое
  открытие, и тяжелая выборка там заметна пользователю.

## Различия версий

Состав модулей и их экспортные методы в 3.1.11 и 3.2.1 совпадают - сверено по
обеим поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check УправлениеСвойствами.ЗначениеСвойства
```

# Адресный классификатор

Механизм БСП, работающий с государственным адресным реестром: загруженные регионы,
поиск адресных объектов, коды и наименования, проверка адреса по классификатору.

Работает в паре с контактной информацией: та хранит адрес объекта, этот проверяет
и разбирает его по реестру.

## Модули механизма

| Модуль | Роль | Контексты |
|---|---|---|
| `АдресныйКлассификатор` | программный интерфейс сервера | сервер, толстый клиент, внешнее соединение |
| `АдресныйКлассификаторКлиент` | клиентская часть | тонкий и толстый клиент |

## Сценарии

### 1. Проверить, загружен ли классификатор

**Задача:** до разбора адреса убедиться, что данные есть.

**Функции:**

`АдресныйКлассификатор.АдресныйКлассификаторЗагружен() Экспорт` - функция, регион
`ПрограммныйИнтерфейс`. Сервер.

`АдресныйКлассификатор.КоличествоЗагруженныхРегионов() Экспорт` - функция, тот же
регион.

**Нюансы и антипаттерны:**

- Классификатор грузится ПО РЕГИОНАМ, а не целиком. Загруженность вообще не
  означает, что есть нужный регион.
- Без проверки разбор адреса тихо вернет пустой результат, и адрес окажется
  введенным в свободной форме.

### 2. Перевести код региона в наименование и обратно

**Задача:** в отчете показать название субъекта по коду из адреса.

**Функции:**

`АдресныйКлассификатор.НаименованиеРегионаПоКоду(КодСубъектаРФ) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

`АдресныйКлассификатор.КодРегионаПоНаименованию(Название) Экспорт` - функция, тот
же регион.

**Нюансы и антипаттерны:**

- Не держать свой список регионов константой: коды и наименования меняются, а
  библиотека берет их из загруженного реестра.
- Поиск по наименованию неточен по природе: одно и то же название пишется
  по-разному, и пустой ответ не означает отсутствия региона.

### 3. Получить коды адреса

**Задача:** для выгрузки в госорган нужны коды адресных объектов, а не текст.

**Функции:**

`АдресныйКлассификатор.КодыАдреса(Адрес, Источник = Неопределено) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

**Нюансы и антипаттерны:**

- Адрес, введенный в свободной форме, кодов не имеет. Это видно функцией
  `УправлениеКонтактнойИнформацией.АдресВведенВСвободнойФорме`.
- Источник кодов различается между реестрами. Полагаться на источник по умолчанию
  при выгрузке в госорган нельзя.

## Различия версий

Состав модулей семейства в 3.1.11 и 3.2.1 совпадает - сверено по обеим поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check АдресныйКлассификатор.КодыАдреса
```

# Администрирование: сеансы, безопасный режим, контроль работы, копирование

Четыре механизма БСП для администратора: завершение работы пользователей,
профили безопасности и выполнение кода с разрешениями, отчеты о действиях
пользователей по журналу регистрации, резервное копирование базы.

**Имена модулей здесь расходятся с названиями подсистем сильнее всего.** Проверено
по обеим поставкам:

| Подсистема называется | А модуль называется |
|---|---|
| Завершение работы пользователей | `СоединенияИБ` |
| Профили безопасности | `РаботаВБезопасномРежиме` |
| Резервное копирование ИБ | `РезервноеКопированиеИБКлиент` и семейство |
| Контроль работы пользователей | `КонтрольРаботыПользователей` (совпадает) |

Модулей `ЗавершениеРаботыПользователей` и `ПрофилиБезопасности` в библиотеке НЕТ.

## Модули

| Модуль | Механизм | Контексты |
|---|---|---|
| `СоединенияИБ` | блокировка новых сеансов, отключение активных соединений | сервер, толстый клиент, внешнее соединение |
| `РаботаВБезопасномРежиме` | запросы разрешений на внешние ресурсы и выполнение кода с ними | сервер, толстый клиент, внешнее соединение |
| `КонтрольРаботыПользователей` | отчеты о действиях по журналу регистрации | сервер, толстый клиент, внешнее соединение |
| `РезервноеКопированиеИБКлиент` и семейство из пяти модулей | резервное копирование | клиент / сервер |
| `БлокировкаРаботыСВнешнимиРесурсами` | блокировка внешних ресурсов при копировании базы | сервер |

## Сценарии

### 1. Завершить работу пользователей перед обновлением

**Задача:** заблокировать новые сеансы и отключить активные.

**Механизм:** модуль `СоединенияИБ`, регион `ПрограммныйИнтерфейс`. Сервер.
Восемь методов: блокировка начала сеансов, перечень активных соединений,
отключение.

**Нюансы и антипаттерны:**

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

### 2. Запросить разрешение на внешний ресурс

**Задача:** обработка обращается в интернет или к файлу, а в базе включены
профили безопасности.

**Функции:**

Модуль `РаботаВБезопасномРежиме`, регион `ПрограммныйИнтерфейс`. Сервер.
Запросы на использование файлов, интернета, COM и внешних компонент, а также
выполнение кода с полученными разрешениями.

**Нюансы и антипаттерны:**

- Разрешение запрашивается ДО операции и подтверждается администратором. Код,
  идущий во внешний ресурс без запроса, при включенных профилях просто упадет.
- Не отключать профили безопасности ради работы своей обработки: это снимает
  защиту со всей базы, а не с одной операции.

### 3. Настроить регистрацию доступа к данным

**Задача:** вести учет того, кто и какие данные смотрел.

**Функции:**

`КонтрольРаботыПользователей.РегистрироватьДоступКДанным() Экспорт` - функция,
регион `ПрограммныйИнтерфейс`. Сервер.

`КонтрольРаботыПользователей.УстановитьРегистрациюДоступаКДанным(РегистрироватьДоступКДанным) Экспорт`
- процедура, тот же регион.

`КонтрольРаботыПользователей.НастройкиРегистрацииСобытийДоступаКДанным() Экспорт`
и `КонтрольРаботыПользователей.УстановитьНастройкиРегистрацииСобытийДоступаКДанным(Настройки) Экспорт`
- функция и процедура, тот же регион.

**Нюансы и антипаттерны:**

- Регистрация доступа заметно нагружает журнал. Включать ее на все объекты сразу
  не следует: настройка задается по видам событий и объектам.
- Отчеты строятся ПО ЖУРНАЛУ регистрации. Очищенный журнал означает пустой отчет,
  и это не ошибка механизма.

### 4. Резервное копирование

**Задача:** предложить пользователю сделать копию перед рискованной операцией.

**Механизм:** семейство `РезервноеКопированиеИБ`. Публичный интерфейс клиентский:
копирование это действие администратора на его рабочем месте.

**Нюансы и антипаттерны:**

- Копирование доступно не во всех вариантах работы. Проверять доступность до
  показа команды обязательно.
- На время копирования работа с внешними ресурсами блокируется отдельным
  механизмом: `БлокировкаРаботыСВнешнимиРесурсами`. Иначе восстановленная копия
  начнет слать письма и обмениваться данными как рабочая база.

## Различия версий

Состав модулей всех четырех механизмов в 3.1.11 и 3.2.1 совпадает - сверено по
обеим поставкам.

## Проверка перед использованием

Имена здесь расходятся с названиями подсистем, поэтому проверка обязательна:

```bash
python skills/1c-bsp-api/scripts/bsp-api.py module СоединенияИБ
```

# Подключаемые команды

Механизм БСП, позволяющий одной подсистеме добавить команду на форму объекта,
принадлежащего другой подсистеме: печать, отправка почтой, создание на основании,
дополнительные обработки. Форма объекта при этом ничего о них не знает.

Через этот механизм на форму попадают команды печати и команды дополнительных
обработок - они не отдельные механизмы размещения, а его потребители.

## Модули механизма

| Модуль | Роль | Контексты |
|---|---|---|
| `ПодключаемыеКоманды` | программный интерфейс сервера: сбор состава и размещение | сервер, толстый клиент, внешнее соединение |
| `ПодключаемыеКомандыКлиент` | программный интерфейс клиента: выполнение команды | тонкий и толстый клиент |
| `ПодключаемыеКомандыКлиентСервер` | общая часть | сервер и клиент |
| `ПодключаемыеКомандыПереопределяемый` | точка расширения: свои виды команд | сервер, толстый клиент, внешнее соединение |
| `ПодключаемыеКомандыГлобальный`, `...ВызовСервера`, `...ПовтИсп`, `...КлиентПовтИсп` | внутренняя реализация библиотеки | - |

## Сценарии

### 1. Подключить механизм к своей форме

**Задача:** на форме своего документа должны появиться команды печати, отправки
и дополнительных обработок.

**Функции:**

`ПодключаемыеКоманды.ПриСозданииНаСервере(Форма, Знач ПараметрыРазмещения = Неопределено) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

`ПодключаемыеКоманды.ПараметрыРазмещения() Экспорт` - функция-конструктор, тот же
регион.

**Пример:**

```bsl
&НаСервере
Процедура ПриСозданииНаСервере(Отказ, СтандартнаяОбработка)

    ПодключаемыеКоманды.ПриСозданииНаСервере(ЭтаФорма);

КонецПроцедуры
```

**Нюансы и антипаттерны:**

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

### 2. Выполнить подключаемую команду

**Задача:** обработчик команды на форме должен передать управление библиотеке.

**Функции:**

`ПодключаемыеКомандыКлиент.ВыполнитьКоманду(Форма, Команда, Источник) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Клиент.

`ПодключаемыеКомандыКлиент.НачатьВыполнениеКоманды(Форма, Команда, Знач Источник = Неопределено) Экспорт`
- процедура, тот же регион: асинхронный вариант.

`ПодключаемыеКоманды.ВыполнитьКоманду(Знач Форма, Знач ПараметрыВызова, Знач Источник = Неопределено, Результат = Неопределено) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

**Нюансы и антипаттерны:**

- Обработчик команды на форме создается библиотекой, свой писать не нужно. Своя
  реализация появляется только тогда, когда команда нетиповая.
- Клиентский и серверный `ВыполнитьКоманду` это РАЗНЫЕ процедуры с разными
  сигнатурами. Путать их легко: имена совпадают.

### 3. Обновить состав команд после записи

**Задача:** после проведения документа набор доступных команд меняется.

**Функции:**

`ПодключаемыеКомандыКлиент.ПослеЗаписи(Форма, Объект, ПараметрыЗаписи) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Клиент.

`ПодключаемыеКомандыКлиент.НачатьОбновлениеКоманд(Форма, Элемент = Неопределено, Строка = Неопределено) Экспорт`
- процедура, тот же регион.

**Нюансы и антипаттерны:**

- Без вызова после записи команды останутся в состоянии, которое было до нее:
  например печать будет недоступна у только что записанного документа.
- Обновление асинхронное. Проверять доступность команды сразу после вызова
  бессмысленно.

### 4. Ограничить видимость команды

**Задача:** команда должна показываться только для определенного вида операции.

**Функции:**

`ПодключаемыеКоманды.ДобавитьУсловиеВидимостиКоманды(Команда, Реквизит, Значение = Неопределено, Знач ВидСравнения = Неопределено) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

**Нюансы и антипаттерны:**

- Условие вычисляет библиотека по реквизиту объекта. Свой код в форме для того же
  отработает на каждое открытие, а условие - один раз на список.
- Условие видимости это не право доступа. Скрытая команда остается вызываемой,
  если пользователь дотянется до нее иначе.

### 5. Объявить свой вид подключаемых команд

**Задача:** своя подсистема должна добавлять команды на чужие формы.

**Функции:**

`ПодключаемыеКомандыПереопределяемый.ПриОпределенииВидовПодключаемыхКоманд(ВидыПодключаемыхКоманд) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. ХУК.

`ПодключаемыеКомандыПереопределяемый.ПриОпределенииКомандПодключенныхКОбъекту(НастройкиФормы, Источники, ПодключенныеОтчетыИОбработки, Команды) Экспорт`
- процедура, тот же регион и та же роль.

**Нюансы и антипаттерны:**

- Не вызывать процедуры `ПодключаемыеКомандыПереопределяемый` из прикладного
  кода: их реализуют.
- Хук вызывается для КАЖДОЙ формы, куда подключен механизм. Тяжелая работа в нем
  замедляет открытие всех таких форм, а не только своей.

## Различия версий

Состав модулей семейства в 3.1.11 и 3.2.1 совпадает - сверено по обеим поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check ПодключаемыеКоманды.ПриСозданииНаСервере
```

# Работа с файлами

Механизм БСП, присоединяющий файлы к объектам конфигурации: договор со сканом,
заказ с накладной, элемент справочника с фотографией. Хранение в базе либо в
томах на диске, версии файла, редактирование во внешней программе.

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

## Модули механизма

| Модуль | Роль | Контексты |
|---|---|---|
| `РаботаСФайлами` | программный интерфейс сервера | сервер, толстый клиент, внешнее соединение |
| `РаботаСФайламиКлиент` | программный интерфейс клиента: открытие, добавление, редактирование, сканирование | тонкий и толстый клиент |
| `РаботаСФайламиКлиентСервер` | общая часть: разбор имен, проверка расширений | сервер и клиент |
| `РаботаСФайламиПереопределяемый`, `РаботаСФайламиКлиентПереопределяемый` | точки расширения сервера и клиента | сервер / клиент |
| `РаботаСФайламиЛокализация` | национальная специфика | сервер |
| `РаботаСФайламиСлужебный` и еще восемь | внутренняя реализация библиотеки | - |

Клиентский модуль здесь БОЛЬШЕ серверного: 53 метода против 38. Работа с файлом -
действие пользователя, и почти все команды живут на клиенте.

## Сценарии

### 1. Прочитать файл, присоединенный к объекту

**Задача:** получить двоичные данные вложения, чтобы отправить его почтой или
разобрать.

**Функции:**

`РаботаСФайлами.ДвоичныеДанныеФайла(Знач ПрисоединенныйФайл, Знач ВызыватьИсключение = Истина) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

`РаботаСФайлами.ДвоичныеДанныеФайлов(Знач ПрисоединенныеФайлы, Знач ВызыватьИсключение = Истина) Экспорт`
- функция, тот же регион: для нескольких файлов сразу.

`РаботаСФайлами.ДанныеФайла(Знач ПрисоединенныйФайл, Знач ДополнительныеПараметры = Неопределено, Знач УдалитьПолучатьСсылкуНаДвоичныеДанные = Истина, Знач УдалитьДляРедактирования = Ложь) Экспорт`
- функция, тот же регион: структура со сведениями о файле, а не сами данные.

**Пример:**

```bsl
&НаСервере
Функция СодержимоеВложения(Знач ФайлСсылка)

    Возврат РаботаСФайлами.ДвоичныеДанныеФайла(ФайлСсылка, Ложь);

КонецФункции
```

**Нюансы и антипаттерны:**

- Не читать реквизит хранилища значения справочника файлов напрямую: файл может
  лежать в томе на диске, а не в базе, и в хранилище его не будет.
- Для нескольких файлов брать `ДвоичныеДанныеФайлов`, а не звать одиночную
  функцию в цикле: она ходит в тома по одному разу на файл.
- Параметр `ВызыватьИсключение` со значением `Ложь` возвращает `Неопределено`
  вместо ошибки, когда файла нет. Для фоновой обработки это нужнее исключения.

### 2. Присоединить файл к объекту из кода

**Задача:** загрузка из внешней системы должна класть документы к заказу.

**Функции:**

`РаботаСФайлами.ДобавитьФайл(ПараметрыФайла, Знач АдресФайлаВоВременномХранилище, Знач АдресВременногоХранилищаТекста = "", Знач Описание = "", Знач НоваяСсылкаНаФайл = Неопределено) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

`РаботаСФайлами.ДобавитьФайлСДиска(ВладелецФайлов, ПутьКФайлуНаДиске) Экспорт`
- функция, тот же регион.

`РаботаСФайлами.НоваяСсылкаНаФайл(ВладелецФайлов, ИмяСправочника = Неопределено) Экспорт`
- функция, тот же регион.

**Нюансы и антипаттерны:**

- Не создавать элемент справочника присоединенных файлов записью объекта: мимо
  библиотеки не запишутся версия, размер, признак хранения в томе.
- Владелец должен допускать присоединение файлов - проверяется функцией
  `РаботаСФайлами.КОбъектуМожноПрисоединятьФайлы`. Иначе файл повиснет без хозяина.
- `ДобавитьФайлСДиска` читает путь НА СЕРВЕРЕ. Для файла с машины пользователя
  сначала помещают его во временное хранилище на клиенте.

### 3. Открыть файл у пользователя

**Задача:** по команде формы показать вложение во внешней программе.

**Функции:**

`РаботаСФайламиКлиент.ОткрытьФайл(Знач ДанныеФайла, Знач ДляРедактирования = Ложь) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Тонкий и толстый клиент.

`РаботаСФайламиКлиент.ДанныеФайла(Знач ФайлСсылка, Знач ИдентификаторФормы = Неопределено, Знач ПолучатьСсылкуНаДвоичныеДанные = Истина, Знач ДляРедактирования = Ложь) Экспорт`
- функция, тот же регион.

`РаботаСФайламиКлиент.ОткрытьКаталогФайла(ДанныеФайла) Экспорт` - процедура, тот
же регион.

**Пример:**

```bsl
&НаКлиенте
Процедура ОткрытьВложение(Команда)

    ДанныеФайла = РаботаСФайламиКлиент.ДанныеФайла(Элементы.Файлы.ТекущаяСтрока,
        УникальныйИдентификатор);
    РаботаСФайламиКлиент.ОткрытьФайл(ДанныеФайла);

КонецПроцедуры
```

**Нюансы и антипаттерны:**

- Не звать серверный `РаботаСФайлами.ДанныеФайла` из клиентского обработчика: у
  него контексты сервера, толстого клиента и внешнего соединения. Для клиента
  есть одноименная функция в модуле с суффиксом `Клиент`, и сигнатуры у них
  РАЗНЫЕ.
- Идентификатор формы передается, чтобы данные во временном хранилище жили,
  пока открыта форма. Без него ссылка протухнет.

### 4. Добавить файл действием пользователя

**Задача:** кнопка на форме, открывающая диалог выбора файла.

**Функции:**

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

`РаботаСФайламиКлиент.ДобавитьФайлы(Знач ВладелецФайла, Знач ИдентификаторФормы, Знач Фильтр = "", ГруппаФайлов = Неопределено, ОбработчикРезультата = Неопределено) Экспорт`
- процедура, тот же регион: несколько файлов сразу.

`РаботаСФайламиКлиент.ДобавитьСоСканера(ПараметрыДобавления, ПараметрыСканирования = Неопределено) Экспорт`
- процедура, тот же регион.

**Нюансы и антипаттерны:**

- Работа асинхронная: результат приходит в обработчик оповещения, а не
  возвращается из процедуры. Код после вызова выполняется ДО того, как
  пользователь выбрал файл.
- Не собирать диалог выбора файла самостоятельно: библиотека проверяет
  расширение, размер и настройки хранения, а свой диалог этого не делает.

### 5. Ограничить, какие файлы принимаются

**Задача:** запретить вложения сверх размера или с опасным расширением.

**Функции:**

`РаботаСФайлами.МаксимальныйРазмерФайла() Экспорт` и
`РаботаСФайлами.МаксимальныйРазмерФайлаОбщий() Экспорт` - функции, регион
`ПрограммныйИнтерфейс`. Сервер.

`РаботаСФайлами.НастройкиРаботыСФайлами() Экспорт` - функция, тот же регион.

`РаботаСФайламиПереопределяемый.ПриОпределенииНастроек(Настройки) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. ХУК.

**Нюансы и антипаттерны:**

- Не проверять размер и расширение своим кодом до вызова библиотеки: настройки
  меняются администратором, и своя проверка разойдется с настройкой.
- Не вызывать процедуры `РаботаСФайламиПереопределяемый` из прикладного кода: их
  реализуют.

## Различия версий

В 3.2.1 появился служебный модуль `РаботаСФайламиВХранилищеДвоичныхДанныхСлужебный`,
которого нет в 3.1.11 - сверено по обеим поставкам. Модуль служебный, на
прикладной код это не влияет, но объясняет разницу в составе семейства.

Состав публичных модулей и их экспортных методов в этих версиях совпадает.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check РаботаСФайлами.ДвоичныеДанныеФайла
```

# Запрет редактирования реквизитов объектов

Механизм БСП, блокирующий на форме ключевые реквизиты после того, как объект
проведен или уже использован: организация, склад, договор. Пользователь видит
кнопку разблокировки и снимает запрет осознанно, а не правит поле случайно.

Не путать с датами запрета изменения: там запрет по периоду для всего объекта,
здесь блокировка отдельных полей на форме.

## Модули механизма

| Модуль | Роль | Контексты |
|---|---|---|
| `ЗапретРедактированияРеквизитовОбъектов` | программный интерфейс сервера | сервер, толстый клиент, внешнее соединение |
| `ЗапретРедактированияРеквизитовОбъектовКлиент` | программный интерфейс клиента: разблокировка на форме | тонкий и толстый клиент |
| `ЗапретРедактированияРеквизитовОбъектовПереопределяемый` | точка расширения: свои запрещенные реквизиты | сервер, толстый клиент, внешнее соединение |
| `ЗапретРедактированияРеквизитовОбъектовСлужебный`, `...СлужебныйКлиент` | внутренняя реализация библиотеки | - |

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

## Сценарии

### 1. Заблокировать реквизиты на форме объекта

**Задача:** после проведения документа ключевые поля должны стать недоступными.

**Функции:**

`ЗапретРедактированияРеквизитовОбъектов.ЗаблокироватьРеквизиты(Форма, ГруппаДляКнопкиЗапрета = Неопределено, ЗаголовокКнопкиЗапрета = "", Объект = Неопределено) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

**Пример:**

```bsl
&НаСервере
Процедура ПриСозданииНаСервере(Отказ, СтандартнаяОбработка)

    ЗапретРедактированияРеквизитовОбъектов.ЗаблокироватьРеквизиты(ЭтаФорма);

КонецПроцедуры
```

**Нюансы и антипаттерны:**

- Вызов идет в `ПриСозданииНаСервере` формы: библиотека добавляет на форму кнопку
  разблокировки, а элементы к моменту открытия должны быть на месте.
- Не гасить доступность полей своим кодом: тогда пользователь не получит кнопку
  разблокировки и не сможет исправить ошибку ввода вовсе.

### 2. Объявить, какие реквизиты блокируются

**Задача:** для своего документа задать перечень ключевых полей.

**Функции:**

`ЗапретРедактированияРеквизитовОбъектовПереопределяемый.ПриОпределенииОбъектовСЗаблокированнымиРеквизитами(Объекты) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. ХУК.

`ЗапретРедактированияРеквизитовОбъектовПереопределяемый.ПриОпределенииЗаблокированныхРеквизитов(ИмяОбъектаМетаданных, ЗаблокированныеРеквизиты) Экспорт`
- процедура, тот же регион и та же роль.

`ЗапретРедактированияРеквизитовОбъектов.НовыйБлокируемыйРеквизит() Экспорт`
- функция-конструктор, регион `ПрограммныйИнтерфейс`.

`ЗапретРедактированияРеквизитовОбъектов.БлокируемыеРеквизитыОбъекта(ИмяОбъекта) Экспорт`
- функция, тот же регион: что уже объявлено.

**Пример:**

```bsl
// Модуль ЗапретРедактированияРеквизитовОбъектовПереопределяемый, тело хука.
Процедура ПриОпределенииЗаблокированныхРеквизитов(ИмяОбъектаМетаданных, ЗаблокированныеРеквизиты) Экспорт

    Если ИмяОбъектаМетаданных = "Документ.РасходТовара" Тогда
        Реквизит = ЗапретРедактированияРеквизитовОбъектов.НовыйБлокируемыйРеквизит();
        Реквизит.Имя = "Организация";
        ЗаблокированныеРеквизиты.Добавить(Реквизит);
    КонецЕсли;

КонецПроцедуры
```

**Нюансы и антипаттерны:**

- Объект должен быть назван в ОБОИХ хуках: сначала в перечне объектов, затем в
  перечне его реквизитов. Пропуск первого выглядит как работающий механизм без
  блокировок.
- Не вызывать процедуры переопределяемого модуля из прикладного кода: их
  реализуют.

### 3. Разблокировать реквизиты по действию пользователя

**Задача:** своя команда должна снимать запрет так же, как типовая кнопка.

**Функции:**

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

`ЗапретРедактированияРеквизитовОбъектовКлиент.УстановитьДоступностьЭлементовФормы(Знач Форма, Знач Реквизиты = Неопределено) Экспорт`
- процедура, тот же регион.

`ЗапретРедактированияРеквизитовОбъектовКлиент.Реквизиты(Знач Форма, Знач ТолькоЗаблокированные = Истина, ТолькоВидимые = Истина) Экспорт`
- функция, тот же регион.

**Нюансы и антипаттерны:**

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

## Различия версий

Состав модулей и их экспортные методы в 3.1.11 и 3.2.1 совпадают - сверено по
обеим поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check ЗапретРедактированияРеквизитовОбъектов.ЗаблокироватьРеквизиты
```

# Базовая функциональность

Базовые модули библиотеки, на которые опираются остальные механизмы: чтение реквизитов объектов без чтения самих объектов, сообщения
пользователю, работа с коллекциями, свойства сеанса и окружения, безопасный режим
выполнения. Самый большой механизм БСП - 211 методов только в серверном модуле.

## Модули механизма

| Модуль | Роль | Контексты |
|---|---|---|
| `ОбщегоНазначения` | базовый серверный модуль, 211 методов | сервер, толстый клиент, внешнее соединение |
| `ОбщегоНазначенияКлиентСервер` | то, что работает и на клиенте: коллекции, пути, отборы, адреса почты | сервер и клиент |
| `ОбщегоНазначенияКлиент` | клиентские свойства сеанса, оповещения, типовые диалоги | тонкий и толстый клиент |
| `ОбщегоНазначенияПереопределяемый` | точки расширения ядра, переименования объектов при обновлении | сервер, толстый клиент, внешнее соединение |
| `ОбщегоНазначенияВызовСервера` | вызов с клиента напрямую | сервер |

**Суффикс здесь особенно важен.** У одноименных методов разных модулей бывают
разные сигнатуры и разное поведение, и выбор модуля определяется тем, откуда идет
вызов, а не тем, что удобнее написать.

## Сценарии

### 1. Прочитать реквизит объекта, не читая объект

**Задача:** узнать одно поле документа в цикле или в отчете, не поднимая весь
объект из базы.

**Функции:**

`ОбщегоНазначения.ЗначениеРеквизитаОбъекта(Ссылка, ИмяРеквизита, ВыбратьРазрешенные = Ложь) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

`ОбщегоНазначения.ЗначенияРеквизитовОбъекта(Ссылка, Знач Реквизиты, ВыбратьРазрешенные = Ложь) Экспорт`
- функция, тот же регион: несколько реквизитов одного объекта.

`ОбщегоНазначения.ЗначенияРеквизитовОбъектов(Знач Ссылки, Знач Реквизиты, Знач ВыбратьРазрешенные = Ложь) Экспорт`
- функция, тот же регион: несколько реквизитов у СПИСКА объектов, одним запросом.

**Пример:**

```bsl
&НаСервере
Функция ОрганизацииДокументов(Знач Ссылки)

    Возврат ОбщегоНазначения.ЗначенияРеквизитовОбъектов(Ссылки, "Организация");

КонецФункции
```

**Нюансы и антипаттерны:**

- Не писать обращение вида точка-реквизит по ссылке в цикле: каждое обращение это отдельное чтение
  объекта из базы. На сотне строк разница уже заметна, на тысячах - критична.
- Для СПИСКА объектов брать `ЗначенияРеквизитовОбъектов` во множественном числе:
  одиночная функция в цикле сделает столько запросов, сколько объектов. Имена
  трех функций различаются одной буквой, и перепутать их легко.

### 2. Сообщить пользователю

**Задача:** показать сообщение, привязанное к полю формы, и прервать запись.

**Функции:**

`ОбщегоНазначения.СообщитьПользователю(Знач ТекстСообщенияПользователю, Знач КлючДанных = Неопределено, Знач Поле = "", Знач ПутьКДанным = "", Отказ = Ложь) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

`ОбщегоНазначенияКлиент.СообщитьПользователю(...)` - парная процедура для клиента,
тот же регион.

**Пример:**

```bsl
// Модуль объекта документа.
Процедура ОбработкаПроверкиЗаполнения(Отказ, ПроверяемыеРеквизиты)

    Если Не ЗначениеЗаполнено(Контрагент) Тогда
        ОбщегоНазначения.СообщитьПользователю(
            "Не заполнен контрагент", ЭтотОбъект, "Контрагент", , Отказ);
    КонецЕсли;

КонецПроцедуры
```

**Нюансы и антипаттерны:**

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

### 3. Работа с коллекциями

**Задача:** объединить структуры, дополнить массив, выгрузить колонку таблицы.

**Функции:**

`ОбщегоНазначенияКлиентСервер.ДополнитьМассив(МассивПриемник, МассивИсточник, ТолькоУникальныеЗначения = Ложь) Экспорт`,
`ОбщегоНазначенияКлиентСервер.ДополнитьСтруктуру(Приемник, Источник, Заменять = Неопределено) Экспорт`,
`ОбщегоНазначенияКлиентСервер.ДополнитьСоответствие(Приемник, Источник, Заменять = Неопределено) Экспорт`,
`ОбщегоНазначенияКлиентСервер.ДополнитьТаблицу(ТаблицаИсточник, ТаблицаПриемник) Экспорт`
- процедуры, регион `ПрограммныйИнтерфейс`. Доступны и на клиенте, и на сервере.

`ОбщегоНазначения.ВыгрузитьКолонку(КоллекцияСтрок, ИмяКолонки, ТолькоУникальныеЗначения = Ложь) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

**Нюансы и антипаттерны:**

- **Функции `КопироватьРекурсивно` в БСП НЕТ**, проверено. Имя выглядит
  правдоподобно и встречается в чужих подсказках, в том числе в прежней редакции
  описания этого скила. Глубокая копия структуры, соответствия или массива
  делается функцией `ОбщегоНазначения.СкопироватьРекурсивно(Источник, ФиксироватьДанные = Неопределено) Экспорт`
  - разница в одной приставке, и она решает.
- Коллекционные процедуры лежат в `КлиентСервер`, а не в серверном модуле:
  серверный вызов ради них не нужен.

### 4. Выполнить сторонний код в безопасном режиме

**Задача:** исполнить алгоритм из настройки или из внешней обработки, не дав ему
доступа к файловой системе.

**Функции:**

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

`ОбщегоНазначения.ВыполнитьМетодКонфигурации(Знач ИмяМетода, Знач Параметры = Неопределено, ЭтоФункция = Ложь) Экспорт`
- функция, тот же регион.

**Нюансы и антипаттерны:**

- Не звать платформенный `Выполнить` напрямую для стороннего кода: безопасный
  режим и профили безопасности при этом не действуют.
- У `ВыполнитьМетодКонфигурации` между версиями 3.1.11 и 3.2.1 изменилась форма:
  она стала функцией. Код, написанный по новой сигнатуре, на старой версии
  отработает иначе - смотреть карточку метода в справочнике перед использованием.

### 5. Свойства сеанса и окружения

**Задача:** ветвление по режиму работы: файловая база, модель сервиса, разделение
данных.

**Функции:**

`ОбщегоНазначения.РазделениеВключено() Экспорт`,
`ОбщегоНазначения.ИнформационнаяБазаФайловая() Экспорт`,
`ОбщегоНазначения.ЭтоВебКлиент() Экспорт` - функции, регион
`ПрограммныйИнтерфейс`. Часть из них есть и в клиентском модуле.

**Нюансы и антипаттерны:**

- Не определять режим работы разбором строки соединения: библиотека учитывает и
  модель сервиса, и внешнее соединение.
- Клиентские и серверные варианты этих функций возвращают одно и то же, но
  вызываются из своего контекста. Серверный вызов с клиента ради них не нужен.

## Различия версий

`ОбщегоНазначения.ВыполнитьМетодКонфигурации` между 3.1.11 и 3.2.1 сменила форму:
из процедуры стала функцией. Это ломающее изменение, и справочник `1c-bsp-api`
помечает такие методы отдельно.

Состав модулей семейства в этих версиях совпадает.

## Проверка перед использованием

Модуль большой, и похожие имена в нем встречаются часто. Проверять обязательно:

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check ОбщегоНазначения.ЗначенияРеквизитовОбъектов
```

# Массовые операции с данными

Четыре механизма БСП, работающих с данными пачками: загрузка из файла в
справочники, групповое изменение реквизитов, выгрузка объектов в файлы, отчет о
структуре подчиненности документов.

## Модули

| Модуль | Механизм | Контексты |
|---|---|---|
| `ЗагрузкаДанныхИзФайла` | загрузка табличных данных в справочники с сопоставлением | сервер, толстый клиент, внешнее соединение |
| `ЗагрузкаДанныхИзФайлаКлиентСервер` | общие правила разбора загружаемых данных | сервер и клиент |
| `ГрупповоеИзменениеОбъектовКлиент` | клиентская часть группового изменения | тонкий и толстый клиент |
| `ГрупповоеИзменениеОбъектовПереопределяемый` | точка расширения группового изменения | сервер, толстый клиент, внешнее соединение |
| `ВыгрузкаОбъектовВФайлы` | выгрузка объектов в файлы для последующей загрузки | сервер, толстый клиент, внешнее соединение |
| `СтруктураПодчиненностиПереопределяемый` | точка расширения отчета о связях документов | сервер, толстый клиент, внешнее соединение |

**У группового изменения и структуры подчиненности в публичном интерфейсе нет
серверного модуля без суффикса.** У первого доступны клиентская часть и точка
расширения, у второй только точка расширения: сами механизмы работают обработкой
и отчетом, а не вызовами из прикладного кода.

## Сценарии

### 1. Описать, что можно загружать из файла

**Задача:** свой справочник должен принимать загрузку из таблицы.

**Функции:**

`ЗагрузкаДанныхИзФайла.ОписаниеЗагружаемыхДанныхДляСправочников(ЗагружаемыеДанные, ОписаниеТипаОбъектаСопоставления, ЗаголовокКолонкиОбъектаСопоставления) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

`ЗагрузкаДанныхИзФайла.НастройкиЗагрузкиДанных() Экспорт` - функция-конструктор,
тот же регион.

**Нюансы и антипаттерны:**

- Не писать свой разбор таблицы: библиотека берет на себя сопоставление колонок,
  распознавание существующих элементов и разбор неоднозначностей.
- Колонка сопоставления это то, по чему строка файла узнается в базе. Без нее
  загрузка создаст дубли вместо обновления.

### 2. Разобрать неоднозначности загрузки

**Задача:** строка файла подошла к нескольким элементам справочника.

**Функции:**

`ЗагрузкаДанныхИзФайла.НовыйСписокНеоднозначностей() Экспорт` - функция, регион
`ПрограммныйИнтерфейс`. Сервер.

`ЗагрузкаДанныхИзФайла.ЗаписатьСвойстваОбъекта(СсылкаНаОбъект, СтрокаТаблицы) Экспорт`
- процедура, тот же регион.

**Нюансы и антипаттерны:**

- Неоднозначность это не ошибка файла: одинаковые наименования у разных элементов
  штатны. Решение принимает пользователь, и механизм для этого есть.
- Молчаливый выбор первого подходящего элемента дает загрузку не туда, и это
  всплывает много позже.

### 3. Выгрузить объекты в файлы

**Задача:** сохранить пачку объектов в файлы заданного формата.

**Функции:**

`ВыгрузкаОбъектовВФайлы.СохранитьПоФорматуВФайл(КомандыВыгрузки, СписокОбъектов, НастройкиСохранения) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер. Публичный интерфейс механизма
состоит из одного метода.

**Нюансы и антипаттерны:**

- Не путать с обменом данными: здесь файлы для человека либо для внешней системы,
  а не сообщение синхронизации.
- Выгрузка на большом списке долгая. Ее место - фоновое задание.

### 4. Вмешаться в отчет о структуре подчиненности

**Задача:** в дереве связанных документов показать свои объекты по-своему.

**Функции:**

`СтруктураПодчиненностиПереопределяемый.ПередВыводомСвязанногоОбъекта(Объект, СвойстваОбъекта, Отказ) Экспорт`
и `СтруктураПодчиненностиПереопределяемый.ПриПолученииПредставления(ТипДанных, Данные, Представление, СтандартнаяОбработка) Экспорт`
- процедуры, регион `ПрограммныйИнтерфейс`. ХУКИ.

**Нюансы и антипаттерны:**

- Не вызывать процедуры переопределяемого модуля из прикладного кода: их
  реализуют.
- Хуки вызываются на КАЖДЫЙ узел дерева. Запрос внутри них дает столько запросов,
  сколько связанных документов.

### 5. Дополнить групповое изменение

**Задача:** свой объект должен поддерживать групповую правку реквизитов.

**Функции:**

Процедуры модуля `ГрупповоеИзменениеОбъектовПереопределяемый` - регион
`ПрограммныйИнтерфейс`. ХУКИ.

`ГрупповоеИзменениеОбъектовКлиент` - клиентская часть, вызывается из формы.

**Нюансы и антипаттерны:**

- Групповое изменение записывает объекты по одному, со всеми проверками и
  подписками. Это не пакетная запись, и на больших списках она долгая.

## Различия версий

Состав модулей всех четырех механизмов в 3.1.11 и 3.2.1 совпадает - сверено по
обеим поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check ЗагрузкаДанныхИзФайла.НастройкиЗагрузкиДанных
```

# Бизнес-процессы и задачи

Механизм БСП поверх бизнес-процессов и задач платформы: адресация задач по ролям
и объектам адресации, отложенный старт процессов, выполнение задач, связь ведущих
и подчиненных процессов.

## Модули механизма

| Модуль | Роль | Контексты |
|---|---|---|
| `БизнесПроцессыИЗадачиСервер` | программный интерфейс сервера, 72 метода | сервер, толстый клиент, внешнее соединение |
| `БизнесПроцессыИЗадачиКлиент` | программный интерфейс клиента: команды на форме | тонкий и толстый клиент |
| `БизнесПроцессыИЗадачиПереопределяемый` | точка расширения | сервер, толстый клиент, внешнее соединение |

**Модуля `БизнесПроцессыИЗадачи` без суффикса не существует**: программный
интерфейс лежит в `БизнесПроцессыИЗадачиСервер`.

## Сценарии

### 1. Выполнить задачу из кода

**Задача:** автоматически закрыть задачу по наступлению события.

**Функции:**

`БизнесПроцессыИЗадачиСервер.ВыполнитьЗадачу(ЗадачаСсылка, ДействиеПоУмолчанию = Ложь) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

**Нюансы и антипаттерны:**

- Не записывать реквизит выполнения задачи объектом: тогда бизнес-процесс не
  продвинется по маршруту и повиснет.
- Выполнение задачи двигает процесс дальше и может создать новые задачи. Это
  не запись одной записи, а шаг маршрута.

### 2. Найти исполнителей по адресации

**Задача:** понять, кому адресована задача роли.

**Функции:**

`БизнесПроцессыИЗадачиСервер.ГруппаИсполнителейЗадач(РольИсполнителя, ОсновнойОбъектАдресации, ДополнительныйОбъектАдресации) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

**Нюансы и антипаттерны:**

- Адресация трехмерная: роль плюс два объекта адресации. Поиск исполнителя только
  по роли дает не тот состав.
- Пустой объект адресации это не ошибка, а более широкая адресация. Трактовать
  его как отсутствие исполнителей неверно.

### 3. Запустить процесс отложенно

**Задача:** процесс должен стартовать не сейчас, а в назначенную дату.

**Функции:**

`БизнесПроцессыИЗадачиСервер.ДобавитьПроцессДляОтложенногоСтарта(Процесс, ДатаСтарта) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

`БизнесПроцессыИЗадачиСервер.ДатаОтложенногоСтартаПроцесса(БизнесПроцесс) Экспорт`
- функция, тот же регион.

**Нюансы и антипаттерны:**

- Отложенный старт выполняется регламентным заданием. Выключенное задание -
  процессы не стартуют, и это не видно до срока.
- Не заводить свой механизм отложенного запуска через реквизит с датой: у
  библиотеки для этого есть очередь и обработка ошибок старта.

### 4. Разобрать связи процессов

**Задача:** от задачи дойти до породившего ее процесса и обратно.

**Функции:**

`БизнесПроцессыИЗадачиСервер.БизнесПроцессыВедущейЗадачи(ЗадачаСсылка, ДляИзменения = Ложь) Экспорт`
и `БизнесПроцессыИЗадачиСервер.БизнесПроцессыГлавнойЗадачи(ЗадачаСсылка, ДляИзменения = Ложь) Экспорт`
- функции, регион `ПрограммныйИнтерфейс`. Сервер.

`БизнесПроцессыИЗадачиСервер.ДатаЗавершенияБизнесПроцесса(БизнесПроцессСсылка) Экспорт`
- функция, тот же регион.

**Нюансы и антипаттерны:**

- Ведущая задача и главная задача это РАЗНЫЕ связи, и функции для них разные.
  Имена похожи, смысл отличается.
- Параметр `ДляИзменения` ставит блокировку. Без нужды его не включают: лишние
  блокировки на маршруте дают взаимные ожидания.

## Различия версий

Состав модулей семейства в 3.1.11 и 3.2.1 совпадает - сверено по обеим поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check БизнесПроцессыИЗадачиСервер.ВыполнитьЗадачу
```

# Обновление конфигурации

Механизм БСП, доставляющий новую версию конфигурации: поиск обновлений на
сервисе, установка из файла, резервная копия перед установкой, перезапуск.

Не путать с обновлением версии информационной базы: то переносит ДАННЫЕ под новую
версию и работает после установки. Это доставляет саму версию.

## Модули механизма

| Модуль | Роль | Контексты |
|---|---|---|
| `ОбновлениеКонфигурации` | программный интерфейс сервера | сервер, толстый клиент, внешнее соединение |
| `ОбновлениеКонфигурацииКлиент` | программный интерфейс клиента: помощник и перезапуск | тонкий и толстый клиент |
| остальные из четырех модулей семейства | внутренняя реализация библиотеки | - |

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

## Сценарии

### 1. Показать пользователю поиск и установку обновлений

**Задача:** своя команда должна открывать типового помощника обновления.

**Функции:**

`ОбновлениеКонфигурацииКлиент.ПоказатьПоискИУстановкуОбновлений(ПараметрыУстановкиОбновлений = Неопределено) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Тонкий и толстый клиент.

`ОбновлениеКонфигурацииКлиент.ПоддерживаетсяУстановкаОбновлений() Экспорт`
- функция, тот же регион.

**Пример:**

```bsl
&НаКлиенте
Процедура ПроверитьОбновления(Команда)

    Если ОбновлениеКонфигурацииКлиент.ПоддерживаетсяУстановкаОбновлений() Тогда
        ОбновлениеКонфигурацииКлиент.ПоказатьПоискИУстановкуОбновлений();
    КонецЕсли;

КонецПроцедуры
```

**Нюансы и антипаттерны:**

- Проверять поддержку обязательно: в клиент-серверном варианте и в модели сервиса
  установка обновлений недоступна, и команда должна быть скрыта, а не падать.
- Не собирать свой помощник установки: библиотека делает резервную копию,
  завершает сеансы и перезапускает программу, и повторить это своим кодом
  безопасно не выйдет.

### 2. Предложить резервную копию перед установкой

**Задача:** до обновления дать пользователю сделать копию базы.

**Функции:**

`ОбновлениеКонфигурацииКлиент.ПоказатьРезервноеКопирование(ПараметрыРезервногоКопирования, ОписаниеОповещения) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Клиент.

**Нюансы и антипаттерны:**

- Работа асинхронная: результат приходит в оповещение. Продолжать установку в
  коде сразу после вызова нельзя, копия еще не сделана.
- Резервное копирование это отдельный механизм библиотеки. Здесь только вызов его
  помощника из сценария обновления.

### 3. Узнать, менялись ли исправления конфигурации

**Задача:** понять, применялись ли к конфигурации патчи, до принятия решения об
обновлении.

**Функции:**

`ОбновлениеКонфигурации.ИсправленияИзменены(ТолькоПроверка = Ложь) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

**Нюансы и антипаттерны:**

- Параметр `ТолькоПроверка` со значением `Истина` не меняет состояние, а лишь
  отвечает на вопрос. По умолчанию функция состояние МЕНЯЕТ - это неочевидно из
  имени.

## Различия версий

Состав модулей семейства в 3.1.11 и 3.2.1 совпадает - сверено по обеим поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check ОбновлениеКонфигурацииКлиент.ПоказатьПоискИУстановкуОбновлений
```

# Контактная информация

Механизм БСП, хранящий адреса, телефоны и почту объектов в отдельном регистре, а
не реквизитами: у одного контрагента бывает несколько адресов разных видов, и
структура адреса зависит от страны.

## Модули механизма

| Модуль | Роль | Контексты |
|---|---|---|
| `УправлениеКонтактнойИнформацией` | программный интерфейс сервера | сервер, толстый клиент, внешнее соединение |
| `УправлениеКонтактнойИнформациейКлиент` | программный интерфейс клиента: ввод и правка на форме, переходы | тонкий и толстый клиент |
| `УправлениеКонтактнойИнформациейЛокализация` | национальная специфика | сервер |

## Сценарии

### 1. Прочитать контактную информацию объекта

**Задача:** взять адрес контрагента для печатной формы или письма.

**Функции:**

`УправлениеКонтактнойИнформацией.ВидыКонтактнойИнформацииОбъекта(ВладелецКонтактнойИнформации, ТипКонтактнойИнформации = Неопределено) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

`УправлениеКонтактнойИнформацией.ВидКонтактнойИнформацииПоИмени(Имя) Экспорт`
- функция, тот же регион.

**Нюансы и антипаттерны:**

- Не читать регистр контактной информации запросом напрямую: значение хранится и
  представлением, и разобранными полями, и правила разбора зависят от вида и
  страны.
- У объекта бывает несколько значений одного вида. Брать первое попавшееся
  неверно: нужен вид, а при нескольких - явное правило выбора.

### 2. Записать адрес или телефон из кода

**Задача:** загрузка из внешней системы должна заполнять контакты.

**Функции:**

`УправлениеКонтактнойИнформацией.ДобавитьКонтактнуюИнформацию(СсылкаИлиОбъект, ЗначениеИлиПредставление, ВидКонтактнойИнформации, Дата = Неопределено, Замещать = Истина, РаспознатьАдрес = Истина) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

**Нюансы и антипаттерны:**

- Параметр `Замещать` по умолчанию ИСТИНА: прежнее значение того же вида
  затирается. Для истории адресов его передают явно.
- `РаспознатьАдрес` включает разбор строки по адресному классификатору. На
  массовой загрузке это заметно по времени, и его отключают осознанно.
- Не записывать набор записей регистра самостоятельно: тогда не заполнятся
  разобранные поля, и отбор по региону или городу перестанет работать.

### 3. Вывести контактную информацию на форму

**Задача:** на форме своего справочника показать блок контактов так же, как в
типовых.

**Функции:**

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

**Нюансы и антипаттерны:**

- Элементы блока создаются библиотекой динамически. Обращаться к ним по имени из
  своего кода нельзя: имена генерируемые.
- Инициализация отложенная: блок появляется не мгновенно, и код, ожидающий
  элементы сразу после вызова, их не найдет.

### 4. Проверить и разобрать адрес

**Задача:** понять, введен ли адрес по классификатору или произвольной строкой.

**Функции:**

`УправлениеКонтактнойИнформацией.АдресВведенВСвободнойФорме(Знач КонтактнаяИнформация) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

**Нюансы и антипаттерны:**

- Адрес в свободной форме не имеет разобранных полей: отбор по региону его не
  найдет, и в отчетах он выпадает молча.
- Проверять корректность адреса своим кодом бессмысленно: правила зависят от
  страны и версии классификатора.

## Различия версий

Состав модулей семейства в 3.1.11 и 3.2.1 совпадает - сверено по обеим поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check УправлениеКонтактнойИнформацией.ДобавитьКонтактнуюИнформацию
```

# Валюты, банки, графики и календари

Четыре механизма БСП, объединенные тем, что все они дают справочные данные и
расчеты по ним: курсы валют, классификатор банков, графики работы организации,
производственный календарь.

**Имена модулей здесь не совпадают с названиями подсистем** - это главное расхождение
в теме. Подсистема называется "Валюты", а модуль `РаботаСКурсамиВалют`; подсистема
"Банки", а модуль `РаботаСБанками`. Модулей `Валюты` и `Банки` в библиотеке НЕТ,
проверено по обеим поставкам.

## Модули

| Модуль | Механизм | Контексты |
|---|---|---|
| `РаботаСКурсамиВалют` | курсы валют: загрузка, пересчет, сумма прописью | сервер, толстый клиент, внешнее соединение |
| `РаботаСКурсамиВалютЛокализация` | национальная специфика курсов | сервер |
| `РаботаСБанками` | классификатор банков: поиск по БИК и корсчету | сервер, толстый клиент, внешнее соединение |
| `РаботаСБанкамиПереопределяемый` | точка расширения классификатора | сервер |
| `ГрафикиРаботы` | графики работы организации, расчет дат по графику | сервер, толстый клиент, внешнее соединение |
| `КалендарныеГрафики` | производственный календарь, рабочие даты | сервер, толстый клиент, внешнее соединение |

## Сценарии

### 1. Пересчитать сумму в другую валюту

**Задача:** привести сумму документа к валюте учета на дату документа.

**Функции:**

`РаботаСКурсамиВалют.ПересчитатьВВалюту(Сумма, ИсходнаяВалюта, НоваяВалюта, Дата) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

`РаботаСКурсамиВалют.ПолучитьКурсВалюты(Валюта, ДатаКурса) Экспорт` - функция, тот
же регион.

**Нюансы и антипаттерны:**

- Не читать регистр курсов валют запросом и не делить самостоятельно: курс имеет
  кратность, и деление без нее дает неверный результат.
- Курс берется НА ДАТУ. Пересчет по текущему курсу задним числом искажает
  историю.

### 2. Сумма прописью

**Задача:** в печатной форме вывести сумму словами с валютой.

**Функции:**

`РаботаСКурсамиВалют.СформироватьСуммуПрописью(СуммаЧислом, Валюта, БезДробнойЧасти = Ложь, Знач КодЯзыка = Неопределено, ДробнаяЧастьПрописью = Ложь) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

**Нюансы и антипаттерны:**

- Не собирать строку платформенным `ЧислоПрописью` со своим шаблоном: параметры
  прописи зависят от валюты и языка, и библиотека берет их из справочника валют.

### 3. Найти банк по БИК

**Задача:** при вводе реквизитов подставить наименование и корсчет банка.

**Функции:**

Модуль `РаботаСБанками`, регион `ПрограммныйИнтерфейс`. Сервер. Интерфейс узкий -
два метода: поиск по классификатору и загрузка самого классификатора.

**Нюансы и антипаттерны:**

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

### 4. Рассчитать дату по графику работы

**Задача:** срок исполнения через пять рабочих дней с учетом выходных.

**Функции:**

`ГрафикиРаботы.ДатаПоГрафику(Знач ГрафикРаботы, Знач ДатаОт, Знач КоличествоДней, ВызыватьИсключение = Истина) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

`ГрафикиРаботы.ДатыПоГрафику(Знач ГрафикРаботы, Знач ДатаОт, Знач МассивДней, Знач РассчитыватьСледующуюДатуОтПредыдущей = Ложь, ВызыватьИсключение = Истина) Экспорт`
- функция, тот же регион: несколько сроков сразу.

`ГрафикиРаботы.БлижайшиеДатыВключенныеВГрафик(ГрафикРаботы, НачальныеДаты, ПараметрыПолучения = Неопределено) Экспорт`
- функция, тот же регион.

**Нюансы и антипаттерны:**

- Для нескольких дат брать множественную функцию: одиночная в цикле читает график
  на каждый вызов.
- График может быть не заполнен на нужный период. Параметр `ВызыватьИсключение`
  решает, будет это ошибкой или пустым ответом - выбирать осознанно.

### 5. Рабочие даты по производственному календарю

**Задача:** то же, но по государственному календарю, а не по графику
организации.

**Функции:**

`КалендарныеГрафики.ДатаПоКалендарю(Знач ГрафикРаботы, Знач ДатаОт, Знач КоличествоДней, ВызыватьИсключение = Истина) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

`КалендарныеГрафики.БлижайшиеРабочиеДаты(ПроизводственныйКалендарь, НачальныеДаты, ПараметрыПолучения = Неопределено) Экспорт`
- функция, тот же регион.

`КалендарныеГрафики.ОсновнойПроизводственныйКалендарь() Экспорт` - функция, тот же
регион.

**Нюансы и антипаттерны:**

- График работы и производственный календарь это РАЗНЫЕ механизмы с похожими
  функциями. График принадлежит организации, календарь государственный.
- Календарь заполняется на год вперед. Расчет за его пределами даст исключение
  либо пустоту в зависимости от параметра.

## Различия версий

Состав модулей всех четырех механизмов в 3.1.11 и 3.2.1 совпадает - сверено по
обеим поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check РаботаСКурсамиВалют.ПересчитатьВВалюту
```

# Обмен данными

Механизм БСП, синхронизирующий данные между информационными базами: настройки
узлов и подключений, запуск и мониторинг обмена, регистрация изменений,
универсальный формат обмена.

Самая крупная тема библиотеки: 79 разделов документации и 291 метод в основном
модуле. Здесь только точки входа прикладного кода, а не устройство механизма
целиком.

## Модули механизма

| Модуль | Роль | Контексты |
|---|---|---|
| `ОбменДаннымиСервер` | программный интерфейс сервера, 291 метод | сервер, толстый клиент, внешнее соединение |
| `ОбменДаннымиXDTOСервер` | универсальный формат обмена: отправка, получение, правила конвертации | сервер, толстый клиент, внешнее соединение |
| `ОбменДаннымиКлиент` | клиентская часть: помощники настройки и мониторинг | тонкий и толстый клиент |
| `Обработка.УниверсальныйОбменДаннымиXML` (модуль объекта) | обмен по правилам конвертации | сервер |

**Часть интерфейса объявлена НЕ в общих модулях.** Универсальный обмен и
конвертация объектов опубликованы модулями объектов обработок. Проверка вызова
для них работает иначе: в коде обращение идет к переменной с подключенным
объектом, и автоматически сверить его нельзя - сигнатура сверяется с модулем
объекта вручную.

## Сценарии

### 1. Запустить обмен из кода

**Задача:** синхронизация по расписанию или по действию пользователя.

**Функции:**

`ОбменДаннымиСервер.ВыполнитьДействиеОбмена(Отказ, УзелИнформационнойБазы, ДействиеПриОбмене, ИдентификаторТранспорта = Неопределено, ДополнительныеПараметры = Неопределено) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

`ОбменДаннымиСервер.ВыполнитьОбменДаннымиСВнешнейСистемой(Корреспондент, ПараметрыОбмена, ФлагОшибка) Экспорт`
- процедура, тот же регион.

**Нюансы и антипаттерны:**

- Не собирать сообщение обмена платформенными средствами мимо библиотеки: тогда
  не отработают регистрация изменений, протокол и разбор конфликтов.
- Параметр `Отказ` передается по ссылке. Проверять его после вызова обязательно:
  обмен завершается без исключения и при ошибке.
- Обмен долгий. Запуск из формы делается фоновым заданием, а не синхронно.

### 2. Прочитать настройку плана обмена

**Задача:** узнать, что поддерживает конкретный обмен, до его запуска.

**Функции:**

`ОбменДаннымиСервер.ЗначениеНастройкиПланаОбмена(ИмяПланаОбмена, ИмяПараметра, ИдентификаторНастройки = "", ВерсияКорреспондента = "") Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

**Нюансы и антипаттерны:**

- Настройки зависят от ВЕРСИИ корреспондента: одна и та же настройка у баз разных
  версий отличается. Параметр версии не декоративный.

### 3. Завершить настройку синхронизации

**Задача:** после создания узла обмена из кода довести настройку до рабочего
состояния.

**Функции:**

`ОбменДаннымиСервер.ЗавершитьНастройкуСинхронизацииДанных(УзелОбмена) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

`ОбменДаннымиСервер.ЗавершитьСозданиеНачальногоОбраза(УзелОбмена) Экспорт`
- процедура, тот же регион.

**Нюансы и антипаттерны:**

- Создание узла записью объекта плана обмена НЕ завершает настройку: без этих
  вызовов обмен будет числиться настроенным и не работать.
- Начальный образ создается один раз. Повторный вызов на рабочем узле сбросит
  состояние регистрации изменений.

### 4. Управлять регистрацией изменений

**Задача:** перерегистрировать данные к отправке после исправления.

**Механизм:** регистрация изменений ведется планом обмена платформы, но библиотека
добавляет к ней свои правила и служебные данные. Прикладной код обращается к
методам `ОбменДаннымиСервер`, а не к платформенному плану обмена напрямую.

**Нюансы и антипаттерны:**

- Прямая запись в план обмена платформы обходит служебные регистры библиотеки:
  обмен отправит данные, но состояние синхронизации разъедется.
- Массовая перерегистрация тяжелая. Ее делают фоново и порциями.

## Различия версий

**Обработки `УниверсальныйОбменДаннымиXML` в дистрибутиве 3.2.1 уже нет** - это
записано и в справочнике `1c-bsp-api`. Код, обращающийся к ней, при переходе на
3.2.1 перестанет работать; обмен переводится на универсальный формат
`ОбменДаннымиXDTOСервер`.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check ОбменДаннымиСервер.ВыполнитьДействиеОбмена
```

Для интерфейса, объявленного модулями объектов обработок, автоматическая проверка
недоступна: сигнатура сверяется с модулем объекта в поставке вручную.

# Электронная подпись

Механизм БСП, подписывающий объекты и файлы криптографической подписью:
сертификаты, интерактивное подписание, проверка подписи, штампы в печатных формах,
работа через облачный сервис подписи.

## Модули механизма

| Модуль | Роль | Контексты |
|---|---|---|
| `ЭлектроннаяПодпись` | программный интерфейс сервера | сервер, толстый клиент, внешнее соединение |
| `ЭлектроннаяПодписьКлиент` | программный интерфейс клиента: интерактивное подписание и проверка, установка расширения криптографии | тонкий и толстый клиент |
| `ЭлектроннаяПодписьКлиентЛокализация` | национальная специфика клиента, 74 метода | тонкий и толстый клиент |
| `ЭлектроннаяПодписьПереопределяемый` | точка расширения | сервер, толстый клиент, внешнее соединение |

**Подписание интерактивное по природе.** Закрытый ключ находится у пользователя,
поэтому подписать объект серверным кодом без участия клиента нельзя. Серверные
методы работают с УЖЕ полученной подписью.

## Сценарии

### 1. Добавить подпись к объекту

**Задача:** сохранить полученную от пользователя подпись рядом с документом.

**Функции:**

`ЭлектроннаяПодпись.ДобавитьПодпись(Объект, Знач СвойстваПодписи, ИдентификаторФормы = Неопределено, ВерсияОбъекта = Неопределено, ЗаписанныйОбъект = Неопределено) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

**Нюансы и антипаттерны:**

- Свойства подписи собирает КЛИЕНТ через `ЭлектроннаяПодписьКлиент`: закрытый ключ
  на сервер не передается.
- Версия объекта не декоративна: подпись относится к конкретному состоянию данных,
  и после правки объекта она перестает быть действительной.

### 2. Прочитать сведения о подписи

**Задача:** показать в интерфейсе, кто и когда подписал.

**Функции:**

`ЭлектроннаяПодпись.ДатаПодписания(Подпись, ПривестиКЧасовомуПоясуСеанса = Истина) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

**Нюансы и антипаттерны:**

- Дата подписания берется ИЗ ПОДПИСИ, а не из момента записи объекта. Это разные
  моменты, и расхождение между ними нормально.
- Приведение к часовому поясу сеанса включено по умолчанию. При сравнении подписей
  из разных баз его отключают.

### 3. Поставить штамп подписи в печатную форму

**Задача:** в печатной накладной показать отметку о подписании.

**Функции:**

`ЭлектроннаяПодпись.ДобавитьШтампыВТабличныйДокумент(Документ, ОписаниеШтампов, Размеры = Неопределено) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

**Нюансы и антипаттерны:**

- Штамп рисуется в уже сформированный табличный документ. Место под него в макете
  предусматривается заранее, иначе штамп наложится на текст.

### 4. Записать сертификат в справочник

**Задача:** зарегистрировать сертификат пользователя для дальнейшего подписания.

**Функции:**

`ЭлектроннаяПодпись.ЗаписатьСертификатВСправочник(Знач Сертификат, ДополнительныеПараметры = Неопределено) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

**Нюансы и антипаттерны:**

- Сертификат читается на клиенте через криптографию и передается на сервер уже
  разобранным. Читать хранилище сертификатов серверным кодом нельзя: его там нет.
- Не создавать элемент справочника сертификатов записью объекта: библиотека
  разбирает отпечаток, срок действия и владельца.

## Различия версий

Состав модулей семейства в 3.1.11 и 3.2.1 совпадает - сверено по обеим поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check ЭлектроннаяПодпись.ДобавитьПодпись
```

# Оригиналы документов, склонение, конструктор формул

Три механизма БСП, дополняющих работу с документами и формами: отметки о
состоянии бумажных оригиналов, склонение наименований по падежам для печатных
форм, конструктор выражений над данными объекта.

## Модули

| Модуль | Механизм | Контексты |
|---|---|---|
| `УчетОригиналовПервичныхДокументов` | состояния оригиналов и их отражение в списках | сервер, толстый клиент, внешнее соединение |
| `СклонениеПредставленийОбъектов` | склонение наименований и ФИО по падежам | сервер, толстый клиент, внешнее соединение |
| `КонструкторФормул` | сбор доступных полей, проверка и вычисление формулы | сервер, толстый клиент, внешнее соединение |

## Сценарии

### 1. Показать состояние оригинала в списке документов

**Задача:** в форме списка отметить, у каких документов бумажный оригинал уже
получен.

**Функции:**

`УчетОригиналовПервичныхДокументов.ВывестиНаФормуКомандыСостоянияОригинала(Форма, Список, СостоянияОригиналов) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

`УчетОригиналовПервичныхДокументов.ВсеСостояния() Экспорт` - функция, тот же
регион.

**Нюансы и антипаттерны:**

- Не заводить свой реквизит состояния у документа: библиотека хранит состояния
  отдельно и меняет их пачкой из списка.
- Состав состояний настраивается пользователем. Своя логика по фиксированному
  списку разойдется с настройкой.

### 2. Раздать права на смену состояний

**Задача:** менять состояние оригинала должны не все.

**Функции:**

`УчетОригиналовПервичныхДокументов.ДополнитьПрофильРольюДляИзмененияСостоянийОригиналовДокументов(ОписаниеПрофиля) Экспорт`
и `УчетОригиналовПервичныхДокументов.ДополнитьПрофильРольюДляНастройкиСостоянийОригиналовДокументов(ОписаниеПрофиля) Экспорт`
- процедуры, регион `ПрограммныйИнтерфейс`. Сервер. Вызываются из описания
поставляемого профиля групп доступа.

**Нюансы и антипаттерны:**

- Изменение состояния и НАСТРОЙКА состояний это разные права, и процедуры для них
  разные. Выдать одну вместо другой значит либо не дать работать, либо пустить
  пользователя менять справочник состояний.

### 3. Просклонять наименование для печатной формы

**Задача:** в доверенности вывести ФИО в родительном падеже.

**Функции:**

`СклонениеПредставленийОбъектов.ДоступенСервисСклонения() Экспорт` - функция,
регион `ПрограммныйИнтерфейс`. Сервер.

`СклонениеПредставленийОбъектов.ПодключитьИсточникДанныхПечатиСклоненияСтрок(ИсточникиДанныхПечати) Экспорт`
- процедура, тот же регион.

`СклонениеПредставленийОбъектов.ПриСозданииНаСервере(Форма, Представление, ИмяОсновногоРеквизитаФормы = "Объект") Экспорт`
и `СклонениеПредставленийОбъектов.ПриЗаписиФормыОбъектаСклонения(Форма, Представление, Объект, ПараметрыСклонения = Неопределено) Экспорт`
- процедуры, тот же регион.

**Нюансы и антипаттерны:**

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

### 4. Дать пользователю конструктор формул

**Задача:** пользователь настраивает выражение над полями документа.

**Функции:**

`КонструкторФормул.ЗаполнитьСписокДоступныхПолей(Форма, ПараметрыЗаполнения) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

`КонструкторФормул.ДобавитьСписокПолейНаФорму(Форма, Параметры) Экспорт`
- процедура, тот же регион.

`КонструкторФормул.ДеревоПолей() Экспорт` - функция, тот же регион.

`КонструкторФормул.ВыполнитьПоискВСпискеПолей(Форма) Экспорт` - процедура, тот же
регион.

**Нюансы и антипаттерны:**

- Не собирать список полей своим обходом метаданных: библиотека учитывает права
  доступа, и в конструкторе не должно быть полей, которых пользователю видеть
  нельзя.
- Формулу вычисляет библиотека в безопасном режиме. Выполнять пользовательское
  выражение платформенным `Вычислить` нельзя.

## Различия версий

Состав модулей всех трех механизмов в 3.1.11 и 3.2.1 совпадает - сверено по обеим
поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check КонструкторФормул.ЗаполнитьСписокДоступныхПолей
```

# Поиск дублей и удаление помеченных объектов

Два механизма БСП, работающих с лишними данными: поиск дублей заменяет копии
элемента на выбранный оригинал, удаление помеченных физически удаляет объекты с
контролем ссылочной целостности.

Механизмы разные, но идут парой: сначала дубли сводят к оригиналу, затем
помеченные удаляют.

## Модули механизмов

| Модуль | Роль | Контексты |
|---|---|---|
| `ПоискИУдалениеДублей` | программный интерфейс поиска дублей | сервер, толстый клиент, внешнее соединение |
| `ПоискИУдалениеДублейПереопределяемый` | точка расширения: свои правила сравнения | сервер, толстый клиент, внешнее соединение |
| `ПоискИУдалениеДублейКлиент` | клиентская часть | тонкий и толстый клиент |
| `УдалениеПомеченныхОбъектов` | программный интерфейс удаления | сервер, толстый клиент, внешнее соединение |
| `УдалениеПомеченныхОбъектовКлиент` | клиентская часть, 11 методов | тонкий и толстый клиент |
| `УдалениеПомеченныхОбъектовПереопределяемый` | точка расширения | сервер, толстый клиент, внешнее соединение |

## Сценарии

### 1. Найти дубли элемента

**Задача:** перед созданием контрагента проверить, нет ли уже такого.

**Функции:**

`ПоискИУдалениеДублей.НайтиДублиЭлемента(Знач ОбластьПоиска, Знач ЭталонныйОбъект, Знач ДополнительныеПараметры) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

`ПоискИУдалениеДублей.НайтиПохожиеСтроки(ИсходнаяСтрока, СтрокаПоиска, Разделитель = "~", ПараметрыПоиска = Неопределено) Экспорт`
- функция, тот же регион: нечеткое сравнение строк.

`ПоискИУдалениеДублей.ПараметрыПоискаПохожихСтрок(ПодключитьКомпоненту = Истина) Экспорт`
- функция-конструктор, тот же регион.

**Нюансы и антипаттерны:**

- Нечеткое сравнение строк опирается на внешнюю компоненту. Параметр
  `ПодключитьКомпоненту` не декоративный: без нее сравнение работает грубее.
- Поиск дублей по всей области тяжелый. В интерактивном сценарии ищут по
  конкретному эталону, а не сканируют справочник целиком.

### 2. Заменить дубли на оригинал

**Задача:** свести найденные копии к одному элементу, не потеряв ссылки.

**Функции:**

`ПоискИУдалениеДублей.ДополнитьДублиСвязаннымиПодчиненнымиОбъектами(ПарыЗамен, ПараметрыЗамены) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

**Нюансы и антипаттерны:**

- Замена ссылок это отдельная операция библиотеки, и делать ее своим кодом
  опасно: ссылки на дубль бывают в реквизитах, движениях, регистрах сведений и
  подчиненных объектах.
- Подчиненные объекты дубля должны переехать к оригиналу. Пропуск этого шага
  оставляет их висеть на удаляемом элементе.

### 3. Удалить помеченные объекты

**Задача:** служебная обработка должна чистить помеченное по расписанию.

**Функции:**

`УдалениеПомеченныхОбъектов.УдалитьПомеченныеОбъекты(УдаляемыеОбъекты, РежимУдаления = "Стандартный") Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

`УдалениеПомеченныхОбъектов.ПомеченныеНаУдаление(Знач ОтборМетаданных = Неопределено, ИскатьТехнологическиеОбъекты = Ложь) Экспорт`
- функция, тот же регион.

`УдалениеПомеченныхОбъектов.РежимУдалятьПоРасписанию() Экспорт` - функция, тот же
регион.

**Нюансы и антипаттерны:**

- Не удалять объект платформенным `Удалить` в обход: контроль ссылочной
  целостности при этом не выполняется, и в базе останутся битые ссылки.
- Результат удаления частичный: часть объектов не удалится из-за ссылок на них.
  Это штатный ответ, и его надо разобрать, а не считать ошибкой.

### 4. Показать, что мешает удалению

**Задача:** объяснить пользователю, почему объект не удаляется.

**Функции:**

`УдалениеПомеченныхОбъектов.СсылкиНаУдаляемыеОбъекты(Источник) Экспорт` - функция,
регион `ПрограммныйИнтерфейс`. Сервер.

`УдалениеПомеченныхОбъектов.ПриСозданииНаСервере(Форма, Знач НастройкиОтображенияПомеченныхОбъектов) Экспорт`
- процедура, тот же регион: встраивание в форму.

`УдалениеПомеченныхОбъектов.НастройкиОтображенияПомеченныхОбъектов() Экспорт`
- функция-конструктор, тот же регион.

**Нюансы и антипаттерны:**

- Искать ссылки платформенным поиском по всей базе долго. Функция библиотеки
  учитывает исключения и служебные объекты.

## Различия версий

Состав модулей обоих механизмов в 3.1.11 и 3.2.1 совпадает - сверено по обеим
поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check УдалениеПомеченныхОбъектов.УдалитьПомеченныеОбъекты
```

# Работа с почтовыми сообщениями

Механизм БСП, отправляющий и загружающий электронную почту через учетные записи,
настроенные пользователем: письма из кода, вложения, загрузка входящих, защита от
небезопасного содержимого.

## Модули механизма

| Модуль | Роль | Контексты |
|---|---|---|
| `РаботаСПочтовымиСообщениями` | программный интерфейс сервера | сервер, толстый клиент, внешнее соединение |
| `РаботаСПочтовымиСообщениямиКлиент` | программный интерфейс клиента: формы отправки | тонкий и толстый клиент |
| `РаботаСПочтовымиСообщениямиЛокализация` | национальная специфика | сервер |

## Сценарии

### 1. Отправить письмо из кода

**Задача:** уведомить пользователя о результате обработки.

**Функции:**

`РаботаСПочтовымиСообщениями.ОтправитьПисьма(УчетнаяЗаписьИлиСоединение, Письма, ТекстОшибки = Неопределено) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

`РаботаСПочтовымиСообщениями.ДоступныеУчетныеЗаписи(Знач ДляОтправки = Неопределено, Знач ДляПолучения = Неопределено, Знач ВключатьСистемнуюУчетнуюЗапись = Истина) Экспорт`
- функция, тот же регион.

`РаботаСПочтовымиСообщениями.ДоступнаОтправкаПисем() Экспорт` - функция, тот же
регион.

**Нюансы и антипаттерны:**

- Проверять `ДоступнаОтправкаПисем` до сборки письма: без настроенной учетной
  записи отправка не состоится, и собранное письмо пропадет впустую.
- Не создавать `Новый ИнтернетПочтовоеСообщение` и не отправлять его платформенным
  профилем напрямую: тогда не отработают настройки учетной записи, журнал и
  ограничения администратора.
- Отправка нескольких писем идет ОДНИМ вызовом со списком: соединение
  устанавливается один раз, а не на каждое письмо.

### 2. Загрузить входящие письма

**Задача:** обработать почту робота: заявки, накладные, ответы.

**Функции:**

`РаботаСПочтовымиСообщениями.ЗагрузитьПочтовыеСообщения(Знач УчетнаяЗаписьИлиСоединение, Знач ПараметрыЗагрузки = Неопределено) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

**Нюансы и антипаттерны:**

- Загрузка долгая и сетевая. Ее место - регламентное задание, а не обработчик
  формы.
- Учетная запись должна быть настроена НА ПОЛУЧЕНИЕ. Запись только для отправки
  вернет пустой результат без ошибки.

### 3. Обезопасить письмо в формате HTML

**Задача:** показать пользователю входящее письмо, не подгружая внешние картинки
и скрипты.

**Функции:**

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

`РаботаСПочтовымиСообщениями.ЕстьВнешниеРесурсы(ДокументHTML) Экспорт` - функция,
тот же регион.

**Нюансы и антипаттерны:**

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

## Различия версий

Состав модулей семейства в 3.1.11 и 3.2.1 совпадает - сверено по обеим поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check РаботаСПочтовымиСообщениями.ОтправитьПисьма
```

# Точки расширения без своего интерфейса

Пять механизмов БСП, у которых прикладному коду доступна ТОЛЬКО точка расширения:
интерфейс OData, информация при запуске, отчет о движениях документа, проверка
легальности обновления, а также ручной порядок элементов в списках.

Общее у них: механизм работает сам, а конфигурация лишь объявляет свое участие в
нем. Вызывать эти модули из прикладного кода не нужно и почти всегда неверно.

## Модули

| Модуль | Механизм | Контексты |
|---|---|---|
| `ИнтерфейсODataПереопределяемый` | состав публикуемых объектов OData | сервер, толстый клиент, внешнее соединение |
| `ИнформацияПриЗапускеПереопределяемый` | информационные сообщения при запуске | сервер, толстый клиент, внешнее соединение |
| `ОтчетОДвиженияхДокументаПереопределяемый` | состав регистров в отчете о движениях | сервер, толстый клиент, внешнее соединение |
| `ПроверкаЛегальностиПолученияОбновленияКлиент` | проверка легальности обновления, клиентская часть | тонкий и толстый клиент |
| `НастройкаПорядкаЭлементов` | ручной порядок элементов в списках | сервер, толстый клиент, внешнее соединение |

## Сценарии

### 1. Объявить зависимые таблицы для OData

**Задача:** при публикации объекта через OData вместе с ним должны выгружаться
связанные таблицы.

**Функции:**

`ИнтерфейсODataПереопределяемый.ПриЗаполненииЗависимыхТаблицДляВыгрузкиЗагрузкиOData(Таблицы) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. ХУК. Единственный метод модуля.

**Нюансы и антипаттерны:**

- Не вызывать этот хук из прикладного кода: его реализуют.
- Незаявленная зависимая таблица выгрузится пустой, и внешняя система получит
  неполные данные без ошибки.

### 2. Показать сообщение при запуске

**Задача:** предупредить пользователей о предстоящих работах.

**Функции:**

`ИнформацияПриЗапускеПереопределяемый.ОпределитьНастройки(Настройки) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. ХУК. Единственный метод модуля.

**Нюансы и антипаттерны:**

- Сообщение показывается КАЖДОМУ при запуске. Тяжелый запрос в этом хуке
  замедляет вход всем пользователям.
- Не выводить сообщение своим кодом при начале работы системы: библиотека
  запоминает, что пользователь его уже видел.

### 3. Дополнить отчет о движениях документа

**Задача:** в отчете о движениях показать свой регистр.

**Функции:**

`ОтчетОДвиженияхДокументаПереопределяемый.ПриОпределенииРегистровСДвижениями(Документ, РегистрыСДвижениями) Экспорт`,
`ОтчетОДвиженияхДокументаПереопределяемый.ПриПодготовкеНабораДанных(Документ, НаборыДанных) Экспорт`,
`ОтчетОДвиженияхДокументаПереопределяемый.ПриРасчетеКоличестваЗаписей(Документ, РассчитанноеКоличество) Экспорт`
- процедуры, регион `ПрограммныйИнтерфейс`. ХУКИ.

**Нюансы и антипаттерны:**

- Хуки вызываются на КАЖДОЕ открытие отчета. Подсчет записей запросом по всей
  таблице делает отчет медленным.
- Не вызывать процедуры этого модуля из прикладного кода: их реализуют.

### 4. Ручной порядок элементов в списке

**Задача:** пользователь двигает строки справочника вверх и вниз, и порядок
сохраняется.

**Функции:**

`НастройкаПорядкаЭлементов.УстановитьЗначениеРеквизитаУпорядочивания(Объект) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

`НастройкаПорядкаЭлементов.СброситьЗначениеРеквизитаУпорядочивания(Источник, ОбъектКопирования) Экспорт`
- процедура, тот же регион: обработчик подписки при копировании.

`НастройкаПорядкаЭлементов.ПолучитьИнформациюДляПеремещения(МетаданныеОбъекта) Экспорт`
- функция, тот же регион.

**Нюансы и антипаттерны:**

- Реквизит упорядочивания заполняет библиотека. Своя нумерация разъедется при
  вставке между элементами.
- Копия элемента НЕ должна наследовать порядок оригинала: для этого и нужна
  процедура сброса, подключаемая подпиской.

### 5. Проверка легальности обновления

**Задача:** библиотека спрашивает пользователя, легально ли получено обновление.

**Механизм:** модуль `ПроверкаЛегальностиПолученияОбновленияКлиент`, клиентская
часть. Вызывается сценарием обновления, а не прикладным кодом.

**Нюансы и антипаттерны:**

- Вопрос задается пользователю интерактивно. Ответ на него серверным кодом
  подменять нельзя.

## Различия версий

Состав модулей всех пяти механизмов в 3.1.11 и 3.2.1 совпадает - сверено по обеим
поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check НастройкаПорядкаЭлементов.УстановитьЗначениеРеквизитаУпорядочивания
```

# Дополнительные отчеты и обработки

Механизм БСП, подключающий внешние обработки и отчеты без изменения конфигурации:
пользователь загружает файл, библиотека регистрирует его команды, назначает права
и размещает на формах объектов.

Через этот механизм подключаются внешние печатные формы и обработки заполнения -
они не отдельные механизмы, а виды дополнительных обработок.

## Модули механизма

| Модуль | Роль | Контексты |
|---|---|---|
| `ДополнительныеОтчетыИОбработки` | программный интерфейс сервера | сервер, толстый клиент, внешнее соединение |
| `ДополнительныеОтчетыИОбработкиКлиент` | программный интерфейс клиента: выполнение команд | тонкий и толстый клиент |
| `ДополнительныеОтчетыИОбработкиКлиентСервер` | общая часть: имена видов и типов команд | сервер и клиент |
| `ДополнительныеОтчетыИОбработкиПереопределяемый` | точка расширения | сервер, толстый клиент, внешнее соединение |
| остальные из пятнадцати модулей семейства | внутренняя реализация и работа в модели сервиса | - |

## Сценарии

### 1. Выполнить команду дополнительной обработки

**Задача:** запустить обработку, подключенную пользователем, из своего кода.

**Функции:**

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

`ДополнительныеОтчетыИОбработки.ВыполнитьКомандуИзФормыВнешнегоОбъекта(ИдентификаторКоманды, ПараметрыКоманды, Форма) Экспорт`
- функция, тот же регион.

**Нюансы и антипаттерны:**

- Не подключать внешнюю обработку платформенным способом мимо библиотеки: тогда
  не отработают проверки прав, режим безопасности и журнал использования.
- Команда может отсутствовать: пользователь мог отключить обработку. Пустой
  результат штатный.

### 2. Получить объект внешней обработки

**Задача:** обратиться к экспортному методу подключенной обработки напрямую.

**Функции:**

`ДополнительныеОтчетыИОбработки.ПодключитьВнешнююОбработку(Ссылка) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер. Возвращает имя подключенной
обработки.

`ДополнительныеОтчетыИОбработки.ОбъектВнешнейОбработки(Ссылка) Экспорт`
- функция, тот же регион. Возвращает сам объект.

**Нюансы и антипаттерны:**

- Подключение и получение объекта это РАЗНЫЕ шаги: первый возвращает имя, второй
  объект. Путать их легко.
- Внешняя обработка выполняется в режиме безопасности, если он включен. Ее код не
  получит доступ к файловой системе и внешним соединениям молча - будет ошибка.

### 3. Печать по внешнему источнику

**Задача:** внешняя печатная форма должна печататься наравне с типовыми.

**Функции:**

`ДополнительныеОтчетыИОбработки.ПечатьПоВнешнемуИсточнику(ДополнительнаяОбработкаСсылка, ПараметрыИсточника, КоллекцияПечатныхФорм, ОбъектыПечати, ПараметрыВывода) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

**Нюансы и антипаттерны:**

- Вызывается библиотекой печати, а не прикладным кодом напрямую: внешние формы
  попадают в общее меню печати через подключаемые команды.
- Внешняя печатная форма получает те же параметры, что и типовая. Своего порядка
  вызова у нее нет.

### 4. Прочитать настройки подключенной обработки

**Задача:** узнать, к каким объектам она назначена и какие у нее команды.

**Функции:**

`ДополнительныеОтчетыИОбработки.ЗагрузитьНастройки(Ссылка) Экспорт` - функция,
регион `ПрограммныйИнтерфейс`. Сервер.

**Нюансы и антипаттерны:**

- Не читать реквизиты справочника дополнительных обработок запросом: часть
  сведений лежит в хранилище значения и разбирается библиотекой.
- Настройки берутся из САМОЙ обработки при загрузке файла. Правка справочника их
  не меняет.

## Различия версий

Состав модулей семейства в 3.1.11 и 3.2.1 совпадает - сверено по обеим поставкам.
Отдельный модуль работы дополнительных обработок с регламентными заданиями в
модели сервиса есть в 3.1.11 и отсутствует в 3.2.1.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check ДополнительныеОтчетыИОбработки.ВыполнитьКоманду
```

# Обновление версии информационной базы

Механизм БСП, приводящий ДАННЫЕ в соответствие новой версии конфигурации:
обработчики обновления, порционная обработка больших объемов, отложенное
обновление. Работает после того, как платформа обновила структуру базы.

Не путать с обновлением конфигурации: то доставляет новую версию, это переносит
данные под нее.

## Модули механизма

| Модуль | Роль | Контексты |
|---|---|---|
| `ОбновлениеИнформационнойБазы` | программный интерфейс | сервер, толстый клиент, внешнее соединение |
| `ОбновлениеИнформационнойБазыПереопределяемый` | точка расширения сервера | сервер, толстый клиент, внешнее соединение |
| `ОбновлениеИнформационнойБазыКлиентПереопределяемый` | точка расширения клиента: что показать до и после перехода | тонкий и толстый клиент |
| `ОбновлениеИнформационнойБазыБСП`, `ОбновлениеИнформационнойБазыБСД` | обработчики самой библиотеки, не прикладной код | сервер |
| `ОбновлениеИнформационнойБазыСлужебный` и еще пять | внутренняя реализация библиотеки | - |

**Собственные обработчики объявляются НЕ в переопределяемом модуле.** Каждая
подсистема заводит у себя процедуру `ПриДобавленииОбработчиковОбновления(Обработчики)`
и наполняет переданную таблицу - так устроены и обработчики самой библиотеки,
проверено по ее исходникам. Переопределяемый модуль отвечает за порядок и за
события вокруг обновления, а не за перечень обработчиков.

## Сценарии

### 1. Объявить обработчик обновления

**Задача:** при переходе на новую версию заполнить новый реквизит у существующих
документов.

**Механизм:** процедура `ПриДобавленииОбработчиковОбновления(Обработчики)` в общем
модуле своей подсистемы. Библиотека собирает обработчики со всех подсистем и
выполняет их по версиям.

**Ключевые свойства строки обработчика** (взято из обработчиков библиотеки):

- `Версия` - версия конфигурации, при переходе на которую обработчик выполняется.
- `Идентификатор` - `УникальныйИдентификатор`, обязателен для отложенных.
- `Процедура` - полное имя процедуры, которая делает работу.
- `РежимВыполнения` - когда выполнять: сразу либо `"Отложенно"`.
- `ПроцедураЗаполненияДанныхОбновления` - что зарегистрировать к обработке, для
  отложенного режима.
- `ЧитаемыеОбъекты` и `ИзменяемыеОбъекты` - на чем обработчик работает; по ним
  библиотека строит порядок и разводит блокировки.

**Пример:**

```bsl
// Общий модуль своей подсистемы.
Процедура ПриДобавленииОбработчиковОбновления(Обработчики) Экспорт

    Обработчик = Обработчики.Добавить();
    Обработчик.Версия = "1.2.3.4";
    Обработчик.Идентификатор = Новый УникальныйИдентификатор("00000000-0000-0000-0000-000000000000");
    Обработчик.Процедура = "Документы.РасходТовара.ЗаполнитьНовыйРеквизит";
    Обработчик.РежимВыполнения = "Отложенно";
    Обработчик.ПроцедураЗаполненияДанныхОбновления = "Документы.РасходТовара.ЗарегистрироватьКОбработке";
    Обработчик.ЧитаемыеОбъекты = "Документ.РасходТовара";
    Обработчик.ИзменяемыеОбъекты = "Документ.РасходТовара";

КонецПроцедуры
```

**Нюансы и антипаттерны:**

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

### 2. Обработать большой объем порциями

**Задача:** заполнить реквизит у миллиона документов, не заблокировав базу.

**Функции:**

`ОбновлениеИнформационнойБазы.ВыбратьСсылкиДляОбработки(Очередь, ПолноеИмяОбъекта, ДополнительныеПараметры = Неопределено) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

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

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

**Нюансы и антипаттерны:**

- Не выбирать все ссылки одним запросом без порций: отложенный обработчик обязан
  завершаться, а не работать часами в одной транзакции.
- Для каждого вида источника своя функция выборки. Регистр сведений и документ
  обрабатываются по-разному, и общей функции нет.

### 3. Узнать версию данных и версию конфигурации

**Задача:** ветвление логики по тому, с какой версии идет переход.

**Функции:**

`ОбновлениеИнформационнойБазы.ВерсияИБ(Знач ИдентификаторБиблиотеки) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

`ОбновлениеИнформационнойБазы.ВерсииПодсистем() Экспорт` - функция, тот же
регион: версии всех подсистем и библиотек сразу.

**Нюансы и антипаттерны:**

- Не читать версию из константы или регистра напрямую: у каждой библиотеки в
  конфигурации своя версия, и одной константой они не описываются.
- Версия ИБ это версия ДАННЫХ, а не версия конфигурации. До выполнения
  обработчиков они различаются, и на этом различии механизм и работает.

### 4. Выполнить свое действие вокруг обновления

**Задача:** до обновления снять блокировки, после - пересчитать итоги.

**Функции:**

`ОбновлениеИнформационнойБазыПереопределяемый.ПередОбновлениемИнформационнойБазы() Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. ХУК.

`ОбновлениеИнформационнойБазыПереопределяемый.ПослеОбновленияИнформационнойБазы(Знач ПредыдущаяВерсияИБ, Знач ТекущаяВерсияИБ, Знач ИтерацииОбновления, ВыводитьОписаниеОбновлений, Знач МонопольныйРежим) Экспорт`
- процедура, тот же регион и та же роль.

`ОбновлениеИнформационнойБазыПереопределяемый.ПриЗаполненииОбъектовПланируемыхКУдалению(Объекты) Экспорт` [3.1.11]
- процедура, тот же регион: объявляет объекты, которые будут удалены в следующих
версиях. **В 3.2.1 этого хука НЕТ** - код, реализующий его, при переходе
перестанет вызываться, и о том, что объекты планируются к удалению, библиотека
не узнает.

**Нюансы и антипаттерны:**

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

### 5. Управлять отложенным обновлением

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

**Функции:**

`ОбновлениеИнформационнойБазы.ВключитьОтключитьОтложенноеОбновление(Использование) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

`ОбновлениеИнформационнойБазы.ВыполнитьОбновлениеИнформационнойБазы(ВыполнятьОтложенныеОбработчики = Ложь) Экспорт`
- функция, тот же регион.

**Нюансы и антипаттерны:**

- Отложенный обработчик обязан переносить неполные данные: пользователь работает
  с базой, где часть записей уже обновлена, а часть еще нет.
- Не считать отложенное обновление завершенным по факту входа в программу: оно
  идет фоново и завершается позже.

## Различия версий

Состав модулей семейства в 3.1.11 и 3.2.1 совпадает - сверено по обеим поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check ОбновлениеИнформационнойБазы.ВерсияИБ
```

# Внешние взаимодействия: интернет, SMS, штрихкоды, внешние компоненты

Четыре механизма БСП, обращенных вовне: загрузка файлов по сети через прокси,
отправка SMS через оператора, формирование штрихкодов и QR-кодов, подключение
внешних компонент на рабочем месте.

Общее у них одно: все зависят от настроек администратора и от окружения, поэтому
каждый сценарий начинается с проверки доступности.

## Модули

| Модуль | Механизм | Контексты |
|---|---|---|
| `ПолучениеФайловИзИнтернета` | загрузка по HTTP и FTP, прокси, диагностика | сервер, толстый клиент, внешнее соединение |
| `ОтправкаSMS` | отправка через оператора, статус доставки | сервер, толстый клиент, внешнее соединение |
| `ГенерацияШтрихкода` | изображения штрихкодов и QR-кодов | сервер, толстый клиент, внешнее соединение |
| `ВнешниеКомпоненты` | подключение и установка компонент на рабочем месте | сервер / клиент |

## Сценарии

### 1. Загрузить файл по сети

**Задача:** скачать классификатор или обновление, не потеряв настройки прокси.

**Функции:**

`ПолучениеФайловИзИнтернета.ПолучитьПрокси(Знач URLИлиПротокол) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

`ПолучениеФайловИзИнтернета.НастройкиПроксиНаСервере() Экспорт` и
`ПолучениеФайловИзИнтернета.НастройкиПроксиНаКлиенте() Экспорт` - функции, тот же
регион.

`ПолучениеФайловИзИнтернета.ДиагностикаСоединения(URL, ЗаписыватьОшибку = Истина, ПроверятьДоставкуПакетов = Истина, ТекстОшибки = "") Экспорт`
- функция, тот же регион.

**Нюансы и антипаттерны:**

- Не создавать `Новый HTTPСоединение` без прокси из библиотеки: в сетях с прокси
  запрос уйдет в никуда, а ошибка будет невнятной.
- Настройки прокси на сервере и на клиенте РАЗНЫЕ. Брать серверные для
  клиентского запроса неверно.
- Диагностика соединения дает пользователю понятную причину отказа вместо кода
  ошибки платформы. Ее стоит звать в обработчике ошибки, а не только при отладке.

### 2. Отправить SMS

**Задача:** уведомить клиента о готовности заказа.

**Функции:**

`ОтправкаSMS.ОтправитьSMS(НомераПолучателей, Знач Текст, ИмяОтправителя = Неопределено, ПеревестиВТранслит = Ложь) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

`ОтправкаSMS.ДоступнаОтправкаSMS() Экспорт` и
`ОтправкаSMS.НастройкаОтправкиSMSВыполнена() Экспорт` - функции, тот же регион.

`ОтправкаSMS.СтатусДоставки(Знач ИдентификаторСообщения) Экспорт` - функция, тот
же регион.

**Нюансы и антипаттерны:**

- Проверять доступность до сборки текста: без настроенного оператора отправка не
  состоится.
- Доставка асинхронная. Возврат функции означает, что сообщение принято
  оператором, а не доставлено; статус спрашивают отдельно и позже.
- Перевод в транслит меняет текст. Включать его молча нельзя: получатель увидит
  латиницу вместо кириллицы.

### 3. Сформировать штрихкод

**Задача:** в печатной форме вывести штрихкод или QR-код.

**Функции:**

`ГенерацияШтрихкода.ИзображениеШтрихкода(ПараметрыШтрихкода) Экспорт` - функция,
регион `ПрограммныйИнтерфейс`. Сервер.

`ГенерацияШтрихкода.ПараметрыГенерацииШтрихкода() Экспорт` - функция-конструктор,
тот же регион.

**Нюансы и антипаттерны:**

- Параметры собираются конструктором, а не структурой вручную: состав полей
  меняется между версиями библиотеки.
- Генерация опирается на внешнюю компоненту. На сервере без нее функция вернет
  пустое изображение, и в печатной форме будет пустое место без ошибки.

### 4. Подключить внешнюю компоненту

**Задача:** использовать компоненту сканера или криптографии.

**Механизм:** модуль `ВнешниеКомпоненты` и его клиентская часть. Компонента
устанавливается на рабочем месте пользователя, и установка интерактивная.

**Нюансы и антипаттерны:**

- Не подключать компоненту платформенным способом мимо библиотеки: тогда не
  отработают проверка версии, установка на рабочем месте и понятное сообщение при
  отказе.
- Установка требует действий пользователя. Серверный код компоненту на клиенте не
  поставит.

## Различия версий

Состав модулей всех четырех механизмов в 3.1.11 и 3.2.1 совпадает - сверено по
обеим поставкам.

## Проверка перед использованием

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

# Шаблоны сообщений

Механизм БСП, формирующий письма и сообщения по шаблону: пользователь заводит
текст с подстановками, библиотека заполняет их данными объекта и собирает готовое
сообщение с вложениями и получателями.

## Модули механизма

| Модуль | Роль | Контексты |
|---|---|---|
| `ШаблоныСообщений` | программный интерфейс сервера | сервер, толстый клиент, внешнее соединение |
| `ШаблоныСообщенийКлиентСервер` | общие правила разбора шаблонов | сервер и клиент |
| `ШаблоныСообщенийПереопределяемый` | точка расширения: свои параметры шаблонов | сервер, толстый клиент, внешнее соединение |

## Сценарии

### 1. Подставить значения в текст шаблона

**Задача:** заполнить заготовку письма данными документа.

**Функции:**

`ШаблоныСообщений.ВставитьПараметрыВСтрокуСогласноТаблицеПараметров(Знач ШаблонСтроки, ВставляемыеЗначения, Знач Префикс = "") Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

**Нюансы и антипаттерны:**

- Не собирать текст конкатенацией и `СтрЗаменить`: шаблон заводит пользователь, и
  имена параметров в нем произвольные, а разбор учитывает вложенность и префиксы.
- Незаполненный параметр остается в тексте как есть. Проверять результат на
  остатки подстановок надо до отправки.

### 2. Объявить свои параметры шаблона

**Задача:** в шаблоне должны быть доступны поля своего документа.

**Функции:**

`ШаблоныСообщений.ДобавитьПараметрШаблона(ТаблицаПараметров, ИмяПараметра, ОписаниеТипа, ЭтоПредопределенныйПараметр, ПредставлениеПараметра = "") Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

`ШаблоныСообщений.ЗаполнитьРеквизитыПоСКД(Реквизиты, Предмет, ПараметрыШаблона) Экспорт`
- процедура, тот же регион: набор параметров берется из схемы компоновки.

**Нюансы и антипаттерны:**

- Представление параметра видит пользователь при вставке. Пустое представление
  оставляет его наедине с техническим именем.
- Тип параметра не декоративен: по нему библиотека форматирует значение при
  подстановке.

### 3. Заполнить получателей письма

**Задача:** взять адреса из контактной информации объекта.

**Функции:**

`ШаблоныСообщений.ЗаполнитьПолучателей(ПолучателиПисьма, ПредметСообщения, ИмяРеквизита, ТипКонтактнойИнформации = Неопределено, ВариантОтправки = "Кому") Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

**Нюансы и антипаттерны:**

- Адреса берутся из механизма контактной информации, а не из реквизита строкой.
  Прямое чтение реквизита пропустит объекты с несколькими адресами.
- Вариант отправки различает основных получателей и копии. По умолчанию все
  попадают в основные.

## Различия версий

Состав модулей семейства в 3.1.11 и 3.2.1 совпадает - сверено по обеим поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check ШаблоныСообщений.ЗаполнитьПолучателей
```

# Замеры, мониторинг, полнотекстовый поиск, итоги

Четыре механизма БСП, не участвующих в прикладной логике напрямую, но влияющих
на нее: замеры производительности ключевых операций, отправка обезличенной
статистики, полнотекстовый поиск по данным, управление итогами и агрегатами.

## Модули

| Модуль | Механизм | Контексты |
|---|---|---|
| `ОценкаПроизводительности`, `ОценкаПроизводительностиКлиент` | замеры ключевых операций | сервер / клиент |
| `ЦентрМониторинга` | обезличенная статистика использования | сервер, толстый клиент, внешнее соединение |
| `ПолнотекстовыйПоиск` | обновление индекса и поиск по данным | сервер, толстый клиент, внешнее соединение |

**Модуля `УправлениеИтогамиИАгрегатами` в публичном интерфейсе нет**: механизм
работает регламентным заданием и настройками, а не вызовами из прикладного кода.
Проверено по обеим поставкам.

## Сценарии

### 1. Замерить свою ключевую операцию

**Задача:** понять, сколько занимает проведение документа у реальных
пользователей.

**Функции:**

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

`ОценкаПроизводительности.ЗакончитьЗамерДлительнойОперации(ОписаниеЗамера, КоличествоДанных, ИмяШага = "", Комментарий = "") Экспорт`
- процедура, тот же регион.

`ОценкаПроизводительности.ЗакончитьЗамерВремениТехнологический(КлючеваяОперация, ВремяНачала, ВесЗамера = 1, Комментарий = Неопределено) Экспорт`
- процедура, тот же регион.

**Нюансы и антипаттерны:**

- Вес замера не декоративен: по нему считается средняя длительность операции на
  разном объеме данных. Замер проведения одной строки и тысячи строк с весом
  единица даст бессмысленное среднее.
- Замер прикладной и технологический идут в разные отчеты. Технологический нужен
  для служебных операций, а не для пользовательских.
- Замер, не завершенный при ошибке, портит статистику. Параметр `ВыполненСОшибкой`
  для этого и есть.

### 2. Записать бизнес-статистику

**Задача:** отправлять в центр мониторинга обезличенный факт использования
механизма.

**Функции:**

`ЦентрМониторинга.ЗаписатьОперациюБизнесСтатистики(ИмяОперации, Значение, Комментарий = Неопределено, Разделитель = ".") Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

`ЦентрМониторинга.ЗаписатьОперациюБизнесСтатистикиСутки(ИмяОперации, КлючУникальности, Значение, Замещать = Ложь) Экспорт`
- процедура, тот же регион: одна запись в сутки на ключ.

`ЦентрМониторинга.ВключитьПодсистему() Экспорт` - процедура, тот же регион.

**Нюансы и антипаттерны:**

- Статистика ОБЕЗЛИЧЕННАЯ. Класть в имя операции или комментарий данные
  пользователей и контрагентов нельзя: они уйдут наружу.
- Суточная запись существует, чтобы не слать одно и то же событие тысячу раз.
  Обычная запись в цикле раздувает отправку.

### 3. Полнотекстовый поиск по данным

**Задача:** найти объекты по фрагменту текста в любом реквизите.

**Механизм:** модуль `ПолнотекстовыйПоиск`, регион `ПрограммныйИнтерфейс`. Сервер.
Обновление индекса и выполнение поиска.

**Нюансы и антипаттерны:**

- Поиск работает по ИНДЕКСУ, а не по текущим данным. Только что записанный объект
  находится не сразу: индекс обновляется регламентным заданием.
- Не подменять полнотекстовый поиск запросом с подобием по всем реквизитам: на
  большой базе он не завершится.

### 4. Итоги и агрегаты

**Механизм:** настраивается администратором и пересчитывается регламентным
заданием. Публичного программного интерфейса у механизма нет.

**Нюансы и антипаттерны:**

- Не пересчитывать итоги своим кодом при каждом проведении: платформа делает это
  сама, а библиотека управляет расписанием пересчета.
- Отключенные итоги ускоряют запись и замедляют чтение остатков. Это решение
  администратора, и прикладной код на него полагаться не должен.

## Различия версий

Состав модулей всех механизмов в 3.1.11 и 3.2.1 совпадает - сверено по обеим
поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check ОценкаПроизводительности.ЗакончитьЗамерВремени
```

# Мультиязычность

Механизм БСП, хранящий данные на нескольких языках: наименование справочника на
русском и английском, подстановка текущего языка в запросы и представления.

Не путать с локализацией интерфейса: та задается языком конфигурации, здесь
многоязычными становятся сами ДАННЫЕ.

## Модули механизма

| Модуль | Роль | Контексты |
|---|---|---|
| `МультиязычностьСервер` | программный интерфейс сервера, 57 методов | сервер, толстый клиент, внешнее соединение |
| `МультиязычностьКлиент` | клиентская часть, три метода | тонкий и толстый клиент |
| `МультиязычностьПереопределяемый` | точка расширения | сервер, толстый клиент, внешнее соединение |

**Модуля `Мультиязычность` без суффикса не существует**: интерфейс лежит в
`МультиязычностьСервер`.

## Сценарии

### 1. Заполнить многоязычный реквизит

**Задача:** при создании элемента справочника заполнить наименование на всех
языках.

**Функции:**

`МультиязычностьСервер.ЗаполнитьМультиязычныйРеквизит(Элемент, ИмяРеквизита, ИсходнаяСтрока, КодыЯзыков = Неопределено) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

**Нюансы и антипаттерны:**

- Не записывать реквизиты вида `НаименованиеЯзык1` напрямую: имена зависят от
  порядкового номера языка в настройках, и они разъезжаются между внедрениями.
- Пустая строка на дополнительном языке это не ошибка: библиотека подставит
  значение основного языка при выводе.

### 2. Подставить текущий язык в запрос

**Задача:** отчет должен выводить наименования на языке пользователя.

**Функции:**

`МультиязычностьСервер.ИзменитьПолеЗапросаПодТекущийЯзык(ТекстЗапроса, ИмяПоля) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

`МультиязычностьСервер.ИменаРеквизитовСУчетомКодаЯзыка(ИменаРеквизитов, КодЯзыка = "") Экспорт`
- функция, тот же регион.

**Нюансы и антипаттерны:**

- Не собирать имя поля конкатенацией с номером языка: библиотека знает, какой
  язык основной, а какой дополнительный, и учитывает выключенные языки.
- Подстановка меняет ТЕКСТ запроса. Делать ее надо до создания запроса, а не
  после.

### 3. Узнать, включены ли дополнительные языки

**Задача:** не показывать поля второго языка, когда он не используется.

**Функции:**

`МультиязычностьСервер.ИспользуетсяДополнительныйЯзык(ПорядковыйНомерЯзыка) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

`МультиязычностьСервер.КоличествоДополнительныхЯзыков() Экспорт` - функция, тот же
регион.

**Нюансы и антипаттерны:**

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

### 4. Поддержать многоязычность в своем объекте

**Задача:** свой справочник должен вести себя как типовой.

**Функции:**

`МультиязычностьСервер.ПередЗаписьюНаСервере(ТекущийОбъект) Экспорт` - процедура,
регион `ПрограммныйИнтерфейс`. Сервер. Вызывается из обработчика формы.

**Нюансы и антипаттерны:**

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

## Различия версий

Состав модулей семейства в 3.1.11 и 3.2.1 совпадает - сверено по обеим поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check МультиязычностьСервер.ЗаполнитьМультиязычныйРеквизит
```

# Префиксация объектов

Механизм БСП, подставляющий префикс в номер документа или код справочника при
записи: префикс информационной базы и префикс организации. Нужен, когда одни и те
же объекты создаются в нескольких базах или от нескольких организаций и номера не
должны сталкиваться.

## Модули механизма

| Модуль | Роль | Контексты |
|---|---|---|
| `ПрефиксацияОбъектовКлиентСервер` | программный интерфейс: разбор и сборка номера | сервер, тонкий и толстый клиент, внешнее соединение |
| `ПрефиксацияОбъектовПереопределяемый` | точка расширения: свои правила формирования префикса | сервер, толстый клиент, внешнее соединение |
| `ПрефиксацияОбъектовКлиентСерверПереопределяемый` | точка расширения: свое правило номера на печать | сервер, тонкий и толстый клиент, внешнее соединение |
| `ПрефиксацияОбъектовСобытия` | обработчики подписок на события, подставляющие префикс при записи | сервер, толстый клиент, внешнее соединение |
| `ПрефиксацияОбъектовСлужебный` | внутренняя реализация библиотеки | - |
| `ПрефиксацияОбъектовПовтИсп` | кэш повторного использования, служебный | - |

**Модуля `ПрефиксацияОбъектов` без суффикса не существует.** Разбор номера лежит в
`ПрефиксацияОбъектовКлиентСервер`, подстановка префикса при записи - в
`ПрефиксацияОбъектовСобытия`, а точки расширения - в двух модулях с суффиксом
`Переопределяемый`.

Модуль `ПрефиксацияОбъектовСобытия` устроен иначе, чем прочие: это не интерфейс
для вызова, а набор обработчиков, которые подписки на события библиотеки вызывают
сами. Прикладной код туда не обращается.

## Сценарии

### 1. Показать номер пользователю без префиксов

**Задача:** в печатной форме или в отчете вывести номер документа так, как его
называет человек, без служебных префиксов базы и организации.

**Функции:**

`ПрефиксацияОбъектовКлиентСервер.НомерНаПечать(Знач НомерОбъекта, УдалитьПрефиксИнформационнойБазы = Ложь, УдалитьПользовательскийПрефикс = Ложь) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Доступна и на клиенте, и на сервере.

**Параметры:**

- `НомерОбъекта` - `Строка`, номер или код как он лежит в базе.
- `УдалитьПрефиксИнформационнойБазы` - `Булево`, убрать префикс базы.
- `УдалитьПользовательскийПрефикс` - `Булево`, убрать префикс, заданный
  пользователем.

**Пример:**

```bsl
&НаКлиенте
Функция НомерДляЗаголовка(Знач Номер)

    Возврат ПрефиксацияОбъектовКлиентСервер.НомерНаПечать(Номер, Истина, Истина);

КонецФункции
```

**Нюансы и антипаттерны:**

- Не резать номер строковыми функциями по фиксированной длине: длина префикса
  зависит от настроек базы и организации и меняется между внедрениями.
- Функция доступна на клиенте, поэтому серверный вызов ради нее не нужен.

### 2. Разобрать номер на части

**Задача:** получить из номера отдельно пользовательский префикс либо очистить
номер от лидирующих нулей перед сравнением.

**Функции:**

`ПрефиксацияОбъектовКлиентСервер.ПользовательскийПрефикс(Знач НомерОбъекта) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`.

`ПрефиксацияОбъектовКлиентСервер.УдалитьЛидирующиеНулиИзНомераОбъекта(Знач НомерОбъекта) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`.

`ПрефиксацияОбъектовКлиентСервер.УдалитьПрефиксыИзНомераОбъекта(Знач НомерОбъекта, УдалитьПрефиксОрганизации = Ложь, УдалитьПрефиксИнформационнойБазы = Ложь) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`.

**Пример:**

```bsl
&НаСервере
Функция НомераСовпадают(Знач Первый, Знач Второй)

    Первый = ПрефиксацияОбъектовКлиентСервер.УдалитьЛидирующиеНулиИзНомераОбъекта(
        ПрефиксацияОбъектовКлиентСервер.УдалитьПрефиксыИзНомераОбъекта(Первый, Истина, Истина));
    Второй = ПрефиксацияОбъектовКлиентСервер.УдалитьЛидирующиеНулиИзНомераОбъекта(
        ПрефиксацияОбъектовКлиентСервер.УдалитьПрефиксыИзНомераОбъекта(Второй, Истина, Истина));

    Возврат Первый = Второй;

КонецФункции
```

**Нюансы и антипаттерны:**

- Сравнивать номера из разных баз без снятия префиксов бессмысленно: у одного и
  того же документа они разные.
- `УдалитьПрефиксыИзНомераОбъекта` по умолчанию не убирает ни один из префиксов -
  оба параметра нужно передавать явно.

### 3. Задать свое правило формирования префикса

**Задача:** префикс организации берется не из типового реквизита, а из своего.

**Функции:**

`ПрефиксацияОбъектовПереопределяемый.ПолучитьПрефиксообразующиеРеквизиты(Объекты) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. ХУК: библиотека вызывает его сама.

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

**Параметры:**

- `Объекты` - `Соответствие`, куда добавляется объект метаданных и имя реквизита,
  из которого берется префиксообразующее значение.
- `СтандартнаяОбработка` - `Булево`; сброс в `Ложь` отключает типовое поведение.

**Пример:**

```bsl
// Модуль ПрефиксацияОбъектовПереопределяемый, тело хука.
Процедура ПолучитьПрефиксообразующиеРеквизиты(Объекты) Экспорт

    Объекты.Вставить(Метаданные.Документы.РасходТовара, "Подразделение");

КонецПроцедуры
```

**Нюансы и антипаттерны:**

- Не вызывать `ПрефиксацияОбъектовПереопределяемый.ПолучитьПрефиксообразующиеРеквизиты(...)`
  из прикладного кода: это хук, его реализуют.
- Реквизит, названный в хуке, должен быть у объекта на момент записи. Пустое
  значение даст номер без префикса организации, а не ошибку.

### 4. Подставить префикс своему объекту

**Задача:** новый документ конфигурации должен получать префикс так же, как
типовые.

**Механизм:** объект включается в подписки на события библиотеки. Обработчики
лежат в `ПрефиксацияОбъектовСобытия` и вызываются подписками, а не прикладным
кодом.

**Нюансы и антипаттерны:**

- Не вызывать обработчики `ПрефиксацияОбъектовСобытия` напрямую из модуля объекта:
  они рассчитаны на параметры подписки и порядок вызовов библиотеки.
- Подписка на событие настраивается в конфигурации; забытая подписка выглядит как
  работающий механизм с номерами без префикса.

## Различия версий

Состав модулей и их экспортные методы в 3.1.11 и 3.2.1 совпадают - сверено по
обеим поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check ПрефиксацияОбъектовКлиентСервер.НомерНаПечать
```

# Версионирование объектов

Механизм БСП, сохраняющий историю изменений объекта: кто и когда правил, что
именно изменилось, откат к прежней версии. Включается на объект метаданных, а не
на конфигурацию целиком.

## Модули механизма

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

Здесь, в отличие от многих механизмов библиотеки, клиентский модуль публичный:
`ВерсионированиеОбъектовКлиент` содержит открытие отчета по версии и по
изменениям. Проверять контекст все равно надо: серверные методы вызывать с
клиента нельзя.

## Сценарии

### 1. Включить версионирование объекта из кода

**Задача:** при внедрении включить хранение истории для своего документа, не
заставляя администратора искать настройку.

**Функции:**

`ВерсионированиеОбъектов.ВключитьВерсионированиеОбъекта(ИмяОбъекта, Знач ВариантВерсионирования = Неопределено) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

`ВерсионированиеОбъектов.ВключеноВерсионированиеОбъекта(ИмяОбъекта) Экспорт`
- функция, тот же регион.

**Параметры:**

- `ИмяОбъекта` - `Строка`, полное имя объекта метаданных.
- `ВариантВерсионирования` - когда версия пишется: при каждой записи, при
  проведении и так далее.

**Пример:**

```bsl
&НаСервере
Процедура ВключитьИсториюПоРасходу()

    ИмяОбъекта = "Документ.РасходТовара";
    Если Не ВерсионированиеОбъектов.ВключеноВерсионированиеОбъекта(ИмяОбъекта) Тогда
        ВерсионированиеОбъектов.ВключитьВерсионированиеОбъекта(ИмяОбъекта);
    КонецЕсли;

КонецПроцедуры
```

**Нюансы и антипаттерны:**

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

### 2. Встроить историю в форму объекта

**Задача:** на форме документа показать команду перехода к истории изменений.

**Функции:**

`ВерсионированиеОбъектов.ПриСозданииНаСервере(Форма) Экспорт` - процедура, регион
`ПрограммныйИнтерфейс`. Сервер.

**Пример:**

```bsl
&НаСервере
Процедура ПриСозданииНаСервере(Отказ, СтандартнаяОбработка)

    ВерсионированиеОбъектов.ПриСозданииНаСервере(ЭтаФорма);

КонецПроцедуры
```

**Нюансы и антипаттерны:**

- Вызов идет в обработчике формы `ПриСозданииНаСервере`, а не в
  `ПриОткрытии`: элементы формы к моменту открытия уже должны быть на месте.
- Имя метода библиотеки совпадает с именем обработчика формы. Это не рекурсия:
  вызывается метод общего модуля, а не сама процедура формы.

### 3. Открыть историю изменений с клиента

**Задача:** по команде формы показать отчет об изменениях объекта.

**Функции:**

`ВерсионированиеОбъектовКлиент.ОткрытьОтчетПоИзменениям(Ссылка, АдресСериализованногоОбъекта) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Тонкий и толстый клиент.

`ВерсионированиеОбъектовКлиент.ОткрытьОтчетПоВерсииОбъекта(Ссылка, АдресСериализованногоОбъекта) Экспорт`
- процедура, тот же регион.

**Пример:**

```bsl
&НаКлиенте
Процедура ИсторияИзменений(Команда)

    ВерсионированиеОбъектовКлиент.ОткрытьОтчетПоИзменениям(Объект.Ссылка, "");

КонецПроцедуры
```

**Нюансы и антипаттерны:**

- Не вызывать серверный `ВерсионированиеОбъектов` из клиентского обработчика:
  у него контексты сервера, толстого клиента и внешнего соединения, на тонком
  клиенте его нет. Для клиента есть парный модуль с суффиксом `Клиент`.
- Ссылка на новый, еще не записанный объект истории не имеет: команду для такого
  случая надо гасить.

### 4. Поправить поведение при восстановлении версии

**Задача:** при откате к прежней версии дозаполнить реквизиты, которых в старой
версии не было.

**Функции:**

`ВерсионированиеОбъектовПереопределяемый.ПриВосстановленииВерсииОбъекта(Объект, ДополнительныеРеквизиты) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. ХУК: библиотека вызывает его сама.

`ВерсионированиеОбъектовПереопределяемый.ПослеРазбораВерсииОбъекта(Ссылка, Результат) Экспорт`
- процедура, тот же регион и та же роль.

**Пример:**

```bsl
// Модуль ВерсионированиеОбъектовПереопределяемый, тело хука.
Процедура ПриВосстановленииВерсииОбъекта(Объект, ДополнительныеРеквизиты) Экспорт

    Если ТипЗнч(Объект) = Тип("ДокументОбъект.РасходТовара")
        И Не ЗначениеЗаполнено(Объект.Ответственный) Тогда
        Объект.Ответственный = Пользователи.ТекущийПользователь();
    КонецЕсли;

КонецПроцедуры
```

**Нюансы и антипаттерны:**

- Не вызывать `ВерсионированиеОбъектовПереопределяемый.ПриВосстановленииВерсииОбъекта(...)`
  из прикладного кода: это хук.
- Не записывать объект внутри хука: запись выполняет библиотека после его вызова,
  и своя запись даст лишнюю версию.

## Различия версий

Состав модулей и их экспортные методы в 3.1.11 и 3.2.1 совпадают - сверено по
обеим поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check ВерсионированиеОбъектов.ВключитьВерсионированиеОбъекта
```

# Организации и настройки программы

Два механизма БСП, задающих рамку внедрения: сведения об организациях с
ответственными лицами и обособленными подразделениями, и форма настроек
программы, куда подсистемы добавляют свои разделы.

## Модули

| Модуль | Механизм | Контексты |
|---|---|---|
| `ОрганизацииСервер` | сведения об организациях, ответственные лица, подразделения | сервер, толстый клиент, внешнее соединение |
| `ОрганизацииПереопределяемый` | точка расширения: свои источники сведений | сервер, толстый клиент, внешнее соединение |
| `НастройкиПрограммыПереопределяемый` | точка расширения формы настроек | сервер, толстый клиент, внешнее соединение |

**Модуля `Организации` без суффикса не существует**: интерфейс лежит в
`ОрганизацииСервер`. У настроек программы своего серверного модуля в публичном
интерфейсе нет вовсе - есть только точка расширения, потому что форма настроек
принадлежит библиотеке.

## Сценарии

### 1. Получить сведения об организации

**Задача:** для печатной формы взять реквизиты и ответственных лиц на дату
документа.

**Механизм:** модуль `ОрганизацииСервер`, регион `ПрограммныйИнтерфейс`. Сервер.

**Нюансы и антипаттерны:**

- Ответственные лица меняются со временем. Брать их НА ДАТУ документа, а не
  текущих: иначе перепечатанный старый документ получит нового подписанта.
- Обособленное подразделение имеет собственные реквизиты. Подставлять реквизиты
  головной организации в его документы неверно.

### 2. Подключить свой источник сведений

**Задача:** реквизиты организации берутся из своего справочника, а не типового.

**Функции:**

Процедуры модуля `ОрганизацииПереопределяемый` - регион `ПрограммныйИнтерфейс`.
ХУКИ: библиотека вызывает их сама.

**Нюансы и антипаттерны:**

- Не вызывать процедуры переопределяемого модуля из прикладного кода: их
  реализуют.
- Хук должен отдавать сведения на любую запрошенную дату, включая прошлые
  периоды: библиотека спрашивает их при перепечатке старых документов.

### 3. Добавить свой раздел в настройки программы

**Задача:** настройки своей подсистемы должны быть там же, где типовые.

**Функции:**

Процедуры модуля `НастройкиПрограммыПереопределяемый` - регион
`ПрограммныйИнтерфейс`. ХУКИ. Каждая отвечает за свою группу настроек: работа с
файлами, пользователи и права, обслуживание, интернет-поддержка.

**Нюансы и антипаттерны:**

- Не заводить свою форму настроек: тогда пользователь ищет настройки в двух
  местах, а права на них расходятся с типовыми.
- Хук вызывается при открытии формы настроек. Тяжелая работа в нем откладывает
  открытие.

## Различия версий

Состав модулей обоих механизмов в 3.1.11 и 3.2.1 совпадает - сверено по обеим
поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py module ОрганизацииСервер
```

# Даты запрета изменения

Механизм БСП, запрещающий править данные раньше указанной даты: закрытый период,
сданная отчетность, зафиксированные остатки. Запрет действует при записи объекта и
при загрузке данных из обмена.

## Модули механизма

| Модуль | Роль | Контексты |
|---|---|---|
| `ДатыЗапретаИзменения` | программный интерфейс: проверка запрета, обработчики подписок | сервер, толстый клиент, внешнее соединение |
| `ДатыЗапретаИзмененияПереопределяемый` | точка расширения: свои разделы запрета | сервер, толстый клиент, внешнее соединение |
| `ДатыЗапретаИзмененияСлужебный` и еще три с тем же суффиксом | внутренняя реализация библиотеки | - |

**Модуля `ДатыЗапрета` без слова `Изменения` не существует**, как и модуля
`ДатыЗапретаИзмененияКлиент`: публичного клиентского интерфейса у механизма нет.
Клиентские модули семейства служебные, все четыре.

## Сценарии

### 1. Проверить запрет перед своей операцией

**Задача:** до записи или до групповой обработки убедиться, что дата попадает в
разрешенный период, и показать понятную причину отказа.

**Функции:**

`ДатыЗапретаИзменения.ИзменениеЗапрещено(ДанныеИлиПолноеИмя, ИдентификаторДанных = Неопределено, ОписаниеОшибки = Null, УзелПроверкиЗапретаЗагрузки = Неопределено) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

`ДатыЗапретаИзменения.НайденЗапретИзмененияДанных(Знач ДанныеДляПроверки, ПараметрыСообщенияОЗапрете = Неопределено, ОписаниеОшибки = Null, УзелПроверкиЗапретаЗагрузки = Неопределено) Экспорт`
- функция, тот же регион. Отличается тем, что сама сообщает пользователю по
переданным параметрам сообщения.

`ДатыЗапретаИзменения.ПараметрыСообщенияОЗапрете() Экспорт` - функция-конструктор
структуры параметров, тот же регион.

**Пример:**

```bsl
&НаСервере
Функция ПериодОткрыт(Знач Ссылка)

    ОписаниеОшибки = "";
    Возврат Не ДатыЗапретаИзменения.ИзменениеЗапрещено(Ссылка, , ОписаниеОшибки);

КонецФункции
```

**Нюансы и антипаттерны:**

- Не сравнивать дату документа с константой даты запрета самостоятельно: запрет
  бывает разным по разделам, по организациям и по видам объектов, и одна дата все
  эти случаи не описывает.
- Параметр `ОписаниеОшибки` передается по ссылке и заполняется библиотекой -
  объявлять переменную нужно до вызова.

### 2. Подключить проверку к своему объекту

**Задача:** свой документ должен подчиняться датам запрета так же, как типовые.

**Механизм:** обработчики подписок на события. Они лежат в самом
`ДатыЗапретаИзменения` и вызываются подписками, а не прикладным кодом.

**Функции (обработчики подписок):**

`ПроверитьДатуЗапретаИзмененияПередЗаписью(Источник, Отказ) Экспорт`,
`ПроверитьДатуЗапретаИзмененияПередЗаписьюДокумента(Источник, Отказ, РежимЗаписи, РежимПроведения) Экспорт`,
`ПроверитьДатуЗапретаИзмененияПередЗаписьюНабораЗаписей(Источник, Отказ, Замещение) Экспорт`,
`ПроверитьДатуЗапретаИзмененияПередУдалением(Источник, Отказ) Экспорт`
- процедуры, регион `ПрограммныйИнтерфейс`. Для регистров бухгалтерии и расчета
есть отдельные обработчики с другой сигнатурой.

**Нюансы и антипаттерны:**

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

### 3. Отключить проверку на время служебной операции

**Задача:** миграция или исправление данных должны пройти мимо запрета.

**Функции:**

`ДатыЗапретаИзменения.ОтключитьПроверкуДатЗапрета(Отключить) Экспорт` - процедура,
регион `ПрограммныйИнтерфейс`.

`ДатыЗапретаИзменения.ПроверкаДатЗапретаОтключена() Экспорт` - функция, тот же
регион.

**Пример:**

```bsl
&НаСервере
Процедура ИсправитьДанныеЗакрытогоПериода()

    ДатыЗапретаИзменения.ОтключитьПроверкуДатЗапрета(Истина);
    Попытка
        // служебная правка
        ДатыЗапретаИзменения.ОтключитьПроверкуДатЗапрета(Ложь);
    Исключение
        ДатыЗапретаИзменения.ОтключитьПроверкуДатЗапрета(Ложь);
        ВызватьИсключение;
    КонецПопытки;

КонецПроцедуры
```

**Нюансы и антипаттерны:**

- Включать проверку обратно обязательно, в том числе при исключении: отключение
  действует на сеанс, и забытый флаг снимает запрет для всей дальнейшей работы
  пользователя.
- Не оставлять отключение в коде, который выполняется по действию пользователя:
  это обход контроля, а не решение задачи.

### 4. Завести свой раздел запрета

**Задача:** запрет нужен не по организации, а по своему измерению - например по
складу.

**Функции:**

`ДатыЗапретаИзмененияПереопределяемый.ПриЗаполненииРазделовДатЗапретаИзменения(Разделы) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. ХУК: библиотека вызывает его сама.

`ДатыЗапретаИзмененияПереопределяемый.ЗаполнитьИсточникиДанныхДляПроверкиЗапретаИзменения(ИсточникиДанных) Экспорт`
- процедура, тот же регион и та же роль: объявляет, откуда брать дату для проверки.

Имя первого хука длиннее, чем кажется: короткого `ПриЗаполненииРазделовДатЗапрета`
в библиотеке НЕТ, слово `Изменения` в конце обязательно.

**Нюансы и антипаттерны:**

- Не вызывать процедуры `ДатыЗапретаИзмененияПереопределяемый` из прикладного
  кода: их реализуют.
- Раздел, объявленный в хуке, должен иметь настройку в интерфейсе, иначе
  пользователь не сможет задать по нему дату.

## Различия версий

Состав модулей и их экспортные методы в 3.1.11 и 3.2.1 совпадают - сверено по
обеим поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check ДатыЗапретаИзменения.ИзменениеЗапрещено
```

# Защита персональных данных

Механизм БСП, ведущий учет доступа к персональным данным и их уничтожение: журнал
событий доступа, согласия субъектов, сроки хранения, встраивание отметок в формы
объектов.

## Модули механизма

| Модуль | Роль | Контексты |
|---|---|---|
| `ЗащитаПерсональныхДанных` | программный интерфейс сервера, 75 методов | сервер, толстый клиент, внешнее соединение |
| `ЗащитаПерсональныхДанныхПереопределяемый` | точка расширения: свои объекты с персональными данными | сервер, толстый клиент, внешнее соединение |

## Сценарии

### 1. Проверить действующее согласие субъекта

**Задача:** до обработки данных убедиться, что согласие получено и не отозвано.

**Функции:**

`ЗащитаПерсональныхДанных.ДействующееСогласиеНаОбработкуПерсональныхДанных(Субъект, Организация = Неопределено, Знач Дата = Неопределено, ИсключаемыйРегистратор = Неопределено) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

**Нюансы и антипаттерны:**

- Согласие привязано к ОРГАНИЗАЦИИ и к дате: действующее у одной организации не
  означает действующего у другой.
- Отсутствие согласия это штатный ответ, а не ошибка программы: обработка данных в
  этом случае прекращается, а пользователю показывается причина.

### 2. Рассчитать срок уничтожения данных

**Задача:** узнать, когда персональные данные субъекта подлежат уничтожению.

**Функции:**

`ЗащитаПерсональныхДанных.ДатаУничтоженияДанныхСубъекта(Субъект) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

`ЗащитаПерсональныхДанных.ДобавитьСубъектыДляРасчетаСроковХранения(Знач Субъекты, Знач ДатаСобытия, ИспользоватьУничтожениеПДн = Неопределено) Экспорт`
- процедура, тот же регион.

`ЗащитаПерсональныхДанных.ЗаполнитьСубъектыДляРасчетаСроковХраненияПерсональныхДанных() Экспорт`
- процедура, тот же регион.

**Нюансы и антипаттерны:**

- Срок считается от ДАТЫ СОБЫТИЯ, а не от даты создания записи. Регистрировать
  событие надо в момент, когда оно произошло.
- Расчет сроков массовый и идет фоново. Ожидать результата сразу после
  регистрации субъекта нельзя.

### 3. Добавить печать согласия

**Задача:** у своего объекта должна быть команда печати согласия.

**Функции:**

`ЗащитаПерсональныхДанных.ДобавитьКомандуПечатиСогласияНаОбработкуПерсональныхДанных(КомандыПечати) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер. Вызывается из процедуры
`ДобавитьКомандыПечати` модуля менеджера объекта.

**Нюансы и антипаттерны:**

- Команда добавляется в общий список команд печати объекта, а не отдельной
  кнопкой: тогда она попадает и в форму списка, и в подменю.

### 4. Объявить свои объекты с персональными данными

**Задача:** свой справочник содержит персональные данные и должен попадать в
учет.

**Функции:**

Процедуры модуля `ЗащитаПерсональныхДанныхПереопределяемый` - регион
`ПрограммныйИнтерфейс`. ХУКИ: библиотека вызывает их сама.

**Нюансы и антипаттерны:**

- Не вызывать процедуры переопределяемого модуля из прикладного кода: их
  реализуют.
- Объект, не объявленный в хуке, в учет доступа не попадет, и журнал событий по
  нему будет пуст. Ошибки при этом нет.

## Различия версий

Состав модулей семейства в 3.1.11 и 3.2.1 совпадает - сверено по обеим поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check ЗащитаПерсональныхДанных.ДатаУничтоженияДанныхСубъекта
```

# Печать

Механизм БСП, формирующий печатные формы: команды печати в объекте, макеты в
табличном документе и в форматах офисных документов, предварительный просмотр,
отправка на принтер и почтой.

## Модули механизма

| Модуль | Роль | Контексты |
|---|---|---|
| `УправлениеПечатью` | программный интерфейс сервера, самый большой модуль механизма | сервер, толстый клиент, внешнее соединение |
| `УправлениеПечатьюКлиент` | программный интерфейс клиента: выполнение команд, просмотр | тонкий и толстый клиент |
| `УправлениеПечатьюПереопределяемый` | точка расширения сервера: свои формы и команды, подмена макетов | сервер, толстый клиент, внешнее соединение |
| `УправлениеПечатьюКлиентПереопределяемый` | точка расширения клиента | тонкий и толстый клиент |
| `УправлениеПечатьюМультиязычностьПереопределяемый` | многоязычность печатных форм | сервер |
| `УправлениеПечатьюРФ` | национальная специфика | сервер |

**Команды печати объявляются в модуле МЕНЕДЖЕРА объекта**, процедурой
`ДобавитьКомандыПечати(КомандыПечати)`, а не в переопределяемом модуле
подсистемы. Переопределяемый модуль нужен, чтобы вмешаться в уже собранный
список или в сам процесс печати.

## Сценарии

### 1. Объявить команду печати у своего объекта

**Задача:** у документа должна появиться кнопка печати со своей формой.

**Механизм:** процедура `ДобавитьКомандыПечати(КомандыПечати)` в модуле менеджера
объекта. Библиотека собирает команды со всех объектов формы и строит подменю
печати.

**Ключевые свойства строки команды:**

- `Идентификатор` - имя макета либо свой идентификатор.
- `Представление` - что видит пользователь в меню.
- `Обработчик` - для нетипового поведения; иначе печать идет через менеджер
  печати объекта.
- `МенеджерПечати` - полное имя объекта, чья процедура `Печать` вызывается.

**Нюансы и антипаттерны:**

- Не добавлять кнопку печати на форму руками: собранная библиотекой команда
  попадает и в форму объекта, и в форму списка, и в подменю рассылки.
- Идентификатор команды должен совпадать с именем макета, если обработчик не
  задан: библиотека ищет макет по нему.

### 2. Сформировать печатную форму в коде

**Задача:** в процедуре `Печать` менеджера объекта заполнить табличный документ и
отдать его библиотеке.

**Функции:**

`УправлениеПечатью.ВывестиТабличныйДокументВКоллекцию(КоллекцияПечатныхФорм, ИмяМакета, СинонимМакета, ТабличныйДокумент, Картинка = Неопределено, ПолныйПутьКМакету = "", ИмяФайлаПечатнойФормы = Неопределено) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

`УправлениеПечатью.НужноПечататьМакет(КоллекцияПечатныхФорм, ИмяМакета) Экспорт`
- функция, тот же регион: пользователь мог снять галку с этой формы.

**Пример:**

```bsl
// Модуль менеджера документа, процедура Печать.
Процедура Печать(МассивОбъектов, ПараметрыПечати, КоллекцияПечатныхФорм,
    ОбъектыПечати, ПараметрыВывода) Экспорт

    Если УправлениеПечатью.НужноПечататьМакет(КоллекцияПечатныхФорм, "Накладная") Тогда
        УправлениеПечатью.ВывестиТабличныйДокументВКоллекцию(
            КоллекцияПечатныхФорм, "Накладная", "Накладная",
            СформироватьНакладную(МассивОбъектов, ОбъектыПечати));
    КонецЕсли;

КонецПроцедуры
```

**Нюансы и антипаттерны:**

- Не формировать макет, не спросив `НужноПечататьМакет`: пользователь мог снять
  галку, и работа уйдет впустую, а на пакетной печати это заметно.
- Заполнять `ОбъектыПечати` обязательно: по нему библиотека связывает области
  документа с объектами и печатает их пачкой.
- Не возвращать табличный документ из процедуры: он кладется в коллекцию, а
  печатью управляет библиотека.

### 3. Выполнить команду печати с клиента

**Задача:** своя кнопка на форме должна печатать так же, как типовая.

**Функции:**

`УправлениеПечатьюКлиент.ВыполнитьКомандуПечати(ИмяМенеджераПечати, ИменаМакетов, МассивОбъектов, ВладелецФормы, ПараметрыПечати = Неопределено) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Тонкий и толстый клиент.

`УправлениеПечатьюКлиент.ВыполнитьКомандуПечатиНаПринтер(ИмяМенеджераПечати, ИменаМакетов, МассивОбъектов, ПараметрыПечати = Неопределено) Экспорт`
- процедура, тот же регион: минуя предварительный просмотр.

**Пример:**

```bsl
&НаКлиенте
Процедура НапечататьНакладную(Команда)

    Объекты = Новый Массив;
    Объекты.Добавить(Объект.Ссылка);

    УправлениеПечатьюКлиент.ВыполнитьКомандуПечати(
        "Документ.РасходТовара", "Накладная", Объекты, ЭтаФорма);

КонецПроцедуры
```

**Нюансы и антипаттерны:**

- Не звать серверный `УправлениеПечатью` из клиентского обработчика: у него нет
  контекста тонкого клиента. Печать с клиента идет через модуль с суффиксом
  `Клиент`.
- Печать на принтер без просмотра не спрашивает пользователя ни о чем. Для
  массовой печати это нужно, для одиночной обычно нет.

### 4. Вмешаться в состав команд печати

**Задача:** скрыть типовую команду печати при определенных условиях либо
добавить свою в чужую форму.

**Функции:**

`УправлениеПечатьюПереопределяемый.ПередДобавлениемКомандПечати(ИмяФормы, КомандыПечати, СтандартнаяОбработка) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. ХУК.

`УправлениеПечатью.ДобавитьУсловиеВидимостиКоманды(КомандаПечати, Реквизит, Значение, Знач МетодСравнения = Неопределено) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`: условие видимости по реквизиту
объекта, вычисляется библиотекой.

**Нюансы и антипаттерны:**

- Не вызывать процедуры `УправлениеПечатьюПереопределяемый` из прикладного кода:
  их реализуют.
- Видимость по реквизиту задается через `ДобавитьУсловиеВидимостиКоманды`, а не
  своим кодом в форме: библиотека вычислит его один раз на список объектов, а
  свой код в форме - на каждое открытие.

### 5. Вмешаться в сам процесс печати

**Задача:** подставить свои параметры вывода или изменить набор форм перед
отправкой почтой.

**Функции:**

`УправлениеПечатьюПереопределяемый.ПередПечатью(Знач ИдентификаторПечатнойФормы, ОбъектыПечати, ПараметрыПечати) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. ХУК.

`УправлениеПечатьюПереопределяемый.ПередОтправкойПоПочте(ПараметрыОтправки, ПараметрыВывода, ОбъектыПечати, ПечатныеФормы) Экспорт`
- процедура, тот же регион и та же роль.

**Нюансы и антипаттерны:**

- Хуки вызываются на КАЖДУЮ печать. Тяжелая работа в них замедляет каждое
  открытие формы печати.
- Не подменять здесь содержимое макета: за макет отвечает менеджер печати
  объекта, а эти хуки за параметры процесса.

## Различия версий

Состав модулей семейства в 3.1.11 и 3.2.1 совпадает - сверено по обеим поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check УправлениеПечатью.ВывестиТабличныйДокументВКоллекцию
```

# Варианты отчетов

Механизм БСП, размещающий отчеты и их варианты в интерфейсе: какие варианты
предопределены, в каких разделах они видны, какие команды отчетов появляются на
формах объектов. Пользовательские варианты хранятся отдельно от предопределенных.

Не путать с системой компоновки данных: там устройство самого отчета, здесь его
место в программе.

## Модули механизма

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

## Сценарии

### 1. Настроить варианты своего отчета

**Задача:** объявить предопределенные варианты и то, где они показываются.

**Функции:**

`ВариантыОтчетов.НастроитьОтчетВМодулеМенеджера(Настройки, ОтчетМетаданные) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер. Вызывается из модуля
менеджера самого отчета.

`ВариантыОтчетов.ВариантОтчета(Отчет, КлючВарианта) Экспорт` - функция, тот же
регион.

`ВариантыОтчетов.КлючиВариантовОтчета(КлючОтчета, Знач Пользователь = Неопределено) Экспорт`
- функция, тот же регион.

**Нюансы и антипаттерны:**

- Настройка идет в модуле менеджера ОТЧЕТА, а не в переопределяемом модуле
  подсистемы: там объявляются разделы и общие правила, а не устройство конкретного
  отчета.
- Ключ варианта должен совпадать с именем варианта схемы компоновки. Расхождение
  дает вариант, который не открывается.

### 2. Объявить разделы, где виден отчет

**Задача:** отчет должен появиться в нужных разделах командного интерфейса.

**Функции:**

`ВариантыОтчетовПереопределяемый.ОпределитьРазделыСВариантамиОтчетов(Разделы) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. ХУК.

`ВариантыОтчетовПереопределяемый.НастроитьВариантыОтчетов(Настройки) Экспорт`
- процедура, тот же регион и та же роль.

**Нюансы и антипаттерны:**

- Не вызывать процедуры `ВариантыОтчетовПереопределяемый` из прикладного кода: их
  реализуют.
- Раздел, не объявленный в хуке, панель отчетов не получит, и отчеты в нем не
  покажутся. Ошибки при этом нет.

### 3. Добавить команду отчета на форму объекта

**Задача:** из формы документа открывать отчет с подставленным отбором.

**Функции:**

`ВариантыОтчетовПереопределяемый.ОпределитьОбъектыСКомандамиОтчетов(Объекты) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. ХУК.

`ВариантыОтчетовПереопределяемый.ПередДобавлениемКомандОтчетов(КомандыОтчетов, Параметры, СтандартнаяОбработка) Экспорт`
- процедура, тот же регион и та же роль.

**Нюансы и антипаттерны:**

- Команды отчетов размещаются на форме подключаемыми командами. Своя кнопка
  вместо них лишает отчет отбора по текущему объекту.
- Хук `ПередДобавлениемКомандОтчетов` вызывается для каждой формы. Тяжелая работа
  в нем замедляет открытие всех форм с командами отчетов.

### 4. Перенести пользовательские варианты при переименовании

**Задача:** ключ варианта изменился, а сохраненные пользователями настройки
должны остаться.

**Функции:**

`ВариантыОтчетовПереопределяемый.ЗарегистрироватьИзмененияКлючейВариантовОтчетов(Изменения) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. ХУК.

`ВариантыОтчетов.ЗагрузитьПользовательские(ПользовательскиеВарианты = Неопределено) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

**Нюансы и антипаттерны:**

- Без регистрации изменения ключа пользовательские варианты теряются молча: они
  остаются в базе, но не привязываются к новому ключу.
- Регистрация нужна ОДИН раз, на версию, где произошло переименование.

## Различия версий

Состав модулей семейства в 3.1.11 и 3.2.1 совпадает - сверено по обеим поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check ВариантыОтчетов.НастроитьОтчетВМодулеМенеджера
```

# Регламентные задания

Механизм БСП для заданий по расписанию: объявление собственного задания, поиск,
включение и выключение, чтение расписания и результата последнего выполнения.

Не путать с длительными операциями. Регламентное задание запускается ПЛАНИРОВЩИКОМ
по расписанию и работает без пользователя. Длительная операция запускается
действием пользователя и держит форму ожидания. Механизмы разные, модули разные.

## Модули механизма

| Модуль | Роль | Контексты |
|---|---|---|
| `РегламентныеЗаданияСервер` | программный интерфейс, его и вызывают | сервер, толстый клиент, внешнее соединение |
| `РегламентныеЗаданияПереопределяемый` | точка расширения: свои задания и расписания | сервер, толстый клиент, внешнее соединение |
| `РегламентныеЗаданияКлиент` | служебный, в прикладном коде не вызывается | тонкий и толстый клиент |
| `РегламентныеЗаданияСлужебный` | внутренняя реализация библиотеки | - |

**Модуля `РегламентныеЗадания` без суффикса не существует.** Имя выглядит
правдоподобно и в коде встречается как выдумка; программный интерфейс лежит
в `РегламентныеЗаданияСервер`.

**`РегламентныеЗаданияКлиент` объявлен целиком в регионе
`СлужебныйПрограммныйИнтерфейс`** - проверено по исходнику библиотеки. Клиентского
публичного интерфейса у механизма нет, и попытка позвать оттуда что-нибудь из
прикладного кода нарушает границу библиотеки.

## Сценарии

### 1. Объявить свое регламентное задание

**Задача:** добавить в конфигурацию задание, которое библиотека покажет в списке
настройки, а планировщик запустит по расписанию.

**Механизм:** объект метаданных `РегламентноеЗадание` создается в конфигурации, а
его описание для библиотеки заполняется в переопределяемом обработчике.

**Функции:**

`РегламентныеЗаданияПереопределяемый.ПриОпределенииНастроекРегламентныхЗаданий(Настройки) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Это ХУК: библиотека вызывает его сама,
прикладной код только реализует тело. Вызывать по имени модуля нельзя.

**Параметры:**

- `Настройки` - `ТаблицаЗначений`, куда добавляется строка на каждое свое задание.
  Заполняются метаданные задания и, при необходимости, форма настройки и
  зависимости от функциональных опций.

**Пример:**

```bsl
// Модуль РегламентныеЗаданияПереопределяемый, тело хука.
Процедура ПриОпределенииНастроекРегламентныхЗаданий(Настройки) Экспорт

    Настройка = Настройки.Добавить();
    Настройка.МетаданныеЗадания = Метаданные.РегламентныеЗадания.ЗагрузкаКурсовВалют;

КонецПроцедуры
```

**Нюансы и антипаттерны:**

- Не вызывать `РегламентныеЗаданияПереопределяемый.ПриОпределенииНастроекРегламентныхЗаданий(...)`
  из прикладного кода. Хук реализуют, а не зовут.
- Обработчик самого задания пишется в отдельном общем модуле и указывается в
  свойстве `ИмяМетода` объекта метаданных, а не в этом хуке.
- Второй метод модуля, `ПриОпределенииНастроек`, отвечает за общие настройки
  подсистемы, а не за перечень заданий. Имена похожи, назначение разное.

### 2. Найти задание по метаданным

**Задача:** получить объект задания, чтобы дальше включить его, выключить или
прочитать расписание.

**Функции:**

`РегламентныеЗаданияСервер.НайтиЗадания(Отбор) Экспорт` - функция, регион
`ПрограммныйИнтерфейс`. Сервер, толстый клиент, внешнее соединение.

**Параметры:**

- `Отбор` - `Структура` с полями отбора; чаще всего заполняется `Метаданные`.
- Возвращает `Массив` из `РегламентноеЗадание` в локальном режиме и
  `ТаблицаЗначений` в модели сервиса - это описано в шапке метода библиотеки.
  Код, рассчитанный только на массив, в модели сервиса сломается.

**Пример:**

```bsl
&НаСервере
Функция НайтиЗаданиеЗагрузкиКурсов()

    Отбор = Новый Структура;
    Отбор.Вставить("Метаданные", Метаданные.РегламентныеЗадания.ЗагрузкаКурсовВалют);

    Задания = РегламентныеЗаданияСервер.НайтиЗадания(Отбор);
    Возврат ?(Задания.Количество() > 0, Задания[0], Неопределено);

КонецФункции
```

**Нюансы и антипаттерны:**

- Не обращаться к `РегламентныеЗадания.НайтиРегламентныеЗадания(...)` платформы
  напрямую: в модели сервиса заданий там нет, они лежат в очереди заданий.
  Функция библиотеки скрывает это различие.
- Пустой результат - штатный случай, а не ошибка: задание могло быть удалено из
  конфигурации при обновлении.

### 3. Включить или выключить задание из кода

**Задача:** погасить задание на время миграции данных и вернуть обратно.

**Функции:**

`РегламентныеЗаданияСервер.УстановитьИспользованиеРегламентногоЗадания(Знач Идентификатор, Знач Использование) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`.

`РегламентныеЗаданияСервер.РегламентноеЗаданиеИспользуется(Знач Идентификатор) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`.

**Параметры:**

- `Идентификатор` - метаданные задания, его уникальный идентификатор либо сам
  объект задания.
- `Использование` - `Булево`.

**Пример:**

```bsl
&НаСервере
Процедура ОстановитьЗагрузкуНаВремяМиграции()

    Задание = Метаданные.РегламентныеЗадания.ЗагрузкаКурсовВалют;
    Если РегламентныеЗаданияСервер.РегламентноеЗаданиеИспользуется(Задание) Тогда
        РегламентныеЗаданияСервер.УстановитьИспользованиеРегламентногоЗадания(Задание, Ложь);
    КонецЕсли;

КонецПроцедуры
```

**Нюансы и антипаттерны:**

- Не менять свойство `Использование` у объекта задания напрямую с последующей
  записью: в модели сервиса это не даст эффекта, а библиотека не узнает об
  изменении.
- Выключение не прерывает уже запущенное задание. Оно лишь не будет запущено
  снова.

### 4. Прочитать и изменить расписание

**Задача:** показать пользователю текущее расписание и записать новое.

**Функции:**

`РегламентныеЗаданияСервер.РасписаниеРегламентногоЗадания(Знач Идентификатор, Знач ВСтруктуре = Ложь) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`.

`РегламентныеЗаданияСервер.УстановитьРасписаниеРегламентногоЗадания(Знач Идентификатор, Знач Расписание) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`.

`ОбщегоНазначенияКлиентСервер.РасписаниеВСтруктуру(Знач Расписание) Экспорт` и
`ОбщегоНазначенияКлиентСервер.СтруктураВРасписание(Знач РасписаниеСтруктурой) Экспорт`
- функции, регион `ПрограммныйИнтерфейс`. Доступны и на клиенте, и на сервере.

**Параметры:**

- `ВСтруктуре` - `Булево`. Истина возвращает расписание структурой, а не объектом
  `РасписаниеРегламентногоЗадания`.

**Пример:**

```bsl
&НаСервере
Процедура ПеренестиЗапускНаНочь()

    Задание = Метаданные.РегламентныеЗадания.ЗагрузкаКурсовВалют;

    Расписание = РегламентныеЗаданияСервер.РасписаниеРегламентногоЗадания(Задание);
    Расписание.ВремяНачала = Дата(1, 1, 1, 3, 0, 0);

    РегламентныеЗаданияСервер.УстановитьРасписаниеРегламентногоЗадания(Задание, Расписание);

КонецПроцедуры
```

**Нюансы и антипаттерны:**

- Объект `РасписаниеРегламентногоЗадания` НЕ сериализуется и на клиент как есть не
  передается. Для передачи между клиентом и сервером его переводят в структуру
  парой `РасписаниеВСтруктуру` и `СтруктураВРасписание`; ключ `ВСтруктуре`
  делает то же самое на чтении.
- Расписание, полученное функцией, это копия. Правка копии ничего не меняет, пока
  не вызвана `УстановитьРасписаниеРегламентногоЗадания`.

### 5. Узнать, чем кончилось последнее выполнение

**Задача:** показать в интерфейсе, когда задание отработало и не упало ли.

**Функции:**

`РегламентныеЗаданияСервер.СвойстваПоследнегоЗадания(Знач Задание) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`.

**Пример:**

```bsl
&НаСервере
Функция СостояниеПоследнейЗагрузки()

    Задание = Метаданные.РегламентныеЗадания.ЗагрузкаКурсовВалют;
    Свойства = РегламентныеЗаданияСервер.СвойстваПоследнегоЗадания(Задание);

    Если Свойства = Неопределено Тогда
        Возврат "Задание еще ни разу не выполнялось";
    КонецЕсли;

    Возврат Свойства.Состояние;

КонецФункции
```

**Нюансы и антипаттерны:**

- `Неопределено` при первом обращении - штатный случай, а не ошибка.
- Не разбирать журнал регистрации ради того же результата: функция библиотеки
  возвращает свойства фонового задания напрямую.

## Различия версий

- Модуль `ДополнительныеОтчетыИОбработкиРегламентныеЗаданияВМоделиСервиса` есть в
  библиотеке 3.1.11 и отсутствует в 3.2.1 - проверено по обеим поставкам. Код,
  ссылающийся на него, при переходе на 3.2.1 перестанет компилироваться.
- Состав `РегламентныеЗаданияСервер` и `РегламентныеЗаданияПереопределяемый` в
  этих версиях совпадает.

## Проверка перед использованием

Любой вызов из этого справочника проверяется до того, как попадет в код:

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check РегламентныеЗаданияСервер.НайтиЗадания
```

Проверка сообщает и об устаревании вызова, а не только о его существовании.

# Модель сервиса, обсуждения, анкетирование, особые случаи внедрения

Четыре темы, у которых прикладного программного интерфейса почти нет: работа
библиотеки в модели сервиса, обсуждения через систему взаимодействия,
анкетирование, а также особенности внедрения подсистем в нетиповых случаях.

Справочник короткий намеренно: там, где интерфейса нет, честнее сказать об этом,
чем описывать несуществующие вызовы.

## Модули

| Модуль | Механизм | Контексты |
|---|---|---|
| `РаботаВМоделиСервисаБСП` | контроль неразделенных данных при записи, два метода | сервер, толстый клиент, внешнее соединение |
| `Обсуждения` | обсуждения и сообщения через систему взаимодействия | сервер, толстый клиент, внешнее соединение |

**Имя модуля модели сервиса кончается на `БСП`:** `РаботаВМоделиСервисаБСП`, а не
`РаботаВМоделиСервиса`. Второго в библиотеке нет, проверено по обеим поставкам.

**Публичных модулей у анкетирования и у особых случаев внедрения НЕТ.**
Анкетирование работает документами и отчетами конфигурации, особые случаи
внедрения это раздел документации, а не механизм. Проверено по обеим поставкам.

## Сценарии

### 1. Проконтролировать разделение данных при записи

**Задача:** в модели сервиса неразделенные данные не должны меняться из области.

**Функции:**

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

**Нюансы и антипаттерны:**

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

### 2. Проверить доступность обсуждений

**Задача:** показать команду обсуждения только там, где система взаимодействия
настроена.

**Функции:**

`Обсуждения.ОбсужденияДоступны() Экспорт` - функция, регион
`ПрограммныйИнтерфейс`. Сервер.

`Обсуждения.ОписаниеВложения(Поток, Наименование) Экспорт` - функция, тот же
регион.

`Обсуждения.ОбновитьПользователяВСистемеВзаимодействия(Пользователь) Экспорт`
- процедура, тот же регион.

**Нюансы и антипаттерны:**

- Система взаимодействия внешняя. При недоступности сервиса обсуждения не
  работают, и команда должна быть скрыта, а не падать.
- Пользователь заводится в системе взаимодействия отдельно от пользователя базы.
  Пропуск обновления оставит его без доступа к обсуждениям.

### 3. Анкетирование

**Механизм:** работает документами, справочниками и отчетами конфигурации.
Публичных общих модулей у него нет: анкеты создаются и обрабатываются штатными
объектами, а не вызовами из прикладного кода.

**Нюансы и антипаттерны:**

- Искать модуль `Анкетирование` бесполезно: его нет. Работа идет через объекты
  метаданных подсистемы.

### 4. Особые случаи внедрения подсистем

**Механизм:** это раздел документации, а не программный механизм. Он описывает,
что делать при нетиповом внедрении: частичное подключение подсистемы, конфликты
имен, отказ от части функциональности.

**Нюансы и антипаттерны:**

- Модуля с таким именем нет и быть не может. Раздел читают, а не вызывают.

## Различия версий

Состав модулей в 3.1.11 и 3.2.1 совпадает - сверено по обеим поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check Обсуждения.ОбсужденияДоступны
```

# Сервисы подписи: МЧД, DSS, мобильная подпись

Три механизма БСП вокруг электронной подписи, каждый со своим сервисом:
машиночитаемые доверенности ФНС, облачная криптография DSS, подписание через
мобильное устройство.

Основной механизм подписи описан отдельно; здесь только то, что добавляют
сервисы.

## Модули

| Модуль | Механизм | Контексты |
|---|---|---|
| `МашиночитаемыеДоверенности` | доверенности ФНС: формирование, подписание, регистрация, проверка | сервер, толстый клиент, внешнее соединение |
| `МашиночитаемыеДоверенностиФНСПереопределяемый` | точка расширения МЧД | сервер, толстый клиент, внешнее соединение |
| `СервисКриптографииDSS` и семейство из шести модулей | облачная криптография DSS | сервер / клиент |
| `СервисМобильнойПодписи`, `СервисМобильнойПодписиКлиентСервер` | подписание через мобильное устройство | сервер / общий |

**Имя модуля DSS не совпадает с названием подсистемы.** Подсистема называется
"Электронная подпись сервиса DSS", а модули начинаются с `СервисКриптографииDSS`.
Модуля `ЭлектроннаяПодписьDSS` в библиотеке НЕТ, проверено по обеим поставкам.

## Сценарии

### 1. Проверить доверенность подписанта

**Задача:** до приема подписанного документа убедиться, что доверенность
действует.

**Механизм:** модуль `МашиночитаемыеДоверенности`, регион `ПрограммныйИнтерфейс`.
Сервер. Формирование, подписание, регистрация в ФНС и проверка идут через него.

**Нюансы и антипаттерны:**

- Проверка обращается к внешнему сервису ФНС. Она сетевая, долгая и может быть
  недоступна: результат кэшируется библиотекой, а свой код обязан обрабатывать
  отказ сервиса.
- Доверенность привязана к сертификату подписанта. Действующая доверенность с
  чужим сертификатом документ не подтверждает.

### 2. Подписать через облачный сервис

**Задача:** у пользователя нет локального сертификата, ключ лежит в облаке.

**Механизм:** семейство `СервисКриптографииDSS`. Клиентская и серверная части
разделены, подтверждение операции интерактивное.

**Нюансы и антипаттерны:**

- Подписание через DSS все равно требует подтверждения ПОЛЬЗОВАТЕЛЕМ: серверный
  код не подпишет документ молча.
- Отдельный модуль подтверждения на клиенте существует именно потому, что
  операция асинхронная и с ожиданием ответа сервиса.

### 3. Подписать с мобильного устройства

**Задача:** руководитель подписывает документ телефоном.

**Механизм:** `СервисМобильнойПодписи` и его общая часть
`СервисМобильнойПодписиКлиентСервер`.

**Нюансы и антипаттерны:**

- Подпись приходит асинхронно и позже: документ остается неподписанным до ответа
  устройства, и интерфейс должен это показывать.
- Не считать вызов отправки подписанием: он лишь запрашивает подпись.

## Различия версий

Состав модулей всех трех механизмов в 3.1.11 и 3.2.1 совпадает - сверено по обеим
поставкам.

## Проверка перед использованием

Имена модулей здесь длинные и несовпадающие с названиями подсистем, поэтому
проверка особенно нужна:

```bash
python skills/1c-bsp-api/scripts/bsp-api.py modules СервисКриптографииDSS
```

# Рабочее место пользователя: напоминания, заметки, текущие дела, взаимодействия

Четыре механизма БСП, из которых складывается личное рабочее место: напоминания к
объектам и датам, личные заметки, начальная страница с текущими делами, история
писем, звонков и встреч с контактами.

## Модули

| Модуль | Механизм | Контексты |
|---|---|---|
| `НапоминанияПользователя` | напоминания к объектам и датам | сервер, толстый клиент, внешнее соединение |
| `НапоминанияПользователяКлиент` | показ и откладывание напоминания | тонкий и толстый клиент |
| `ЗаметкиПользователя` | личные заметки к объектам и разделам | сервер, толстый клиент, внешнее соединение |
| `ТекущиеДела` | начальная страница: состав дел, счетчики, обновление | сервер, толстый клиент, внешнее соединение |
| `Взаимодействия` | письма, звонки, встречи, планируемые взаимодействия | сервер, толстый клиент, внешнее соединение |

## Сценарии

### 1. Создать и найти напоминание

**Задача:** поставить пользователю напоминание о сроке по документу.

**Функции:**

`НапоминанияПользователя.НайтиНапоминания(Знач Предмет = Неопределено, Идентификатор = Неопределено) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

`НапоминанияПользователя.ОбновитьНапоминанияПоПредметам(Предметы) Экспорт`
- процедура, тот же регион.

`НапоминанияПользователя.ИспользуютсяНапоминанияПользователя() Экспорт` - функция,
тот же регион.

**Нюансы и антипаттерны:**

- Проверять, включен ли механизм, до создания напоминания: при выключенном оно
  создастся и не покажется.
- Напоминание привязано к ПРЕДМЕТУ. Обновление по предметам сдвигает сроки пачкой,
  а не заводит новые.

### 2. Собрать счетчики текущих дел

**Задача:** на начальной странице показать, сколько задач ждет пользователя.

**Механизм:** модуль `ТекущиеДела` и его переопределяемая часть. Своя подсистема
объявляет дела и считает их количество; библиотека размещает их на начальной
странице и обновляет.

**Нюансы и антипаттерны:**

- Счетчик считается при КАЖДОМ открытии начальной страницы. Тяжелый запрос там
  замедляет вход в программу всем пользователям.
- Дело без счетчика показывается без числа. Это допустимо, когда подсчет дорогой.

### 3. Заполнить реквизиты взаимодействия

**Задача:** создать письмо или звонок из кода с правильным заполнением.

**Функции:**

`Взаимодействия.ЗаполнитьРеквизитыПоУмолчанию(Объект, ДанныеЗаполнения) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. Сервер.

`Взаимодействия.ЗаполнитьНаборыЗначенийДоступаПоУмолчанию(Объект, Таблица) Экспорт`
- процедура, тот же регион.

`Взаимодействия.ИспользуетсяПочтовыйКлиент() Экспорт` и
`Взаимодействия.ИспользуетсяОтправкаПисемВФорматеHTML() Экспорт` - функции, тот же
регион.

**Нюансы и антипаттерны:**

- Взаимодействия участвуют в ограничении доступа. Пропуск заполнения наборов
  значений оставит запись видимой не тем, кому следует.
- Формат письма зависит от настройки. Собирать HTML, не проверив ее, значит
  показать пользователю разметку текстом.

### 4. Отметить изменение пометки удаления

**Задача:** заметки и связанные данные должны знать, что объект помечен на
удаление.

**Функции:**

`ЗаметкиПользователя.УстановитьСтатусИзмененияПометкиУдаленияОбъекта(Источник, Отказ) Экспорт`
и `ЗаметкиПользователя.УстановитьСтатусИзмененияПометкиУдаленияДокумента(Источник, Отказ, РежимЗаписи, РежимПроведения) Экспорт`
- процедуры, регион `ПрограммныйИнтерфейс`. Сервер. Это обработчики подписок на
события, а не методы для прямого вызова.

**Нюансы и антипаттерны:**

- Обработчик подбирается ПО ВИДУ объекта: у документа и у прочих объектов разные
  сигнатуры, и подписка с чужим обработчиком не скомпилируется.
- Не звать их из модуля объекта напрямую: они рассчитаны на параметры подписки.

## Различия версий

Состав модулей всех четырех механизмов в 3.1.11 и 3.2.1 совпадает - сверено по
обеим поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check НапоминанияПользователя.НайтиНапоминания
```

# Пользователи

Механизм БСП, связывающий элемент справочника пользователей с учетной записью
информационной базы: текущий пользователь, полнота прав, внешние пользователи,
настройки пользователя.

Отвечает на вопрос КТО работает. На вопрос ЧТО ему разрешено видеть отвечает
управление доступом - другой механизм и другие модули.

## Модули механизма

| Модуль | Роль | Контексты |
|---|---|---|
| `Пользователи` | программный интерфейс сервера | сервер, толстый клиент, внешнее соединение |
| `ПользователиКлиент` | программный интерфейс клиента, четыре функции | тонкий и толстый клиент |
| `ПользователиКлиентСервер` | общая часть | сервер и клиент |
| `ПользователиПереопределяемый` | точка расширения | сервер, толстый клиент, внешнее соединение |
| `ВнешниеПользователи`, `ВнешниеПользователиКлиент` | контрагенты и партнеры, работающие через отдельный вход | сервер / клиент |
| `ПользователиСлужебный` и еще восемь с тем же началом | внутренняя реализация библиотеки | - |

Клиентский модуль здесь публичный, но НЕБОЛЬШОЙ: в нем четыре функции о текущем
пользователе. Все остальное на сервере.

## Сценарии

### 1. Получить текущего пользователя

**Задача:** подставить автора в документ, отфильтровать список по пользователю,
показать имя в заголовке.

**Функции:**

`Пользователи.ТекущийПользователь() Экспорт` - функция, регион
`ПрограммныйИнтерфейс`. Сервер, толстый клиент, внешнее соединение. Возвращает
`СправочникСсылка.Пользователи`.

`ПользователиКлиент.ТекущийПользователь() Экспорт` - функция, тот же регион.
Тонкий и толстый клиент.

`Пользователи.АвторизованныйПользователь() Экспорт` и парная
`ПользователиКлиент.АвторизованныйПользователь() Экспорт` - функции, тот же
регион. Отличие от текущего: в сеансе внешнего пользователя возвращается объект
авторизации, а не элемент справочника пользователей.

**Пример:**

```bsl
&НаКлиенте
Процедура ПриОткрытии(Отказ)

    Заголовок = "Работает: " + Строка(ПользователиКлиент.ТекущийПользователь());

КонецПроцедуры

&НаСервере
Процедура ЗаполнитьАвтора(Объект)

    Объект.Автор = Пользователи.ТекущийПользователь();

КонецПроцедуры
```

**Нюансы и антипаттерны:**

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

### 2. Проверить полноту прав

**Задача:** показать администратору то, что не показывают остальным.

**Функции:**

`Пользователи.ЭтоПолноправныйПользователь(Пользователь = Неопределено, ПроверятьПраваАдминистрированияСистемы = Ложь, СчитатьПолноправнымПользователемВФайловойИБ = Истина) Экспорт`
- функция, регион `ПрограммныйИнтерфейс`. Сервер.

`ПользователиКлиент.ЭтоПолноправныйПользователь(ПроверятьПраваАдминистрированияСистемы = Ложь) Экспорт`
- функция, тот же регион. Клиент.

**Нюансы и антипаттерны:**

- Не проверять полноту прав перечислением ролей: набор ролей администратора
  различается между конфигурациями и внедрениями.
- Полнота прав это не разрешение на конкретные данные. Право на запись
  проверяется управлением доступом, а не этой функцией.

### 3. Понять, что сеанс внешнего пользователя

**Задача:** для контрагента, работающего через отдельный вход, показать другой
интерфейс.

**Функции:**

`Пользователи.ЭтоСеансВнешнегоПользователя() Экспорт` и парная
`ПользователиКлиент.ЭтоСеансВнешнегоПользователя() Экспорт` - функции, регион
`ПрограммныйИнтерфейс`.

`ВнешниеПользователи.ПолучитьОбъектАвторизацииВнешнегоПользователя(ВнешнийПользователь = Неопределено) Экспорт`
- функция, тот же регион. Сервер. Возвращает того контрагента или физическое
лицо, от имени которого работает внешний пользователь.

`ВнешниеПользователи.ИспользоватьВнешнихПользователей() Экспорт` - функция, тот
же регион: включен ли механизм вообще.

**Нюансы и антипаттерны:**

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

### 4. Найти пользователя по учетной записи базы

**Задача:** сопоставить учетную запись информационной базы с элементом
справочника.

**Функции:**

`Пользователи.НайтиПоИдентификатору(Знач ИдентификаторПользователяИБ) Экспорт`,
`Пользователи.НайтиПоИмени(Знач ИмяДляВхода) Экспорт`,
`Пользователи.НайтиПоСсылке(Пользователь) Экспорт` - функции, регион
`ПрограммныйИнтерфейс`. Сервер.

**Нюансы и антипаттерны:**

- Не искать пользователя запросом по наименованию справочника: имя для входа и
  наименование это разные поля, и совпадают они не всегда.
- Пустой результат штатный: учетная запись могла быть удалена из базы, а элемент
  справочника остаться.

### 5. Выполнить свое действие при записи пользователя

**Задача:** при создании учетной записи завести связанные данные.

**Функции:**

`ПользователиПереопределяемый.ПриЗаписиПользователяИнформационнойБазы(Знач СтарыеСвойства, Знач НовыеСвойства) Экспорт`
- процедура, регион `ПрограммныйИнтерфейс`. ХУК: библиотека вызывает его сама.

`ПользователиПереопределяемый.ПослеУдаленияПользователяИнформационнойБазы(Знач СтарыеСвойства) Экспорт`
- процедура, тот же регион и та же роль.

`ПользователиПереопределяемый.ПриОпределенииНазначенияРолей(НазначениеРолей) Экспорт`
- процедура, тот же регион: объявляет, какие роли считать служебными и какие
назначаются автоматически.

**Нюансы и антипаттерны:**

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

## Различия версий

Состав модулей семейства в 3.1.11 и 3.2.1 совпадает - сверено по обеим поставкам.

## Проверка перед использованием

```bash
python skills/1c-bsp-api/scripts/bsp-api.py check Пользователи.ТекущийПользователь
```