krona-front/COMMUNICATIONS_HANDOFF.md

Техническая спецификация передачи (Handoff) для бэкенда krona-omnichannel

1. Введение и назначение

Данный документ описывает архитектурный контракт взаимодействия между клиентским интерфейсом krona-front (модуль /communications) и микросервисной бэкенд-платформой krona-omnichannel.

Интерфейс спроектирован по принципу контрактного разделения: UI обращается к слою communicationsService, который в текущей версии предоставляет надёжную локальную модель с реактивным состоянием, полностью совместимую с будущими REST / WebSocket эндпоинтами.

---

2. Сопоставление доменных моделей (Domain Mapping)

Модель krona-front	Сущность в krona-omnichannel	Описание и соответствие полей
Conversation	ChatSession / Thread	id: ULID, contactId, primaryConnector (enum: telegram, whatsapp, vk, max, email), unreadCount: int, lastMessage: Message, isFavorite: bool, assignedUserId: UUID
Message	MessageRecord	id: ULID, conversationId, direction (incoming / outgoing), text: str, timestamp: ISO8601, status (sent / delivered / read), senderName, attachments: Attachment[], isInternal: bool
Channel	CorporateChannel	id: ULID, name: str, description: str, isPrivate: bool, membersCount: int, pinnedMessageId: ULID, unreadCount: int
ContactOmnichannel	CustomerProfile / Party	id: ULID, name: str, avatarUrl: str, phone: str, email: str, company: str, role: str, isVip: bool, isClient: bool, linkedDealsCount: int, linkedOrdersCount: int, channels: ChannelAccount[]
RoutingRule	OmnichannelRoutingRule	id: ULID, title: str, condition: str, assigneeDepartment: str, assigneeUser: str, enabled: bool
QuickReply	CannedResponse	id: ULID, title: str, text: str, shortcut: str, category: str
Connector	ConnectorIntegration	id: enum, name: str, status (connected / degraded / disconnected), pingMs: int, accountsCount: int, uptimePercent: float

---

3. Спецификация REST API эндпоинтов

Базовый префикс: /api/v1/omnichannel

3.1. Мессенджеры и диалоги

• GET /conversations?connector={type}&filter={unread|favorite}&search={query}&limit=50&cursor={ulid}
  • Возвращает список диалогов с пагинацией по курсору ULID.
• GET /conversations/{id}/messages?limit=100&before={messageId}
  • Возвращает историю сообщений чата.
• POST /conversations/{id}/messages
  • Тело запроса:

    {
      "text": "Здравствуйте, коммерческое предложение во вложении",
      "attachments": [
        { "name": "offer_2026.pdf", "url": "https://storage.krona.ru/...", "size": "2.4 MB" }
      ],
      "isInternal": false
    }
    

• PATCH /conversations/{id}/read
  • Сброс счётчика непрочитанных для пользователя.
• POST /conversations/{id}/actions/crm-deal
  • Создание быстрой сделки в CRM из контекста переписки.

3.2. Внутрикорпоративные каналы

• GET /channels — список каналов компании.
• POST /channels — создание нового канала.
• GET /channels/{id}/messages — получение ленты канала.
• POST /channels/{id}/messages/{messageId}/reactions
  • Тело запроса: { "emoji": "👍" } (добавить или снять реакцию).

3.3. Корпоративная почта (Email)

• GET /email/messages?mailbox={id}&folder={inbox|sent|trash}&search={query}
• POST /email/messages/send
  • Тело: { "from": "...", "to": "...", "subject": "...", "body": "...", "attachments": [] }

3.4. Диагностика коннекторов и VPN Gateway

• POST /connectors/{id}/ping
  • Запускает проверку связи с шлюзом соответствующей платформы, возвращает { "status": "connected", "latencyMs": 42 }.
• GET /gateway/status
  • Возвращает статус VPN / Sing-box тоннеля (node, uptime, protocol, totalTraffic).

---

4. Спецификация событий реального времени (WebSocket)

Подключение: wss://krona-platform.ru/ws/omnichannel?token={jwt}

Входящие события с бэкенда на фронтенд:

1. message.received — поступление нового сообщения от клиента из внешнего мессенджера (Telegram, WhatsApp, VK, MAX, Email).

   {
     "event": "message.received",
     "data": {
       "conversationId": "01J9...",
       "message": {
         "id": "01J9...",
         "direction": "incoming",
         "text": "Подтверждаю оплату счета",
         "senderName": "Иван Петров",
         "connector": "telegram",
         "timestamp": "2026-09-11T16:20:00Z"
       }
     }
   }
   

2. message.status_updated — обновление статуса доставки/прочтения (delivered, read).
3. channel.reaction_updated — синхронизация реакций в каналах в реальном времени.
4. connector.health_changed — изменение статуса коннектора или сетевого шлюза.

---

5. Webhook-контракты внешних коннекторов

Бэкенд krona-omnichannel принимает вебхуки от внешних систем:

• POST /webhooks/telegram/{botToken}
• POST /webhooks/whatsapp/{tenantId}
• POST /webhooks/vk/{communityId}
• POST /webhooks/max/{gatewaySecret}
• POST /webhooks/mail/{inboundKey}

Все вебхуки преобразуются нормализатором krona-omnichannel в каноническую структуру MessageRecord и транслируются в UI через WebSocket.