@besales/mcp 0.1.0 → 0.11.1

package/dist/resources/docs/crm-integration.md

@@ -0,0 +1,535 @@
+# 12. CRM-интеграция
+
+> **Источник правды:** `ai-aniomaly/docs/ai-prompt-builder/12-crm-integration.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. Назначение
+
+Animaly интегрируется с 4 типами CRM. Цель интеграции:
+- Сохранять контакты и сделки в CRM при первом контакте.
+- Перемещать сделки по воронке через триггеры.
+- Передавать оператору-человеку с правильным контекстом.
+- Маппить поля платформы (имя, телефон, UTM) в кастомные поля CRM.
+- Получать статус лида для маршрутизации между агентами.
+
+## 2. Поддерживаемые CRM
+
+```ts
+enum CrmType {
+  AMOCRM,    // AmoCRM (OAuth + REST API + Chat API)
+  BITRIX24,  // Bitrix24 (REST API + Open Lines + лиды-сделки)
+  TELEGRAM,  // Telegram Forum CRM (топик-based группа как «CRM»)
+  GETCOURSE, // GetCourse как CRM (заказы/доски/этапы/теги/группы/менеджеры)
+}
+```
+
+## 3. Сущность `Crm`
+
+```json
+{
+  "id": "uuid",
+  "type": "AMOCRM",
+  "status": "active",
+  "config": { /* зависит от type — см. §7 для AMOCRM, §8 для BITRIX24, §10 для GETCOURSE */ },
+  "workspaceId": "<workspaceId>",
+  "chatApiScope": "WORKSPACE"
+}
+```
+
+| Поле | Описание |
+|---|---|
+| `type` | enum `CrmType`. |
+| `status` | Текстовая строка: `active`, `inactive`, `error`. |
+| `config` | JSON, специфичный для CRM-провайдера (см. §7-§10). |
+| `chatApiScope` | `WORKSPACE` (один канал AmoCRM на весь workspace) или `PLATFORM` (отдельный канал для каждой платформы через `PlatformAmoChatConfig`). Применяется только для AmoCRM. |
+
+Уникален в `(workspaceId, type)` — нельзя подключить две AmoCRM в один workspace.
+
+**Важно:** Поле `Crm.config.managedTagPrefix` используется только в **Bitrix24** (для тегов сделок) и **GetCourse** (`Crm.config.managedTagPrefix` для тегов; см. §10). В AmoCRM такого префикса нет.
+
+## 4. Воронки и статусы
+
+### `CrmPipeline`
+
+```json
+{
+  "crmId": "<Crm.id>",
+  "id": 1234567,
+  "name": "Основная воронка",
+  "sort": 0,
+  "isMain": true,
+  "isUnsortedOn": true,
+  "isArchive": false,
+  "accountId": 87654321,
+  "isActive": true,
+  "isCustom": false,
+  "pipelineType": "deal",
+  "pipelineMetadata": null
+}
+```
+
+`pipelineType`: `deal` (сделки, default) или `lead` (только Bitrix24 — отдельные лиды).
+
+### `CrmPipelineStatus`
+
+```json
+{
+  "pipelineCrmId": "<Crm.id>",
+  "pipelineId": 1234567,
+  "id": 142,
+  "name": "Переговоры",
+  "sort": 10,
+  "color": "#FFFF00",
+  "type": 0,
+  "isEditable": true,
+
+  "isOptional": false,
+  "isSystemManaged": true,
+  "statusTypes": ["INCOMING", "OUTGOING"],
+
+  "isBotActive": true,
+  "isOperatorAvailable": true,
+  "onMessageReceivedMoveToStatus": null,
+
+  "statusMetadata": null
+}
+```
+
+| Поле | Описание |
+|---|---|
+| `statusTypes[]` | enum `StatusType[]`: `INCOMING`, `OUTGOING`, `MESSAGE_SENT`, `AI_TOOK_OVER`, `OPERATOR_TOOK_OVER`, `USER_BLOCKED`. Используется в Pipeline Builder. |
+| `isBotActive` | Если `false` — бот не отвечает в этом статусе. |
+| `isOperatorAvailable` | Доступен ли оператор для перевода. |
+| `onMessageReceivedMoveToStatus` | ID статуса, в который перевести при получении сообщения от пользователя (автоперевод). |
+| `isSystemManaged` | Управляется системой (для Bitrix24 live-проверки). |
+
+## 5. Маппинг полей (`CrmFieldMapping`)
+
+Маппит поля платформы (имя, телефон, email, UTM) в кастомные поля CRM:
+
+```json
+{
+  "id": "uuid",
+  "workspaceId": "<workspaceId>",
+  "crmType": "AMOCRM",
+  "fieldMappings": {
+    "enabled": true,
+    "fields": {
+      "phone": {
+        "crmFieldId": "PHONE",
+        "saveAs": "phone",
+        "enabled": true,
+        "specialPurpose": "phone"
+      },
+      "first_name": {
+        "crmFieldId": "FIRST_NAME",
+        "saveAs": "first_name",
+        "enabled": true,
+        "specialPurpose": null
+      },
+      "telegram_id": {
+        "crmFieldId": "12345",
+        "saveAs": "telegram_id",
+        "enabled": true,
+        "specialPurpose": "telegramId"
+      },
+      "company_name": {
+        "crmFieldId": "67890",
+        "saveAs": "company_name",
+        "enabled": true,
+        "specialPurpose": null
+      }
+    }
+  },
+  "isActive": true
+}
+```
+
+### `specialPurpose` — зачем оно
+
+`specialPurpose` подсказывает системе, что в этом CRM-поле «лежит» и позволяет:
+- **Task-trigger**: при создании задачи в CRM искать пользователя по этому полю.
+- **Pipeline-фильтр**: проверять существующие сделки с этим контактом.
+- **Кросс-платформенный мердж**: объединять `ChatUser` в `UnifiedCustomer` по совпадению `phone`/`telegramId`/`avitoId`.
+
+> ⚠️ **Полный список допустимых значений `specialPurpose` — ровно 6** (`src/core/application/crms/services/crm-field-mapping.service.ts:38-45`, тип `FieldSpecialPurpose`):
+>
+> - `phone` — телефон в формате для отправки сообщений (E.164 без `+` для Wazzup).
+> - `telegramId` — Telegram user ID (числовой).
+> - `username` — Telegram username (без `@`).
+> - `avitoId` — Avito user ID.
+> - `instagramId` — Instagram user ID / username (Direct API).
+> - `vkonId` — VK user ID.
+>
+> Никаких `email`, `firstName`, `lastName`, `lastMessage` — этих значений в коде НЕТ. Если AI-сервис подставит любое из них, runtime отклонит запись (через DTO `IsIn([...])`-валидацию).
+>
+> Для `email`/`firstName`/`lastName` и подобных бизнес-полей используется обычный маппинг **без** `specialPurpose` (поле остаётся `null`). Имя клиента сохраняется в `ChatUser.firstName` / `ChatUser.lastName` через builtin-инструмент `save_user_info` (см. [03-tools-catalog.md](03-tools-catalog.md), §2.3) или через `ActionCrmUpdateField`. Email сохраняется в `ChatUser.email`. Эти поля не нужно мапить через `specialPurpose`.
+
+## 6. Операторы (`CrmOperator`)
+
+```json
+{
+  "id": "uuid",
+  "crmType": "AMOCRM",
+  "crmAccountId": "12345",
+  "crmId": "<Crm.id>",
+  "name": "Сергей Иванов",
+  "email": "sergey@example.com",
+  "lang": "ru",
+  "isAdmin": false,
+  "isSDR": true,
+  "isOperator": true
+}
+```
+
+Используются для:
+- Стратегии назначения ответственного при создании сделки (`Platform.responsibleAssigneeStrategy`, см. §12).
+- Выбора оператора при `CALL_OPERATOR` action (`OperatorStrategy`):
+  - `OperatorStrategy.RANDOM` — случайный оператор с `isOperator=true`.
+  - `OperatorStrategy.FROM_DEAL` — ответственный текущей сделки (если есть).
+- Отправки уведомлений и постановки задач.
+
+> Не путать: `OperatorStrategy.FROM_DEAL` существует и используется в `CALL_OPERATOR` action. `Platform.responsibleAssigneeStrategy` — отдельный enum, и значения `FROM_DEAL` там **нет** (см. §12).
+
+## 7. AmoCRM — особенности
+
+### Подключение — OAuth 2.0 (через UI)
+
+Поток: workspace получает `accessToken` (TTL ~24 часа) + `refreshToken` (TTL ~3 месяца). Refresh автоматический. Endpoint авторизации — `https://www.amocrm.ru/oauth/`. После авторизации сохраняются `subdomain`, `accountId`, `amojoAccountId`.
+
+### Подключение — MCP-провизионинг (долгосрочный токен)
+
+> Через MCP (`besales_crm_create_init`, `crm_type=AMOCRM`) AmoCRM подключается **НЕ** OAuth-redirect'ом, а **долгосрочным токеном** (long-lived token). Пользователь создаёт в AmoCRM приватную интеграцию и вводит на setup-странице 4 значения: `sub_domain` + `client_id` (несекретные), `client_secret` + `long_access_token` (секреты). `Crm.config` хранит `subDomain` + `longAccessToken` (Bearer для REST-вызовов), redirect_uri не нужен. На `READY` токен онлайн-проверяется живым запросом к аккаунту. Операционные шаги (где взять значения, какие scopes — в т.ч. доступ к **событиям/звонкам** для выгрузки аудио-диалогов) — `besales://workflows/connect-crm-from-scratch`.
+
+### Chat API (Amojo) — отдельный канал для сообщений в карточке сделки
+
+Чтобы сообщения от бота отображались в карточке сделки AmoCRM, нужен **отдельный Amojo-канал** (`chats.amojo.amocrm.ru`). AmoCRM требует обращения в техподдержку для получения `channelId` + `channelSecretKey`. Без этого канала бот может управлять сделкой, но переписка не появится в карточке.
+
+Endpoint в Animaly для привязки канала: `POST /api/amo-crm/channel-connect`.
+
+Чтобы сообщения от бота отображались в карточке сделки AmoCRM:
+
+```json
+{
+  "Crm": { "chatApiScope": "WORKSPACE" }
+}
+```
+
+Если `chatApiScope=WORKSPACE` — один канал на весь workspace. Если `PLATFORM` — каждая платформа имеет свой канал через `PlatformAmoChatConfig`:
+
+```json
+{
+  "platformId": "<platformId>",
+  "channelId": "<AmoCRM channel ID>",
+  "channelSecretKey": "<AmoCRM channel secret>",
+  "scopeId": "<scope id>",
+  "amoAccountId": "<amojo account>",
+  "amojoId": "<amojo user>"
+}
+```
+
+### Поля контакта vs сделки
+
+В AmoCRM два уровня:
+- **Контакт** (`CONTACT`): телефон, email, имя.
+- **Сделка** (`LEAD`): сумма, статус, кастомные поля воронки.
+
+В `ActionCrmUpdateField.fieldMappings[].entityType` указывается `LEAD` или `CONTACT`.
+
+### Жизненный цикл интеграции AmoCRM
+
+Интеграция переключается между `isActive=true/false` не только вручную: система сама охраняет состояние.
+
+**1. Валидация перед активацией.** Перед тем как `Crm.isActive` поднимется в `true`, бэкенд проверяет валидность OAuth-токенов и доступность AmoCRM API (`/api/v4/account` или эквивалент). Если токены просрочены, scope недостаточен или API возвращает ошибку — активация отклоняется с понятным сообщением. AI-сервис должен **не предлагать** клиенту включать CRM, не пройдя OAuth-flow заново.
+
+**2. Авто-отключение при ошибке авторизации.** Если в процессе работы AmoCRM начинает отвечать `401`/`403` на refresh token (отозвали доступ, удалили интеграцию в админке AmoCRM, истёк `refreshToken`), Animaly автоматически выставляет `Crm.isActive=false`. После этого:
+- Триггеры с `CRM_*`-actions перестают писать в CRM (Action завершается с error → дальнейшие actions в триггере прерываются, если не стоит `continueOnError=true`).
+- Запись новых ChatUser в CRM приостанавливается.
+- В UI клиенту нужно повторно пройти OAuth — после успешного re-connect система пройдёт валидацию и снова активирует интеграцию.
+
+**3. Guard платформы — `Platform.sendToCrm`.** Регистрация нового `ChatUser` в CRM выполняется только если **обе** проверки пройдены: `Platform.sendToCrm=true` И связанная `Crm.isActive=true`. Иначе ChatUser создаётся локально, но без CRM-записи (это допустимо — можно дослать позже action'ом `CRM_UPDATE_FIELD` или вручную).
+
+**4. Флаг `sendToCrm` на платформе.** По умолчанию `true`. Используется для платформ, где новые лиды **не нужны** в CRM:
+- Технические каналы (Web Widget для поддержки уже зарегистрированных клиентов).
+- Тестовые и стейджинговые платформы.
+- Каналы, где лиды квалифицируются на отдельной платформе и переносятся вручную.
+
+> ⚠️ Если AI-сервис проектирует платформу, где CRM нужна только для **части** диалогов — лучше держать `sendToCrm=true` и фильтровать неподходящие случаи через триггер с `CALL_OPERATOR` или `SILENT_AI`, чем выключать регистрацию глобально.
+
+**5. Stale lead cleanup при ошибках AmoCRM.** Если AmoCRM-операция (`CRM_MOVE_STAGE`, `CRM_UPDATE_FIELD` и т.п.) падает с ошибкой «entity not found» (типично — лид был вручную удалён в админке AmoCRM), Animaly **проверяет** через `/api/v4/leads/{id}` (или `/contacts/{id}`), реально ли entity отсутствует. Если так:
+- В `ChatUser` обнуляются поля `leadId`, `leadStatus`, `leadStatusId`.
+- Если **и** контакт тоже missing — обнуляются `amoContactId`, `amoUserId`, `conversationId`.
+- В `UnifiedCustomer` — те же поля + `amoTagNames = []`.
+
+Cleanup — best-effort: если он сам упал (например, AmoCRM API недоступен) — ошибка логируется и проглатывается, основной триггер продолжает работу. Лог формата `[AmoCRM stale] {opName}: lead {id} отсутствует в AmoCRM. chatUser={id}. Очищены локальные ссылки: chatUsers={count}, unifiedCustomers={count}, clearContact={bool}` появляется в WARN-уровне. AI-сервис не должен учитывать эту механику при генерации триггеров — она работает прозрачно.
+
+## 8. Bitrix24 — особенности
+
+### Подключение — OAuth 2.0 через установку Bitrix24 App
+
+> ⚠️ В прошлой версии документации было сказано «без OAuth, ручная установка приложения через webhook URL». **Это неверно.** Bitrix24 в Animaly использует полноценный OAuth 2.0, аналогично AmoCRM. Ручной inbound webhook не поддерживается.
+
+**Поток подключения:**
+
+1. Пользователь устанавливает Bitrix24 App из marketplace портала клиента.
+2. Bitrix24 выполняет `POST /api/bitrix24/:workspaceId/install` с кредами в теле:
+   - `member_id` — идентификатор портала.
+   - `domain` — `<example>.bitrix24.ru`.
+   - `access_token`, `refresh_token`, `application_token`.
+   - `expires_in` — TTL access-токена (обычно 3600 сек).
+   - `client_endpoint`, `server_endpoint` — REST endpoints портала.
+3. Animaly создаёт `Crm{ type: BITRIX24 }` с заполненным `config`.
+4. Все REST-вызовы идут через `client_endpoint` с `access_token`.
+5. `Bitrix24TokenService` следит за TTL: за **5 минут до истечения** автоматически обновляет токены (с backoff на `invalid_client`).
+
+**Структура `Crm.config` для Bitrix24:**
+
+```json
+{
+  "type": "BITRIX24",
+  "config": {
+    "domain": "example.bitrix24.ru",
+    "memberId": "<portal member id>",
+    "clientId": "<oauth client id app>",
+    "clientSecret": "<oauth client secret>",
+    "accessToken": "<encrypted>",
+    "refreshToken": "<encrypted>",
+    "applicationToken": "<used for event signature validation>",
+    "expiresAt": "2026-04-30T13:00:00Z",
+    "clientEndpoint": "https://example.bitrix24.ru/rest/",
+    "serverEndpoint": "https://oauth.bitrix.info/rest/",
+    "managedColumnPrefix": "[BOT] "
+  }
+}
+```
+
+### Endpoints Bitrix24 в Animaly
+
+| Endpoint | Назначение |
+|---|---|
+| `POST /api/bitrix24/:workspaceId/install` | Установка приложения, сохранение токенов |
+| `POST /api/bitrix24/:workspaceId/handler` | Обработчик событий портала (события сделок/контактов) |
+| `POST /api/bitrix24/:workspaceId/deal-update` | Обновление полей сделки из Animaly |
+| `POST /api/bitrix24-bot/:workspaceId/:platformId/webhook` | Open Lines bot — входящие сообщения от клиентов |
+
+Подпись событий проверяется через `application_token` (Bitrix24 включает его в payload).
+
+### Лиды и сделки
+
+В Bitrix24 — отдельные сущности «Лид» и «Сделка». Можно конвертировать лид в сделку через `ActionConvertLeadToDeal`:
+
+```json
+{
+  "actionType": "CONVERT_LEAD_TO_DEAL",
+  "params": {
+    "crmId": "<Crm.id>",
+    "crmType": "BITRIX24",
+    "targetPipelineId": 1,
+    "targetStatusId": 5,
+    "note": "Конвертирован из лида в сделку"
+  }
+}
+```
+
+### Open Lines
+
+Bitrix24 Open Lines — отдельный канал для общения с клиентом из Telegram/WhatsApp/etc внутри Bitrix24. Подключается через `Platform.type=Bitrix24Bot`.
+
+### Live-проверка колонки
+
+Для follow-up и Inactive User: перед отправкой проверяется текущая колонка сделки. Если она не `system managed` или `OPERATOR_TOOK_OVER` — отправка отменяется. См. [`08-follow-up.md`](08-follow-up.md), раздел 4.1.
+
+### Каскадная деактивация `Bitrix24Bot`-платформ при удалении Bitrix24 CRM
+
+При удалении Bitrix24-CRM (`DELETE /api/crms/{crmId}`) Animaly **автоматически деактивирует** все привязанные `Platform.type=Bitrix24Bot` записи этого workspace:
+1. Backend находит все `Platform { workspaceId, type=Bitrix24Bot, isActive=true }`.
+2. Для каждой — best-effort вызов `imbot.unregister` в Bitrix24 (через `BotId`-маппинг). При неудаче — warning лог, deactivation продолжается.
+3. Single `UPDATE` ставит `isActive=false, isAiEnabled=false` всем найденным платформам в одной транзакции.
+
+Платформы **не удаляются физически** — сохраняется история чатов/сообщений. Webhook-handler фильтрует по `isActive=true`, так что даже если Bitrix24 продолжит слать события — они будут проигнорированы.
+
+Возвращается `DeactivatedBitrix24BotPlatformInfo[]` для UI-баннера, чтобы клиенту было понятно, какие платформы выключились. AI-сервис должен предупредить клиента: «Если удалить Bitrix24 CRM — все Bitrix24Bot платформы воркспейса будут автоматически отключены».
+
+## 9. Telegram Forum CRM
+
+Топик-based «CRM»: в Telegram-группе с включёнными темами каждый клиент = одна тема. Удобно для маленьких команд.
+
+```json
+{
+  "ChatUser": {
+    "forumTopicId": 42,
+    "forumTopicStatus": "OPERATOR_SET"
+  }
+}
+```
+
+`forumTopicStatus`: `NEW_MESSAGE` / `AI_HANDLE` / `TAKE_INTO_WORK` / `OPERATOR_SET` / `DEAL_DONE`.
+
+Не имеет воронок и кастомных полей в обычном смысле — статус хранится в названии топика (через эмодзи или префикс).
+
+## 10. GetCourse — особенности
+
+### Подключение
+
+API Key школы + Webhook secret. Действует только для одной школы.
+
+### Особенности
+
+- Нет «воронки» в обычном понимании — есть **доски** (boards) с **этапами** (stages).
+- Сделки хранят `status` (строка: `paid`, `cancelled`, `in_work`, …) — не `statusId`.
+- Менеджеры назначаются через `manager_user_id` (числовой).
+- **Managed-prefix теги**: триггер `GETCOURSE_SET_DEAL_TAGS` управляет только тегами с префиксом школы (`Crm.config.managedTagPrefix`). Бизнес-теги защищены.
+- **Departments**: список отделов хранится в `Platform.getcourseDepartments` (вручную, GetCourse не имеет API списка отделов).
+
+### GetCourse-специфичные actions триггеров
+
+См. [`04-triggers-and-actions.md`](04-triggers-and-actions.md), раздел 5.15–5.23. Все 9 действий:
+- `GETCOURSE_SET_DEAL_TAGS`
+- `GETCOURSE_CLOSE_DIALOG`
+- `GETCOURSE_UPDATE_USER_CUSTOM_FIELDS`
+- `GETCOURSE_UPDATE_DEAL_STATUS`
+- `GETCOURSE_SET_DEAL_MANAGER`
+- `GETCOURSE_SET_PERSONAL_MANAGER`
+- `GETCOURSE_ADD_USER_GROUPS`
+- `GETCOURSE_REMOVE_USER_GROUPS`
+- `GETCOURSE_CHANGE_DEPARTMENT`
+
+## 11. Маркеры сделок (`Platform.dealMarkerType`)
+
+Чтобы отделить «свои» сделки от пришедших из других источников:
+
+```json
+{
+  "Platform": {
+    "dealMarkerType": "TAG",
+    "dealMarkerValue": "telegram-bot",
+    "dealMarkerFieldId": null
+  }
+}
+```
+
+| `dealMarkerType` | Поведение |
+|---|---|
+| `NONE` | Без маркировки. |
+| `TAG` | Добавлять тег `dealMarkerValue` к сделке при создании. |
+| `CUSTOM_FIELD` | Заполнить кастомное поле `dealMarkerFieldId` значением `dealMarkerValue`. |
+
+## 12. Стратегия ответственного (`Platform.responsibleAssigneeStrategy`)
+
+```json
+{
+  "responsibleAssigneeStrategy": "RANDOM_OPERATOR",
+  "fixedResponsibleId": null
+}
+```
+
+| Значение | Поведение |
+|---|---|
+| `KEEP` | Сохранять текущего ответственного (если есть). |
+| `ALWAYS_ONE` | Всегда `fixedResponsibleId` (`CrmOperator.id`). |
+| `RANDOM_OPERATOR` | Случайный из `CrmOperator` с `isOperator=true`. |
+
+## 13. Inline-пример: AmoCRM с маппингом UTM
+
+```json
+{
+  "crm": {
+    "type": "AMOCRM",
+    "config": { "subdomain": "example", "...": "..." },
+    "chatApiScope": "PLATFORM"
+  },
+  "fieldMapping": {
+    "crmType": "AMOCRM",
+    "fieldMappings": {
+      "enabled": true,
+      "fields": {
+        "phone":      { "crmFieldId": "PHONE",      "saveAs": "phone",      "enabled": true, "specialPurpose": "phone" },
+        "first_name": { "crmFieldId": "FIRST_NAME", "saveAs": "first_name", "enabled": true, "specialPurpose": null },
+        "telegram_id":{ "crmFieldId": "987654",     "saveAs": "telegram_id","enabled": true, "specialPurpose": "telegramId" },
+        "utm_source": { "crmFieldId": "111",        "saveAs": "utm_source", "enabled": true, "specialPurpose": null },
+        "utm_campaign":{"crmFieldId": "112",        "saveAs": "utm_campaign","enabled": true, "specialPurpose": null }
+      }
+    }
+  },
+  "platformAmoChatConfig": {
+    "platformId": "<platformId>",
+    "channelId": "<from AmoCRM support>",
+    "channelSecretKey": "<from AmoCRM support>",
+    "scopeId": "<scope id>",
+    "amoAccountId": "<amojo>",
+    "amojoId": "<amojo user>"
+  }
+}
+```
+
+## 14. Inline-пример: Bitrix24 с конвертацией лида
+
+```json
+{
+  "crm": {
+    "type": "BITRIX24",
+    "config": {
+      "domain": "example.bitrix24.ru",
+      "memberId": "<portal member id>",
+      "clientId": "<oauth client id>",
+      "clientSecret": "<oauth client secret>",
+      "accessToken": "<encrypted>",
+      "refreshToken": "<encrypted>",
+      "applicationToken": "<encrypted>",
+      "expiresAt": "2026-04-30T13:00:00Z",
+      "clientEndpoint": "https://example.bitrix24.ru/rest/",
+      "managedColumnPrefix": "[BOT] "
+    }
+  },
+  "platform": {
+    "type": "Bitrix24Bot",
+    "bitrix24BotId": 42,
+    "bitrix24BotName": "BeSales AI",
+    "bitrix24OpenLineId": "5"
+  },
+  "trigger": {
+    "name": "convert_lead_when_qualified",
+    "condition": "user explicitly confirmed product interest and budget",
+    "actions": [
+      {
+        "actionType": "CONVERT_LEAD_TO_DEAL",
+        "priority": 10,
+        "params": {
+          "crmId": "<Crm.id>",
+          "crmType": "BITRIX24",
+          "targetPipelineId": 1,
+          "targetStatusId": 5,
+          "note": "Лид квалифицирован"
+        }
+      }
+    ]
+  }
+}
+```
+
+## 15. Граничные случаи и валидация
+
+| Правило | Что AI-сервису помнить |
+|---|---|
+| Один `Crm` на `(workspaceId, type)` | Нельзя подключить две AmoCRM в один workspace. |
+| `chatApiScope=PLATFORM` требует `PlatformAmoChatConfig` | Иначе сообщения не уйдут в карточку. |
+| Bitrix24 — лид≠сделка | Если у `ChatUser` `bitrixLeadId` — это лид, нужно конвертировать. |
+| Telegram Forum CRM — без воронок | Не использовать `LEAD_STATUS` маршрутизацию для этого типа. |
+| GetCourse `dealsTagPrefix` обязателен | Без него action `GETCOURSE_SET_DEAL_TAGS` не будет работать. |
+| Live-проверка Bitrix24 | Follow-up не отправится, если колонка не `system managed`. |
+| Маркеры — для аналитики | Не критично, но полезно для отделения «своих» сделок. |
+| Composite ключ статусов | `(pipelineCrmId, pipelineId, id)` — не использовать только `id`. |
+| `onMessageReceivedMoveToStatus` | Может конфликтовать с `CRM_MOVE_STAGE` action — приоритет последнего. |
+| `isBotActive=false` у статуса | Бот молчит в этом статусе. Часто — для «закрытых» этапов. |
+
+## 16. Связь с другими подсистемами
+
+| Подсистема | Связь |
+|---|---|
+| **Триггеры** ([`04-triggers-and-actions.md`](04-triggers-and-actions.md)) | `CRM_MOVE_STAGE`, `CRM_UPDATE_FIELD`, `CRM_ADD_NOTE`, `CONVERT_LEAD_TO_DEAL`, `GETCOURSE_*`. |
+| **Маршрутизация** ([`06-routing.md`](06-routing.md)) | `RoutingStrategy=LEAD_STATUS` использует `CrmPipelineStatus` через `AgentRoutingRuleLeadStatus`. |
+| **Платформы** ([`11-platforms.md`](11-platforms.md)) | `sendToCrm`, `dealMarkerType`, `responsibleAssigneeStrategy`, `PlatformAmoChatConfig`. |
+| **Follow-up** ([`08-follow-up.md`](08-follow-up.md)) | `crmNote` пишется в CRM. Bitrix24 — live-проверка колонки. |
+| **Переменные** ([`05-variables.md`](05-variables.md)) | `crmFields`, `outgoingCrmFields`, `{leadStatus}`, `{crmContactLink}`, `{crmDealLink}`. |
+| **Поведение** ([`10-agent-behavior.md`](10-agent-behavior.md)) | `botWaitingReturn`, `aiErrorTargetStageId`, `skipTaskCreationOnCallOperator`. |