Grok version

2026-07-09 12:39:52 +03:00
parent ea8bb6181a
commit 8835677860
7 changed files with 353 additions and 155 deletions
@@ -22,12 +22,13 @@
 |---|---|---|
 | `UserIdentity` | `han_app` | Локальный пользователь, связь с Keycloak |
 | `UxSession` | `han_app` | Аналитическая UX-сессия (период активности пользователя) |
-| `UserConsent` | `han_app` | Запись о принятии согласий (до OTP) |
+| `UserConsent` | `han_app` | Запись о принятии согласий (после OTP, привязка к `user_id`) |
 | `ClientProfile` | `han_app` | Кэш профиля для UI |
 | `Dialog` | `han_app` | Диалог клиента с Open Lines |
 | `Message` | `han_app` | Сообщение в диалоге |
 | `MessageAttachment` | `han_app` | Вложение к сообщению |
 | `sync_queue` | `han_app` | Очередь sync App → Bitrix24 |
+| `safety_tasks` | `han_app` | Checkpoint sync-wait Message Safety (`task_id`) для recovery |
 | `entity_external_mapping` | `han_app` | Маппинг App entity ↔ Bitrix entity |
 | `app_settings` | `han_app` | Бизнес-настройки |
 | `text_resources` | `han_app` | Тексты UI по мнемоникам |
@@ -40,8 +41,9 @@
 |---|---|
 | `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 |
+| `keycloak_sub` | Subject JWT Keycloak (`sub`); ключ `UserIdentity` |
+| `phone_number` | Auth-телефон пользователя; master — Keycloak; в App DB пишется из JWT claims при `bootstrap`, не из body клиента |
+| `guest_session_id` | Опциональный локальный UUID на устройстве (UI); **не** auth и **не** открывает write API |
 | `ux_session_id` | UUID **аналитической UX-сессии**; заголовок `X-Ux-Session-Id` |
 | `bitrix_contact_id` | ID Contact в Bitrix24 CRM |
 | `bitrix_chat_id` | ID чата Open Lines в Bitrix24 |
@@ -60,10 +62,10 @@

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

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

 ### Когда начинается **новая** `UxSession`
 Новый **`ux_session_id`** + событие **`session_start`** — **только** если:
@@ -76,17 +78,41 @@
 - успешный OTP или refresh access token;
 - навигация между экранами внутри приложения.

+## `Dialog.status`
+
+| Значение | Смысл |
+|---|---|
+| `open` | Диалог создан, сообщений ещё нет (сразу после `POST /dialogs`) |
+| `waiting_for_company` | Последнее значимое событие — исходящее от клиента; ждём оператора |
+| `waiting_for_client` | Последнее значимое событие — входящее от оператора; ждём клиента |
+| `closed` | Диалог закрыт в Open Lines (`dialog.closed` / `ONIMCONNECTORDIALOGFINISH`) |
+
+Переходы задаёт `api-backend` (см. arch-01, потоки чата). Значения — **строковые enum** в API и App DB (не sequence-справочник).
+
 ## `Message` — enum и поля

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

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

+### `Message.delivery_status` (смысл)
+
+| Значение | Когда |
+|---|---|
+| `accepted` | Сообщение принято API, safety ещё не завершена или только начата |
+| `processing` | Внутренний/transient на время sync-wait safety; клиенту на `POST .../messages` не отдаётся как финальный ответ |
+| `delivered` | Финальный `allow`, сообщение ушло в Open Lines (или входящее от оператора сохранено) |
+| `rejected` | Финальный `deny` от Message Safety |
+| `failed` | Инфраструктурная ошибка доставки (Bitrix/S3), не safety-deny |
+
+Realtime-событие `message.status` передаёт актуальные `safety_status` и/или `delivery_status`.
+
 ## `MessageAttachment.scan_status`

 | Значение | Смысл |
@@ -96,6 +122,11 @@
 | `infected` | Проверка завершена, deny |
 | `failed` | Ошибка инфраструктуры проверки |

+## Строковые enum vs справочники
+
+- **Строковые enum** (значения в API/контрактах): `Dialog.status`, `Message.sender_type`, `Message.safety_status`, `Message.delivery_status`, `MessageAttachment.scan_status`, `content_kind`, `start_reason`.
+- **Справочники (sequence ID)** — для больших/изменяемых списков UI и доменных классификаторов (типы документов post-MVP, причины и т.п.); правило — [`arch-05-agent-development-process.md`](arch-05-agent-development-process.md).
+
 ## Мнемоники internal API

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