74 lines
4.0 KiB
Markdown
74 lines
4.0 KiB
Markdown
# Логика чатботов VK, Telegram и Messenger Max
|
||
|
||
## Общий принцип
|
||
|
||
Все каналы работают через единый слой адаптеров:
|
||
|
||
1. webhook принимает событие от канала;
|
||
2. адаптер нормализует payload в общую структуру;
|
||
3. сообщение или действие сохраняется в `chat_messages`;
|
||
4. при изменении состояния заказа создаётся запись в `order_history`;
|
||
5. UI обновляет карточку заказа и уведомления.
|
||
|
||
## Единая модель событий
|
||
|
||
```json
|
||
{
|
||
"order_id": "uuid",
|
||
"channel": "telegram | vk | messenger_max",
|
||
"direction": "inbound | outbound",
|
||
"message_type": "text | button | system",
|
||
"sender_type": "client | bot | operator",
|
||
"text": "Подтверждаю доставку",
|
||
"payload": {
|
||
"action": "confirm_delivery",
|
||
"slot_id": "uuid"
|
||
},
|
||
"external_message_id": "string"
|
||
}
|
||
```
|
||
|
||
При обновлении заказа бот теперь меняет два поля:
|
||
- `orders.status` — основной статус заказа;
|
||
- `orders.delivery_agreement_status` — состояние согласования доставки с клиентом.
|
||
|
||
## Telegram
|
||
|
||
- Отправка статуса готовности через `sendMessage`.
|
||
- Кнопки подтверждения через inline keyboard: `confirm`, `reschedule`, `cancel`.
|
||
- Callback query несёт `order_id`, `slot_id`, `action`.
|
||
- При ответе клиента обновляются `chat_messages`, `delivery_slots`, `orders.status`.
|
||
|
||
## VK
|
||
|
||
- Используется Callback API сообщества.
|
||
- Кнопки в `keyboard` отправляют payload с `order_id` и `action`.
|
||
- Система проверяет подпись webhook, нормализует payload и сохраняет событие.
|
||
|
||
## Messenger Max
|
||
|
||
- Адаптер должен принимать webhook событий сообщений и postback-действий.
|
||
- На входе событие маппится в ту же структуру, что и Telegram/VK.
|
||
- Неизвестные типы сохраняются как `system` для последующего разбора администратором.
|
||
|
||
## Автоматические сценарии
|
||
|
||
- `Готово к доставке` → бот отправляет предложение со слотами.
|
||
- `Подтверждение клиента` → статус `Доставка согласована`, согласование `Подтверждено клиентом`.
|
||
- `Перенос` → создаётся новый `delivery_slot`, статус `Ожидает согласования доставки`, согласование `Перенос запрошен`.
|
||
- `Отмена` или сбой сценария → статус `Проблема доставки`.
|
||
- `Нет ответа` после SLA → согласование `Нет ответа` и задача логисту на ручную обработку.
|
||
|
||
## Надёжность и аудит
|
||
|
||
- Все inbound/outbound события нужно логировать с `external_message_id`.
|
||
- Ошибки интеграции стоит писать в отдельную таблицу `integration_events` или `error_logs`.
|
||
- Повторная обработка webhook должна быть идемпотентной по `external_message_id`.
|
||
|
||
## Что уже добавлено в репозиторий
|
||
|
||
- `supabase/functions/chatbot-webhook/index.ts` — приём webhook и фиксация inbound-событий.
|
||
- `supabase/functions/send-chatbot-message/index.ts` — отправка outbound-сообщений и логирование.
|
||
- `supabase/functions/_shared/chatbot.ts` — общий слой нормализации событий и статусов.
|
||
- `supabase/functions/_shared/workflow.ts` — чистая карта переходов для inbound/outbound событий.
|