ochenstarik
721deee615
- Integrate @krona/tokens, @krona/themes, and @krona/ui from krona-library without code duplication - Support three official V3 themes: noble-green, parchment-light, and graphite-forest-dark - Rebuild Communications module with 5 interactive views: Messengers, Email, Channels, Contacts, Settings - Implement mobile-first drill-down, tablet 2-column, and desktop 3-column responsive layouts - Connect Telegram, WhatsApp, VK, MAX, and Email connector pills with real-time filters - Implement simulated incoming replies, quick replies manager, CRM deal/task creation, Sing-box VPN status monitor - Add comprehensive test suite in communicationsDesignSystem.test.tsx (11/11 passing) - Add IMPLEMENTATION_REPORT.md, UI_LIBRARY_USAGE.md, and COMMUNICATIONS_HANDOFF.md
107 lines
6.5 KiB
Markdown
107 lines
6.5 KiB
Markdown
# Техническая спецификация передачи (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.
|