han-app/architectory/arch-01-system-architecture.md

arch-01. Общая архитектура системы

Термины — в arch-00-glossary.md. Приоритет документов — в README.md.

Назначение

HAN Chat - приложение для мигрантов, где стартовый экран знакомит клиента с сервисом и предлагает задать вопрос. Авторизация не требуется при первом входе: она запрашивается при попытке отправить первое сообщение, потому что в переписке могут обрабатываться персональные данные.

Зафиксированные решения MVP

• Авторизация: только OTP по номеру телефона (email-канал в MVP не используется).
• Вторая сторона чата: Битрикс24 Open Lines.
• Master source auth-данных: Keycloak; профиль в UI — кэш App DB с двусторонней sync через bitrix-sync.
• Диалог приложения соответствует диалогу в Битрикс24 Open Lines.
• Лиды и сделки в MVP не используются.
• Файлы production-хранилища: Selectel S3, бакет S3-data (логическое имя; физически два бакета — han-chat-attachments для файлов чата и han-chat-documents для документов компании).
• Файлы до проверки: Selectel S3, бакет S3-quarantine; после 200 allow — перенос в S3-data (attachments). Имена бакетов — arch-00-glossary.md; права доступа — ниже и в «Принципы безопасности».
• Мультиязычность в первом релизе не нужна, но тексты должны храниться по мнемоникам для будущих переводов.
• Среда на первом этапе одна и проектируется как боевая.
• Вложения чата MVP: только изображения и PDF — см. arch-04-settings-and-content.md, «Разрешённые типы файлов чата».
• SMS OTP на старте: заглушка — пользователь вводит фиксированный код из .env (KEYCLOAK_OTP_MOCK_CODE); SMS не отправляется. Интеграция с SMS-провайдерами — в бэклоге (см. !Backlog.md).
• Популярный вопрос при выборе автоматически отправляется как сообщение; если пользователь не авторизован — сначала согласия и OTP, затем отправка.
• Перечень таблиц и миграций App DB проектирует модуль database (и владельцы схем других сервисов); arch фиксирует только разделение схем PostgreSQL и контракты между сервисами.

Пользовательские сценарии

1. Клиент открывает мобильное или web-приложение и видит главный экран с приветствием, популярными вопросами и полем ввода.
2. Frontend определяет, нужна ли новая UX-сессия, и при необходимости отправляет событие session_start (см. «Аналитическая UX-сессия»). Клиент может изучить сервис без авторизации.
3. Если у клиента сохранён действующий refresh token, frontend выполняет silent refresh без OTP (см. «Поток возврата пользователя»).
4. Клиент нажимает популярный вопрос — frontend подставляет текст вопроса и инициирует отправку сообщения (тот же поток, что ручной ввод). Либо клиент вводит свой текст и отправляет.
5. Если клиент не авторизован, перед отправкой первого сообщения frontend показывает pop-up с согласиями и запускает OTP (см. «Поток авторизации»).
6. После успешной авторизации api-backend создаёт или находит локального пользователя по keycloak_sub, связывает ранее сохранённые согласия с guest_session_id, создаёт или обновляет профиль; триггер App DB ставит задачу в sync_queue для bitrix-sync.
7. api-backend выполняет find-or-create диалога (см. «Создание диалога») и отправляет сообщение (текст популярного вопроса или введённый клиентом).
8. Сообщение клиента проходит Message Safety и через Bitrix24 Local App направляется в Битрикс24 Open Lines.
9. Ответ оператора из Битрикс24 Open Lines поступает через Bitrix24 Local App в api-backend и отображается в чате приложения.
10. Клиент может открыть историю диалогов.
11. Клиент может открыть профиль, где данные структурированы блоками: «Личные данные» и «Документы». В дальнейшем могут добавляться новые блоки.
12. Редактирование профиля из профиля недоступно. Для изменения данных клиент переходит в чат и пишет запрос оператору.

Компоненты верхнего уровня

• Expo App: единая frontend-кодовая база для iOS, Android и web.
• Keycloak: identity provider, OTP-only авторизация по номеру телефона.
• api-backend: Python-приложение с REST API, realtime-доставкой сообщений и бизнес-логикой.
• Nginx Reverse Proxy: единая публичная точка входа, HTTPS termination и маршрутизация на Keycloak/API/frontend web/Bitrix24.
• Message Safety Service: отдельный сервис проверки входящих сообщений; синхронный вызов из API → 200 allow | 403 deny | 203 pending + task_id.
• Bitrix24 Local App: локальное приложение, custom connector han_mobile_app для Bitrix24 Open Lines: чат, OAuth, webhook-события, маппинг dialog_id ↔ bitrix_chat_id.
• Bitrix24 sync service: двусторонняя синхронизация App DB ↔ Битрикс24 CRM (Contact на MVP; маппинг ID, очередь через триггеры, webhook от роботов Bitrix24).
• Managed PostgreSQL (приватная сеть, одна база): схемы han_app, bitrix_sync, bitrix_local, keycloak, message_safety — отдельный DB-user на схему.
• Redis: rate limits, временные счетчики OTP и realtime/service coordination.
• S3-data: production-хранилище проверенных файлов чата (han-chat-attachments) и документов компании (han-chat-documents).
• S3-quarantine: временное хранилище загруженных файлов до вердикта Message Safety Service (han-chat-quarantine); read-only для message-safety.
• observability: JSON-логи в stdout, request_id, trace_id, ux_session_id (если передан), базовая трассировка через OpenTelemetry Collector.

Инфраструктура развёртывания (зафиксировано)

На первом этапе весь backend-контур работает на одной VM в облаке провайдера:

• nginx, api-backend, message-safety, keycloak, bitrix-sync, bitrix-local-app, redis, otel-collector — в Docker Compose на VM;
• публичный доступ из интернета только через nginx (порты 80/443);
• внутренние сервисы общаются по Docker-сети на localhost VM.

Базы данных — managed PostgreSQL того же провайдера в том же облачном кластере/VPC, без публичного доступа из интернета. VM подключается к БД только по приватной сети.

Схема данных в managed PostgreSQL (перечень таблиц внутри схем — в модульных спецификациях, не в arch-*):

База / схема	Сервисы	Назначение схемы
одна база / han_app	api-backend, bitrix-sync (ограниченный GRANT)	прикладные данные приложения, очередь sync, audit
одна база / bitrix_sync	bitrix-sync	worker state, retry/dead letter, sync audit
одна база / message_safety	message-safety	verdict cache, safety_task, rule config
одна база / bitrix_local	bitrix-local-app	OAuth, inbox, dialog_sessions
одна база / keycloak	Keycloak	учётные записи, realm, сессии IdP

Redis на первом этапе остаётся на VM в Docker (ephemeral/coordination). Selectel S3 — внешнее object storage: три бакета (han-chat-quarantine, han-chat-attachments, han-chat-documents); см. arch-00-glossary.md.

Контекстная схема

flowchart LR
    Client[Expo Mobile/Web App]
    Nginx[Nginx Reverse Proxy]
    Keycloak[Keycloak OTP]
    API[Python api-backend]
    Safety[Message Safety Service]
    DB[(PostgreSQL)]
    Redis[(Redis)]
    Sync[Bitrix24 sync service]
    LocalApp[Bitrix24 Local App]
    Bitrix[Bitrix24 CRM]
    S3Data[(S3-data: attachments + documents)]
    S3Q[(S3-quarantine)]
    Obs[observability]

    Client -->|HTTPS REST + Realtime| Nginx
    Nginx -->|/auth| Keycloak
    Nginx -->|/api + /realtime| API
    Keycloak --> DB
    API --> DB
    API --> Redis
    API -->|upload / move / delete| S3Q
    API -->|promote delivered files| S3Data
    API -->|internal check message| Safety
    Safety --> DB
    Safety --> Redis
    Safety -->|read scan| S3Q
    API -->|send messages| LocalApp
    API -->|App DB writes| DB
    Sync -->|sync_queue + profile| DB
    Sync -->|CRM Contact REST| Bitrix
    Bitrix -->|robot webhook| Sync
    Bitrix -->|ONIMCONNECTOR*| LocalApp
    LocalApp -->|imconnector.send.messages/status| Bitrix
    LocalApp -->|normalized inbox events| API
    API -->|WebSocket/SSE or polling fallback| Client
    API --> Obs
    Safety --> Obs
    Sync --> Obs
    LocalApp --> Obs
    LocalApp --> DB

Архитектурные границы

Frontend

Отвечает за:

• стартовый экран с приветствием, популярными вопросами, полем ввода, историей и профилем;
• гостевой режим до первого сообщения;
• показ pop-up с обязательными согласиями на обработку персональных данных и пользовательское соглашение, а также необязательным согласием на рекламные коммуникации;
• сбор данных устройства для передачи в backend;
• управление аналитической UX-сессией на клиенте: определение начала нового периода активности, хранение ux_session_id и last_activity_at только в памяти, отправка session_start, заголовок X-Ux-Session-Id во всех запросах;
• хранение access token и refresh token в безопасном хранилище после авторизации;
• жизненный цикл access token: проактивное обновление по расписанию (до истечения exp) и обработка 401 от api-backend (см. «Обновление access token (frontend)»);
• при открытии приложения: проверку refresh token → silent refresh через Keycloak или OTP-flow при истечении refresh token;
• отображение входящих сообщений от оператора;
• загрузку файлов в чат через backend;
• работу с текстовыми мнемониками;
• отправку traceparent/correlation id в backend.

Frontend не должен:

• хранить бизнес-логику синхронизации с Битрикс24;
• принимать решения о доступе к чужим документам или диалогам;
• обращаться напрямую к Битрикс24, Selectel S3 или базе данных.

api-backend

Отвечает за:

• публичные настройки приложения для frontend;
• проверку JWT от Keycloak для защищенных операций; при истёкшем или невалидном access token — 401 (refresh выполняет frontend, не backend);
• локальную регистрацию пользователя приложения: find-or-create UserIdentity по keycloak_sub, создание минимального ClientProfile для нового пользователя, обновление last_login_at для существующего (после OTP — см. POST /api/v1/auth/bootstrap);
• приём события session_start: запись UxSession, audit/analytics-событие; не используется для контроля доступа;
• валидация данных получаемых от frontend (соответствие типов данных, проверка обязательности полей, проверка формата данных, диапазоны значений, размер полей) через Pydantic
• хранение согласий пользователя в App DB (guest_session_id, ux_session_id, client_ip, версии документов);
• профиль, структурированный блоками;
• API чата, истории, файлов и документов;
• realtime-доставку входящих сообщений клиенту;
• отправку сообщений клиента в Open Lines через Bitrix24 Local App;
• прием нормализованных входящих событий Open Lines от Bitrix24 Local App;
• хранение истории диалогов;
• запись данных профиля в App DB (синхронизация с Bitrix24 — триггеры → sync_queue → bitrix-sync, без участия api-backend);
• загрузку файлов из чата в S3-quarantine до проверки;
• синхронный вызов Message Safety Service (POST /internal/safety/v1/messages/check) и интерпретацию ответа: 200 allow, 403 deny, 203 pending + task_id;
• при 200: перенос файлов quarantine → S3-data, сохранение сообщения, отправка в Bitrix24;
• при 403: удаление файлов из quarantine, безопасный ответ клиенту;
• при 203: сохранение сообщения со статусом ожидания проверки, ответ клиенту «обрабатывается», опрос GET /internal/safety/v1/messages/tasks/{task_id} и доставка цепочки после финального 200 или cleanup после 403;
• auth-aware rate limits для сообщений, пользовательских и сервисных операций;
• аудит пользовательских действий;
• единые ошибки и валидацию входных данных.

Bitrix24 Local App

Отвечает за Open Lines (чат):

• регистрацию локального приложения Bitrix24;
• OAuth lifecycle Bitrix24 и хранение токенов портала;
• регистрацию и активацию custom connector han_mobile_app для открытой линии 8;
• прием публичных событий Bitrix24 ONIMCONNECTOR* на /bitrix/handler;
• нормализацию событий Open Lines в доменные события HAN;
• хранение dialog_sessions: связка external_chat_id (=dialog_id приложения) ↔ bitrix_chat_id ↔ session_id;
• хранение локального inbox до готовности API;
• internal API для api-backend: POST /internal/openlines/v1/messages, GET /internal/openlines/v1/dialogs/{external_chat_id};
• forward нормализованных событий оператора в API (BITRIX_API_FORWARD_URL);
• вызовы imconnector.send.messages и imconnector.send.status.delivery.

Не отвечает за:

• CRM Contact mapping и синхронизацию прочих CRM-сущностей;
• сохранение сообщений и истории чата в App DB;
• realtime-доставку в Expo App;
• бизнес-логику профиля и документов.

Bitrix24 sync service

Отвечает за двустороннюю синхронизацию данных между App DB и Битрикс24 CRM:

• маппинг ID сущностей приложения ↔ Bitrix24 (bitrix_contact_id, entity_external_mapping);
• App DB → Bitrix24: обработка очереди sync_queue (триггеры App DB) — map/create Contact по телефону, push обновлений полей;
• Bitrix24 → App DB: приём webhook от роботов Bitrix24, обновление профиля с GUC han.sync_suppress;
• реестр синхронизируемых сущностей (MVP: Contact; post-MVP: Lead, Deal, Document);
• повторные попытки, rate limiting Bitrix REST, dead letter;
• прямой доступ к схеме han_app и собственной bitrix_sync.

Не отвечает за:

• hot path чата Open Lines;
• OAuth lifecycle локального приложения Bitrix24;
• создание UserIdentity / ClientProfile в auth-flow;
• хранение dialog_sessions.

Keycloak

Отвечает за:

• OTP-only регистрацию и вход;
• OTP по номеру телефона; проверка кода — в Keycloak (заглушка KEYCLOAK_OTP_MOCK_* или SMS-провайдер, см. arch-04 и «Поток авторизации»);
• хранение учетных записей;
• выдачу и обновление токенов;
• настройку realm, clients, roles, policies.

Парольная авторизация, magic link и социальные логины не входят в MVP.

Nginx Reverse Proxy

Отвечает за:

• прием внешнего HTTPS-трафика;
• TLS termination;
• редирект HTTP на HTTPS (на веб-домене; для выделенного API-домена HTTP не допускается — см. «Принципы безопасности»);
• маршрутизацию /api/* и /realtime/* в api-backend;
• маршрутизацию /auth/* или выделенного auth-домена в Keycloak;
• маршрутизацию публичных /bitrix/* endpoint в bitrix-local-app;
• маршрутизацию /bitrix/sync/* webhook endpoint в bitrix-sync;
• защиту internal endpoint bitrix-local-app через private network или nginx allowlist;
• отсутствие публичной маршрутизации к message-safety — сервис доступен только из внутренней Docker-сети;
• передачу X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host, X-Request-ID;
• базовые лимиты размера запроса и timeout;
• грубые edge rate limits по IP, route и зоне риска;
• TLS 1.2/1.3, HSTS, security headers и скрытие технологических заголовков;
• кэширование публичных endpoint настроек и контента;
• запрет доступа к внутренним сервисам и техническим портам извне.

Message Safety Service

Отвечает за:

• проверку входящих сообщений от пользователя (текст, ссылки, файлы);
• внутреннюю orchestration: синхронно текст и ссылки; при необходимости — async-проверка файлов;
• HTTP-контракт для api-backend:
  • 200 — синхронная проверка завершена, allow;
  • 403 — синхронная проверка завершена, deny;
  • 203 + task_id — нужна async-проверка (обычно файлы), сообщение в обработке;
• финальный вердикт async-задачи по GET /internal/safety/v1/messages/tasks/{task_id}: 200 allow | 403 deny | 203 pending;
• SHA-256 хеширование и lookup кэша вердиктов;
• отдельный pipeline проверки ссылок;
• запись verdict cache, safety_task и audit в схеме message_safety;
• internal API: POST /internal/safety/v1/messages/check, GET /internal/safety/v1/messages/tasks/{task_id}.

Не отвечает за:

• загрузку файлов клиентом, presigned URL, перемещение quarantine → S3-data, удаление из quarantine;
• сохранение сообщений, истории диалогов (CRM sync — зона bitrix-sync, не api-backend);
• доставку в Bitrix24 Open Lines и realtime клиенту;
• проверку JWT, согласий, edge rate limits;
• polling task_id на стороне клиента — только api-backend (фоновый worker или internal loop).

api-backend не решает, sync или async нужна проверка: это определяет Message Safety Service по результатам фазы текста/ссылок и кэша файлов.

Гостевая сессия (до JWT)

До OTP frontend работает в гостевом режиме с локально сгенерированным guest_session_id (UUID v4):

• создаётся при первом запуске приложения, хранится в secure storage устройства;
• передаётся в POST /api/v1/consents вместе с согласиями и device metadata;
• api-backend сохраняет согласия с привязкой к guest_session_id (TTL записи — 24 ч);
• после успешного OTP api-backend связывает записи согласий и device session с UserIdentity по keycloak_sub;
• guest_session_id не используется для доступа к защищённым ресурсам после выдачи JWT.

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

UX-сессия — период непрерывной активности пользователя в приложении для аналитики и сквозной трассировки. Это не сессия Keycloak, не refresh/access token и не механизм авторизации.

Роли компонентов

Frontend (источник истины по правилам сессии):

• хранит ux_session_id и last_activity_at только в памяти (не в localStorage/secure storage);
• при новой сессии вызывает POST /api/v1/analytics/session-start и сохраняет полученный ux_session_id;
• обновляет last_activity_at при пользовательской активности и при возврате из фона;
• при resume проверяет (now - last_activity_at) > idle_timeout → при превышении — новая сессия;
• передаёт X-Ux-Session-Id во всех запросах к backend (public и JWT).

api-backend:

1. принимает session_start, создаёт запись UxSession, возвращает ux_session_id;
2. пишет analytics/audit-событие session_start (без PII);
3. включает ux_session_id из заголовка в JSON-логи (если передан);
4. не блокирует запросы при отсутствии или неизвестном ux_session_id — это не auth.

request_id — один HTTP-запрос; ux_session_id — период UX-активности для аналитики и корреляции логов.

Поток возврата пользователя (без OTP)

1. Клиент открывает приложение (UX-сессия определяется по правилам выше, независимо от auth).
2. Frontend проверяет наличие refresh token в secure storage.
3. Если refresh token действителен — frontend запрашивает новый access token у Keycloak (Refresh Token Grant), OTP не показывается.
4. Frontend работает как авторизованный пользователь (история, профиль, чат).
5. Если refresh token отсутствует или истёк — клиент остаётся в гостевом режиме до сценария, требующего auth; при первом сообщении — «Поток авторизации» с OTP.

Обновление access token (frontend)

Пока refresh token действителен, frontend сам поддерживает актуальный access token — не полагаясь только на открытие приложения и не дожидаясь истечения refresh token (использует его для обновления access token заранее).

Проактивное обновление по расписанию

1. После получения tokens (OTP или refresh) frontend сохраняет access token, refresh token и момент истечения access token (exp из JWT или expires_in из ответа Keycloak).
2. Запускает таймер/scheduler: обновить access token до наступления exp (рекомендуемый запас — 60 с до exp; константа модуля frontend).
3. По срабатыванию таймера — Refresh Token Grant к Keycloak, сохранение новой пары tokens, перепланирование следующего обновления.
4. Single-flight: параллельные refresh-запросы не дублируются (один in-flight refresh, остальные ждут результат).
5. Успешный refresh access token не создаёт новую UX-сессию и не вызывает session_start.

Обработка 401 от api-backend

Если запрос с access token вернул 401 (токен уже истёк или отклонён):

1. HTTP-клиент frontend один раз инициирует Refresh Token Grant (если refresh ещё не выполняется — через тот же single-flight).
2. При успехе — подставляет новый access token и повторяет исходный запрос (без бесконечных retry).
3. При неудаче refresh (invalid_grant, истёк refresh token, ошибка Keycloak) — очищает tokens, переводит UI в гостевой режим; повторная авторизация — через OTP при следующем защищённом действии.
4. Запросы, пришедшие во время in-flight refresh, ставятся в очередь и выполняются после успешного обновления (или отклоняются при провале refresh).
5. Тот же принцип — для WebSocket /api/v1/realtime: при ошибке auth — refresh и переподключение с новым access token.

Разделение ответственности

Компонент	Поведение
Frontend	scheduler refresh, intercept 401, retry, single-flight, хранение tokens
Keycloak	выдача и ротация tokens (Refresh Token Grant)
api-backend	проверка JWT; при невалидном/expired access token — 401, refresh не выполняет

Создание диалога (MVP)

• Диалог создаётся лениво при первой отправке сообщения авторизованным клиентом.
• Frontend перед POST .../messages вызывает POST /api/v1/dialogs (idempotency key), получает dialog_id и использует его далее.
• Популярный вопрос: после auth тот же порядок — POST /dialogs → POST .../messages с текстом вопроса.
• dialog_id = external_chat_id для Open Lines (см. arch-00-glossary.md, «Идентификаторы»).
• При первой доставке в Bitrix24 bitrix-local-app создаёт запись dialog_sessions.

Поток авторизации (OTP)

Срабатывает, когда клиент ещё не имеет действующего refresh token (первый вход) или refresh token истёк. Если refresh token валиден — см. «Поток возврата пользователя».

1. Клиент находится в гостевом режиме (guest_session_id уже создан).
2. Клиент инициирует отправку сообщения (ручной ввод или популярный вопрос).
3. Frontend показывает pop-up с тремя согласиями.
4. Клиент обязан принять согласие на обработку персональных данных и пользовательское соглашение.
5. Клиент может опционально согласиться на рекламные коммуникации.
6. Если обязательные согласия не даны, отправка блокируется.
7. Frontend вызывает POST /api/v1/consents с guest_session_id, версиями документов, device metadata, IP/user agent (через backend).
8. Frontend запрашивает публичные настройки и показывает форму ввода номера телефона (единственный канал MVP).
9. Keycloak запускает OTP-flow по телефону: клиент вводит номер, инициируется «отправка» OTP (при заглушке SMS фактически не уходит — см. arch-04).
10. Лимиты OTP проверяются по app_settings (otp.phone.*).
11. Клиент вводит OTP и отправляет его в Keycloak.
12. Keycloak проверяет корректность введённого OTP:
    • при KEYCLOAK_OTP_MOCK_ENABLED=true (MVP и любой режим с включённой заглушкой): введённое значение должно совпадать с KEYCLOAK_OTP_MOCK_CODE из .env;
    • при KEYCLOAK_OTP_MOCK_ENABLED=false (после интеграции с SMS-провайдером, см. бэклог): введённое значение должно совпадать с одноразовым OTP, сгенерированным Keycloak и отправленным провайдером на телефон клиента (с учётом TTL и лимита попыток).
    • при неверном коде Keycloak возвращает ошибку; frontend не получает tokens, шаг 13 не выполняется.
13. При успешной проверке frontend получает tokens через OIDC Authorization Code Flow with PKCE.
14. Frontend вызывает POST /api/v1/auth/bootstrap с JWT и guest_session_id (см. arch-02).
15. api-backend выполняет find-or-create пользователя, связывает согласия с guest_session_id, при необходимости привязывает user_id к текущей UxSession по ux_session_id.
16. Триггер App DB ставит задачу contact.map_or_create в sync_queue; bitrix-sync асинхронно находит или создает Contact в Битрикс24. Авторизация не должна синхронно зависеть от ответа Битрикс24 CRM.
17. Frontend создаёт диалог и отправляет отложенное сообщение (см. «Создание диалога» и поток чата).

Поток работы с чатом: клиент -> Битрикс24

В MVP сообщение клиента — content_kind text или file, не оба (см. arch-02-api-contracts.md, «Формат исходящего сообщения»).

Текстовое сообщение:

1. Frontend вызывает POST /api/v1/dialogs (если dialog_id ещё нет), затем отправляет POST /api/v1/dialogs/{dialog_id}/messages с непустым text (без вложения).
2. Nginx и API применяют rate limits.
3. API синхронно вызывает Message Safety Service (POST /internal/safety/v1/messages/check) — шаги текст и ссылки.
4. Далее — общая ветка вердикта (п. 5–8 ниже).

Файловое сообщение:

1. Frontend инициализирует одно вложение (POST .../attachments/init), загружает файл; api-backend сохраняет его в S3-quarantine.
2. Frontend отправляет POST /api/v1/dialogs/{dialog_id}/messages с attachment_id и checksum (поле text пустое).
3. Nginx и API применяют rate limits.
4. API синхронно вызывает Message Safety Service — шаг проверки файла (текст и ссылки пропускаются, если text пуст).

Общая ветка вердикта (оба типа):

5. 403 deny: API удаляет quarantine (если был файл), возвращает клиенту безопасную ошибку; в Bitrix24 ничего не уходит.
6. 200 allow: API переносит файл в S3-data (если был), сохраняет сообщение, отправляет в Bitrix24, подтверждает клиенту (realtime/polling).
7. 203 pending + task_id: api-backend сохраняет сообщение со статусом ожидания проверки, отвечает клиенту, что сообщение обрабатывается; quarantine не трогает.
8. Фоновый процесс API опрашивает GET /internal/safety/v1/messages/tasks/{task_id}:
   • финальный 200 allow → S3-data, Bitrix24, статус «доставлено», realtime клиенту;
   • финальный 403 deny → удаление quarantine, статус «отклонено», уведомление клиенту;
   • 203 pending → повтор опроса с backoff.

Поток работы с чатом: Битрикс24 -> клиент

1. Оператор отвечает клиенту в Битрикс24 Open Lines.
2. Битрикс24 отправляет ONIMCONNECTOR* webhook/event в bitrix-local-app.
3. bitrix-local-app проверяет application_token, нормализует payload и сохраняет idempotent inbox.
4. bitrix-local-app обогащает событие данными из dialog_sessions и forward-ит в API, если BITRIX_API_FORWARD_URL включен.
5. api-backend находит локальный диалог по external_chat_id (= dialog_id, см. arch-00-glossary.md).
6. api-backend сохраняет входящее сообщение в App DB (sender_type=company), а файл — в Selectel S3 (documents) с metadata в App DB. По факту сообщения API обновляет Dialog.status: входящее от оператора → waiting_for_client, исходящее от клиента → waiting_for_company.
7. bitrix-local-app подтверждает доставку в Bitrix24 через imconnector.send.status.delivery.
8. api-backend публикует событие для frontend через WebSocket/SSE. Если realtime недоступен, frontend получает сообщение через polling GET /api/v1/dialogs/{dialog_id}/messages?after=....
9. Frontend отображает сообщение оператора в чате.
10. При получении от bitrix-local-app доменного события dialog.closed (Bitrix24 ONIMCONNECTORDIALOGFINISH) API переводит Dialog.status в closed.

Документы компании (post-MVP)

Доставка документов из Bitrix24 в приложение не входит в MVP — см. !Backlog.md, п. 9.

В MVP блок профиля «Документы» и API GET /api/v1/me/documents зарезервированы; список может быть пустым. Контракт endpoint — в arch-02-api-contracts.md.

Профиль клиента

Профиль должен быть блочным.

Блок "Личные данные":

• ФИО;
• гражданство;
• номер телефона в РФ;
• зарубежный номер телефона;
• email.

Блок "Документы":

• перечень документов, отправленных клиенту компанией (в MVP — пустой до реализации бэклога);
• дата отправки;
• наименование документа;
• возможность скачать документ (после реализации доставки).

Редактирование данных профиля недоступно.

Sync профиля и master для PII

App DB — локальный кэш для UI. Двусторонний sync — bitrix-sync (имена полей — arch-00-glossary.md):

• Auth-телефон: master — Keycloak (UserIdentity.phone_number); изменения могут инициировать contact.update через триггеры.
• Поля профиля для UI: master — последнее успешно синхронизированное значение; основной входящий поток на MVP — правки сотрудником в Bitrix24 (webhook → App DB).
• App → Bitrix: триггеры han_app → sync_queue (contact.update).
• Bitrix → App: webhook робота → bitrix-sync; запись с GUC han.sync_suppress (без эхо в очередь).
• Конфликт: побеждает более позднее событие (updated_at, audit в bitrix_sync).

Аудит скачиваний

При выдаче presigned URL на скачивание (GET .../download-url, вложения чата) api-backend пишет audit-событие в App DB:

Поле	Значение
event_type	attachment.download_url_issued / document.download_url_issued
user_id	текущий пользователь из JWT
resource_type	attachment / document
resource_id	UUID сущности
ux_session_id	из заголовка X-Ux-Session-Id
request_id	из заголовка запроса
ip, user_agent	из proxy headers

В audit не сохраняются presigned URL, содержимое файлов и PII. Формат таблицы — в модуле database.

Realtime (кратко)

Детальный контракт — arch-02-api-contracts.md, раздел «Realtime».

• Transport: WebSocket WS /api/v1/realtime (JWT).
• Fallback: polling GET /api/v1/dialogs/{dialog_id}/messages?after=....
• События: новое сообщение, смена статуса сообщения/диалога.

Принципы безопасности

• Все защищенные пользовательские API требуют валидный JWT.
• Гостевые API доступны только для публичных настроек и стартового контента.
• Все внешние пользовательские соединения работают через HTTPS.
• HTTP допускается только для веб-домена как вход для редиректа на HTTPS. Для api домена HTTP не допускается.
• TLS завершается на reverse proxy; внутренний HTTP между контейнерами допускается только в закрытой backend-сети.
• TLS 1.0/1.1 и слабые шифры запрещены.
• HSTS обязателен после проверки домена и сертификата.
• INPUT-validation на api-backend
• использовать только Параметризованные SQL-запросы
• обязательное Экранирование вывода
• настройка CORS только на разрешенные домены (указать в .env)
• настройка Secure Headers (CSP, X-Frame-Options и др.)
• Доступ к профилю, диалогам, сообщениям, файлам и документам ограничен текущим user_id.
• Все запросы, содержащие в себе ссылку на сущность, которая относится к конкретному пользователю (ИД продукта, услуги, чата, документа и тп), проверяются backend_api на соответствие тому пользователю, от которого пришел запрос.
• Все публичные id создаются в формате UUID.
• Сервисные API защищаются внутренней сетью Docker/VPC плюс service token (перечень переменных — arch-04-settings-and-content.md, «Service tokens (internal API)»).
• Rate limits применяются минимум на двух уровнях: edge-лимиты в nginx и пользовательские лимиты в API с состоянием в Redis.
• Входящие сообщения пользователя: синхронный POST /internal/safety/v1/messages/check → 200 | 403 | 203; при 203 API опрашивает task_id до финального вердикта.
• Файлы пользователя до финального allow только в S3-quarantine; в S3-data — после 200 allow.
• Клиент не пишет напрямую в S3; загрузка только через api-backend.
• message-safety — read-only к S3-quarantine, без прав записи в бакеты.
• Все изменяемые параметры, телефоны, лимиты, mime types и флаги хранятся в настройках (arch-04-settings-and-content.md).
• PII-данные не пишутся в логи в открытом виде.
• Документы и файлы чата должны иметь контроль доступа и аудит скачиваний.

Backend-репозиторий и инфраструктура

Состав backend-контура

Минимальный production-like контур на одной VM: nginx, api-backend, message-safety, keycloak, bitrix-sync, bitrix-local-app, redis, otel-collector. Managed PostgreSQL и Selectel S3 находятся вне Docker Compose.

Предлагаемая структура backend-репозитория

backend/
  docker-compose.yml                 # корневой compose: nginx + include сервисов + networks/volumes
  .env.example
  nginx/
    docker-compose.yml
    nginx.conf
    conf.d/
    certs/
      .gitkeep
  api-backend/
    app/
    docker-compose.yml
    tests/
    pyproject.toml
    Dockerfile
  message-safety/
    app/
    docker-compose.yml
    tests/
    pyproject.toml
    Dockerfile
  bitrix-local-app/
    app/
    docker-compose.yml
    deploy/
    tests/
    pyproject.toml
    Dockerfile
  bitrix-sync/
    app/
    docker-compose.yml
    tests/
    pyproject.toml
    Dockerfile
  keycloak/
    docker-compose.yml
    realm/
    themes/
    providers/
  redis/
    docker-compose.yml
  observability/
    docker-compose.yml              # сервис otel-collector
    otel-collector.yaml

Детальная внутренняя структура каждого сервиса (app/, модули, миграции) определяется в профильных спецификациях модулей (TBD).

Compose-контур

Корневой backend/docker-compose.yml подключает сервисные compose-файлы через include.

Публикация портов наружу разрешена только nginx (80/443). Остальные сервисы доступны через Docker-сети и private VPC.