@besales/mcp 0.1.0 → 0.11.1

package/dist/resources/docs/platforms.md

@@ -0,0 +1,513 @@
+# 11. Платформы (каналы связи)
+
+> **Источник правды:** `ai-aniomaly/docs/ai-prompt-builder/11-platforms.md` — копия для MCP doc-bridge (v1.5 Increment 6b). Синкать при изменении оригинала.
+>
+> ⚠️ **MCP-контекст:** это доменная справка, написанная для людей/админ-UI. В MCP-сессии ты выполняешь те же операции **через besales_* tools**, а не через UI (drag-n-drop, клики в админке). Где текст ниже говорит «клиент/админ делает X через UI» — это «что должно получиться»; механику бери из tool (напр. загрузка файла → `besales_file_upload_request`; документ в knowledge → `besales_knowledge_document_upload`; сайт → `besales_knowledge_website_add`) + из workflow-ресурсов. Внутренние ссылки `[NN-name.md]` — относительные пути исходной доки, через MCP НЕ резолвятся: ищи `besales://docs/<slug>` или concept-resource.
+
+## 1. Назначение
+
+`Platform` — это «канал», через который бот общается с пользователями. Каждая платформа — один внешний account/bot/instance. Animaly поддерживает **11 типов** платформ (`PlatformType`): Telegram Bot, Telegram Personal, Wazzup (WhatsApp), Avito, Instagram DM, VKontakte, SmsGorod (SMS), Web Widget, Bitrix24 Bot, Salebot и **GetCourse**.
+
+> Ранее в обзорной части документации фигурировало «10 каналов» — это устаревшая цифра. GetCourse — отдельный полноценный адаптер с собственным контроллером (`/api/getcourse/webhook/:platformId/:secret/...`), и его нужно учитывать при настройке.
+
+## 2. Общая структура `Platform`
+
+```json
+{
+  "id": "uuid",
+  "type": "TelegramBot",
+  "name": "Главный Telegram-бот",
+  "isActive": true,
+  "isAiEnabled": true,
+  "timezone": "Europe/Moscow",
+  "offMessage": "Бот временно недоступен. Пожалуйста, попробуйте позже.",
+  "workspaceId": "<workspaceId>",
+
+  // Поля, специфичные для каждого type — см. ниже
+  "config": null,
+  "botToken": "...",
+
+  "isUserFilterEnabled": false,
+  "filteredUserIds": [],
+
+  "useDynamicVariables": false,
+  "clearDynamicVarsOnHistoryClear": true,
+
+  "responsibleAssigneeStrategy": "KEEP",
+  "fixedResponsibleId": null,
+
+  "sendToCrm": false,
+  "useCrossPlatformHistory": false,
+
+  "sendStartNoteToCrm": false,
+  "sendFailedNoteToCrm": false,
+  "sendOperatorTakeoverNoteToCrm": false,
+  "sendFinishAutoNoteToCrm": false,
+
+  "finishAutoEnabled": false,
+  "finishAutoDays": 7,
+
+  "dealMarkerType": "NONE",
+  "dealMarkerValue": null
+}
+```
+
+### Общие поля (для всех платформ)
+
+| Поле | Дефолт | Описание |
+|---|---|---|
+| `type` | — | enum `PlatformType`. Определяет, как платформа подключается. |
+| `name` | null | Пользовательское название (для UI). |
+| `isActive` | false | Включён ли канал. |
+| `isAiEnabled` | true | Работает ли AI на этой платформе. Если `false` — все сообщения уходят оператору. |
+| `timezone` | `"Europe/Moscow"` | Таймзона для расписаний и `{currentTime}`. |
+| `offMessage` | `"Бот временно недоступен..."` | Что отвечать, если `isActive=false`. |
+| `useDynamicVariables` | false | Можно ли использовать `ChatUser.dynamicVariables`. |
+| `clearDynamicVarsOnHistoryClear` | true | Очищать ли динамические переменные при очистке истории. |
+| `responsibleAssigneeStrategy` | `KEEP` | Стратегия выбора ответственного. |
+| `sendToCrm` | false | Отправлять ли сообщения от бота в CRM (Bitrix24 Open Line, AmoCRM Chat API). |
+| `useCrossPlatformHistory` | false | Использовать историю из всех платформ `UnifiedCustomer`. |
+| `dealMarkerType` | `NONE` | Маркировка сделок: `NONE` / `TAG` / `CUSTOM_FIELD`. |
+
+### Workspace-scoped API
+
+Legacy endpoints `GET /api/platforms` и `POST /api/platforms` берут `workspaceId` из JWT.
+Для экранов, где workspace выбран явно в UI, используется route-scoped вариант:
+
+| Endpoint | Назначение |
+|---|---|
+| `GET /api/workspace/:workspaceId/platforms` | Список платформ выбранного workspace для текущего пользователя. |
+| `POST /api/workspace/:workspaceId/platforms` | Создание платформы в выбранном workspace. |
+
+Оба endpoint проверяют права пользователя в `:workspaceId` через `PermissionsService`:
+`PLATFORM_READ` для чтения и `PLATFORM_CREATE` для создания. Это защищает сценарии, где
+access token ещё содержит старый workspace, а интерфейс уже переключился на другой.
+
+### CRM-заметки
+
+| Поле | Дефолт | Описание |
+|---|---|---|
+| `sendStartNoteToCrm` | false | Отправлять ли заметку в CRM при первом контакте. |
+| `startNoteTemplate` | null | Кастомный текст (null — дефолтный). |
+| `sendFailedNoteToCrm` | false | Заметка при ошибке отправки. |
+| `sendOperatorTakeoverNoteToCrm` | false | Заметка при вызове оператора. |
+| `sendFinishAutoNoteToCrm` | false | Заметка при `FINISH_AUTO`. |
+
+### Авто-завершение по неактивности
+
+| Поле | Дефолт | Описание |
+|---|---|---|
+| `finishAutoEnabled` | false | Включить автозакрытие после N дней молчания. |
+| `finishAutoDays` | 7 | Сколько дней молчания. |
+
+## 3. Каталог платформ по типам
+
+### 3.1. `TelegramBot` (Telegram через BotFather)
+
+```json
+{
+  "type": "TelegramBot",
+  "botToken": "<токен от @BotFather>",
+  "isActive": true,
+  "isAiEnabled": true,
+  "enableCleanupCommands": false
+}
+```
+
+| Поле | Описание |
+|---|---|
+| `botToken` | Токен от @BotFather. **Обязательное** для активации. |
+| `enableCleanupCommands` | По умолчанию `false`. Если `true` — Animaly через `setMyCommands` регистрирует у бота меню `/clean` (очистить историю чата) и `/delete` (удалить ChatUser-контакт). Используется только для **TelegramBot**-платформ; на других channel-типах backend отклоняет с 400 (typed validation). Команды реализованы через отдельный сервисный Cleanup Bot — клиент должен добавить себя как `WorkspaceTrustedIdentity` (по `telegram_user_id`/`telegram_username`) ещё ДО первого `/start`. |
+
+**Поддерживает:** медиа (фото/видео/документы/аудио/voice/video_note), кнопки (INLINE/REPLY), группы (с ограничениями), polling/webhook, Markdown.
+
+**Лимиты:** caption ≤1024, текст ≤4096, файлы ≤50MB.
+
+### 3.2. `TelegramPersonal` (личный Telegram-аккаунт через MTProto)
+
+```json
+{
+  "type": "TelegramPersonal",
+  "isActive": true,
+  "isAiEnabled": true
+}
+```
+
+Привязка через `TelegramPersonalAccount` (отдельная сущность):
+
+```json
+{
+  "phoneNumber": "+79991234567",
+  "apiId": 12345,
+  "apiHash": "<api hash>",
+  "sessionString": "<MTProto сессия>",
+  "status": "CONNECTED",
+  "dailyMessageLimit": 10,
+  "isActiveInCampaigns": true,
+  "sendingIntervalMinutes": 2,
+  "proxyId": "<Proxy.id>"
+}
+```
+
+**Поддерживает:** все медиа, voice, video_note, кнопки только REPLY (Telegram personal не поддерживает inline).
+
+**Особенности:**
+- Можно несколько аккаунтов на одну платформу (карусель для рассылок).
+- `dailyMessageLimit` — анти-бан защита (default 10).
+- `restrictionStatus` отслеживает баны Telegram.
+- `messageOpenDelay` (`AgentBehavior`) применяется только здесь.
+
+### 3.3. `Wazzup` (агрегатор каналов)
+
+```json
+{
+  "type": "Wazzup",
+  "wazzupCrmKey": "<ключ от Wazzup>",
+  "wazzupChannel": "WhatsApp",
+  "isActive": true
+}
+```
+
+| `wazzupChannel` | Канал |
+|---|---|
+| `WhatsApp` | WhatsApp Business |
+| `Avito` | Avito (через Wazzup) |
+| `Instagram` | Instagram DM (через Wazzup) |
+| `Vk` | ВКонтакте |
+| `Telegram` | Telegram (через Wazzup) |
+| `Viber` | Viber |
+| `Max` | Max (Россия) |
+| `TelegramPersonal` | Telegram Personal через Wazzup |
+
+**Поддерживает:** WhatsApp шаблоны (WABA), медиа, кнопки (для Telegram-канала). На WhatsApp — лимит 24h-окна и approved templates.
+
+### 3.4. `Avito` (Avito Messenger напрямую)
+
+```json
+{
+  "type": "Avito",
+  "config": {
+    "clientId": "<Avito Client ID>",
+    "clientSecret": "<...>",
+    "userId": "<Avito User ID>",
+    "accessToken": "<oauth token>",
+    "refreshToken": "<...>",
+    "expiresAt": "..."
+  },
+  "isActive": true
+}
+```
+
+**Подключение (OAuth):** браузерная OAuth-авторизация Avito (`clientId` / `clientSecret` → `accessToken` / `refreshToken`); с OAuth Phase 2 доступно подключение через MCP setup-flow (Setup URL), код авторизации не проходит через чат. Поддерживает: текст, картинки. **Не поддерживает:** кнопки, документы, видео.
+
+### 3.5. `Instagram` (Direct API через Facebook Graph)
+
+```json
+{
+  "type": "Instagram",
+  "instagramBusinessAccountId": "<IG account>",
+  "instagramPageId": "<Facebook Page>",
+  "instagramPageAccessToken": "<encrypted>",
+  "instagramTokenExpiresAt": "...",
+  "instagramUserAccessToken": "<encrypted>",
+  "instagramWebhookVerifyToken": "<token>",
+
+  "replyToInstagramComments": false,
+  "instagramCommentHandlingMode": "MENTIONS_ONLY",
+  "instagramCommentReplyMethod": "PRIVATE_DM",
+  "instagramCommentKeywords": null,
+  "replyToStoryMentions": false,
+
+  "isActive": true
+}
+```
+
+**Особенности:**
+- **24h-окно**: можно отвечать только в течение 24 часов после сообщения пользователя.
+- Комментарии под постами обрабатываются отдельно (`instagramCommentHandlingMode`).
+- Story Mentions/Replies — опционально.
+
+**Подключение (OAuth):** канал подключается браузерной OAuth-авторизацией через Facebook Graph API (v21). Поток: `POST /api/instagram/auth/initiate` (под JWT) возвращает `authUrl` с подписанным HMAC-`state` → клиент подтверждает доступ в диалоге Facebook → `GET /api/instagram/auth/callback` обменивает `code` на токены и сохраняет `instagramPageAccessToken` / `instagramUserAccessToken`. Токены не вводятся вручную и не проходят через чат; тот же поток используется при подключении через MCP setup-flow (OAuth Phase 2).
+
+### 3.6. `Salebot` (внешний агрегатор)
+
+```json
+{
+  "type": "Salebot",
+  "salebotApiKey": "<API key>",
+  "salebotProjectId": "<project id>",
+  "salebotGroupId": "<group/bot name>",
+  "isActive": true
+}
+```
+
+Salebot сам подключает Telegram/VK/WhatsApp/etc. Animaly через API Salebot отправляет/принимает сообщения.
+
+### 3.7. `SmsGorod` (SMS через сервис)
+
+```json
+{
+  "type": "SmsGorod",
+  "smsgorodApiKey": "<API key>",
+  "smsgorodChannel": "DIGIT",
+  "smsgorodSender": null,
+  "isActive": true
+}
+```
+
+| `smsgorodChannel` | Описание |
+|---|---|
+| `DIGIT` | Цифровой номер отправителя (sender необязателен). |
+| `CHAR` | Буквенное имя отправителя — `smsgorodSender` обязателен. |
+
+**Лимиты:**
+- Один SMS = 70 символов кириллицей или 160 латиницей.
+- Длинные сообщения разбиваются провайдером.
+- **Не поддерживает:** медиа, кнопки.
+- Рекомендуется задать `AgentChat.maxResponseSymbols` (например, 140), чтобы LLM не генерировал слишком длинно.
+
+### 3.8. `VKon` (VK сообщество)
+
+```json
+{
+  "type": "VKon",
+  "config": {
+    "groupId": "<community ID>",
+    "accessToken": "<community access token>",
+    "secret": "<callback secret>",
+    "confirmation": "<callback confirmation string>"
+  },
+  "isActive": true
+}
+```
+
+**Поддерживает:** текст, медиа (фото/видео/аудио/документы), кнопки (как REPLY-клавиатура), карусели.
+
+### 3.9. `WebWidget` (встраиваемый виджет на сайт)
+
+```json
+{
+  "type": "WebWidget",
+  "webWidgetAllowedOrigins": ["*"],
+  "webWidgetShowPageInfo": true,
+  "webWidgetRateLimitPerMinute": 20,
+  "webWidgetCustomization": {
+    "logo": "https://example.com/logo.png",
+    "colors": { "primary": "#7B61FF" },
+    "position": "bottom-right",
+    "buttonStyle": "rounded"
+  },
+  "webWidgetMarketingFieldMappings": {
+    "utm_source": "<crmFieldId>",
+    "utm_campaign": "<crmFieldId>",
+    "ymClientId": "<crmFieldId>",
+    "googleClientId": "<crmFieldId>"
+  },
+  "webWidgetEntryUrlVariableMapping": {
+    "variableName": "first_visit_url",
+    "regex": null
+  }
+}
+```
+
+**Особенности:**
+- Real-time через **Socket.IO** (не webhook).
+- `webWidgetShowPageInfo=true` — добавляет в промпт URL текущей страницы.
+- `webWidgetMarketingFieldMappings` — UTM/yaClientId/gaClientId автоматически отправляются в CRM-поля.
+- Push-кампании **не поддерживаются** (нет инициатора со стороны бота).
+- Особая логика follow-up через `webWidgetLastSeenAt` (см. [`08-follow-up.md`](08-follow-up.md)).
+
+### 3.10. `Bitrix24Bot` (Bitrix24 Open Lines)
+
+```json
+{
+  "type": "Bitrix24Bot",
+  "bitrix24BotId": 42,
+  "bitrix24BotCode": "animaly_bot_<workspaceId>",
+  "bitrix24BotName": "BeSales AI",
+  "bitrix24OpenLineId": "5",
+  "isActive": true
+}
+```
+
+Бот регистрируется в Bitrix24 и принимает сообщения из всех каналов Open Lines (Telegram/WhatsApp/VK/Viber/Avito).
+
+**Особенности:**
+- Live-проверка колонки CRM перед отправкой follow-up (см. [`08-follow-up.md`](08-follow-up.md), раздел 4.1).
+- `hasExitedSilentMode` у `ChatUser` — лид/сделка активирована (попала в INCOMING/OUTGOING).
+
+### 3.11. `GetCourse` (LMS GetCourse)
+
+```json
+{
+  "type": "GetCourse",
+  "getcourseAccountDomain": "school.getcourse.ru",
+  "getcourseSchoolApiKey": "<encrypted>",
+  "getcourseEmployeeUserId": 42,
+  "getcourseAvailableTransports": ["Site", "Email", "Telegram"],
+  "getcourseDefaultTransport": "Site",
+  "getcourseWebhookSecret": "<random32bytes>",
+  "getcourseDepartments": [
+    { "id": 1, "label": "Отдел продаж" },
+    { "id": 2, "label": "Поддержка" }
+  ]
+}
+```
+
+**Особенности:**
+- **Single Platform** на школу с массивом активных транспортов (`Site`, `Email`, `SMS`, `Telegram`, `Facebook`, `VK`, `Chatium`, `WhatsApp`, `Viber`).
+- Каждое сообщение знает свой транспорт (`ChatUsersMessages.getcourseTransport`).
+- Reply-routing: куда написал — туда отвечаем (`ChatUser.lastGetcourseTransport`).
+- Поддерживает GetCourse как CRM (отдельные `ActionGetCourse*` — см. [`04-triggers-and-actions.md`](04-triggers-and-actions.md)).
+
+## 4. Сводная таблица возможностей
+
+| Платформа | Кнопки | Медиа | Группы | Push-кампании | 24h-окно |
+|---|---|---|---|---|---|
+| `TelegramBot` | INLINE+REPLY | Все | Да | Да | — |
+| `TelegramPersonal` | REPLY | Все | Да | Да | — |
+| `Wazzup` (WhatsApp) | Inline (WABA) | Да | Да | Через WABA шаблоны | Да |
+| `Wazzup` (Telegram) | Inline | Все | Да | Да | — |
+| `Avito` | Нет | Картинки | Нет | Ограниченно | — |
+| `Instagram` | Quick Replies | Изображения | Нет | Только в 24h-окне | Да |
+| `Salebot` | Зависит от подключённого канала | Зависит | Зависит | Да | Зависит |
+| `SmsGorod` | Нет | Нет | Нет | Да | — |
+| `VKon` | REPLY-клавиатура | Все | Да | Да | — |
+| `WebWidget` | Inline + popup | Да | Нет | **Нет** | — |
+| `Bitrix24Bot` | Зависит от Open Line | Да | Зависит | Да | — |
+| `GetCourse` | Нет (Inbox API ограничен) | Да | Нет | Да | — |
+
+## 5. Стратегии ответственного (`responsibleAssigneeStrategy`)
+
+| Значение | Поведение |
+|---|---|
+| `KEEP` | Сохранять текущего ответственного в CRM. |
+| `ALWAYS_ONE` | Всегда `fixedResponsibleId`. |
+| `RANDOM_OPERATOR` | Случайный оператор из списка `CrmOperator`. |
+
+## 6. PipelineSettings — фильтрация существующих сделок
+
+```json
+{
+  "platformId": "<platformId>",
+  "filters": [
+    {
+      "fieldId": "PHONE",
+      "valueType": "SYSTEM_VARIABLE",
+      "value": "phone",
+      "action": "LINK"
+    }
+  ]
+}
+```
+
+`PipelineSettings` определяет, что делать, если в CRM уже есть сделка с тем же телефоном/email:
+- `LINK` — привязать пользователя к существующей сделке.
+- `IGNORE` — игнорировать (создать новую, или `isBotActive=false`).
+
+## 7. Inline-пример: Telegram-бот для интернет-магазина
+
+```json
+{
+  "type": "TelegramBot",
+  "name": "Главный Telegram-бот",
+  "botToken": "<TOKEN>",
+  "isActive": true,
+  "isAiEnabled": true,
+  "timezone": "Europe/Moscow",
+
+  "useDynamicVariables": true,
+  "clearDynamicVarsOnHistoryClear": true,
+
+  "responsibleAssigneeStrategy": "RANDOM_OPERATOR",
+  "sendToCrm": false,
+
+  "sendStartNoteToCrm": true,
+  "startNoteTemplate": "Новый лид из Telegram-бота",
+
+  "sendOperatorTakeoverNoteToCrm": true,
+
+  "finishAutoEnabled": true,
+  "finishAutoDays": 14,
+  "sendFinishAutoNoteToCrm": true,
+
+  "dealMarkerType": "TAG",
+  "dealMarkerValue": "telegram-bot"
+}
+```
+
+## 8. Inline-пример: SmsGorod для отправки уведомлений
+
+```json
+{
+  "type": "SmsGorod",
+  "name": "SMS-уведомления",
+  "smsgorodApiKey": "<KEY>",
+  "smsgorodChannel": "CHAR",
+  "smsgorodSender": "MyShop",
+  "isActive": true,
+  "isAiEnabled": false,
+  "timezone": "Europe/Moscow"
+}
+```
+
+`isAiEnabled=false`: SMS-канал часто не для AI-диалога, а для исходящих уведомлений (через follow-up/кампании).
+
+## 9. Inline-пример: Web Widget с UTM-маркетингом
+
+```json
+{
+  "type": "WebWidget",
+  "name": "Виджет на сайте",
+  "isActive": true,
+  "isAiEnabled": true,
+  "timezone": "Europe/Moscow",
+
+  "webWidgetAllowedOrigins": ["https://shop.example.com", "https://example.com"],
+  "webWidgetShowPageInfo": true,
+  "webWidgetRateLimitPerMinute": 30,
+
+  "webWidgetCustomization": {
+    "colors": { "primary": "#7B61FF", "background": "#FFFFFF" },
+    "position": "bottom-right"
+  },
+
+  "webWidgetMarketingFieldMappings": {
+    "utm_source": "<crmFieldId-utm_source>",
+    "utm_campaign": "<crmFieldId-utm_campaign>",
+    "ymClientId": "<crmFieldId-yandex_client_id>"
+  },
+
+  "webWidgetEntryUrlVariableMapping": {
+    "variableName": "first_visit_url"
+  }
+}
+```
+
+## 10. Граничные случаи и валидация
+
+| Правило | Что AI-сервису помнить |
+|---|---|
+| `botToken` обязателен для TelegramBot | Без него `isActive=true` всё равно не сработает. |
+| `wazzupChannel` определяет фичи | На WhatsApp — лимит 24h, на Telegram через Wazzup — нет. |
+| Avito — без кнопок и видео | Не предлагать. |
+| Instagram — только в 24h-окне | Кампании пройдут только тем, кто писал недавно. |
+| WebWidget — нет push-кампаний | Используется только в реальном времени. |
+| SMS — `maxResponseSymbols` критично | LLM может генерировать длинные ответы; для SMS обязательно ограничить (например, 140). |
+| `useCrossPlatformHistory=true` | Требует `UnifiedCustomer`-привязки клиентов. |
+| `finishAutoEnabled=true` | Автозакрытие после `finishAutoDays` дней. Полезно для аналитики «потерянных», но не для активных воронок. |
+| `dealMarkerType=TAG` | Создаёт тег в CRM (например, для атрибуции). |
+| Telegram Personal лимиты | `dailyMessageLimit`, `sendingIntervalMinutes` — иначе бан. |
+| `proxyId` для TG Personal | Желательно — Telegram быстро банит без прокси. |
+
+## 11. Связь с другими подсистемами
+
+| Подсистема | Связь |
+|---|---|
+| **Агенты** ([`01-agents.md`](01-agents.md)) | Все агенты привязаны к платформе. |
+| **Поведение** ([`10-agent-behavior.md`](10-agent-behavior.md)) | Один `AgentBehavior` на платформу. |
+| **Follow-up** ([`08-follow-up.md`](08-follow-up.md)) | WebWidget — особая логика. Bitrix24Bot — live-проверка. |
+| **Кампании** ([`09-campaigns.md`](09-campaigns.md)) | Не все платформы поддерживают; разные лимиты. |
+| **CRM** ([`12-crm-integration.md`](12-crm-integration.md)) | `sendToCrm`, `dealMarkerType`, `responsibleAssigneeStrategy`, `PlatformAmoChatConfig`. |
+| **Переменные** ([`05-variables.md`](05-variables.md)) | `useDynamicVariables`, `webWidgetEntryUrlVariableMapping`. |
+| **CustomVariable** | Привязаны к платформе через `platformId`. |