Раздел 1. Вводная часть¶
1.1. Основные сведения об АС, необходимые для разработки ПО¶
BOX5-DIT-MGSN является автоматизированной системой промышленной видеоаналитики. Система получает live-видеопотоки, архивные видеозаписи и загруженные видеофайлы, применяет NRI-сценарии и модели компьютерного зрения, формирует события и нарушения, хранит связанные медиа и предоставляет пользователям web-интерфейс и API для работы с результатами обработки.
Настоящий документ относится к комплекту рабочей документации по ГОСТ 34.201-89 и выполняет роль ПА «Описание программного обеспечения» для API-слоя BOX5-DIT-MGSN. Вводная часть задаёт сведения об автоматизированной системе, которые необходимы разработчикам, интеграторам, администраторам и специалистам сопровождения при использовании, развитии и проверке программных интерфейсов.
Назначение API-документа¶
Документ применяется при:
- разработке и сопровождении API-клиентов и интеграций с BOX5-DIT-MGSN;
- проверке состава опубликованных REST endpoint-ов, GraphQL и WebSocket маршрутов;
- согласовании границ внутренних service-to-service интерфейсов;
- анализе потоков данных между UI, gateway, backend-сервисами, inference, хранилищами и внешними системами;
- планировании поставки, обновления, rollback и проверок API после изменения версии программного обеспечения.
ПА не заменяет эксплуатационные инструкции, пользовательские инструкции, реестр сервисов ПД и каталог БД. Связанные документы используются совместно:
| Документ | Что уточняет |
|---|---|
| ПД «Концептуальный проект» | Назначение системы, функции, пользователи, роли, внешние системы и полный реестр сервисов. |
| И2 «Настройки» | Развёртывание, настройку, обновление, резервное копирование и восстановление контура. |
| И3 «Инструкции администратора» | Прикладное и системное администрирование BOX5-DIT-MGSN. |
| В7 «Каталог базы данных» | Хранилища, таблицы, ключевые поля и владельцев данных. |
Область описания API¶
В область настоящего документа входят программные интерфейсы BOX5-DIT-MGSN, применяемые в эксплуатационных контурах DEV, TEST и PROD. Описание является типовым: состав API-групп, форматы, правила авторизации и межсервисные границы едины для версии поставки, а адреса, количество серверов, TLS-терминация, таймауты, ретраи, лимиты и подключённые внешние источники задаются эксплуатационной конфигурацией конкретного контура.
| Область | Описание |
|---|---|
| Внешний вход | ui-nginx и ui-rest-to-gprc как единая точка публикации web UI, REST API, GraphQL, WebSocket, файловых и медиа-маршрутов. |
| Прикладные домены | statistics, severstal, data-storage, inference и extended-inference, реализующие авторизацию, камеры, события, отчёты, интеграции, медиа и видеоаналитику. |
| Асинхронный обмен | kafka-domain, технологический ASUTP Kafka-контур и технические очереди sandbox/Redis, используемые для событий, команд, статусов, audit и фоновых задач. |
| Хранилища | PostgreSQL, ClickHouse, Redis, MinIO/S3, DataTemporaryStorage и файловые каталоги compose-контура как внутренние интерфейсы данных. |
| Наблюдаемость | Prometheus/Loki, Docker logs и сервисные /metrics, где они предусмотрены реализацией. |
| Внешние системы | IP-камеры, VMS/CSVN, ПК-КОТ, АСУ ТП, Keycloak/OIDC, SMTP и согласованные внешние API получателей данных. |
Документ описывает API-группы, домены и сервисы проекта «BOX5-DIT-MGSN». Состав REST API сверяется с OpenAPI-приложением, а состав сервисов - с Приложением Г к ПД. Если конкретный контур отличается только количеством узлов или подключённых камер, API-контракты не считаются отличающимися.
Границы ответственности¶
Пользовательские и внешние API-вызовы проходят через gateway-слой. Внутренние
сервисы statistics, inference, severstal, data-storage и их
sidecar-компоненты не рассматриваются как самостоятельные публичные точки
входа, если это явно не указано в эксплуатационной конфигурации.
публикованная граница"] gateway["ui-rest-to-gprc
REST / GraphQL / WebSocket"] backend["Доменные сервисы
statistics / inference / severstal / data-storage"] infra["Хранилища и шина
PostgreSQL / Redis / MinIO / Kafka"] external --> edge --> gateway --> backend --> infra backend --> gateway --> edge --> external
Исходный Mermaid-код схемы: ПА-MER-001. Границы ответственности.
Чувствительная информация и контурные параметры не являются частью открытого API-контракта. В документации используются только имена сервисов, логические префиксы, форматы данных и плейсхолдеры. Не публикуются:
- JWT, refresh tokens, sync-key и постоянные токены;
- пароли БД, SMTP, OIDC, S3, Kafka и registry credentials;
- полные
.env-файлы, DSN и приватные адреса внешних систем; - необезличенные payload-ы с персональными или конфиденциальными данными;
- сведения, относящиеся только к внутренним контурам разработки поставщика.
Основные участники взаимодействия¶
| Участник | Используемые интерфейсы | Роль в обмене |
|---|---|---|
| Пользователь web UI | HTTP/HTTPS, REST, GraphQL, WebSocket, файловые маршруты | Работает с камерами, событиями, отчётами, ролями, сценариями и настройками через браузер. |
| Внешний API-клиент | Опубликованные REST endpoint-ы и файловые ссылки | Получает или передаёт данные по согласованным интеграционным сценариям. |
| IP-камера / VMS | RTSP, HTTP/VMS API, архивные файлы | Передаёт live-видео, preview, топологию камер или архивные видеозаписи. |
| Система заказчика | PostgreSQL read-only, HTTP/REST, Kafka/Avro, SMTP/OIDC в зависимости от интеграции | Предоставляет справочники, технологические сигналы, SSO, email-канал или принимает события и статусы. |
| Сервис BOX5-DIT-MGSN | HTTP/gRPC, REST, Kafka, S3, SQL, Redis | Выполняет доменную операцию, хранит состояние, публикует события или обрабатывает асинхронные сообщения. |
Требования к использованию API¶
При разработке и проверке API необходимо учитывать следующие общие правила:
| Правило | Описание |
|---|---|
| Единая точка входа | Клиенты должны обращаться к опубликованным маршрутам gateway, а не напрямую к контейнерам доменных сервисов. |
| Авторизация | Защищённые операции используют Bearer JWT или согласованный контурный механизм для сервисных сценариев. |
| Форматы данных | Основной формат REST API - JSON; файлы, отчёты, изображения и видео могут передаваться как multipart, бинарные ответы, S3/HTTP-ссылки или потоковые данные. |
| Версионирование | Версия API определяется версией поставки ПО, OpenAPI-спецификацией и зафиксированным составом сервисов. |
| Совместимость | Несовместимые изменения endpoint-а, метода, схемы, формата ошибки или авторизации требуют обновления OpenAPI-приложения и описания интерфейсов. |
| Проверяемость | После изменения API выполняются сборка документации, сверка OpenAPI и контрольные вызовы безопасных read-only операций в применимом контуре. |
Подробная структура программного обеспечения приведена в разделе 2, функции интерфейсов - в разделе 3, порядок поставки - в разделе 4, а полный перечень REST endpoint-ов - в OpenAPI-приложении.