Раздел 3. Функции частей программного обеспечения¶

3.1. Реестр интерфейсов¶

Реестр фиксирует основные интерфейсы между частями программного обеспечения BOX5-DIT-MGSN, инфраструктурными компонентами и внешними системами. Перечень согласован со структурой ПО из раздела 2, реестром сервисов ПД и OpenAPI-приложением. На этом уровне endpoint-ы не дублируются поштучно: детальный состав REST API приведён в приложении OpenAPI, а в таблице ниже показаны границы обмена и применяемые протоколы.

Код	Источник	Получатель	Назначение обмена	Тип обмена	Протокол	Формат данных	Направление
`PA-IF-01`	Пользователь / внешний API-клиент	`ui-nginx`	Доступ к web-интерфейсу, REST API, GraphQL, WebSocket, файлам и медиа через единую опубликованную точку входа.	Синхронный, потоковый	HTTP/HTTPS, WebSocket	HTML, CSS, JavaScript, JSON, multipart, бинарные файлы, HLS/WebRTC media	Входящий внешний
`PA-IF-02`	`ui-nginx`	`ui-react`	Выдача SPA, статических ресурсов, конфигурации UI, логотипов и статического раздела документации.	Синхронный	HTTP	HTML, JavaScript, CSS, JSON, изображения	Внутренний
`PA-IF-03`	`ui-nginx`	`ui-rest-to-gprc`	Проксирование browser-facing API: `/api/`, `/api/graphql`, `/api/ws/`, `/api/base/`, `/api/config/`, `/api/consul/`.	Синхронный, потоковый	HTTP/REST, GraphQL, WebSocket	JSON, multipart, бинарные ответы, WebSocket-сообщения	Внутренний
`PA-IF-04`	`ui-rest-to-gprc`	Сервисы `statistics`	Авторизация, права доступа, камеры, события, отчёты, аудит, комментарии, статистика событий и виртуальные камеры.	Синхронный	HTTP/gRPC, REST	JSON, protobuf/gRPC, файловые и отчётные бинарные ответы	Внутренний
`PA-IF-05`	`ui-rest-to-gprc`	Сервисы `inference` и `extended-inference`	Получение изображений, сведений о моделях, состояния inference, HLS/WebRTC и данных балансировщика.	Синхронный, потоковый	HTTP/gRPC, REST, HLS/WebRTC	JSON, protobuf/gRPC, изображения, HLS-фрагменты, SDP/WebRTC payload	Внутренний
`PA-IF-06`	`ui-rest-to-gprc`	Сервисы `severstal`	Customer-domain API: сценарии, ассеты, запуски, реестр моделей, переводы и интеграционные операции заказчика.	Синхронный	HTTP/gRPC, REST	JSON, protobuf/gRPC, файловые метаданные	Внутренний
`PA-IF-07`	`ui-rest-to-gprc`, `ui-nginx`, доменные сервисы	`data-storage`, `ds-minio`, `ds-data-temporary-storage`, `st-domain-gateway`	Загрузка, временное хранение и выдача изображений, видеофрагментов, отчётов и объектных ссылок `/api/s3/`, `/api/data-storage/`.	Синхронный, файловый	HTTP, S3-compatible API	Бинарные объекты, JSON-метаданные, UUID временных объектов	Внутренний / опубликованный через gateway
`PA-IF-08`	`ui-rest-to-gprc`	Consul KV / локальная конфигурация gateway	Чтение и изменение клиентской конфигурации и служебных параметров UI/API gateway.	Синхронный	HTTP/REST, Consul HTTP API, файловое чтение	JSON, key-value	Внутренний
`PA-IF-09`	`statistics`, `inference`, `severstal`, `ui-rest-to-gprc`	`inf-kafka`	Асинхронная доставка событий инференса, команд, heartbeats, audit-сообщений, статусов, синхронизации справочников и WebSocket-уведомлений.	Асинхронный	Kafka	Protobuf, JSON, служебные ключи сообщений	Внутренний двунаправленный
`PA-IF-10`	Сервисы `statistics`, `inference`, `severstal`, `node-red-sandbox`	Доменные PostgreSQL sidecar	Хранение пользователей, прав, камер, событий, отчётов, сценариев, моделей, ассетов, запусков и служебных таблиц.	Синхронный	PostgreSQL wire protocol	Реляционные таблицы, SQL-запросы, транзакции	Внутренний
`PA-IF-11`	Сервисы `statistics`, `inference`, `data-storage`, `node-red-sandbox`	Доменные Redis sidecar	Кэш, блокировки, очереди задач, временное состояние и координация фоновых процессов.	Синхронный	Redis RESP/TCP	Key-value, TTL-записи, очереди/служебные структуры	Внутренний
`PA-IF-12`	Сервисы `statistics`, `inference`, `ui-rest-to-gprc`	ClickHouse sidecar	Аналитические витрины событий, ускорение выборок, зеркала событий и lookup-таблицы.	Синхронный	ClickHouse native TCP, ClickHouse HTTP	Табличные данные, SQL-запросы, агрегаты	Внутренний / технический
`PA-IF-13`	Сервисы BOX5-DIT-MGSN, Docker log driver	`log-prometheus`, `log-loki`	Передача метрик и журналов для эксплуатационного мониторинга и диагностики.	Периодический сбор, поток логов	HTTP `/metrics`, Docker Loki driver	Prometheus text exposition, строки журналов, labels	Внутренний эксплуатационный
`PA-IF-14`	IP-камеры и виртуальные источники видео	`inf-mediaserver`, `inf-load-balancer`, `inf-nri-inference`	Получение live-видеопотоков и файловых/HTTP-источников для online-инференса и формирования событий.	Потоковый	RTSP, HTTP/MP4, внутренние media URI	Видео/аудиопоток, MP4/фрагменты media	Входящий внешний
`PA-IF-15`	CSVN/VMS Cisco, Milestone, Macroscop	`svr-severstal-integration`, `svr-severstal-org-sync`, `st-camera-storage`, `st-virt-cam-video-upload`	Синхронизация топологии камер, обязательных камер, архивной информации и архивных видеозаписей.	Синхронный, файловый	SOAP/WSDL, HTTP VMS API, локальный connector `VIRTUAL`	XML/SOAP, JSON/HTTP, бинарные видеофрагменты	Входящий внешний
`PA-IF-16`	ПК-КОТ	`svr-postgres-pk-kot`, `svr-severstal-integration`, `svr-severstal-org-sync`	Чтение справочников нарушений, опасностей, зон и камер; передача статусов и подтверждённых событий во внешнюю систему.	Синхронный	PostgreSQL read-only, HTTP/REST push	SQL-строки, JSON payload, статусы обработки	Внешний двунаправленный
`PA-IF-17`	АСУ ТП	`svr-asutp-kafka`, `svr-asutp`, `svr-asutp-schema-registry`	Приём `_meta` и `_data` сигналов, проверка схем, расчёт состояний ASUTP-юнитов и публикация результата в основной контур.	Асинхронный	Kafka, Avro, Schema Registry HTTP API	Avro-сообщения, схемы, JSON/служебные метаданные	Входящий внешний
`PA-IF-18`	Браузер пользователя, `st-auth`, `ui-rest-to-gprc`	Keycloak / OpenID Connect	SSO-авторизация пользователя, обмен authorization code на локальные токены BOX5-DIT-MGSN и получение параметров внешнего провайдера.	Синхронный	OIDC/OAuth2 authorization code, HTTP/gRPC	Redirect parameters, JSON, JWT, локальные access/refresh tokens	Внешний двунаправленный
`PA-IF-19`	`st-auth`, `st-report-email`, отчётные сервисы	SMTP / Email	Отправка служебных писем, сброса пароля, email-уведомлений и отчётов.	Синхронный / регламентный	SMTP	MIME-сообщения, вложения PDF/XLSX/CSV	Исходящий внешний
`PA-IF-20`	`svr-severstal-integration`, сервисы событий и отчётов	Внешние системы-получатели данных заказчика	Передача событий, статусов, отчётов, ссылок на медиа и выгрузок данных по согласованным интеграционным сценариям.	Синхронный, файловый	HTTP/REST, S3/HTTP-ссылки	JSON, файлы отчётов, ссылки на объекты, статусы	Исходящий внешний
`PA-IF-21`	`ui-nginx`	`node-red-sandbox`	Доступ к песочнице подготовки NRI-сценариев через `/sandbox/`, включая UI sandbox и backend-интерфейсы.	Синхронный, потоковый	HTTP, WebSocket	HTML/JS/CSS, JSON, flow JSON, служебные сообщения	Внутренний / технический
`PA-IF-22`	`node-red-sandbox`	Основной API BOX5-DIT-MGSN, MinIO, sandbox Kafka/Redis	Публикация подготовленных flows и сценарных артефактов, работа с временными файлами и проверочными запусками.	Синхронный, асинхронный, файловый	HTTP/REST, S3 API, Kafka, Redis	JSON flow, файлы, модели, служебные сообщения	Внутренний технический

Низкоуровневый реестр интерфейсов ведётся по типам контрактов:

Тип контракта	Где описан полный перечень	Обязательные поля реестра	Применение для контуров
REST/OpenAPI endpoint-ы	Приложение OpenAPI, разделы 2-3: 23 подсистемы и 206 операций.	Подсистема, метод, путь, назначение, авторизация, параметры, тело запроса, успешный ответ, типовые ошибки.	Единый REST-контракт версии поставки для DEV, TEST и PROD; отличаются base URL и эксплуатационные настройки.
GraphQL и WebSocket gateway	`PA-IF-01`, `PA-IF-03`, реестр сервисов ПД и gateway-конфигурация.	Канал, endpoint, инициатор, формат сообщений, авторизация, reconnect/error handling.	Используются через опубликованный gateway; внутренние upstream-адреса не являются публичным контрактом.
Kafka topic / Redis queue / Celery task	Подраздел 3.4 и реестр сервисов ПД.	Topic/queue, producer, consumer, назначение, формат, retention, retry, DLQ/обработка ошибок.	Имена и retention берутся из конфигурации версии поставки; топология брокеров может отличаться по контуру.
Файловый и S3-обмен	`PA-IF-07`, `PA-IF-20`, приложение OpenAPI для `/api/s3/` и `/api/data-storage/`, В7.	Владелец, путь/URL, формат, срок хранения, связь с БД, правила удаления и восстановления.	Bucket/prefix и физические каталоги задаются эксплуатационной конфигурацией; API-маршруты остаются типовыми.
SQL/ClickHouse/Redis внутренние интерфейсы	В7 и реестр сервисов ПД.	Владелец схемы, клиент, назначение, критичность, backup/restore, ограничения прямого доступа.	Внутренний контракт сервисов; не публикуется как внешний API.

3.2. Детальное описание интерфейсов¶

Детализация ниже дополняет реестр 3.1. Для REST endpoint-ов указан уровень групп и базовых префиксов; полный перечень методов, схем запросов и ответов приведён в OpenAPI-приложении. Чувствительная информация, включая JWT, пароли, ключи Kafka/S3/SMTP/OIDC и реальные адреса внешних систем, в документ не включается. Таймауты, лимиты размера запроса, параметры retry, TLS-терминация и целевые показатели доступности задаются эксплуатационной конфигурацией конкретного контура; в ПА фиксируется применяемый механизм и граница ответственности без публикации чувствительной информации.

Для каждого интерфейса PA-IF-* обязательные атрибуты трактуются следующим образом:

Код	Наименование	Источник	Получатель	Тип / протокол / формат	Метод, endpoint, topic или queue	Защита	Таймауты, retry и ошибки	SLA/доступность и ограничения
`PA-IF-01`	Публичный вход UI/API	Пользователь, внешний API-клиент	`ui-nginx`	HTTP/HTTPS, WebSocket; HTML/JSON/binary/media	`/`, `/login`, `/api/`, `/api/graphql`, `/api/ws/`, `/api/s3/`	Bearer JWT для защищённых API; TLS на периметре контура	HTTP 4xx/5xx, client reconnect; retry безопасен для `GET`	Доступность зависит от gateway и периметра; внутренние сервисы не публикуются напрямую.
`PA-IF-02`	Статический UI	`ui-nginx`	`ui-react`, UI-config	HTTP; HTML/JS/CSS/JSON/assets	`/config.json`, `/settings.json`, `/logo/*`, статические ресурсы	Сетевой периметр, без Bearer для статических файлов	Повтор безопасен; ошибки nginx 4xx/5xx	Проверяется загрузкой UI и runtime-конфигурации.
`PA-IF-03`	Gateway REST/GraphQL/WebSocket	`ui-nginx`	`ui-rest-to-gprc`	REST, GraphQL, WebSocket; JSON/multipart/binary	`/api/*`, `/api/graphql`, `/api/ws/`, `/api/base/ping/`	Bearer JWT, service/sync keys для отдельных входов	Upstream/gRPC errors транслируются в HTTP; WebSocket reconnect	Browser-facing API проверяется через `/api/base/ping/` и read-only операции.
`PA-IF-04`	API `statistics`	`ui-rest-to-gprc`	`statistics`	REST/gRPC; JSON/protobuf/files	`/api/statistics/auth/`, `access`, `camera-storage`, `event-storage`, `audit`, `report-`	Bearer JWT, service keys для sync	401/403/404/422/5xx; retry по идемпотентности метода	Схемы endpoint-ов и ошибки фиксируются в OpenAPI-приложении.
`PA-IF-05`	API `inference`	`ui-rest-to-gprc`	`inference`, `extended-inference`	REST/gRPC, HLS/WebRTC; JSON/images/media	`/api/inference/`, `/api/thermal/mediaserver/video/`	Bearer JWT, внутренний Docker DNS	Stream reconnect, upstream media errors, 4xx/5xx	Зависит от GPU, медиасервера, моделей и состояния камер.
`PA-IF-06`	API `severstal`	`ui-rest-to-gprc`	`severstal`	REST/gRPC; JSON/files	Customer-domain маршруты сценариев, ассетов, запусков, ПК-КОТ/CSVN/АСУ ТП	Bearer JWT и параметры внешних интеграций	Retry только с контролем версии/идентификатора	Состав маршрутов зависит от включённых сервисов домена.
`PA-IF-07`	Файлы и S3/DTS	UI/gateway/сервисы	`data-storage`, MinIO, DTS	HTTP, S3-compatible; binary/JSON UUID	`/api/s3/`, `/api/data-storage/`	Bearer/gateway checks, bucket credentials внутри контура	Ошибки 403/404/5xx; retry загрузки после проверки состояния	Бинарные данные должны быть согласованы с БД-владельцем.
`PA-IF-08`	Конфигурация gateway/UI	`ui-rest-to-gprc`	Consul KV, локальные config files	HTTP/REST, KV, file read; JSON	`/api/config/`, `/api/consul/`	Административные права, сетевой периметр	Изменения проверяются чтением конфигурации	Контурные значения не публикуются в ПА.
`PA-IF-09`	Основная Kafka	`statistics`, `inference`, `severstal`, gateway	`inf-kafka`, consumers	Kafka; protobuf/JSON	`camera_`, `KAFKA_TOPIC_`, `add_audit_record`, event/status topics	Внутренняя сеть `bx_default`	At-least-once, retry consumer-а, dedup по UUID	Retention и consumer groups задаются конфигурацией версии поставки.
`PA-IF-10`	PostgreSQL sidecar	Доменные сервисы	Доменные PostgreSQL	PostgreSQL wire; SQL rows	DSN/host aliases доменов	Внутренняя сеть, DB credentials	Транзакционные ошибки; retry только для read-only/идемпотентных операций	Схемами владеют сервисы; внешний доступ не публикуется.
`PA-IF-11`	Redis sidecar / очереди	Доменные сервисы	Redis sidecar	Redis RESP; key-value/TTL/queues	Redis DB/keyspace, Celery broker/result backend	Внутренняя сеть, credentials при наличии	TTL/connection errors; повтор зависит от владельца задачи	Redis не является долговечным источником истины.
`PA-IF-12`	ClickHouse	`statistics`, gateway	ClickHouse sidecar	ClickHouse native/HTTP; SQL rows	ClickHouse tables/views из В7	Внутренняя сеть, DB credentials	Ошибки запросов/мутаций; retry read-only	Производное зеркало; восстановление согласуется с PostgreSQL/MinIO.
`PA-IF-13`	Метрики и логи	Сервисы, Docker log driver	Prometheus, Loki	HTTP `/metrics`, Loki driver; text/log labels	`/metrics`, Loki push/query API	Внутренняя сеть, доступы observability	Scrape errors, log delivery retry	Наблюдаемость не заменяет functional health конкретного API.
`PA-IF-14`	Видеопотоки	IP-камеры/VMS	`inf-mediaserver`, NRI	RTSP, HTTP media; video stream	RTSP URL, virtual/file media URI	Камерные credentials в конфигурации	Reconnect media/inference; ошибки источника видео	Качество зависит от сети, FPS, кодека и доступности камеры.
`PA-IF-15`	CSVN/VMS	VMS/CSVN	`severstal`, `st-camera-storage`	SOAP/WSDL, HTTP, file; XML/JSON/media	Connector-specific endpoints, upload routes	Credentials внешней системы	Retry sync по внешнему ID; ошибки VMS логируются	Реальные endpoints задаются эксплуатационной конфигурацией.
`PA-IF-16`	ПК-КОТ	ПК-КОТ	`svr-postgres-pk-kot`, `severstal`	PostgreSQL read-only, HTTP push; SQL/JSON	Tables ПК-КОТ, status push endpoint	DB/HTTP credentials	Retry push статусов, dedup по внешнему ID	Отказ ПК-КОТ деградирует интеграцию, но не весь inference.
`PA-IF-17`	АСУ ТП	ASUTP Kafka	`svr-asutp-*`	Kafka, Avro, Schema Registry	`<topic>_meta`, `<topic>_data`, `asutp_unit_*`	Изолированный Kafka-контур	Retry consumer-а, Schema Registry errors	Схемы и topics согласуются для версии поставки.
`PA-IF-18`	OIDC/Keycloak	Браузер, `st-auth`	Keycloak/OIDC	OAuth2/OIDC, HTTP; JWT/JSON	`/api/statistics/auth/keycloak/*`, OIDC endpoints	OIDC client settings	Ошибки redirect/code/token; retry входа пользователем	Внешний провайдер управляется вне BOX5-DIT-MGSN.
`PA-IF-19`	SMTP/email	`st-auth`, report services	SMTP relay	SMTP; MIME/PDF/XLSX/CSV	SMTP host/port, report send operations	SMTP credentials	Retry зависит от SMTP/сервиса	Отказ SMTP деградирует уведомления и рассылку.
`PA-IF-20`	Внешние получатели	`severstal`, events/reports	Системы заказчика	HTTP/REST, S3/HTTP links; JSON/files	Согласованные external API endpoints	Credentials внешней системы	Retry по идемпотентному внешнему ID	Точные адреса и SLA задаются эксплуатационным соглашением.
`PA-IF-21`	Sandbox UI	`ui-nginx`	`node-red-sandbox`	HTTP/WebSocket; HTML/JSON/flow	`/sandbox/*`, `/sandbox/socket.io/`	Gateway/perimeter, sandbox auth при наличии	Reconnect UI/Socket.IO, 4xx/5xx	Технический контур подготовки сценариев.
`PA-IF-22`	Публикация сценариев	`node-red-sandbox`	API BOX5-DIT-MGSN, MinIO, sandbox Kafka/Redis	REST/S3/Kafka/Redis; JSON/files/models	`processings_status_topic`, `processings_control_topic`, Box API routes	Внутренние credentials и service settings	Celery/Kafka retry, dedup по session/task id	Результаты sandbox не считаются рабочими до публикации и проверки.

Код	Каналы, методы и endpoint-ы	Частота и объём данных	Авторизация и защита	Ошибки, таймауты, retry и идемпотентность	Логирование, мониторинг, доступность и ограничения
`PA-IF-01`	Пользовательский вход через `ui-nginx`: `/`, `/login`, `/api/`, `/api/graphql`, `/api/ws/`, `/api/s3`, файловые маршруты, HLS/WebRTC.	По действиям пользователя и потокам UI. Объём от малых JSON-запросов до бинарных файлов, видеофрагментов и WebSocket-сообщений.	Защищённые REST-операции используют Bearer JWT; часть публичных статических маршрутов доступна без токена. TLS/HTTPS включается эксплуатационной конфигурацией периметра.	HTTP-коды gateway и upstream-сервисов; повтор безопасен для `GET`, для изменяющих операций выполняется на уровне прикладного сценария. WebSocket переподключается клиентом.	Access/error logs `ui-nginx`, логи gateway, проверки `/login`, `/config.json`, `/api/base/ping/`. Внутренние сервисы напрямую пользователю не публикуются.
`PA-IF-02`	`ui-nginx` выдаёт `ui-react` и статические файлы: SPA, `/config.json`, `/settings.json`, `/logo/*`, статические ресурсы и `/docs/`.	При открытии интерфейса, обновлении страницы и загрузке ассетов; объём зависит от размера frontend-бандлов и статических файлов.	Обычно без Bearer-токена, так как это статический контент. Защита внешнего доступа обеспечивается сетевым периметром и настройками `ui-nginx`.	Ошибки отдаются HTTP-кодами `ui-nginx`; повтор безопасен и идемпотентен.	Access/error logs `ui-nginx`; контроль доступности статических файлов и корректности runtime-конфигурации UI.
`PA-IF-03`	Проксирование `ui-nginx` -> `ui-rest-to-gprc`: `/api/`, `/api/graphql`, `/api/ws/`, `/api/base/ping/`, `/api/config/`, `/api/consul/*`.	По действиям пользователя и фоновых UI-запросов. Основной объём - JSON; возможны multipart upload, бинарные downloads и WebSocket-события.	Bearer JWT для защищённых операций; отдельные служебные и auth-маршруты могут быть открыты согласно OpenAPI/gateway-настройкам.	HTTP/gRPC ошибки транслируются в REST-ответы; `GET` идемпотентны, `POST/PUT/DELETE` повторяются только с учётом прикладной сущности. WebSocket восстанавливается клиентом.	Логи `ui-rest-to-gprc` и `ui-nginx`; базовый health - `/api/base/ping/`. Полная схема REST API описана в OpenAPI-приложении.
`PA-IF-04`	Gateway -> `statistics`: `/api/statistics/auth/`, `access`, `camera-storage`, `event-storage`, `audit`, `comments`, `report-`, `event-statistics`, `object-visit-zone-counter`, `virt-cam-video-upload`.	По действиям UI/API, отчётным операциям и чтению событий. Объём от небольших JSON до PDF/XLSX/CSV, изображений и видеофрагментов.	Bearer JWT для пользовательских операций; отдельные sync/service-входы защищаются настройками gateway и контурными ключами.	Ошибки FastAPI/gRPC возвращаются как HTTP-статусы, типовая ошибка валидации - `422 HTTPValidationError`. Идемпотентность зависит от метода: чтение безопасно, изменение проверяется контрольным чтением.	Логи gateway и сервисов `statistics`, Kafka/audit-события, `/metrics` там, где endpoint исправен; некоторые сервисные `/metrics` могут быть недоступны, что фиксируется в реестре сервисов ПД.
`PA-IF-05`	Gateway -> `inference`/`extended-inference`: `/api/inference/image-storage/`, `models-storage`, `gateway`, `load-balancer`, `monitoring`, `/api/thermal/mediaserver/video/`.	По просмотру видео, preview, мониторинга камер и запросам состояния inference. Потоковые HLS/WebRTC и изображения могут быть существенно больше JSON-ответов.	Bearer JWT на пользовательских маршрутах; внутренние gRPC/HTTP-связи доступны только в Docker-сети. WebRTC/TURN параметры задаются конфигурацией.	Для потоков применяется переподключение клиента; для read-only методов повтор безопасен. Ошибки upstream транслируются gateway или проявляются как недоступность media-сегментов.	Логи `ui-rest-to-gprc`, `inf-domain-gateway`, `inf-load-balancer`, `inf-mediaserver`, `inf-monitoring`; метрики и состояние камер используются для диагностики видеоконтура.
`PA-IF-06`	Gateway -> `severstal`: customer-domain REST/gRPC для сценариев, ассетов, запусков, реестра моделей, переводов, CSVN/ПК-КОТ/АСУ ТП операций.	По действиям пользователей, интеграционным задачам и публикации сценариев. Объём - JSON/gRPC metadata, файлы ассетов и ссылки на объекты MinIO.	Bearer JWT на пользовательских маршрутах; внутренние сервисы доступны по Docker DNS. Доступ к внешним системам использует параметры эксплуатационной конфигурации.	Изменяющие операции должны проверяться чтением статуса/сущности. Повтор файловых операций и запусков выполняется только с контролем версии или идентификатора объекта.	Логи `svr-*` сервисов, PostgreSQL/MinIO/Kafka-состояние, ошибки интеграций. Набор customer-domain маршрутов зависит от включённых сервисов `severstal`.
`PA-IF-07`	Файловый контур: `/api/s3/`, `/api/data-storage/`, S3 API `ds-minio`, DTS по UUID, `st-domain-gateway` для object URLs.	По загрузке/скачиванию медиа, отчётов, изображений событий, ассетов и временных файлов. Объём от малых JSON-метаданных до крупных бинарных объектов.	Пользовательский доступ идёт через gateway/nginx и Bearer JWT там, где маршрут защищён. Прямые MinIO/DTS credentials и endpoint-ы не публикуются.	Повтор чтения идемпотентен. Upload повторяется по UUID/ключу объекта с учётом риска перезаписи; временные объекты DTS ограничены временем жизни.	Логи `ui-nginx`, `ds-minio`, DTS и сервисов-владельцев объектов. Ограничение: прямой S3 endpoint считается техническим, пользовательский доступ должен идти через опубликованный маршрут.
`PA-IF-08`	Gateway -> Consul KV / локальные конфигурационные файлы: `/api/config/`, `/api/consul/`, чтение `config.json` и UI settings.	Редкие операции чтения/изменения конфигурации UI и gateway; объём малый, JSON/key-value.	Доступ к изменяющим операциям ограничивается правами пользователя и настройками gateway. Чувствительная информация в клиентскую конфигурацию не выносится.	Чтение идемпотентно; изменение конфигурации требует проверки повторным чтением. Ошибки возвращаются HTTP-кодами gateway.	Логи `ui-rest-to-gprc`; контроль корректности конфигурации через `/config.json` и профильные API. Ограничение: изменения влияют на поведение UI/API без перезаписи документации.
`PA-IF-09`	Основная Kafka `inf-kafka`: события инференса, audit, команды камер/объектов, heartbeat, статусы, websocket fan-out, синхронизация справочников.	Непрерывный асинхронный поток. Объём зависит от числа камер, событий и фоновых синхронизаций.	Kafka доступна внутри `bx_default`; параметры подключения и имена групп задаются конфигурацией сервисов. Внешний доступ к основной Kafka не публикуется.	Retry и offset management реализуются Kafka-клиентами сервисов. Идемпотентность обеспечивается message UUID, идентификаторами сущностей и проверкой состояния в хранилищах.	Логи consumers/producers, consumer lag, состояние `inf-kafka`. Ограничение: порядок гарантируется в рамках partition/topic, межтопиковый порядок не считается строгим контрактом.
`PA-IF-10`	Доменные PostgreSQL sidecar: подключения сервисов к своим БД, Aerich/миграции, CRUD и транзакции.	Постоянные синхронные обращения сервисов. Объём зависит от числа пользователей, камер, событий, сценариев и отчётных операций.	Доступ только из Docker-сети; логины и пароли БД задаются env/защищёнными параметрами доступа и не документируются.	Транзакционные ошибки обрабатываются приложениями; retry применяется осторожно для read-only или идемпотентных операций. Миграции выполняются владельцем схемы.	Проверки контейнеров БД, `pg_isready`, логи PostgreSQL и сервисов-владельцев. Sidecar-БД не являются публичным API.
`PA-IF-11`	Доменные Redis sidecar: кэши, locks, очереди, временное состояние, bootstrap-координация.	Постоянные короткие операции; объём малый или средний, зависит от очередей и TTL-состояний.	Доступ только из Docker-сети; параметры подключения не публикуются.	Повтор команд зависит от типа операции: чтение безопасно, lock/queue операции повторяются только по логике владельца. Потеря Redis может приводить к деградации кэша или фоновых задач.	Проверки контейнеров и Redis `PING`, логи сервисов-владельцев. Redis не является источником истины для пользователей, событий и сценариев.
`PA-IF-12`	ClickHouse sidecar: native TCP/HTTP SQL для событийных зеркал, статистики, lookup-таблиц и аналитических маршрутов gateway.	По аналитическим запросам UI, ingest из сервисов и resync/backfill. Объём средний/высокий, зависит от событий и глубины выборок.	Внутренний технический доступ; отдельные опубликованные порты используются для эксплуатации, не как пользовательский API.	SQL mutations ClickHouse асинхронны; повтор чтения безопасен, повтор resync/backfill выполняется регламентно. Возможна eventual consistency с PostgreSQL.	Проверки ClickHouse `SELECT 1`, `/ping`, наличие таблиц, логи сервисов-владельцев и consumer lag.
`PA-IF-13`	Наблюдаемость: сервисы -> Prometheus `/metrics`, Docker logs -> Loki.	Метрики собираются периодически; логи передаются непрерывно. Объём зависит от нагрузки и уровня логирования.	Эксплуатационный доступ ограничивается сетевым периметром; чувствительная информация и JWT не должны публиковаться в логах и документации.	Потеря Prometheus/Loki не останавливает бизнес-функции, но ухудшает диагностику. Повтор scrape выполняет Prometheus.	Состояние targets Prometheus, Loki API, Docker log driver. Ограничение: не все сервисные `/metrics` endpoint-ы исправны в текущем контуре.
`PA-IF-14`	IP-камеры и виртуальные источники -> inference: RTSP, HTTP/MP4, `virtual`/file media URI; downstream HLS/WebRTC внутри BOX5-DIT-MGSN.	Непрерывный поток для активных камер; объём высокий, пропорционален числу потоков, FPS и разрешению.	Камерные URL и credentials задаются эксплуатационной конфигурацией и не публикуются. Доступ к downstream-просмотру идёт через UI/gateway.	Переподключение и recovery выполняют media/inference-компоненты. Идемпотентность неприменима к live-потоку; для событий используется message UUID downstream.	Логи `inf-mediaserver`, `inf-load-balancer`, `inf-nri-inference`, мониторинг состояния камер. Ограничение: физические камеры и VMS находятся за границей ПО BOX5-DIT-MGSN.
`PA-IF-15`	CSVN/VMS -> `severstal`/statistics: Cisco/Milestone SOAP/WSDL, Macroscop HTTP, connector `VIRTUAL`, загрузка архивных видео.	По расписанию синхронизации, запросам архива и настройкам интеграции. Объём от JSON/XML метаданных до видеофайлов.	Credentials и реальные VMS endpoints задаются эксплуатационной конфигурацией и не раскрываются.	Повтор синхронизации должен учитывать внешние идентификаторы камер и уже загруженные медиа. Ошибки внешнего VMS логируются интеграционными сервисами.	Логи `svr-severstal-integration`, `svr-severstal-org-sync`, `st-virt-cam-video-upload`; контроль результата в camera-storage и списках загруженных видео.
`PA-IF-16`	ПК-КОТ <-> BOX5-DIT-MGSN: PostgreSQL read-only для справочников, HTTP push для событий/статусов.	По регламенту синхронизации и при изменении статуса события. Объём малый/средний, табличные строки и JSON-статусы.	Параметры подключения к БД и push URL задаются эксплуатационной конфигурацией. В документации не фиксируются логины, пароли и реальные адреса.	Read-only операции повторяемы. Push статусов должен быть устойчив к повторной отправке по внешнему идентификатору события/статуса.	Логи `svr-postgres-pk-kot`, `svr-severstal-integration`, `svr-severstal-org-sync`; контроль успешности push и свежести справочников.
`PA-IF-17`	АСУ ТП -> `svr-asutp`: Kafka `_meta`/`_data`, Avro, Schema Registry API; публикация результата в основной Kafka.	Асинхронный поток сигналов. Объём зависит от числа ASUTP-юнитов и частоты сигналов.	Доступ к ASUTP Kafka и Schema Registry задаётся конфигурацией; внешние credentials не публикуются.	Kafka retry/offset management на стороне consumers; сообщения проверяются по Avro-схемам. Дубли обрабатываются по ключам, timestamp и логике расчёта состояния.	Логи `svr-asutp`, `svr-asutp-kafka`, Schema Registry, consumer lag. Ограничение: ASUTP Kafka является отдельным технологическим контуром.
`PA-IF-18`	OIDC/Keycloak: браузер пользователя, `st-auth`, `ui-rest-to-gprc`; authorization code flow и локальный выпуск JWT.	При входе пользователя и обновлении сессии; объём малый, redirect parameters и JSON/JWT.	Защита определяется OIDC/OAuth2 и локальной проверкой JWT. Параметры `OPEN_ID_*`, конфиденциальный параметр OIDC-клиента и URL провайдера не публикуются.	Ошибки авторизации возвращаются через auth API/UI. Повтор login выполняется пользователем; refresh token обновляет локальную пару токенов.	Логи `st-auth` и gateway без публикации токенов. Ограничение: уже выданные stateless JWT действуют до истечения срока.
`PA-IF-19`	SMTP/email: `st-auth`, `st-report-email`, отчётные сервисы -> SMTP.	По событию сброса пароля, настройкам рассылки или регламенту отчёта. Объём малый/средний, возможны вложения PDF/XLSX/CSV.	SMTP credentials, адрес сервера и отправителей задаются конфигурацией и не документируются.	Повтор отправки может привести к дублю письма, поэтому выполняется по прикладному статусу/журналу. Ошибки SMTP логируются сервисом-отправителем.	Логи `st-auth`, `st-report-email`, отчётных сервисов; контроль успешности по статусам отправки и отсутствию ошибок SMTP.
`PA-IF-20`	BOX5-DIT-MGSN -> внешние получатели данных: HTTP/REST, S3/HTTP ссылки, отчётные и событийные выгрузки.	По интеграционным сценариям, событиям, статусам или регламентным выгрузкам. Объём от JSON-статусов до отчётов и ссылок на медиа.	Способ авторизации зависит от согласованного внешнего API и задаётся эксплуатационной конфигурацией. Чувствительная информация не публикуется.	Retry и идемпотентность определяются внешним контрактом; рекомендуемый ключ идемпотентности - идентификатор события, статуса или отчёта.	Логи интеграционных сервисов и отчётных задач; контроль HTTP-кодов внешней системы. Ограничение: внешняя доступность не контролируется BOX5-DIT-MGSN.
`PA-IF-21`	`ui-nginx` -> `node-red-sandbox`: `/sandbox/`, UI sandbox, backend, WebSocket.	По действиям инженера/администратора при подготовке сценариев. Объём - UI assets, flow JSON, служебные ответы.	Доступ технический; ограничения задаются `ui-nginx`, sandbox-настройками и сетевым периметром.	Ошибки прокси/backend возвращаются HTTP-кодами; повтор чтения безопасен, изменение flows требует контроля версии/содержимого.	Логи `nr-sbx-nginx`, frontend/backend, Node-RED; sandbox не является пользовательским API рабочего контура.
`PA-IF-22`	`node-red-sandbox` -> основной API BOX5-DIT-MGSN, MinIO, sandbox Kafka/Redis: публикация flows, файлы, проверочные запуски.	По действиям подготовки и публикации сценариев; объём зависит от размера flows, моделей и тестовых артефактов.	Технические параметры доступа задаются конфигурацией sandbox и Box API. Чувствительная информация и токены не документируются.	Публикация должна проверяться чтением опубликованной версии/сценария. Повтор операции выполняется только с контролем версии flow или имени артефакта.	Логи sandbox backend, Node-RED, NRI, Celery, Kafka/Redis. Ограничение: результат sandbox-проверки не заменяет проверку опубликованного сценария в рабочем контуре.

3.3. Общие требования к API¶

Общие требования применяются к опубликованным REST API, GraphQL/WebSocket маршрутам gateway, внутренним HTTP/gRPC-вызовам и интеграционным HTTP API, если для конкретного интерфейса не задано более строгое правило в разделе 3.2, OpenAPI-приложении или эксплуатационной конфигурации.

3.3.1. Источник спецификации и область действия¶

Требование	Описание
Основной источник REST-контракта	Детальный состав REST endpoint-ов, схем запросов, схем ответов и security-схем фиксируется в OpenAPI-приложении.
Состав API эксплуатационных контуров	В ПА приведены API-группы применяемых сервисов и доменов BOX5-DIT-MGSN. Для DEV, TEST и PROD состав API-контрактов считается единым в рамках одной версии поставки; различия относятся к base URL, числу узлов, подключённым источникам данных и эксплуатационным параметрам.
Базовый URL	Все пути в документации указываются относительно базового URL API эксплуатационного контура (`<base_url>`). Фактический адрес контура, доменное имя и TLS-настройки задаются эксплуатационной конфигурацией.
Единая точка публикации	Пользовательские и внешние API-вызовы проходят через gateway/edge-слой `ui-nginx` и `ui-rest-to-gprc`. Внутренние сервисы не рассматриваются как самостоятельные публичные точки входа.
Машинная сверяемость	При выпуске версии документа OpenAPI-приложение должно соответствовать доступной Swagger/OpenAPI-спецификации применяемого контура без публикации чувствительной информации, JWT, паролей и постоянных токенов. Машиночитаемый OpenAPI JSON/YAML передаётся или хранится как артефакт версии поставки; внутренние URL выгрузки в ПА не публикуются.

3.3.2. Именование, методы и версии¶

Требование	Описание
Именование путей	REST endpoint-ы группируются по доменным префиксам: `/api/statistics/`, `/api/inference/`, `/api/data-storage/`, `/api/s3/`, `/api/base/`, `/api/config/`, `/api/consul/*` и customer-domain маршрутам gateway.
Стабильность префиксов	Публичные префиксы API считаются частью контракта документа. Изменение префикса допускается только вместе с обновлением OpenAPI-приложения и описания интерфейсов.
HTTP-методы	`GET` используется для чтения, `POST` - для создания, запуска операций и сложных выборок, `PUT` - для изменения, `DELETE` - для удаления. Исторические отклонения фиксируются в OpenAPI как существующий контракт.
Версионирование	Версия API определяется версией поставки ПО, документации и OpenAPI-спецификации. Опубликованные пути API приведены в OpenAPI-приложении.
Версия API по подсистемам	Если отдельная версия подсистемы не выделена в URL или OpenAPI metadata, версия её API равна версии поставки BOX5-DIT-MGSN и идентификатору OpenAPI-выгрузки. Дополнительные `/v1`, `/v2` и аналогичные префиксы вводятся только при явном появлении такого контракта в реализации.
Обратная совместимость	Расширение схемы новыми необязательными полями допускается как совместимое изменение. Удаление endpoint-а, переименование поля, изменение типа поля или изменение обязательности параметра считается несовместимым и требует отдельного согласования релиза.

3.3.3. Форматы запросов и ответов¶

Требование	Описание
Основной формат	Основной формат запросов и ответов REST API - JSON (`application/json`).
Формы и файлы	Для входа пользователя может использоваться `application/x-www-form-urlencoded`; для загрузки файлов используется `multipart/form-data`; для скачивания отчётов, изображений и видео допускаются бинарные ответы без JSON-схемы.
Потоковые данные	HLS/WebRTC, WebSocket и файловые маршруты могут возвращать потоковое или фрагментированное содержимое. Такие ответы описываются в ПА как медиа/потоковые и не требуют JSON-схемы.
Кодировка и даты	Текстовые JSON-данные передаются в UTF-8. Временные метки должны передаваться в формате, заданном схемой конкретного endpoint-а; при наличии timezone-параметра он передаётся явно.
Схемы данных	Для REST endpoint-ов применяются схемы из OpenAPI-приложения. Для Kafka/gRPC/S3/SQL-интерфейсов схемы и структуры данных задаются сервисами-владельцами и реестром сервисов ПД.

3.3.4. Ошибки и статусы¶

Требование	Описание
HTTP-статусы	Успешные операции возвращают 2xx-коды. Ошибки запроса возвращают 400, ошибки авторизации и доступа - 401/403, отсутствие ресурса - 404, конфликт состояния - 409, ошибки валидации - 422, внутренние ошибки upstream-сервиса - 5xx.
Ошибка валидации	Типовая ошибка валидации FastAPI описывается схемой `HTTPValidationError` и кодом `422`.
Бизнес-ошибки	Прикладные ошибки возвращаются в формате, заданном конкретным сервисом и OpenAPI-схемой. Текст ошибки не должен раскрывать чувствительную информацию: пароли, токены, внутренние DSN и полные env-настройки.
Ошибки по API-группам	Для endpoint-ов типовые ошибки указаны в реестрах подсистем OpenAPI-приложения. Если у endpoint-а нет отдельной схемы ошибки, применяется общий набор 400/401/403/404/409/422/5xx с телом ошибки, определённым сервисом-владельцем.
Повторы запросов	Повтор безопасен для операций чтения. Повтор изменяющих операций выполняется только при наличии прикладного идентификатора, контроля статуса или проверки результата чтением.
Таймауты	Значения таймаутов gateway, upstream-сервисов и внешних интеграций задаются эксплуатационной конфигурацией. Документация фиксирует механизм обработки ошибок, но не публикует контурные значения таймаутов.

3.3.5. Авторизация и технические заголовки¶

Требование	Описание
Основная схема авторизации	Защищённые пользовательские операции используют Bearer JWT, выданный `st-auth` или полученный после OIDC/Keycloak-входа.
Публичные операции	Операции входа, получения параметров внешней авторизации, статические файлы и отдельные служебные проверки могут быть доступны без Bearer-токена, если это указано в OpenAPI или настройках gateway.
Постоянные и sync-токены	Постоянные токены и контурные ключи синхронизации применяются только для специальных сценариев. Их значения не приводятся в документации и не должны попадать в журналы.
Обязательные HTTP-заголовки	Для JSON-запросов передаются `Content-Type: application/json` и `Accept: application/json`; для защищённых операций - `Authorization: Bearer <token>`; для multipart-загрузок - соответствующий `multipart/form-data` boundary.
Корреляция запросов	Для интеграционных и изменяющих запросов клиент должен передавать `X-Request-ID` или `X-Correlation-ID`. Если заголовок не передан, gateway или сервис может сформировать локальный идентификатор. Полученный идентификатор сохраняется в логах и проксируется downstream, где это поддержано реализацией.
Чувствительная информация в заголовках	JWT, постоянные токены, SMTP/OIDC/S3/Kafka credentials и sync-ключи запрещено публиковать в документации, примерах, скриншотах и открытых логах.

3.3.6. Логирование, мониторинг и аудит¶

Требование	Описание
Логирование API	Edge/gateway и backend-сервисы должны писать технологические логи запросов, ошибок и upstream-сбоев в stdout/stderr контейнеров с последующей доставкой в Loki, если это включено конфигурацией.
Audit-события	Пользовательские действия, влияющие на состояние системы, должны передаваться в audit-контур, если операция поддерживается соответствующим сервисом и gateway.
Метрики	Сервисы могут предоставлять `/metrics` для Prometheus. Если endpoint метрик отсутствует или неисправен у конкретного сервиса, эксплуатационный контроль выполняется по состоянию контейнера, логам и профильным read-only проверкам.
Проверка доступности	Базовая проверка browser-facing API - `/api/base/ping/`. Для доменных API применяются контрольные read-only операции из OpenAPI-приложения и реестра сервисов ПД.
Персональные данные и чувствительная информация	Логи и метрики не должны раскрывать пароли, JWT, постоянные токены, ключи доступа, полные DSN и конфиденциальные значения env.

3.3.7. Требования к изменениям API¶

Требование	Описание
Обновление документации	Любое изменение опубликованного endpoint-а, схемы запроса, схемы ответа или security-схемы требует обновления OpenAPI-приложения и соответствующих разделов ПА.
Совместимые изменения	Допускаются новые endpoint-ы применяемых сервисов, новые необязательные поля, новые значения справочников и уточнение описаний без нарушения существующих клиентов.
Несовместимые изменения	Удаление endpoint-а, изменение метода, пути, типа поля, обязательности поля, формата ошибки или схемы авторизации требует отдельного описания в релизной документации и миграции клиентов.
Деградация внешних систем	Отказ внешних систем (OIDC, SMTP, ПК-КОТ, CSVN/VMS, АСУ ТП, внешние API получателей данных) должен обрабатываться как деградация соответствующего интерфейса без раскрытия чувствительной информации и без остановки независимых функций BOX5-DIT-MGSN.
Проверка после изменения	После изменения API выполняется сборка документации, сверка OpenAPI-реестра и, для применимых операций, контрольные вызовы в эксплуатационном контуре или read-only проверки сервисов без публикации чувствительных данных.

3.3.8. Версии, ошибки и совместимость по API-группам¶

API-группа	Версия API	Типовые ошибки	Правила совместимости
`auth`, `access`, `audit`	Версия поставки BOX5-DIT-MGSN и OpenAPI-выгрузки.	400/401/403/404/409/422/5xx; `HTTPValidationError` для ошибок схемы.	Нельзя менять формат токенов, ролей, прав и audit-событий без миграции клиентов и обновления gateway.
`camera-storage`, `comments`, `config`, `consul`	Версия поставки BOX5-DIT-MGSN и OpenAPI-выгрузки.	400/401/403/404/409/422/5xx; прикладные ошибки владельца справочника.	Совместимы новые необязательные поля и справочники; удаление поля камеры, зоны или конфигурации считается breaking change.
`event-storage`, `event-statistics`, `object-visit-zone-counter`	Версия поставки BOX5-DIT-MGSN и OpenAPI-выгрузки.	400/401/403/404/409/422/5xx; ошибки отсутствия события, медиа или аналитической витрины.	Идентификаторы событий, структура фильтров и форматы дат должны оставаться совместимыми в пределах релиза.
`report-pdf-xlsx-generator`, `auth-report-pdf-xlsx-generator`, `report-email`	Версия поставки BOX5-DIT-MGSN и OpenAPI-выгрузки.	400/401/403/404/409/422/5xx; ошибки генерации, отсутствия шаблона, SMTP или файла.	Изменение формата отчёта допустимо как версия шаблона; изменение API запуска/скачивания требует обновления клиентов.
`image-storage`, `models-storage`, `gateway`, `load-balancer`, `monitoring`, `mediaserver`	Версия поставки BOX5-DIT-MGSN и OpenAPI-выгрузки.	400/401/403/404/409/422/5xx; ошибки недоступности модели, камеры, медиапотока или GPU-сервиса.	Медиа-URL, идентификаторы моделей и статусы inference не должны менять тип без отдельного релиза.
`s3`, `data-storage`, `virt-cam-video-upload`	Версия поставки BOX5-DIT-MGSN и OpenAPI-выгрузки.	400/401/403/404/409/422/5xx; ошибки доступа к объекту, истечения срока временного файла или несогласованности БД/MinIO.	Совместимы новые необязательные метаданные; изменение жизненного цикла файлов должно быть отражено в В7 и И3.
Интеграционные маршруты customer-domain API	Версия поставки BOX5-DIT-MGSN и OpenAPI-выгрузки либо согласованной интеграционной спецификации.	400/401/403/404/409/422/5xx; ошибки внешнего источника, недоступности connector-а или конфликта статуса.	Breaking changes согласуются как изменение интеграционного сценария с заказчиком и сопровождаются правилами повторной отправки/идемпотентности.

3.4. Асинхронный обмен (базовое)¶

Асинхронный обмен используется для доставки событий инференса, команд синхронизации, статусов, heartbeats, audit-записей, WebSocket-уведомлений и интеграционных сигналов. Подраздел задаёт базовые правила для интерфейсов PA-IF-09, PA-IF-17, PA-IF-22 и Redis/Celery-очередей, которые перечислены в разделе 3.1. Асинхронные топики, consumer groups, Kafka/S3/DB credentials и контурные значения retention задаются эксплуатационной конфигурацией и не публикуются как чувствительная информация. Отдельная AsyncAPI-спецификация на момент подготовки ПА не выделяется: согласованным описанием асинхронного обмена для документа является таблица topic/queue ниже, код сервисов-владельцев сообщений и эксплуатационная конфигурация версии поставки. При появлении AsyncAPI она должна быть включена в комплект поставки и связана с данным разделом.

3.4.1. Контуры асинхронного обмена¶

Контур	Компоненты	Назначение	Ограничения
Основная событийная шина BOX5-DIT-MGSN	`inf-kafka` в домене `kafka-domain`	Связность `statistics`, `inference`, `severstal`, `ui-rest-to-gprc` и отчётных сервисов: события, команды камер, изменения справочников, audit, статусы, WebSocket fan-out.	Внутренний Kafka-контур, не является публичным REST/gRPC API. Схемами сообщений владеют сервисы-производители и потребители.
Технологический контур АСУ ТП	`svr-asutp-kafka`, `svr-asutp-schema-registry`, `svr-asutp`	Приём пар топиков `<topic>_meta` / `<topic>_data`, проверка Avro-схем, расчёт состояния ASUTP-юнитов и публикация итоговых `asutp_unit_*` сообщений в основную шину.	Изолирован от основной Kafka. Входные сигналы и схемы относятся к интеграции АСУ ТП и не заменяют общую событийную шину BOX5-DIT-MGSN.
Песочница Node-RED/NRI	`nr-sbx-kafka`, `nr-sbx-redis`, `nr-sbx-celery`, `nr-sbx-flower`	Статусы, прогресс, control-сообщения и фоновые задачи подготовки сценариев в sandbox-контуре.	Технический контур подготовки сценариев; рабочие события видеоаналитики хранятся в событийных сервисах BOX5-DIT-MGSN.
Доменные Redis sidecar	Redis-сервисы `statistics`, `inference`, `data-storage`, `severstal`, `node-red-sandbox`	Кэш, locks, TTL-состояние, временные объекты, Celery broker/result backend и короткие технические очереди.	Redis не рассматривается как долговечная событийная шина и не является источником истины для пользователей, камер, событий или сценариев.

3.4.2. Базовая схема потоков¶

Исходный Mermaid-код схемы: ПА-MER-003. 3.4.2. Базовая схема потоков.

3.4.3. Топики и маршрутизация¶

Точные имена топиков задаются переменными вида KAFKA_TOPIC_*, настройками сервисов и таблицами интеграционных конфигураций. В ПА фиксируются логические семейства топиков и правила обработки, а не чувствительные значения и не полный снимок состояния брокера.

Семейство сообщений	Типовые производители	Типовые потребители	Назначение маршрута
События видеоаналитики и жизненный цикл событий	`inf-nri-inference`, `inf-load-balancer`, `st-event-storage`, `svr-severstal-integration`	`st-event-storage`, отчётные сервисы, `severstal`, UI/WebSocket consumers	Создание события, добавление медиа, завершение события, статусы обработки, downstream-уведомления.
Камеры, объекты, зоны, presets и модели	`st-camera-storage`, сервисы моделей, `severstal`	`inference`, `statistics`, отчёты, integration-сервисы	Распространение актуальной топологии, правил обработки и готовности моделей.
Audit-записи	`ui-rest-to-gprc`, `st-audit`, прикладные сервисы	`st-audit`	Централизованная запись действий пользователей и сервисов в audit-хранилище.
WebSocket и сервисные статусы	`ui-rest-to-gprc`, `st-event-storage`, `severstal`, сервисы launch/status	Browser-facing gateway и прикладные consumers	Доставка прогресса, состояния сервисов и обновлений UI без синхронного polling.
АСУ ТП `_meta` / `_data`	Внешний ASUTP Kafka producer или интеграционный collector	`svr-asutp`, `svr-asutp-schema-registry`	Приём технологических сигналов, проверка Avro-схем и вычисление состояния ASUTP-юнитов.
Sandbox status/control	`nr-sbx-backend`, `nr-sbx-celery`, sandbox NRI	`nr-sbx-backend`, `nr-sbx-celery`, `nr-sbx-flower`	Отображение прогресса sandbox-запусков, управление задачами и диагностика подготовки сценариев.

Базовая матрица topic/queue для применяемых асинхронных контрактов:

Topic / queue	Producer	Consumer	Назначение	Формат	Retention	Retry	DLQ / обработка ошибок
`KAFKA_TOPIC_INFERENCE_SEND_EVENT` и семейство событий inference	`inf-nri-inference`, `inf-load-balancer`	`st-event-storage`, отчётные и integration-сервисы	Создание и обновление событий видеоаналитики, доставка медиа-ссылок и статусов обработки.	Protobuf/JSON по схеме владельца события.	По конфигурации `inf-kafka` версии поставки.	Повтор чтения по offset; запись результата до commit offset.	Отдельная DLQ не фиксируется; сбои разбираются по логам, lag и resync из хранилища владельца.
`camera_`, `statistic_camera_`, `statistic_cmd_camera_*`	`st-camera-storage`, gateway, integration-сервисы	`inference`, `statistics`, отчёты	Синхронизация камер, объектов, зон, presets и команд camera lifecycle.	JSON/protobuf.	По конфигурации `inf-kafka`.	Повтор безопасен по `camera_uuid`, версии или текущему состоянию.	Невалидные сообщения не должны подтверждаться до обработки; отдельная DLQ не описана.
`add_audit_record`	`ui-rest-to-gprc`, прикладные сервисы	`st-audit`	Централизованная запись audit-действий пользователей и сервисов.	JSON/protobuf audit payload.	По конфигурации `inf-kafka`.	Retry consumer-а, дедупликация по действию/идентификатору, если задан.	Ошибки фиксируются в логах audit-сервиса; отдельная DLQ не описана.
`websocket_*`, service status topics	`st-event-storage`, `severstal`, launch/status services	Browser-facing gateway, UI/WebSocket consumers	Доставка прогресса, обновлений UI и состояния сервисов без polling.	JSON status/event payload.	По конфигурации `inf-kafka`.	Повторная доставка допускается; UI должен уметь обновлять состояние идемпотентно.	При сбое UI восстанавливает состояние read-only запросом к API.
`model_version_*`, `models_storage_ready`	Сервисы моделей, sandbox, storage-сервисы	`inference`, sandbox consumers	Уведомление о версии модели, готовности артефактов и изменении model registry.	JSON/protobuf metadata.	По конфигурации `inf-kafka`.	Retry по UUID/версии модели.	Ошибки требуют проверки модельного хранилища и статуса модели.
`continue_launch`, `change_launch_status`	`svr-launch-storage`, sandbox/backend-сервисы	Launch/status consumers, sandbox workers	Управление запуском сценариев и сменой статусов выполнения.	JSON command/status payload.	По конфигурации `inf-kafka`.	Повтор по `launch_uuid`/`session_id` и текущему статусу.	Ошибки обрабатываются статусом запуска и логами владельца.
`<topic>_meta`, `<topic>_data`	Внешний ASUTP Kafka producer	`svr-asutp`, `svr-asutp-schema-registry`	Приём технологических сигналов АСУ ТП и проверка Avro-схем.	Avro + Schema Registry.	По конфигурации ASUTP Kafka.	Consumer не фиксирует offset до успешной проверки и расчёта.	Невалидная схема или payload фиксируются в логах; отдельная DLQ не описана.
`asutp_unit_*`	`svr-asutp`	Основные consumers BOX5-DIT-MGSN	Публикация рассчитанного состояния ASUTP-юнитов в основной контур.	JSON/protobuf state payload.	По конфигурации `inf-kafka`.	Retry по `unit_uuid`, timestamp и версии состояния.	Ошибки потребителей разбираются по lag/logs; восстановление через актуальное состояние владельца.
`processings_status_topic`	`nr-sbx-celery`, sandbox jobs	`nr-sbx-backend`, `nr-sbx-flower`	Прогресс и статусы sandbox-обработок.	JSON status payload.	По конфигурации sandbox Kafka; в типовом sandbox-профиле retention может быть сокращённым.	Повтор по `session_id`/task id.	Ошибки отображаются через статус задачи и логи worker-а.
`processings_control_topic`	`nr-sbx-backend`, управляющие сценарии	`nr-sbx-celery`, consumer group вида `process_session_<session_id>`	Управление sandbox-задачами и обработкой текущей сессии.	JSON command payload.	По конфигурации sandbox Kafka.	Повтор по `session_id` и текущему состоянию задачи.	Остановка/отмена задачи дополнительно контролируется средствами Celery.
Celery/Redis queues sandbox	`nr-sbx-backend`, Node-RED sandbox	`nr-sbx-celery`	Фоновые задачи подготовки, проверки и публикации сценариев.	Celery metadata, Redis key-value.	По конфигурации Redis/Celery.	Retry Celery-задачи согласно настройкам worker-а.	Отдельная DLQ не фиксируется; состояние проверяется через task result, Flower и логи.

Маршрутизация сообщений выполняется по топику и consumer group. Ключ сообщения, если он задан производителем, должен соответствовать устойчивой доменной сущности: event_uuid, message_uuid, camera_uuid, object_uuid, unit_uuid, launch_uuid, session_id или аналогичному идентификатору. Это позволяет сохранять порядок в пределах partition для одной сущности и упрощает дедупликацию.

3.4.4. Формат сообщений¶

Контур	Основной формат	Требования
Основная Kafka `inf-kafka`	Protobuf и JSON, зависящие от сервиса-владельца	Сообщение должно содержать доменный идентификатор, время события или изменения, тип операции и полезную нагрузку без чувствительной информации. Схема payload фиксируется в коде владельца топика и совместимых клиентах.
АСУ ТП	Avro-сообщения, Schema Registry HTTP API	Для обработки требуется согласованная пара `<topic>_meta` / `<topic>_data`. `_meta` описывает идентификатор, имя тега и ключ данных; `_data` передаёт значение и timestamp.
Sandbox Kafka/Redis	JSON/status payload, Celery task metadata, Redis key-value	Данные используются для прогресса и управления текущими sandbox-запусками. Они не являются долговечным бизнес-состоянием продукта.
Медиа и крупные файлы	Ссылки на MinIO/S3, DTS UUID, файловые URL	По возможности через Kafka передаются идентификаторы, статусы и ссылки, а бинарные объекты размещаются в файловом или объектном хранилище.

В сообщениях запрещено передавать пароли, JWT, постоянные токены, Kafka/S3/SMTP/OIDC credentials, DSN с конфиденциальными параметрами и значения закрытых env-параметров. Если диагностический payload содержит персональные или конфиденциальные данные, публикация такого примера в документации допускается только после обезличивания.

3.4.5. Порядок обработки и гарантии доставки¶

Правило	Описание
Модель доставки	Базовая модель для Kafka-потоков - at-least-once: сообщение может быть доставлено повторно, если consumer не подтвердил offset или был перезапущен до фиксации результата.
Фиксация offset	Consumer должен фиксировать offset после успешной прикладной обработки: записи в PostgreSQL/ClickHouse, загрузки объекта в MinIO, изменения статуса или публикации downstream-события, если это часть операции.
Порядок	Порядок гарантируется только внутри одного topic partition. Между разными топиками и разными partition строгий глобальный порядок не является контрактом.
Источник истины	Kafka и Redis не заменяют основное хранилище состояния. Канонические данные пользователей, камер, событий, сценариев, ASUTP-настроек и справочников хранятся в PostgreSQL/MinIO у сервисов-владельцев; ClickHouse является производным зеркалом.
Replay и восстановление	После сбоя consumer должен уметь продолжить чтение с сохранённого offset. Если retention топика истёк или сообщение удалено, восстановление выполняется через resync из хранилища владельца, а не через Kafka.

3.4.6. Retry, идемпотентность и дубликаты¶

Ситуация	Требование
Временная недоступность consumer	Сообщения остаются в Kafka до истечения retention, consumer продолжает обработку после восстановления и повторного чтения offset.
Ошибка обработки сообщения	Consumer не должен подтверждать offset до успешного завершения операции. Повторная обработка должна быть безопасной для уже записанного результата.
Дубли событий	Сервис-получатель обязан проверять `message_uuid`, `event_uuid`, доменный ключ сущности, timestamp, версию или текущий статус перед созданием новой записи.
Дубли команд изменения	Изменяющие команды должны приводить систему к одному и тому же итоговому состоянию при повторе: обновление по UUID/версии, soft delete по существующей сущности, повторная публикация статуса без создания лишнего бизнес-объекта.
Дубли audit-записей	Audit-сообщения должны содержать пользователя/сервис, действие, время и контекст. Если операция повторяется технически, сервис-владелец должен исключать неконтролируемое размножение записей или явно трактовать повтор как отдельное действие.
ASUTP-сигналы	Повторы обрабатываются по topic, ключу данных, timestamp и `unit_uuid`. Более старое или уже учтённое значение не должно откатывать актуальный результат ASUTP-юнита без явного правила сервиса.
Sandbox-задачи	Повтор запуска или control-команды выполняется по `session_id`/task id и текущему состоянию задачи. Результат sandbox-проверки не считается подтверждением готовности рабочего сценария без публикации и проверки в рабочем контуре.

3.4.7. Наблюдаемость асинхронного обмена¶

Проверка	Что контролируется
Состояние брокеров	Контейнеры `inf-kafka`, `svr-asutp-kafka`, `nr-sbx-kafka`, наличие Kafka listener-ов, topic list и отсутствие критических broker/controller ошибок в логах.
Consumer lag	Отставание групп потребителей по основным topic families: события, камеры, audit, ASUTP, launch/status и sandbox status/control.
Состояние сервисов-потребителей	Логи producers/consumers, успешность записи в PostgreSQL/MinIO/ClickHouse, ошибки десериализации, ошибки Schema Registry и повторные restart-циклы.
Redis/Celery	Доступность Redis `PING`, длина очередей, task state, ошибки Celery worker-ов и доступность Flower для sandbox-контура, если он включён.
Пользовательский эффект	Появление события в `st-event-storage`, обновление UI/WebSocket, актуальность статусов ASUTP-юнитов, появление audit-записи и корректность отчётных данных.

Диагностические проверки выполняются read-only командами и не должны переносить в документацию чувствительную информацию, содержимое токенов, закрытые env-параметры, полные payload-ы с персональными данными или необезличенные фрагменты логов.