han-app/architectory/arch-00-glossary.md

arch-00. Глоссарий и единый словарь терминов

Назначение

Канонические имена сущностей, полей, идентификаторов, enum-значений, бакетов S3, env-переменных и терминов проекта.

При расхождении имён приоритет у настоящего словаря.

Bucket Selectel S3

Логическое имя	env-переменная	Пример физического бакета
S3-quarantine	SELECTEL_S3_BUCKET_QUARANTINE	han-chat-quarantine
S3-data (attachments)	SELECTEL_S3_BUCKET_ATTACHMENTS	han-chat-attachments
S3-data (documents)	SELECTEL_S3_BUCKET_DOCUMENTS	han-chat-documents

В тексте: S3-quarantine — временное хранилище до вердикта Message Safety; S3-data — проверенные файлы (attachments и documents — два физических бакета).

Сущности App DB (основные)

Имя	Схема	Назначение (кратко)
UserIdentity	han_app	Локальный пользователь, связь с Keycloak
UxSession	han_app	Аналитическая UX-сессия (период активности пользователя)
UserConsent	han_app	Запись о принятии согласий (до OTP)
ClientProfile	han_app	Кэш профиля для UI
Dialog	han_app	Диалог клиента с Open Lines
Message	han_app	Сообщение в диалоге
MessageAttachment	han_app	Вложение к сообщению
sync_queue	han_app	Очередь sync App → Bitrix24
entity_external_mapping	han_app	Маппинг App entity ↔ Bitrix entity
app_settings	han_app	Бизнес-настройки
text_resources	han_app	Тексты UI по мнемоникам
popular_questions	han_app	Популярные вопросы главного экрана
dialog_sessions	bitrix_local	Маппинг чата Open Lines

Идентификаторы

Имя	Где используется
dialog_id	UUID диалога в приложении; равен external_chat_id в Open Lines
external_chat_id	Идентификатор чата для bitrix-local-app / imconnector
keycloak_sub	Subject JWT Keycloak; ключ UserIdentity
guest_session_id	UUID гостевой сессии до OTP
ux_session_id	UUID аналитической UX-сессии; заголовок X-Ux-Session-Id
bitrix_contact_id	ID Contact в Bitrix24 CRM
bitrix_chat_id	ID чата Open Lines в Bitrix24
session_id	ID сессии Open Lines (поле dialog_sessions; не путать с ux_session_id)
task_id	ID async-проверки Message Safety
request_id	Корреляция HTTP-запроса (заголовок X-Request-ID)

Публичные id сущностей — UUID.

UxSession (аналитическая UX-сессия)

Определение

UxSession — период непрерывной активности пользователя в приложении (web / iOS / Android) для аналитики и сквозной корреляции логов и событий.

• Идентификатор периода — ux_session_id (UUID).
• Начало периода фиксируется событием session_start (ровно один раз на период).
• Запись создаётся в App DB при POST /api/v1/analytics/session-start (см. arch-02).
• Frontend передаёт X-Ux-Session-Id во всех запросах к backend, пока сессия активна.

UxSession не является механизмом авторизации. Отсутствие или неизвестный ux_session_id не блокирует API (кроме endpoint, где id обязателен по контракту, напр. POST /api/v1/consents).

Когда начинается новая UxSession

Новый ux_session_id + событие session_start — только если:

1. first_launch — приложение открыто, в памяти нет ux_session_id.
2. cold_start — после kill app или закрытия вкладки браузера (память очищена).
3. idle_timeout — возврат спустя более N минут (ux.session.idle_timeout_minutes в app_settings, default 30).

Когда та же UxSession продолжается

• возврат из фона в пределах idle timeout (напр. через 5 минут — без нового session_start);
• успешный OTP или refresh access token;
• навигация между экранами внутри приложения.

Message — enum и поля

Имя	Допустимые значения
Message.sender_type	client, company
Message.safety_status	pending, allowed, blocked (needs_review — зарезервирован, MVP не используется)
Message.text	текст сообщения; пустая строка для файлового сообщения
content_kind (логическое)	text, file — тип исходящего сообщения клиента (MVP)

Семантика allow / deny / pending в message-safety и HTTP-коды — arch-02-api-contracts.md.

MessageAttachment.scan_status

Значение	Смысл
pending	Файл в S3-quarantine, проверка не завершена
clean	Проверка завершена, allow
infected	Проверка завершена, deny
failed	Ошибка инфраструктуры проверки

Мнемоники internal API

Префикс: /internal/{service_mnemonic}/v1/. Health: /health/*.

{service_mnemonic}	Сервис
safety	message-safety
openlines	bitrix-local-app, приёмник inbox на api-backend
sync	bitrix-sync

Bitrix24 Open Lines

Имя	Значение
BITRIX_CONNECTOR_ID / connector	han_mobile_app
BITRIX_OPEN_LINE_ID	8
Канонический URL коннектора	https://han0107.bitrix24.ru/contact_center/connector/?ID=han_mobile_app&LINE=8

Термины чата

Термин	Message.sender_type / направление
клиент	client; исходящее сообщение
оператор	company; входящее сообщение
сообщение пользователя	исходящее; проверяет Message Safety