Main build (Jenkins)

2026-06-20 09:19:27 +02:00 · 2025-06-01 16:47:58 +03:00
parent 6f7db78e78
commit b542a19a47
8 changed files with 8119 additions and 8114 deletions
@@ -8,7 +8,7 @@ keywords: [1C, 1С, 1С:Предприятие, 1С:Предприятие 8.3,

 ![Melezh](../../../static/img/melezh_long.png)

-**Melezh** - это Серверная версия Открытого пакета интеграций, предоставляющая единый настраиваемый HTTP API для доступа к его библиотекам и произвольным `.os` скриптам (расширениям), с возможностью установки значений по умолчанию, веб-консолью и встроенным логированием входящих запросов
+**Melezh** - это серверная версия Открытого пакета интеграций, предоставляющая единый настраиваемый HTTP API для доступа к его библиотекам и произвольным `.os` скриптам (расширениям), с возможностью установки значений по умолчанию, веб-консолью и встроенным логированием входящих запросов

 ## Принцип работы

@@ -40,7 +40,7 @@ http://localhost:7788/42281f11b?chat=123123123&text="Hello world!"

 Как вы могли заметить, мы не передаем токен, так как он установлен по умолчанию

-## Web UI
+## Веб-интерфейс

 Кроме CLI интерфейса, для более простой интерактивной настройки и управления, можно использовать встроенную в Melezh веб-консоль:

@@ -9,7 +9,7 @@ sidebar_position: 2

 ## Запуск

-Вне зависимости от операционной системы и способа установки, после ее завршения, Melezh должен быть доступен в терминале (командной строке) по команде `melezh`. 
+Вне зависимости от операционной системы и способа установки, после ее завершения, Melezh должен быть доступен в терминале (командной строке) по команде `melezh`. 


 >На Windows может потребоваться перезагрузка, но также там присутствует возможность прямого запуска по ярлыку в меню "Пуск"
@@ -25,7 +25,7 @@ sidebar_position: 2

 ## Создание проекта

-Для полноценного начала работы с Melezh необходимо создать **проект** - файл, в котором будут хранится основные настройки и данные об обработчиках. Для этого необходимо вызывать команду `СоздатьПроект` и указать путь для сохранения нового файла в аргументе `--path`
+Для полноценного начала работы с Melezh необходимо создать **проект** - файл, в котором будут храниться основные настройки и данные об обработчиках. Для этого необходимо вызывать команду `СоздатьПроект` и указать путь для сохранения нового файла в аргументе `--path`

 ![Запуск Melezh](../../../../static/img/Docs/Melezh/4.gif)

@@ -33,12 +33,12 @@ sidebar_position: 2

 ## Настройка проекта

-Дальнейшая настройка проекта после создания может осуществляться двумя способами:
+Дальнейшая настройка проекта может осуществляться двумя способами:

 + **С использованием консольного интерфейса** <br/>
 Настройка проекта может осуществляться дальнейшим вызовом команд `melezh` в терминале (командной строке). Список доступных команд и их аргументы перечислены в разделе *Консольный интерфейс* и встроенной справке приложения

-+ **В веб-панели управления** <br/>
-Кроме консольного интерфейса, Melezh имеет встроенный Web UI, позволяющий упралвять проектом в интерактивном режиме. Подробнее о работе через веб-интерфейс можно узнать в разделе *Web-интерфейс*
+ **С использованием веб-интерфейса** <br/>
+Кроме консольного интерфейса, Melezh имеет встроенный Web UI, позволяющий управлять проектом в интерактивном режиме. Подробнее о работе через веб-интерфейс можно узнать в разделе *Web-интерфейс*


@@ -5,20 +5,20 @@ title: Основные положения
 sidebar_position: 3
 ---

-В этом разделе содержится глоссарий основных терминов и положений, связанных с настройкой и администрированием Melezh
+В этом разделе содержится глоссарий основных терминов и положений, связанных с настройкой и администрированием решения на базе Melezh

 ### Проект

-Основным объектом при работе с Melezh является **Проект** - файл с произвольным расширением, представляющий из себя SQLite базу с определенным набором таблиц, в которых хранится информация об общих настройках и параметрах обработчиков конкретного решения на базе Melezh
+Основным объектом при работе с Melezh является **Проект** - файл с произвольным расширением, представляющий собой SQLite базу с определенным набором таблиц, в которых хранится информация об общих настройках и параметрах обработчиков конкретного решения на базе Melezh

 Создать проект можно только из консоли (командной строки) при помощи команды `СоздатьПроект` с указанием пути сохранения файла проекта (см. *Консольный интерфейс*). После создания файла проекта, он будет иметь стандартную конфигурацию, которую можно изменять в дальнейшем при помощи консольных командам или Web-консоли (требуется запуск проекта, см. Web-интерфейс)

 ### Обработчик

-**Обработчик** - часть проекта, отвечающая за обработку запросов на одном конкретном пути URL. Характеризуется обработчик уникальным ключом, методом HTTP, библиотекой и функцией обработк из набора ОПИ или стороннего расширения:
+**Обработчик** - часть проекта, отвечающая за обработку запросов на одном конкретном пути URL. Характеризуется обработчик уникальным ключом, методом HTTP, библиотекой и функцией обработки из набора ОПИ или стороннего расширения:

-+ **Ключ** обработчика служит для его идентификации при настройке, удалении или получении логов. Также ключ равен пути, по которому обработчик принимает запросы. Т.е. обработчик с ключом `0d17ad53c` бедут принимать запросы на `localhost:<port>/0d17ad53c`
-+ **Метод HTTP** определяет, какие запросы может принимать обработчик. Всего их три на выбор: Get, Post c JSON телом (`JSON`), Post с form-data телом (`FORM`). Запросы, отправляемые на обработчик с form-data телом, могут иметь как тело в формате `application/x-www-form-urlencoded`, так и в формате `multipart/form-data`. Запросы, приходящие в формает, отличном от установленного, будут отклонены
+ **Ключ** обработчика служит для его идентификации при настройке, удалении или получении логов. Также ключ равен пути, по которому обработчик принимает запросы. Т.е. обработчик с ключом `0d17ad53c` будет принимать запросы на `localhost:<port>/0d17ad53c`
+ **Метод HTTP** определяет, какие запросы может принимать обработчик. Всего их три на выбор: Get, Post c JSON телом (`JSON`), Post с form-data телом (`FORM`). Запросы, отправляемые на обработчик с form-data телом, могут иметь как тело в формате `application/x-www-form-urlencoded`, так и в формате `multipart/form-data`. Запросы, приходящие в формате, отличном от установленного, будут отклонены
 + **Библиотека** или **Команда** является идентификатором набора функций из Открытого пакета интеграций или подключаемого расширения. Она определяет, в каком модуле находится функция, отвечающая за основную обработку запроса
 + **Функция** обработчика - это имя метода, отвечающего за основную обработку приходящих по пути обработчика запросов. Как уже было сказано, это может быть функция одной из библиотек ОПИ или метод из подключаемого расширения. Функция не отвечает за принятие, разбор или логирование запроса, но только за формирование ответа из уже обработанных данных на основе собственной логики

@@ -26,3 +26,10 @@ sidebar_position: 3

 **Аргументы** - уникальный набор ожидаемых в запросе полей, передаваемый при приеме в функцию обработчика. Аргументы могут быть как просто получены из запроса в полном объеме, так и иметь значения по умолчанию, установленные при настройке. Это позволяет не указывать отдельные (или все) параметры функции при формировании запроса на стороне клиента. Помимо этого, каждый аргумент может быть установлен как *строгий*, что запрещает его перезапись данными из запроса (без установки этого флага, данные, переданные в запросе, замещают значения по умолчанию)

+Не смотря на то, что все аргументы заполняются и хранятся в текстовом виде, в Melezh работает та же система приведения типов во время вызова функций, что и в других поставках Открытого пакета интеграций:
+
+ Коллекции могут быть указаны в виде JSON-строки, URL или путей к JSON-файлам на сервере 
+ Двоичные данные могут быть указаны как пути к файлам на сервере или URL
+ Даты могут быть указаны в формате ISO 8601
+ Значения типа Булево могут быть указаны как строки `true` или `false`
+
@@ -5,11 +5,11 @@ title: Логирование
 sidebar_position: 5
 ---

-В этом разделе описаны возможожности для настройки и использования встроенной системы сбора логов Melezh
+В этом разделе описаны возможности для настройки и использования встроенной системы сбора логов Melezh

 ## Сбор информации о входящих запросах

-При создании нового проекта Melezh, в нем по умолчанию включено **логирование** - сбор и запись информации о входящих запросах и ответах на них. Логи хранятся в виде отдельных файлов в опеределенной структуре каталогов
+При создании нового проекта Melezh, в нем по умолчанию включено **логирование** - сбор и запись информации о входящих запросах и ответах на них. Логи хранятся в виде отдельных файлов в определенной структуре каталогов

 По умолчанию основной каталог логов находится в директории `temp/Melezh/<Случайный UUID проекта>`. Найти полный путь к этом каталогу, а также изменить его, можно в панели настроек веб-интерфейса или при помощи соответствующих консольных команд

@@ -19,14 +19,14 @@ sidebar_position: 5
    + Каталог на дату (хранит логи за определенный день)
        + Каталог конкретного запроса

-Файлы с полезной информацией хранятся только в каталогах для информации о конкретных запросах, в то время как остальные уровни хранят лишь вложенные подкаталоги
+Файлы с информацией хранятся только в каталогах конкретных запросов, в то время как остальные уровни структуры каталогов хранят лишь вложенные подкаталоги

 ## Формат записи

 Каталог с информацией о конкретном обработанном запросе может содержать файлы одного из следующих видов:

-+ `req.info` - JSON файл с основной информацией о событии, вроде даты, HTTP-методе, URL параметрах и пр.
-+ `req.body` - JSON файл с информацией о теле запроса. Содержит оригинальный JSON тела для соответствующих запросов или преобразованный в JSON `form-data`
+ `req.info` - JSON файл с основной информацией о событии, вроде даты, HTTP-метода, URL параметрах и пр.
+ `req.body` - JSON файл с информацией о теле запроса. Содержит оригинальный JSON тела для `application/json` запросов или преобразованный в JSON `form-data`
 + `req.header` - JSON файл со списком заголовков запроса
 + `res.body` - файл, хранящий тело ответа, возвращаемого Melezh
 + Произвольное количество дополнительных файлов, приходящих в `multipart/form-data` запросах
@@ -42,8 +42,8 @@ sidebar_position: 5
 + **logs_req_body** - логирование тела входящих запросов
 + **logs_req_max_size** - отключение логирования logs_req_body для запросов, свыше этого размер (в байтах). 0 - без ограничений
 + **logs_res_body** - логирование тела исходящих ответов
-+ **logs_res_max_size** - Ооключение логирования logs_res_body для запросов, свыше этого размер (в байтах). 0 - без ограничений
+ **logs_res_max_size** - отключение логирования logs_res_body для запросов, свыше этого размер (в байтах). 0 - без ограничений

 :::tip 
-Работа с файлами логов напрямую может быть не совсем удобной. Для просмотра событий и посика информации о конкретных запросах рекомендуется использовать средста просмотра логов встроенного веб-интерфейса (см. раздел *Веб-интерфейс*)
+Работа с файлами логов напрямую может быть не совсем удобной. Для просмотра событий и поиска информации о конкретных запросах рекомендуется использовать средства просмотра логов встроенного веб-интерфейса (см. раздел *Веб-интерфейс*)
 :::
@@ -9,19 +9,19 @@ sidebar_position: 4

 ## Методы ОПИ (стандартный набор)

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

-При настройке обработчиков в консольном режиме, для получения правильных имен библиотек (команд), функций и их аргументов можно воспользоваться документацией самого Открытого пакета интеграций. Также там приведены примервы возвращаемых значений, которые будут помещены в тела ответов на запросы
+При настройке обработчиков в консольном режиме, для получения правильных имен библиотек (команд), функций и их аргументов можно воспользоваться документацией самого Открытого пакета интеграций. Также там приведены примеры возвращаемых значений, которые будут помещены в тела ответов на запросы

 ![Документация ОПИ](../../../../static/img/Docs/Melezh/3.png)

 :::warning
-Имена библиотек указываются в формет CLI приложения. Например, `telegram` или `gdrive` (Google Drive)
+Имена библиотек указываются в форме CLI приложения. Например, `telegram` или `gdrive` (Google Drive)
 :::

 <br/>

-При работе в Web-консоли нужную библиотеку и функцию можно выбрать в выпадающем спике при настройке обработчика
+При работе в Web-консоли нужную библиотеку и функцию можно выбрать в выпадающем списке при настройке обработчика

 ![Web консоль](../../../../static/img/Docs/Melezh/4.png)

@@ -29,50 +29,50 @@ sidebar_position: 4

 ## Расширения

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

 + Метод должен быть функцией, возвращающей двоичные данные, строку или сериализуемую в JSON коллекцию (массив, структуру или соответствие без несериализуемых полей)
-+ Файл скрипта должен быть помещен в подкаталог `extensions/Modules` основного каталога Melezh:
+ Файл скрипта должен иметь корректное имя (без пробелов, желательно латинскими буквами), расширение `.os` и быть помещен в подкаталог `extensions/Modules` основного каталога Melezh:

-Windows (стандартная установка из exe установщика):
-```
-C:\Program Files (x86)\OInt\share\oint\lib\melezh\extensions\Modules
-```
+	Windows (стандартная установка из exe установщика):
+	```
+	C:\Program Files (x86)\OInt\share\oint\lib\melezh\extensions\Modules
+	```

-Linux:
-```
-share/oint/lib/melezh/extensions/Modules
-```
+	Linux:
+	```
+	share/oint/lib/melezh/extensions/Modules
+	```

-OneScript, в качестве OPM пакета:
-```
-<каталог OneScript>/lib/melezh/extensions/Modules
-```
+	OneScript, в качестве OPM пакета:
+	```
+	<каталог OneScript>/lib/melezh/extensions/Modules
+	```

-+ Метод должны иметь документриующий комментарий следующего вида:
+ Метод должны иметь документирующий комментарий следующего вида:

-```bsl
-// Отображаемое имя метода
-// Описание метода
-//
-// Параметры:
-//  Поле1 - Строка  - Значение поля 1 - field1
-//  Поле2 - Строка  - Значение поля 2 - field2
-//  Поле3 - Строка  - Значение поля 3 - field3
-//
-// Возвращаемое значение:
-//  Структура Из КлючИЗначение - возвращаемое значение
-```
+	```bsl
+	// Отображаемое имя метода
+	// Описание метода
+	//
+	// Параметры:
+	//  Поле1 - Строка  - Значение поля 1 - field1
+	//  Поле2 - Строка  - Значение поля 2 - field2
+	//  Поле3 - Строка  - Значение поля 3 - field3
+	//
+	// Возвращаемое значение:
+	//  Структура Из КлючИЗначение - возвращаемое значение
+	```

-Это - стандартный формат комментария EDT, но с тремя отличительными особенностями: второй строкой является краткое описание функции, у параметров есть четверый блок описания - имя аргумента в CLI стиле, в описании параметра нельзя использовать знак `-` кроме как для разделения частей описания
+	Это - стандартный формат комментария EDT, но с тремя отличительными особенностями: второй строкой является краткое описание функции (не обязательно), у параметров есть четвертый блок описания - имя аргумента в CLI стиле, в описании параметра нельзя использовать знак `-` кроме как для разделения его блоков

-:::warning
-Использование `-` в тексте описания параметра приведет к ошибке 
-:::
+	:::warning
+	Использование `-` в тексте описания параметра приведет к ошибке 
+	:::

 <br/>

-В стандартной поставке, в каталоге `extensions/Modules` есть модуль `RequestsEcho.os`, который может быть использован в качестве шаблона для нового расширения:
+В стандартной поставке, в каталоге `extensions/Modules` есть модуль `RequestsEcho.os`, который может быть использован в качестве примера для создания нового расширения:

 ```bsl title="RequestsEcho.os"

@@ -13,13 +13,13 @@ sidebar_position: 1

 ![Страница входа](../../../../static/img/Docs/Melezh/6.png)

-Пароль по умолчанию - `admin`. Сменить его можно только в консольном режиме, о чем также будет сказано в подсказке на самой странице входа. После ввода пароля, будет отображена **основная панель**:
+Пароль по умолчанию - `admin`. Сменить его можно только в консольном режиме, о чем также будет сказано в подсказке на самой странице входа. После ввода пароля, будет отображена **главная панель**:

 ![Основная панель](../../../../static/img/Docs/Melezh/7.png)

-На главной панели отображается краткая сводка о сервере и его последних событиях: время старта сервера и число обработанных запросов, краткая информация о последних 30 из них с возможностью перейти к более подробному описанию (кнопка в колонке *Действия* в конце каждой строки события) 
+На главной панели отображается краткая сводка о сервере и его последних событиях: время старта и число обработанных запросов, краткая информация о последних 30 из них с возможностью перейти к более подробному описанию (кнопка в колонке *Действия* в конце каждой строки события) 

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

 ![Верхняя часть сайдбара](../../../../static/img/Docs/Melezh/8.png)

@@ -5,19 +5,17 @@ title: Панель обработчиков
 sidebar_position: 2
 ---

-Следющией, после главной панели, идет **панель обработчиков**. Она отвечает за показ и средства управления всеми обработчиками текущего проекта Melezh
+Следующией, после главной панели, идет **панель обработчиков**. Она отвечает за показ и средства управления всеми обработчиками текущего проекта Melezh

 ## Общий вид

 ![Панель обработчиков](../../../../static/img/Docs/Melezh/10.png)

-В основной части панели находится таблица, отображающая информацию о существующих обработчиках. В первых четрыех колонках расположена информация о ключе (пути) обработчика, HTTP-методе, библиотеке и функции обработки. После них расположен тумблер активности, позволяющий включать и отключать определенные обработчики без их полного удаления
-
-В крайней правой колонке находятся кнопки управления обработчиком: изменение, просмотр логов и удаление. Их назначение также отображается текстом при наведении:
+В основной части панели находится таблица, отображающая информацию о существующих обработчиках. В первых четырех колонках расположена информация о ключе (пути) обработчика, HTTP-методе, библиотеке и функции обработки. После них расположен тумблер активности, позволяющий включать и отключать определенные обработчики без их полного удаления, а в крайней правой колонке - кнопки управления обработчиком: изменение, просмотр логов и удаление. Их назначение также отображается текстом при наведении:

 ![Действия обработчиков](../../../../static/img/Docs/Melezh/11.png)

-В верхней части панели, справа от заголовка "Панель обработчиков", находятся кнопки добавления нового обработчика и обновления списка:
+В верхней части панели, справа от заголовка "Панель обработчиков", находятся кнопки добавления нового обработчика и обновления данных в основном списке:

 ![Общие действия](../../../../static/img/Docs/Melezh/12.png)

@@ -27,11 +25,11 @@ sidebar_position: 2

 ![Редактор](../../../../static/img/Docs/Melezh/13.png)

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

 ![Списки](../../../../static/img/Docs/Melezh/14.png)

-После выбора функции становится доступен список ее аргументов. В нем можно указать стандартные значения параметров функции, которые будут использоваться в случае отсутствия таковых в запросе от клиента (нестрогие) или безусловно замещать их, вне зависимости от того, были переданы указанные поля внутри запроса или нет (строгие). Принцип заполнения и интерпретации этих полей совпадает с таковым у других поставок Открытого пакета интеграций: переданные значения по возможности будут приведены к необходимым типам, коллекции передаются в формате JSON-строки, двоичные данные могут быть также переданы как пути к файлам на сервере или URL
+После выбора функции становится доступен список ее аргументов. В нем можно указать стандартные значения параметров функции, которые будут использоваться в случае отсутствия таковых в запросе от клиента (нестрогие) или безусловно замещать их, вне зависимости от того, были переданы указанные поля внутри запроса или нет (строгие). Принцип заполнения и интерпретации этих полей совпадает с таковым у других поставок Открытого пакета интеграций: переданные значения по возможности будут приведены к необходимым типам, коллекции передаются в формате JSON-строки, двоичные данные могут быть также переданы как пути к файлам на сервере или URL и т.д. (см Основные положения)

 ![Списки](../../../../static/img/Docs/Melezh/15.png)