Initial commit

architectory/arch-00-glossary.md

@@ -0,0 +1,123 @@
+# 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`](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 |