# Техническая спецификация передачи (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`
  - Тело запроса:
    ```json
    {
      "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).
   ```json
   {
     "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.