Перейти к содержанию

Раздел 3. Структура записей (строк) в файлах

Раздел описывает структуру записей в реляционных и аналитических хранилищах BOX5-DIT-MGSN. Полный машинный перечень полей для 1029 PostgreSQL-таблиц эталонного состава и двух PostgreSQL views приведён в приложении; основной текст фиксирует классы записей, типовые поля, типы данных и ограничения, которые важны для проектирования интеграций, резервного копирования и восстановления.

Описание не включает значения прикладных данных, пароли, токены, DSN и другие чувствительные параметры эксплуатационного контура.

3.1. Состав полей

В PostgreSQL-схемах BOX5-DIT-MGSN повторяются несколько устойчивых классов полей:

Класс полей Типовые поля Назначение
Техническая идентификация id, uuid, guid, message_uuid, file_id, report_uuid Первичные и логические идентификаторы записей, внешних событий и файлов.
Аудит времени created_at, updated_at, timestamp, start_time, end_time, *_ts_* Время создания, изменения, события, обработки или периода отчёта.
Состояния и флаги is_enabled, is_deleted, is_active, blocked, synchronized, confirmation_status, pk_kot_status Жизненный цикл сущности, soft-delete, статусы подтверждения и синхронизации.
Связи *_id, *_uuid, связующие таблицы вида *_camera_*, *_category_* Внешние ключи внутри одной БД и логические ссылки между сервисными БД.
Настройки и расширения etc_params, extended_params, flags, roles, ad_groups, llm_response JSON/текстовые расширения, параметры интеграций и модельные ответы.
Файлы и медиа file, preview, image, video_file, report_path, name_on_disk, storage_size Ссылки на MinIO или bind-mounted каталоги; сами бинарные объекты обычно лежат вне PostgreSQL.
Геометрия и зоны polygon, coords, bbox_*, min_x, min_y, max_x, max_y, zone Координаты камер, зон и bbox-объектов детекции.

Ключевые записи, которые образуют предметное ядро BOX5-DIT-MGSN:

Хранилище и таблица Основные поля записи Комментарий
st-auth.user id, guid, username, password, email, firstname, surname, blocked, roles, type, uuid, last_activity Пользователь. Значение password в документацию не выгружается; фиксируется только наличие поля схемы.
st-access.privilege id, user_id, object_type, object_id, access_type, simple, access_source_id Плоский пересобираемый кэш прав доступа пользователя к объектам.
st-camera-storage.object_observation id, name, uuid, image, has_children, has_cameras, o_type, synchronized, map_image Объект наблюдения и узел объектного дерева.
st-camera-storage.camera id, name, is_enabled, media_uri, camera_type, object_observation_id, uuid, protobuf_bytes, protobuf_bytes_hash_md5, flags Каноническая запись камеры; protobuf_bytes используется downstream-сервисами для быстрой синхронизации runtime-конфигурации.
st-camera-storage.zone id, polygon, color_hex, zone_config_id, camera_id, model_id, group_id, title Зона камеры для правил инференса и сценариев.
st-event-storage.event id, camera_id, message_uuid, timestamp, confirmation_status, image_id, model_id, video_file, etc_params, group_uuid, llm_response, pk_kot_status, addition_fields Основная запись события/нарушения. camera_id является логической ссылкой на камеру; медиа хранится отдельно.
st-event-storage.image id, width, height, file, preview, is_deleted, quality, storage_size Метаданные изображения события и ссылки на объектное/файловое хранилище.
st-event-storage.primaryobject id, person_id, score, zone, bbox_id, crop_id, event_id, person_violator_id, primary_category_id, vis_crop_id, camera_storage_zone_id Первичный объект детекции внутри события.
st-event-storage.secondaryobject id, score, message, bbox_id, primary_object_id, secondary_category_id Вторичный объект/категория, связанная с первичным объектом.
st-event-storage.severstal_event_datas id, event_kind_id, event_kind_section_id, risk_work_area_id, risk_danger_id, technical_barrier_id, violation_event_id, violation_nature, basic_rule_id, description Отраслевая классификация события для BOX5-DIT-MGSN/ДИТ-МГСН и ПК-КОТ.
st-virt-cam-video-upload.videofile file_id, original_name, name_on_disk, upload_name, is_ready, video_state, duration_seconds Загруженный видеофайл для виртуальных камер.
svr-postgres-pk-kot.* Id/Guid-подобные поля, наименования, статусы, классификаторы, связи справочников Внешняя БД заказчика. Большинство таблиц не объявляет PK/FK на уровне PostgreSQL, поэтому связи используются как прикладной контракт интеграции.

Для ClickHouse основная запись чаще является денормализованной строкой факта: событие, состояние камеры или агрегированный интервал. Примеры:

ClickHouse-таблица Основные поля записи Назначение
st-event-storage-clickhouse.event event_id, message_uuid, timestamp, camera_id, pr_obj_*, pr_obj_sec_obj_*, svr_*, pk_kot_status Денормализованная поисковая строка события с объектами, категориями и отраслевой классификацией.
st-event-statistic-clickhouse.event event_id, timestamp, confirmation_status, cam_*, obj_*, pr_obj_* Строка статистики событий для UI, фильтров и отчётов.
st-ex-statistics-clickhouse.stay_zone_event event_uuid, timestamp_start, timestamp_end, time_duration_sec, cam_*, obj_*, zone, primary_category_*, secondary_category_* Событие пребывания в зоне для EX-статистики.

3.2. Типы данных

В PostgreSQL-схемах эталонного состава используются следующие типовые категории данных:

Тип PostgreSQL Где используется
integer Суррогатные ключи, внешние ключи, статусы и счётчики.
boolean Флаги активности, удаления, синхронизации, готовности и настроек.
timestamp without time zone Даты внешней БД ПК-КОТ и части сервисных таблиц.
character varying(N) Имена, статусы, URI, идентификаторы и коды; наиболее частые размеры: 20, 36, 64, 255, 512, 1024, 2048, 4096.
timestamp with time zone Сервисные created_at, updated_at, время событий и отчётных периодов.
jsonb Расширяемые настройки, фильтры, списки категорий, LLM-ответы, роли и flags.
bigint Размеры файлов, timestamp-подобные значения, крупные идентификаторы.
text Длинные JSON/text-поля, пути к файлам, описания и параметры.
smallint Enum-подобные статусы, типы камер, темы UI, типы событий.
double precision / numeric Координаты, температуры, score, скорости, интервалы и числовые справочники.
uuid Логические идентификаторы объектов, событий, групп и треков.
bytea Бинарные runtime-представления, например protobuf_bytes, и отдельные изображения профиля.

В ClickHouse используются типы, оптимизированные под аналитическое чтение: Int64/UInt64 для идентификаторов, DateTime для временной оси, Float32/Float64 для score и координат, String для JSON/URI/текстов и LowCardinality(String) для категорий, статусов и имён, которые часто повторяются в выборках.

3.3. Размеры и ограничения

Ограничения проверены по pg_constraint:

Тип ограничения Что означает для данных
Primary key Большинство сервисных таблиц имеет суррогатный id; часть справочников использует собственные ключи (param_id, measure_id, status_id, file_id).
Foreign key Ссылочная целостность в основном обеспечивается внутри одной сервисной БД; межсервисные ссылки часто логические и передаются через Kafka/API.
Unique Уникальные логины, GUID/UPN пользователей, одно-к-одному связи и отдельные бизнес-идентификаторы.

Типовые ограничения и размеры:

  • NOT NULL применяется к основным идентификаторам, статусам, флагам и обязательным ссылкам внутри сервисной БД.
  • DEFAULT CURRENT_TIMESTAMP используется для created_at и updated_at; DEFAULT false/true — для большинства флагов; sequence-default вида nextval(..._seq) — для integer/bigint ключей.
  • varchar(20) используется для коротких статусов и автомобильных признаков, varchar(36) — для UUID-строк отчётов, varchar(64) — для message_uuid и версий, varchar(255) — для имён, логинов, email и коротких URI, varchar(512+) — для описаний и длинных путей.
  • Большие и вариативные структуры не нормализуются в отдельные таблицы, если являются расширениями сценария или интеграции: для них используются jsonb или text.
  • Таблицы-связки N:M часто состоят только из двух внешних ключей и не имеют отдельного primary key. Это осознанный паттерн для связей камер, тегов, категорий, зон и расписаний.
  • В БД ПК-КОТ большинство пользовательских таблиц не содержит явных PK/FK на уровне PostgreSQL. Для BOX5-DIT-MGSN эти таблицы рассматриваются как внешний источник, а не как внутренняя нормализованная схема.