Документация

Author: Segate-ekb

docs/.vitepress/config.ts

@@ -46,7 +46,9 @@ export default defineConfig({
           text: 'Практические руководства',
           items: [
             { text: 'Создание потока данных', link: '/guide/create-flow' },
-            { text: 'Настройка подписчиков', link: '/guide/configure-subscribers' }
+            { text: 'Настройка подписчиков', link: '/guide/configure-subscribers' },
+            { text: 'Настройка эндпоинтов', link: '/guide/configure-endpoints' },
+            { text: 'Обработка входящих HTTP', link: '/guide/incoming-http-processing' }
           ]
         }
       ],
@@ -57,10 +59,12 @@ export default defineConfig({
             { text: 'Обзор архитектуры', link: '/concepts/' },
             { text: 'Потоки данных', link: '/concepts/data-flows' },
             { text: 'Подписчики', link: '/concepts/subscribers' },
+            { text: 'Kafka-консьюмеры', link: '/concepts/kafka-consumers' },
             { text: 'Очереди сообщений', link: '/concepts/message-queues' },
             { text: 'Валидация', link: '/concepts/validation' },
             { text: 'Многопоточность', link: '/concepts/multithreading' },
-            { text: 'Мониторинг и метрики', link: '/concepts/monitoring' }
+            { text: 'Мониторинг и метрики', link: '/concepts/monitoring' },
+            { text: 'Управление эндпоинтами', link: '/concepts/endpoint-management' }
           ]
         }
       ],
@@ -105,7 +109,7 @@ export default defineConfig({
 
     // Social links
     socialLinks: [
-      { icon: 'github', link: 'https://github.com/your-org/integration_subsystem' }
+      { icon: 'github', link: 'https://github.com/Segate-ekb/integration_subsystem' }
     ],
 
     // Last updated text

docs/api/index.md

@@ -12,7 +12,6 @@ outline: deep
 Подсистема интеграции
 ├── Справочники (конфигурация)
 │   ├── инт_ПотокиДанных
-│   ├── инт_Подписчики
 │   ├── инт_ПодписчикиHTTP
 │   ├── инт_ПодписчикиRabbitMQ
 │   ├── инт_ПодписчикиKafka
@@ -33,6 +32,9 @@ outline: deep
 │   ├── инт_ИсторияСтатусовРассылкиСообщений
 │   ├── инт_МенеджерПотоковФормированияСообщений
 │   ├── инт_МенеджерПотоковОтправкиСообщений
+│   ├── инт_АктивныеКонсьюмеры
+│   ├── инт_СтатистикаОбработкиСообщений
+│   ├── инт_СообщенияКУдалению
 │   ├── инт_ХешиОбъектов
 │   ├── инт_ИдентификаторыВнешнихСистем
 │   └── инт_КэшированиеСхемOpenApi
@@ -41,27 +43,35 @@ outline: deep
 │   ├── инт_ФормированиеИсходящихСообщений
 │   ├── инт_ОтправкаИсходящихСообщений
 │   ├── инт_ОбработкаВходящихПотоков
+│   ├── инт_МенеджерВходящихПотоков
+│   ├── инт_КонсьюмерОчередей
 │   ├── инт_ВалидаторПакетов
 │   ├── инт_КоннекторHTTP
 │   ├── инт_ПодписчикиОбщий
-│   ├── инт_РаботаССообщениямиПроизвольныйHTTP
-│   ├── инт_РаботаССообщениямиRabbitMQ
-│   ├── инт_РаботаССообщениямиKafka
-│   └── инт_РаботаССообщениямиJRPC2
+│   ├── инт_РаботаСКафка
+│   ├── инт_РаботаСБезопаснымХранилищем
+│   ├── инт_ЭндпоинтыКлиент
+│   └── инт_ЭндпоинтыКлиентСервер
 │
 ├── Перечисления
 │   ├── инт_НаправлениеПотокаДанных
 │   ├── инт_СтатусыИсходящихСообщений
 │   ├── инт_СтатусыВходящихСообщений
 │   ├── инт_СтатусыРассылкиИсходящихСообщений
 │   ├── инт_ТипыПодписчиков
-│   └── инт_ТипыАвторизации
+│   ├── инт_ТипыАвторизации
+│   ├── инт_СпособыПередачиПараметровПоHTTP
+│   └── инт_ТипыСжатияKafka
 │
 ├── Регламентные задания
 │   ├── инт_МенеджерПотоковФормированияИсходящихСообщений
 │   ├── инт_МенеджерПотоковРассылкиСообщений
+│   ├── инт_МенеджерВходящихПотоков
 │   ├── инт_ОбработкаВходящейОчереди
-│   └── инт_ОчисткаУстаревшихСообщений
+│   ├── инт_ОчисткаУстаревшихСообщений
+│   ├── инт_ОчисткаСтатистикиОбработкиСообщений
+│   ├── пэмВыполнитьРасчетМетрик
+│   └── пэмРегламентныеОперации
 │
 └── HTTP-сервисы
     └── prometheus (экспорт метрик)
@@ -74,9 +84,13 @@ outline: deep
 | Объект | Описание |
 |--------|----------|
 | `инт_ПотокиДанных` | Потоки данных с обработчиками |
-| `инт_Подписчики` | Базовый справочник подписчиков |
+| `инт_ПодписчикиHTTP` | HTTP/HTTPS подписчики |
+| `инт_ПодписчикиKafka` | Подписчики Apache Kafka |
+| `инт_ПодписчикиJRPC` | Подписчики JSON-RPC 2.0 |
+| `инт_ПодписчикиПодсистемаИнтеграции` | Межбазовые подписчики |
+| `инт_ПодписчикиRabbitMQ` | Подписчики RabbitMQ |
 | `инт_Схемы` | OpenAPI-схемы для валидации |
-| `инт_Эндпоинты` | Настройки подключения |
+| `инт_Эндпоинты` | Настройки подключения (URL, авторизация) |
 
 ### Регистры сведений
 
@@ -146,18 +160,44 @@ outline: deep
 | `Отправлено` | Успешно отправлено |
 | `ОшибкаОтправки` | Ошибка отправки |
 
-### инт_ТипыПодписчиков
+### инт_ТипыАвторизации
 
 | Значение | Описание |
 |----------|----------|
-| `HTTP` | Произвольный HTTP |
-| `ПодсистемаИнтеграции` | Межбазовый обмен |
-| `RabbitMQ` | AMQP брокер |
-| `Kafka` | Apache Kafka |
-| `JRPC` | JSON-RPC 2.0 |
+| `Анонимный` | Без авторизации |
+| `Basic` | HTTP Basic Auth |
+| `Bearer` | Bearer Token |
+| `Digest` | HTTP Digest Auth |
+| `Tls` | Клиентский TLS-сертификат (mTLS) |
+| `ApiKey` | API Key в HTTP-заголовке |
+
+### инт_ТипыСжатияKafka
+
+| Значение | Описание |
+|----------|----------|
+| `БезСжатия` | Без сжатия (none) |
+| `Gzip` | Gzip |
+| `Snappy` | Google Snappy |
+| `Lz4` | LZ4 |
+| `Zstd` | Zstandard |
 
 ## Типы данных
 
+### ОпределяемыйТип.инт_Подписчик
+
+Полиморфный тип для ссылки на любой справочник подписчика. Используется в табличной части `ПодписчикиПотока` справочника `инт_ПотокиДанных`.
+
+```
+ОпределяемыйТип.инт_Подписчик
+  ├── СправочникСсылка.инт_ПодписчикиHTTP
+  ├── СправочникСсылка.инт_ПодписчикиJRPC
+  ├── СправочникСсылка.инт_ПодписчикиПодсистемаИнтеграции
+  ├── СправочникСсылка.инт_ПодписчикиKafka
+  └── СправочникСсылка.инт_ПодписчикиRabbitMQ
+```
+
+Диспетчеризация вызовов реализована в модуле `инт_ПодписчикиОбщий`.
+
 ### ОпределяемыйТип.инт_ИсходныеДанные
 
 Типы, которые могут быть исходными данными для сообщений:

docs/concepts/endpoint-management.md

@@ -0,0 +1,122 @@
+---
+outline: deep
+---
+
+# Управление эндпоинтами
+
+Справочник `инт_Эндпоинты` хранит настройки подключения ко внешним системам: URL, тип авторизации и учётные данные. Все подписчики ссылаются на эндпоинт — это позволяет переключать среды (dev/test/prod) одним изменением без правки каждого подписчика.
+
+## Структура эндпоинта
+
+| Реквизит | Тип | Описание |
+|----------|-----|----------|
+| `Наименование` | Строка(150) | Понятное имя (например, «WMS Production») |
+| `АдресРесурса` | Строка(500) | Базовый URL (`https://api.example.com`) |
+| `ТипАвторизации` | `инт_ТипыАвторизации` | Способ авторизации |
+| `ПроверятьSSL` | Булево | Проверять TLS-сертификат сервера (по умолчанию `Истина`) |
+| `ТаймаутСоединения` | Число | Таймаут подключения в секундах |
+
+Секретные данные (пароли, токены, ключи) **не хранятся в реквизитах справочника** — они записываются в `БезопасноеХранилище` при сохранении формы и читаются оттуда при отправке запросов.
+
+## Типы авторизации
+
+### Анонимный
+
+Без авторизации. Используется для публичных API или внутренних сервисов в доверенной сети.
+
+### Basic
+
+HTTP Basic Authentication — имя пользователя и пароль передаются в заголовке `Authorization: Basic <base64>`.
+
+| Параметр | Описание |
+|----------|----------|
+| Пользователь | Логин |
+| Пароль | Пароль (хранится в БезопасноеХранилище) |
+
+### Bearer
+
+Bearer Token — токен передаётся в заголовке `Authorization: Bearer <token>`.
+
+| Параметр | Описание |
+|----------|----------|
+| Токен | Access token или API key (хранится в БезопасноеХранилище) |
+
+### Digest
+
+HTTP Digest Authentication — более безопасный вариант Basic Auth с challenge-response механизмом.
+
+| Параметр | Описание |
+|----------|----------|
+| Пользователь | Логин |
+| Пароль | Пароль (хранится в БезопасноеХранилище) |
+
+### TLS (mTLS)
+
+Клиентский TLS-сертификат для двусторонней аутентификации (Mutual TLS).
+
+| Параметр | Описание |
+|----------|----------|
+| Источник сертификата | Файл `.pfx`/`.p12` или хранилище Windows |
+| Путь к файлу | Полный путь к файлу сертификата |
+| Пароль сертификата | Пароль защиты файла (хранится в БезопасноеХранилище) |
+| Отпечаток (хранилище) | Fingerprint сертификата в хранилище Windows |
+
+### ApiKey
+
+API Key в произвольном HTTP-заголовке.
+
+| Параметр | Описание |
+|----------|----------|
+| Имя заголовка | Например, `X-API-Key` или `X-Auth-Token` |
+| Значение ключа | Сам ключ (хранится в БезопасноеХранилище) |
+
+## Хранение секретных данных
+
+Все чувствительные данные хранятся в регистре `инт_БезопасноеХранилищеДанных` (обёртка над стандартным `БезопасноеХранилище`). Ключи хранения зависят от типа авторизации:
+
+| Ключ | Тип авторизации | Содержимое |
+|------|-----------------|------------|
+| `Basic_Пользователь` | Basic, Digest | Имя пользователя |
+| `Basic_Пароль` | Basic, Digest | Пароль |
+| `Bearer_Токен` | Bearer | Токен |
+| `Tls_СертификатПуть` | Tls | Путь к файлу сертификата |
+| `Tls_СертификатПароль` | Tls | Пароль сертификата |
+| `Tls_СертификатХранилище` | Tls | Отпечаток сертификата Windows |
+| `ApiKey_ИмяЗаголовка` | ApiKey | Имя заголовка |
+| `ApiKey_Значение` | ApiKey | Значение ключа |
+
+::: warning Права доступа
+Запись в безопасное хранилище требует права администратора или наличия роли `инт_АдминистраторПодсистемы`. Убедитесь, что регламентные задания также имеют право на чтение.
+:::
+
+## Проверка подключения
+
+Форма элемента эндпоинта содержит кнопку **«Проверить подключение»**, которая выполняет тестовый HTTP-запрос (для Kafka — проверку доступности брокера) и отображает результат. Это позволяет убедиться в корректности настроек до запуска потоков.
+
+```bsl
+// Программная проверка подключения
+Результат = инт_КоннекторHTTP.ПроверитьПодключение(Эндпоинт);
+Если Результат.Успех Тогда
+    Сообщить("Подключение успешно: " + Результат.КодСостояния);
+Иначе
+    Сообщить("Ошибка: " + Результат.ОписаниеОшибки);
+КонецЕсли;
+```
+
+## Несколько сред (dev/test/prod)
+
+Рекомендуемый подход: создайте три эндпоинта с одинаковыми именами с суффиксами, например:
+
+```
+WMS API (Dev)    → https://wms-dev.internal/api
+WMS API (Test)   → https://wms-test.internal/api
+WMS API (Prod)   → https://wms.example.com/api
+```
+
+Подписчик в потоке данных ссылается на один эндпоинт. При переключении среды достаточно поменять ссылку в подписчике — без изменения авторизационных данных. Все три эндпоинта хранят свои собственные учётные данные.
+
+## Следующие шаги
+
+- [Настройка подписчиков](/guide/configure-subscribers) — привязка эндпоинтов к типам подписчиков
+- [Настройка эндпоинтов (практика)](/guide/configure-endpoints) — пошаговое руководство
+- [Подписчики](/concepts/subscribers) — типы подписчиков и их параметры

docs/concepts/index.md

@@ -83,11 +83,11 @@ outline: deep
 | Объект | Назначение |
 |--------|------------|
 | `инт_ПотокиДанных` | Определение потоков: направление, обработчик, валидация |
-| `инт_Подписчики` | Базовый справочник подписчиков |
-| `инт_ПодписчикиHTTP` | HTTP-подписчики с настройками endpoint |
-| `инт_ПодписчикиRabbitMQ` | Подписчики RabbitMQ |
+| `инт_ПодписчикиHTTP` | HTTP/HTTPS подписчики |
 | `инт_ПодписчикиKafka` | Подписчики Apache Kafka |
 | `инт_ПодписчикиJRPC` | Подписчики JSON-RPC 2.0 |
+| `инт_ПодписчикиПодсистемаИнтеграции` | Межбазовая интеграция |
+| `инт_ПодписчикиRabbitMQ` | Подписчики RabbitMQ |
 | `инт_Схемы` | Схемы валидации (OpenAPI 3.0) |
 | `инт_Эндпоинты` | Настройки подключения к внешним системам |
 
@@ -102,15 +102,22 @@ outline: deep
 | `инт_ОчередьОтправкиИсходящихСообщений` | Связь сообщение ↔ подписчик |
 | `инт_МенеджерПотоковФормированияСообщений` | Контроль фоновых заданий формирования |
 | `инт_МенеджерПотоковОтправкиСообщений` | Контроль фоновых заданий отправки |
+| `инт_АктивныеКонсьюмеры` | Активные фоновые задания Kafka-консьюмеров |
+| `инт_СтатистикаОбработкиСообщений` | Статистика обработки (производительность) |
 
 ### Общие модули (логика)
 
 | Модуль | Назначение |
 |--------|------------|
 | `инт_ФормированиеИсходящихСообщений` | Запуск потоков формирования |
 | `инт_ОтправкаИсходящихСообщений` | Запуск потоков отправки |
+| `инт_МенеджерВходящихПотоков` | Управление Kafka-консьюмерами |
+| `инт_КонсьюмерОчередей` | Чтение сообщений из Kafka |
+| `инт_ПодписчикиОбщий` | Диспетчер вызовов типизированных подписчиков |
 | `инт_ВалидаторПакетов` | Валидация по OpenAPI-схемам |
 | `инт_КоннекторHTTP` | HTTP-клиент для отправки |
+| `инт_РаботаСКафка` | Работа с Apache Kafka (отправка, чтение, топики) |
+| `инт_РаботаСБезопаснымХранилищем` | Управление секретами в безопасном хранилище |
 
 ## Жизненный цикл сообщения
 
@@ -139,6 +146,7 @@ outline: deep
 - [Потоки данных](/concepts/data-flows) — подробнее о конфигурации потоков
 - [Подписчики](/concepts/subscribers) — типы и настройка подписчиков
 - [Kafka-консьюмеры](/concepts/kafka-consumers) — входящие потоки из Kafka
+- [Управление эндпоинтами](/concepts/endpoint-management) — авторизация и безопасное хранение
 - [Валидация](/concepts/validation) — работа с OpenAPI-схемами
 - [Многопоточность](/concepts/multithreading) — параллельная обработка
 - [Мониторинг и метрики](/concepts/monitoring) — Prometheus-метрики и алерты