added new and updated existing documentation (#58)

Добавлена документация на подсистемы
2024-11-21 17:56:47 +02:00 · 2024-05-06 18:47:27 +03:00 · 2024-05-06 18:47:27 +03:00 · 37712a2817
commit 37712a2817
parent 45faad37f8
6 changed files with 184 additions and 21 deletions
--- a/README.md
+++ b/README.md
@ -16,11 +16,12 @@

 1. [Предопределенные значения](docs/ПредопределенныеЗначения.md)
 2. [Соответствия объектов ИБ](docs/СоответствиеОбъектовИнформационнойБазы.md)
-3. [Программная модификация форм](docs/РаботаСФормами.md)
-4. Подписки на события
+3. [Программная модификация форм](docs/МодификацияФорм.md)
+4. [Подписки на события](docs/ПодпискиНаСобытия.md)
 5. Управление интеграциями
-6. Пользовательские функции
+6. [Пользовательские функции](docs/ПользовательскиеФункции.md)
 7. [Загрузка файла через табличный документ](docs/ЗагрузкаФайлаЧерезТабличныйДокумент.md)
+8. [Переопределения методов БСП](docs/ПереопределениеМетодовБСП.md)

 ## Заимствованные разработки

--- a/docs/МодификацияФорм.md
+++ b/docs/МодификацияФорм.md
@ -1,4 +1,14 @@
-# Общий модуль __РаботаСФормами - Модуль динамического формирования интерфейса
+# Подсистема "модификация форм"
+
+Предназначена для динамического формирования интерфейса. Также использовать в случае изменения типовых форма.
+
+- Общий модуль **__МодификацияКонфигурацииПереопределяемый** используется для маршрутизации из серверных процедур (напр. **ПриСозданииНаСервере**) по дополнительным модулям разбитым по объектам (напр. **__МодификацияКонфигурацииПереопределяемыйДокумент**). В сам модуль **__МодификацияКонфигурацииПереопределяемый** могут добавляться обработчики событий которых нет изначально.
+- Для вызова общего модуля **__МодификацияКонфигурацииПереопределяемый**:
+  - В случае если в типовой форме которую нужно программно изменить есть в обработчике события вызов типового общего модуля **МодификацияКонфигурацииПереопределяемый** или **СобытияФорм**, то необходимо добавить в общий модуль **__ОбщегоНазначенияПовтИсп** соответствие в нужную функцию (напр. **ФормыПриСозданииНаСервере**)
+  - В случае если в типовой форме отсутствуют данные вызовы типовых модулей, то необходимо вызывать сразу общий модуль **__МодификацияКонфигурацииПереопределяемый** через добавление в расширение обработчика события **После**.
+- В переопределяемом общем модуле для объекта (напр. **__МодификацияКонфигурацииПереопределяемыйДокумент**) необходимо добавить процедуру-обработчик изменения (напр. **ДокументАвансовыйОтчетФормаДокументаПриСозданииНаСервере(Форма, Отказ, СтандартнаяОбработка, ДополнительныеПараметры = Неопределено) Экспорт**)
+- Использовать функции и процедуры общего модуля **__РаботаСФормами** для уменьшения объема текста при добавлении элементов (напр. **__РаботаСФормами.СоздатьПоле(Форма, "_ДемоДата", ГруппаНомерДата, "от", 1, "_ДемоДата")**)
+- В случае если для нужного типа объекта ещё не был создан общий модуль, создать его и добавить в подсистему **__МодификацияФорм**

 Демо-пример использования методов общего модуля

--- a/docs/ПодпискиНаСобытия.md
+++ b/docs/ПодпискиНаСобытия.md
@ -0,0 +1,54 @@
+# Подсистема "подписки на события"
+
+Подписки на события применяются для реализации дополнительной постобработки или проверок, которые активируются после определённых событий в типовых объектах или модулях менеджера.
+В случае отстутствия типовой подписки, используется подсистема **"Подписки на события"**. Если нужно внести изменения в типовую логику работы подписки, используется заимствование методов в расширении с аннотацией &ИзменениеИКонтроль.
+
+Порядок действий при работе с подсистемой:
+ - Необходимо проверить, существует ли общая подписка на нужный тип объекта и событие. Например: **ДокументОбработкаПроведения**, **СправочникПриЗаписи** и так далее.
+Недопускается смешение типов объектов и событий в одной подписке. Если подписки не существует, нужно её добавить, а так же общий модуль с аналогичным названием (напр. **__ДокументыОбработкаЗаполнения** - и подписка, и общий модуль).
+Добавить их в подсистему **__ПодпискиНаСобытия**.
+ - Если создана новая подписка и модуль, то в модуле создается обработчик для подписки и выбрать его в подписке. У каждого события свой набор параметров.
+
+```1C (BSL)
+Процедура ДокументыОбработкаПроведения(Источник, Отказ, РежимПроведения) Экспорт
+    // Опустить обработку, если есть отказ или идёт загрузка обмена данными
+    Если Отказ Или Источник.ОбменДанными.Загрузка Тогда
+        Возврат;
+    КонецЕсли;
+
+    // Получение имени метода для исполнения
+    ИмяМетода = юр_ОбщегоНазначенияПовтИсп.ДокументыОбработкаПроведения().Получить(ТипЗнч(Источник));
+    
+    // Выполнение метода, если он определён
+    Если ЗначениеЗаполнено(ИмяМетода) Тогда
+        // Попытка выполнения метода с необходимыми параметрами
+        Попытка
+            ПараметрыМетода = Новый Массив;
+            ПараметрыМетода.Добавить(Источник);
+            ПараметрыМетода.Добавить(Отказ);
+            ПараметрыМетода.Добавить(РежимПроведения);
+            ОбщегоНазначения.ВыполнитьМетодКонфигурации(ИмяМетода, ПараметрыМетода);
+        Исключение
+            // В случае ошибки вывод информации о ней
+            ВызватьИсключение СтрШаблон("%1%2Имя метода: %3", ОписаниеОшибки(), Символы.ПС, ИмяМетода);
+        КонецПопытки;
+    КонецЕсли;
+КонецПроцедуры
+```
+
+ - В общем модуле **__ОбщегоНазначенияПовтИсп** найти функцию с названием объекта и события и добавить в соответствие тип объекта и вызываемую процедуру. Если функции для данного набора нет, создать её.
+
+```1C (BSL)
+Функция ДокументыОбработкаПроведения() Экспорт
+    Соответствие = Новый Соответствие;
+    // Добавление соответствий между типами объектов и методами
+    Соответствие.Вставить(Тип("ДокументОбъект.СписаниеБезналичныхДенежныхСредств"),
+        "юр_ДокументыОбработкаПроведения.СписаниеБезналичныхДенежныхСредств");
+    Соответствие.Вставить(Тип("ДокументОбъект.ПоступлениеБезналичныхДенежныхСредств"),
+        "юр_ДокументыОбработкаПроведения.ПоступлениеБезналичныхДенежныхСредств");
+    
+    Возврат Соответствие;
+КонецФункции
+```
+
+- В модуле объекта и события добавить экспортную процедуру с такими же параметрами как у основной и добавить необходимую логику.
--- a/docs/ПользовательскиеФункции.md
+++ b/docs/ПользовательскиеФункции.md
@ -0,0 +1,67 @@
+# Подсистема "пользовательские функции"
+
+## Общие сведения
+
+Пользовательские функции в системе 1С предназначены для эффективного повторного использования кода. Они позволяют классифицировать и хранить часто используемые фрагменты кода, упрощая настройку шаблонов проводок и других операций.  
+Форма списка справочника содержит перечень пользовательских функций, описание выделенной функции, а также код функции с указанием типов входных параметров в виде комментария. 
+В случае если выделена группа функций в окне кода появляется список функций, которые эта группа содержит.
+
+## Создание функции
+
+Функции создаются в справочнике "Пользовательские функции". Они являются глобальными. Пользователь имеет возможность самостоятельно определить алгоритм, который сформирует возвращаемое значение.  
+Главным условием, является то, что сформированное значение должно быть помещено в переменную "Результат".
+
+## Параметры функции
+
+В пользовательских функциях значения параметров используются для проведения проверок.  
+При создании пользовательской функции пользователь имеет возможность указать перечень входных параметров, их количество может быть произвольным.  
+Параметры и их тип хранятся в разрезе элементов, значения хранятся в разрезе пользователей.  
+Тип параметров - в текущим релизе реализованы типы параметров: примитивные типы, ссылочные типы, коллекции(таблица значений, список значений, массив, структура).  
+Допускается не указывать тип параметра, в таком случае при выборе значения параметра ограничение типа не накладывается. Существует возможность создания необязательных параметров.  
+![Параметры функ](https://github.com/firstBitSportivnaya/PSSL/assets/59319861/30367563-ce96-46d9-9b25-07d1b714cc87)
+
+## Переменные функции
+
+Предназначены для внедрения ссылочных констант в код, обеспечивая удобное управление этими константами в рамках разработки кода.
+
+## Работа с функциями
+
+В коде пользовательской функции допускается использование запросов. Для вызова конструктора запросов можно воспользоваться кнопкой "Конструктор запроса" на панели инструментов редактора кода или сочетанием клавиш "Ctrl + D".
+  
+В процессе написания пользовательской функции может потребоваться проверка выполнения кода. Для запуска пользовательской функции на выполнение можно воспользоваться кнопкой "Выполнить" на панели инструментов редактора кода.
+  
+Произойдет попытка исполнения кода функции в контексте общего модуля. В случае ошибки при исполнении кода, пользователю будет сообщено об этом.
+
+Для вызова пользовательской функции из произвольного места существует функция - **__ОбщегоНазначенияСервер.ВыполнитьПользовательскуюФункциюСПараметрами(Ссылка, Параметры)**  
+Параметры:  
+Ссылка - СправочникСсылка.__ПользовательскиеФункции - ссылка на выполняемую функцию;  
+Параметры - Структура - где ключ - имя параметра, значение - значение передаваемого параметра.  
+В случае если не передан обязательный параметр в структуре параметров, будет вызвано исключение, можно не передавать необязательные параметры, в таком случае их значение будет по умолчанию "Неопределено"
+
+**Пример создания пользовательской функции:**
+
+```1C (BSL)
+Функция УдалитьНедопустимыеСимволы(ИсходнаяСтрока) // Формируется на основании наименования элемента справочника и параметров
+
+    НедопустимыеСимволы = """'`/\[]{}:;|-=?*<>,.()+#№@!%^&~«»";
+    Результат = СтрСоединить(СтрРазделить(ИсходнаяСтрока, НедопустимыеСимволы, Истина));
+
+    Возврат Результат; // Установлен автоматически, отдельно прописывать не нужно
+
+КонецФункции // Установлен автоматически, отдельно прописывать не нужно
+```
+
+**Пример вызова пользовательской функции:**
+
+```1C (BSL)
+Функция ПолучитьВалиднуюСтроку(СсылкаНаПользовательскуюФункцию, Имя)
+
+    ИмяБезПробелов = СтрЗаменить(Имя, " ", "");
+    ПараметрыФункции = Новый Структура;
+    ПараметрыФункции.Вставить("ИсходнаяСтрока", ИмяБезПробелов);
+    Результат = __ОбщегоНазначенияСервер.ВыполнитьПользовательскуюФункциюСПараметрами(СсылкаНаПользовательскуюФункцию, ПараметрыФункции);
+
+    Возврат Результат;
+
+КонецФункции
+```
--- a/docs/ПредопределенныеЗначения.md
+++ b/docs/ПредопределенныеЗначения.md
@ -1,6 +1,27 @@
-# Подсистема предопределенных значений
+# Подсистема "предопределенные значения"

-Пример добавления нового элемента в модуле __ПредопределенныеЗначенияПереопределяемый
+Для обращения к ссылкам из кода используем предопределенные значения, добавляем их в план видов характеристик (ПВХ) "__ПредопределенныеЗначения"
+
+Для удобной работы с ПВХ у нас есть следующие функции:
+ - **__ОбщегоНазначенияСервер.ПолучитьПредопределенноеЗначение(Имя, ИспользоватьКэш)** - если это единичное значение, возвращается сразу оно, если установлен флаг "Список значений" то возвращает массив значений. Для получения часто используемых предопределенных значений, установите ИспользоватьКэш = Истина.
+   - Параметры:
+     - Имя - Строка
+     - ИспользоватьКэш - Булево
+   - Возвращаемое значение:
+     - ПроизвольныйТип - Значение переменной ПВХ.
+     - Массив - Массив значений переменной ПВХ.
+ - **__ОбщегоНазначенияСервер.ПолучитьПредопределенныеЗначения(Имена, ВРазрезеКлючей, ИспользоватьКэш)** - если "ВРазрезеКлючей" то возвращает соответствие нескольких элементов ПВХ, если ВРазрезеКлючей = ложь, то возвращает массив значений. Для получения часто используемых предопределенных значений, установите ИспользоватьКэш = Истина.
+   - Параметры:
+     - Имена - Строка - Имена переменных ПВХ, перечисленные через запятую.
+     - ВРазрезеКлючей - Булево
+     - ИспользоватьКэш - Булево
+   - Возвращаемое значение:
+     - Соответствие - Соответствие имен и значений переменных ПВХ.
+       - Ключ - Строка - имя значения
+       - Значение - ПроизвольныйТип
+     - Массив - ПроизвольныйТип
+
+Пример добавления нового элемента в модуле __ПредопределенныеЗначенияПереопределяемый:

 ```1C (BSL)
 Функция ПредопределенныеЗначения() Экспорт
@ -21,7 +42,7 @@
 КонецФункции
 ```

-Пример получения множественного результата, второй параметр указывает если Истина, то результат оборачивается в соответствие, где Ключ - Имя предопределенного элемента, Значение - значение предопределенного элемента
+Пример получения множественного результата:

 ```1C (BSL)
 Функция ПолучитьДанныеАвторизации()
@ -40,12 +61,12 @@
 КонецФункции
 ```

-Пример получения единичного результата
+Пример получения единичного результата:

 ```1C (BSL)
 Функция ЗаписыватьДанныеСтандартнымСпособом(ПроверяемаяДата)

-    Результат = __ОбщегоНазначенияСервер.ПолучитьПредопределенныеЗначения("ДатаНачалаЗаписиВРегистры", Истина, Истина);
+    Результат = __ОбщегоНазначенияСервер.ПолучитьПредопределенноеЗначение("ДатаНачалаЗаписиВРегистры", Истина);

    Возврат ПроверяемаяДата = Результат;

--- a/docs/СоответствиеОбъектовИнформационнойБазы.md
+++ b/docs/СоответствиеОбъектовИнформационнойБазы.md
@ -1,22 +1,31 @@
-# Соответствие объектов информационной базы через регистр сведений
+# Подсистема "Соответствие объектов информационной базы"
+
+Для хранения соответствия 2-3х объектов в системе предназначен регистр сведений (РС) __СоответствияОбъектовИБ. В некоторых случаях можно создавать отдельные регистры (при использовании в высоконагруженных транзакциях или при наличии большого (более 100) количества соответствий или при более чем 3 соответствующих объектов).
+
+Порядок создания соответствия:
+ - Добавить новое значение в перечисление **"Тип соответствия объектов ИБ"**, если нужно, расширить типы измерений/ресурсов через определяемый тип __ТипыОбъектовСоответствийИБ.
+ - Создаем запись в регистре
+
+Варианты получения соответствия:
+ - **__ОбщегоНазначенияСервер.ПолучитьСоответствиеОбъектовИБ(ИдентификаторНастройки, Объект1, Объект2, Объект3, ИспользоватьКэш)** - (параметры: Объект1, Объект2, Объект3, ИспользоватьКэш - необязательные) - Возвращает массив структур соответствий по установленному отбору
+ - **__ОбщегоНазначенияСервер.ПолучитьЗначенияОбъектаСоответствияПоКлючу(ИдентификаторНастройки, ИмяКлюча, ЗначениеКлюча, ИмяОбъекта, ИспользоватьКэш)** - (параметры: ИспользоватьКэш - необязательные) - Возвращает массив значений произвольного типа, объекта соответствия.
+ - Делать соединение с регистром в запросах

 1. ПолучитьСоответствиеОбъектовИБ - Позволяет фильтровать результаты по трем объектам.

 ```1C (BSL)
 Процедура Тест()
    // Вызов метода с заданными параметрами
-    МассивСоответствий = __ОбщегоНазначенияСервер.ПолучитьСоответствиеОбъектовИБ(ТипСоответствия, Объект1, Объект2, , Истина);
-    
-    // Пример обработки полученного массива структур
-    Для Каждого Соответствие Из МассивСоответствий Цикл
-        Сообщить("Тип соответствия: " + Соответствие.ТипСоответствия);
-        Сообщить("Объект 1: " + Соответствие.Объект1);
-        Сообщить("Объект 2: " + Соответствие.Объект2);
-        Сообщить("Объект 3: " + Соответствие.Объект3);
-    КонецЦикла;
+    ИдентификаторНастройки = "Тест";
+    МассивСоответствий = __ОбщегоНазначенияСервер.ПолучитьСоответствиеОбъектовИБ(ИдентификаторНастройки, Тест1, Тест2, , Истина);
+
+    Если ЗначениеЗаполнено(МассивСоответствий) Тогда
+        РезультатТест = МассивСоответствий[0].Объект3;
+    КонецЕсли;
+
 КонецПроцедуры
 ```
-2. ПолучитьЗначенияОбъектаСоответствияПоКлючу
+2. ПолучитьЗначенияОбъектаСоответствияПоКлючу - Позволяет получить массив значений по ключу 

 ```1C (BSL)
 Процедура Тест()
@ -24,7 +33,8 @@
    ЗначениеКлюча = Склад;
    ИмяОбъекта = "Объект3";
    // Вызов метода с заданными параметрами
-    Значения = __ОбщегоНазначенияСервер.ПолучитьЗначенияОбъектаСоответствияПоКлючу(ТипСоответствия, ИмяКлюча, ЗначениеКлюча, ИмяОбъекта);
+    ИдентификаторНастройки = "Тест";
+    Значения = __ОбщегоНазначенияСервер.ПолучитьЗначенияОбъектаСоответствияПоКлючу(ИдентификаторНастройки, "Объект1", Тест, "Объект2");
    
    // Пример использования полученного массива значений
    Если ЗначениеЗаполнено(Значения) Тогда