@besales/mcp 0.1.0 → 0.11.1

package/dist/resources/docs/pipeline-builder.md

@@ -0,0 +1,221 @@
+# 14. Pipeline Builder и PipelineSettings
+
+> **Источник правды:** `ai-aniomaly/docs/ai-prompt-builder/14-pipeline-builder.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. Назначение
+
+Когда платформа подключена к CRM, нужно решить две задачи:
+
+1. **Что делать, если в CRM уже есть сделка/контакт с тем же телефоном** (повторное обращение клиента) — `PipelineSettings.filter*`.
+2. **Куда автоматически переводить сделку** при определённых событиях: пришло сообщение от пользователя, ответил бот, ответил оператор — `PipelineSettings.*MoveToStatus`.
+
+Обе задачи настраиваются в Pipeline Builder UI (одна страница админки). Структура — модель `PipelineSettings` (one-to-one с `Platform`).
+
+## 2. JSON-схема
+
+```json
+{
+  "id": "uuid",
+  "platformId": "<platformId>",
+
+  "filterEnabled": true,
+  "filterByPhoneEnabled": true,
+  "filterByFieldEnabled": false,
+  "filterByContactEnabled": false,
+
+  "fieldId": null,
+  "fieldEntityType": null,
+  "valueType": null,
+  "value": null,
+
+  "actionOnFound": "LINK",
+
+  "createNewLead": true,
+  "createNewContact": true,
+
+  "incomingMoveToStatus": 142,
+  "incomingMoveToStatusPipelineId": 1234567,
+  "incomingMoveToStatusCrmId": "<Crm.id>",
+
+  "outgoingMoveToStatus": 143,
+  "outgoingMoveToStatusPipelineId": 1234567,
+  "outgoingMoveToStatusCrmId": "<Crm.id>",
+
+  "aiResponseMoveToStatus": null,
+  "aiResponseMoveToStatusPipelineId": null,
+  "aiResponseMoveToStatusCrmId": null,
+
+  "operatorSpeechMoveToStatus": 145,
+  "operatorSpeechMoveToStatusPipelineId": 1234567,
+  "operatorSpeechMoveToStatusCrmId": "<Crm.id>"
+}
+```
+
+## 3. Фильтрация существующих сделок
+
+### Поля
+
+| Поле | Тип | Описание |
+|---|---|---|
+| `filterEnabled` | bool | Главный выключатель — без него фильтр не работает. |
+| `filterByPhoneEnabled` | bool | Искать существующую сделку/контакт по телефону клиента. |
+| `filterByFieldEnabled` | bool | Искать по кастомному CRM-полю. |
+| `filterByContactEnabled` | bool | Полнотекстовый поиск через CRM-контакт. |
+| `fieldId` | string / null | ID кастомного поля CRM (для `filterByFieldEnabled`). |
+| `fieldEntityType` | string / null | `LEAD` или `CONTACT` — где искать поле. |
+| `valueType` | enum `PipelineFilterValueType` / null | `CONSTANT` (фиксированное значение) или `SYSTEM_VARIABLE` (имя системной переменной — `phone`, `telegramId` и т.п.). |
+| `value` | string / null | Само значение или имя системной переменной. |
+| `actionOnFound` | enum `PipelineFilterAction` / null | `IGNORE` (игнорировать обращение, `isBotActive=false`) или `LINK` (привязать к существующей сделке и продолжить). |
+
+### Сценарии
+
+| Сценарий бизнеса | Настройки |
+|---|---|
+| «Если клиент уже у нас в работе — не дублировать сделку, а продолжить в существующей» | `filterEnabled=true`, `filterByPhoneEnabled=true`, `actionOnFound=LINK` |
+| «Если есть сделка — не отвечать ботом, отдать оператору» | `filterEnabled=true`, `filterByPhoneEnabled=true`, `actionOnFound=IGNORE` |
+| «Искать по нашему UTM-полю, чтобы не дублировать с лендингов» | `filterEnabled=true`, `filterByFieldEnabled=true`, `fieldId=<UTM_FIELD_ID>`, `fieldEntityType=LEAD`, `valueType=CONSTANT`, `value="lp_main_2026"`, `actionOnFound=LINK` |
+
+### Создание новых сущностей
+
+| Поле | Описание |
+|---|---|
+| `createNewLead` | Создавать ли сделку в CRM при первом обращении клиента, если фильтр не нашёл существующую (или фильтр выключен). |
+| `createNewContact` | Аналогично для контакта. |
+
+Обычно оба `true` — иначе сделки/контакты в CRM не появятся.
+
+## 4. Status movement: автоматические переходы между этапами
+
+Каждое событие в системе может автоматически двигать сделку. Настройка задаёт композитный ключ `(crmId, pipelineId, statusId)` — статус **может быть в любой воронке** активной для платформы (см. `PlatformPipeline`).
+
+### Все события
+
+| Поле | Когда срабатывает | Куда уйдёт сделка |
+|---|---|---|
+| `incomingMoveToStatus` | Пользователь написал в бот (входящее сообщение) | На указанный статус (обычно «Новый» или «В работе») |
+| `outgoingMoveToStatus` | Бот/оператор ответил пользователю | На указанный статус (обычно «Идёт диалог») |
+| `aiResponseMoveToStatus` | Бот сгенерировал и отправил ответ через LLM | На указанный статус (опционально — если хочется отделить «AI ответил» от «оператор ответил») |
+| `operatorSpeechMoveToStatus` | Оператор написал в карточку (через CRM Chat API) | На указанный статус (обычно «У оператора») |
+
+Каждое поле — это **тройка**: `*MoveToStatus`, `*MoveToStatusPipelineId`, `*MoveToStatusCrmId`. Если основное поле `null` — переход не выполняется.
+
+### Связь со `StatusType`
+
+В `CrmPipelineStatus.statusTypes[]` (массив enum `StatusType`) можно указать «семантику» этапа: `INCOMING`, `OUTGOING`, `MESSAGE_SENT`, `AI_TOOK_OVER`, `OPERATOR_TOOK_OVER`, `USER_BLOCKED`. Эти теги — для UI и аналитики (показывают, какие этапы что обрабатывают), но **не управляют автопереходами** — это делает `PipelineSettings.*MoveToStatus`.
+
+### `CrmPipelineStatus.onMessageReceivedMoveToStatus`
+
+Альтернативный механизм автоперехода — на уровне самого статуса: `null` или ID статуса, в который перейти при получении сообщения от пользователя. Может конфликтовать с `PipelineSettings.incomingMoveToStatus` — приоритет за `PipelineSettings`.
+
+### `CrmPipelineStatus.isBotActive` и `isOperatorAvailable`
+
+Не часть Pipeline Builder, но влияют на работу:
+- `isBotActive=false` → бот молчит на этом этапе.
+- `isOperatorAvailable=false` → оператор не может быть подключён через `CALL_OPERATOR`.
+
+## 5. PlatformPipeline — связь платформы с воронками
+
+Платформа может работать с **несколькими воронками** одной CRM (например, одна для лидов, другая для текущих клиентов):
+
+```json
+{
+  "platformId": "<platformId>",
+  "pipelineCrmId": "<Crm.id>",
+  "pipelineId": 1234567,
+  "isActive": true
+}
+```
+
+Это many-to-many связь. PipelineSettings может ссылаться на статусы из любой активной воронки.
+
+## 6. Inline-пример: типичный e-commerce setup
+
+```json
+{
+  "platformId": "<platformId>",
+
+  "filterEnabled": true,
+  "filterByPhoneEnabled": true,
+  "filterByFieldEnabled": false,
+  "filterByContactEnabled": false,
+  "actionOnFound": "LINK",
+
+  "createNewLead": true,
+  "createNewContact": true,
+
+  "incomingMoveToStatus": 142,
+  "incomingMoveToStatusPipelineId": 1234567,
+  "incomingMoveToStatusCrmId": "<Crm.id>",
+
+  "outgoingMoveToStatus": 143,
+  "outgoingMoveToStatusPipelineId": 1234567,
+  "outgoingMoveToStatusCrmId": "<Crm.id>",
+
+  "operatorSpeechMoveToStatus": 145,
+  "operatorSpeechMoveToStatusPipelineId": 1234567,
+  "operatorSpeechMoveToStatusCrmId": "<Crm.id>"
+}
+```
+
+Логика:
+- При первом сообщении — ищем по телефону, если уже есть — привязываем; если нет — создаём новую сделку в этапе 142.
+- При первом ответе — переводим в 143 («Идёт диалог»).
+- Когда оператор подключился — 145 («У оператора»).
+
+## 7. Inline-пример: фильтр по UTM (B2B-лендинг)
+
+Для разных лендингов — разные воронки:
+
+```json
+{
+  "filterEnabled": true,
+  "filterByFieldEnabled": true,
+  "fieldId": "987",
+  "fieldEntityType": "LEAD",
+  "valueType": "SYSTEM_VARIABLE",
+  "value": "telegramId",
+  "actionOnFound": "LINK",
+  "createNewLead": true,
+  "createNewContact": true
+}
+```
+
+Логика: ищем сделку по полю с ID `987` (например, «Telegram User ID» в LEAD), значение которого совпадает с `{telegramId}` текущего пользователя. Если найдено — привязываем; иначе создаём новую.
+
+## 8. Граничные случаи и валидация
+
+| Правило | Что AI-сервису помнить |
+|---|---|
+| `PipelineSettings` — one-to-one с Platform | Для каждой платформы максимум одна запись. |
+| `filterEnabled=true` без `filterBy*` | Бесполезно — система не знает, по чему искать. |
+| `filterByPhoneEnabled=true` для платформ без телефона (Web Widget без UTM) | Может не найти, но бот всё равно сработает (фильтр пропустится). |
+| `actionOnFound=IGNORE` | `ChatUser.isBotActive=false` — бот не отвечает. Подходит для «после ручного открытия сделки оператор сам отвечает». |
+| `actionOnFound=LINK` | `ChatUser` привязывается к существующей `leadId/bitrixDealId`. Хорошо для непрерывности. |
+| `*MoveToStatus` без всех трёх ID | Если нет `*MoveToStatusPipelineId`/`*MoveToStatusCrmId` — переход не сработает. |
+| Конфликт `aiResponseMoveToStatus` и `outgoingMoveToStatus` | Оба сработают по очереди (сначала AI, потом outgoing). Часто хватает только `outgoing`, чтобы не перегружать. |
+| Composite key статуса | Все три поля (`MoveToStatus`, `MoveToStatusPipelineId`, `MoveToStatusCrmId`) или ни одного. |
+| Удаление воронки/статуса | Если ID удалится в CRM — переход просто не выполнится (без ошибки). Регулярно проверять синхронизацию. |
+| Pipeline Builder не управляет триггерами | Это два разных механизма перевода. Триггер `CRM_MOVE_STAGE` — точечный, по условию. PipelineSettings — автоматически по событию. |
+
+## 9. Что AI-сервис должен спрашивать у клиента
+
+Перед генерацией PipelineSettings:
+
+1. «Если клиент уже есть в CRM — продолжить в существующей сделке или создать новую?» (`actionOnFound`).
+2. «Куда переводить сделку, когда клиент написал?» (`incomingMoveToStatus`).
+3. «Куда переводить, когда вы ответили?» (`outgoingMoveToStatus`).
+4. «Куда переводить, когда подключился оператор?» (`operatorSpeechMoveToStatus`).
+5. «Создавать ли новые сделки/контакты автоматически?» (`createNewLead`/`createNewContact`).
+6. «По какому ключу искать дубликаты — телефон, кастомное поле, что-то ещё?» (`filterBy*`).
+
+## 10. Связь с другими подсистемами
+
+| Подсистема | Связь |
+|---|---|
+| **Платформы** ([`11-platforms.md`](11-platforms.md)) | `PipelineSettings` принадлежит платформе (one-to-one). |
+| **CRM** ([`12-crm-integration.md`](12-crm-integration.md)) | Использует `CrmPipelineStatus` (composite key). `StatusType` теги влияют на UI/аналитику. |
+| **Триггеры** ([`04-triggers-and-actions.md`](04-triggers-and-actions.md)) | Триггер `CRM_MOVE_STAGE` — независимый механизм перевода (точечный, по условию). Совместимы — могут работать параллельно. |
+| **Маршрутизация** ([`06-routing.md`](06-routing.md)) | `LEAD_STATUS` стратегия router-а опирается на `ChatUser.leadStatusId`, который обновляется автоматически после переходов через PipelineSettings. |
+| **AgentBehavior** ([`10-agent-behavior.md`](10-agent-behavior.md)) | `aiErrorTargetStageId` — куда перевести при ошибке LLM (читает напрямую `pipelineId` текущей воронки, если `null`). |

package/dist/resources/docs/pipeline-settings-deep.md

@@ -0,0 +1,221 @@
+# 24. Pipeline Settings — глубокая конфигурация
+
+> **Источник правды:** `ai-aniomaly/docs/ai-prompt-builder/24-pipeline-settings-deep.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. Назначение
+
+`PipelineSettings` — расширение [14-pipeline-builder.md](14-pipeline-builder.md). Настройки 1:1 с `Platform`, отвечают за две группы поведения:
+
+1. **Фильтр поиска существующих сделок** — когда новый клиент пишет, нужно ли искать его уже-имеющуюся сделку и как с ней поступить.
+2. **Автопереход статусов** — 6 разных триггеров системного перемещения сделки по воронке.
+
+Базовый файл [14-pipeline-builder.md](14-pipeline-builder.md) описывал часть полей; здесь — **полная JSON-схема** со всеми 30+ полями.
+
+## 2. Полная JSON-схема `PipelineSettings`
+
+```json
+{
+  "id": "uuid",
+  "platformId": "<Platform.id>",
+
+  // === FILTER SEARCH (поиск существующих сделок) ===
+  "filterEnabled": true,
+  "filterByPhoneEnabled": true,
+  "filterByFieldEnabled": false,
+  "filterByContactEnabled": false,
+  "fieldId": null,
+  "fieldEntityType": null,
+  "valueType": null,
+  "value": null,
+  "actionOnFound": "LINK",
+
+  // === CREATION FLAGS ===
+  "createNewLead": true,
+  "createNewContact": true,
+
+  // === STATUS MOVEMENT (6 триггеров) ===
+  "aiResponseMoveToStatus": 142,
+  "aiResponseMoveToStatusPipelineId": 1234567,
+  "aiResponseMoveToStatusCrmId": "<Crm.id>",
+
+  "operatorSpeechMoveToStatus": 145,
+  "operatorSpeechMoveToStatusPipelineId": 1234567,
+  "operatorSpeechMoveToStatusCrmId": "<Crm.id>",
+
+  "incomingMoveToStatus": 140,
+  "incomingMoveToStatusPipelineId": 1234567,
+  "incomingMoveToStatusCrmId": "<Crm.id>",
+
+  "outgoingMoveToStatus": 141,
+  "outgoingMoveToStatusPipelineId": 1234567,
+  "outgoingMoveToStatusCrmId": "<Crm.id>",
+
+  "messageSentMoveToStatus": null,
+  "messageSentMoveToStatusPipelineId": null,
+  "messageSentMoveToStatusCrmId": null,
+
+  "userBlockedMoveToStatus": 199,
+  "userBlockedMoveToStatusPipelineId": 1234567,
+  "userBlockedMoveToStatusCrmId": "<Crm.id>",
+
+  // === GLOBAL ===
+  "alwaysMoveToAiStatus": false,
+  "preventBackwardMovement": true
+}
+```
+
+## 3. Группа: Фильтр поиска существующих сделок
+
+### 3.1. Master switch
+
+`filterEnabled: true` — без этого ни один из под-флагов не работает.
+
+### 3.2. Три режима поиска (взаимоисключающие, AI-сервис выбирает один)
+
+| Флаг | Поведение | Когда использовать |
+|---|---|---|
+| `filterByPhoneEnabled` | Искать сделку по полю `phone` контакта **И** по кастомным полям сделки, в которых есть телефон | По умолчанию для всех платформ с телефоном (Wazzup, Avito, SMS) |
+| `filterByFieldEnabled` | Искать по конкретному кастомному полю CRM | Когда у клиента CRM-поле «UTM» или «email», и нужно дедуплицировать по нему |
+| `filterByContactEnabled` | Полнотекстовый поиск через **контакт** CRM (AmoCRM Search Contact API) | Когда у клиента нет фиксированных полей, но нужен fuzzy-матч |
+
+### 3.3. Параметры для `filterByFieldEnabled`
+
+```json
+{
+  "filterByFieldEnabled": true,
+  "fieldId": "12345",
+  "fieldEntityType": "CONTACT",
+  "valueType": "SYSTEM_VARIABLE",
+  "value": "phone"
+}
+```
+
+| Поле | Тип | Описание |
+|---|---|---|
+| `fieldId` | string | ID кастомного поля в CRM (числовой ID) |
+| `fieldEntityType` | `'LEAD'` / `'CONTACT'` | Где искать поле — у сделки или у контакта |
+| `valueType` | enum `PipelineFilterValueType` | `CONSTANT` (искать по фиксированной строке) / `SYSTEM_VARIABLE` (брать значение из системной переменной типа `{phone}`) |
+| `value` | string | Либо константа, либо имя переменной (`phone`, `telegramId`, etc.) |
+
+### 3.4. Действие при нахождении сделки
+
+`actionOnFound` — enum `PipelineFilterAction`:
+
+| Значение | Поведение |
+|---|---|
+| `LINK` | Привязать `ChatUser` к найденной сделке. Бот будет общаться с этой сделкой |
+| `IGNORE` | Игнорировать существующую сделку, создать новую (если `createNewLead=true`) |
+
+### 3.5. Флаги создания
+
+| Флаг | Поведение | Default |
+|---|---|---|
+| `createNewLead` | Создать новую сделку, если ничего не найдено или `actionOnFound=IGNORE` | true |
+| `createNewContact` | Создать новый контакт, если ничего не найдено | true |
+
+> Если `createNewLead=false` и сделка не найдена → бот будет общаться без CRM-сделки. CRM-actions триггеров (`CRM_MOVE_STAGE`) silently не сработают.
+
+## 4. Группа: Автопереход статусов
+
+`PipelineSettings` определяет **6 триггеров** автоматического перевода сделки по воронке. Каждый триггер — composite-FK на `CrmPipelineStatus` (3 поля: `<X>MoveToStatus`, `<X>MoveToStatusPipelineId`, `<X>MoveToStatusCrmId`).
+
+| Триггер | Когда срабатывает | Назначение |
+|---|---|---|
+| `aiResponseMoveToStatus` | После каждого ответа AI боту | Маркировка «бот говорил с клиентом» |
+| `operatorSpeechMoveToStatus` | После каждого сообщения от оператора-человека | Маркировка «оператор уже подключился» |
+| `incomingMoveToStatus` | При первом входящем сообщении от пользователя | Маркировка «появился новый запрос» |
+| `outgoingMoveToStatus` | При первом исходящем сообщении (например, follow-up) | Маркировка «бот написал первым» |
+| `messageSentMoveToStatus` | После любого исходящего сообщения (повторяется) | Аналитика «сколько касаний с клиентом» |
+| `userBlockedMoveToStatus` | Когда пользователь блокирует бота / пишет «STOP» | Архив для очистки воронки |
+
+### 4.1. Composite-FK
+
+В CRM статус идентифицируется тройкой: `(crmId, pipelineId, statusId)`. AI-сервис всегда заполняет все три поля или все три оставляет null. Заполнить только `<X>MoveToStatus` без `<X>MoveToStatusPipelineId` нельзя — runtime не поймёт, в какую воронку.
+
+### 4.2. Конфликты и приоритеты
+
+| Конфликт | Поведение |
+|---|---|
+| Триггер `CRM_MOVE_STAGE` сработал ПЕРЕД ответом ИИ | После ответа ИИ применится `aiResponseMoveToStatus` (если задан) — может перезаписать только что выставленный статус |
+| `incomingMoveToStatus` И `aiResponseMoveToStatus` оба заданы | На входящем сначала переведётся в incoming-статус, потом — после ответа — в ai-response статус. Клиент видит две движухи в воронке |
+| `alwaysMoveToAiStatus=true` | Любой ai-response игнорирует текущую колонку и форсит переход в `aiResponseMoveToStatus` (даже если бот уже там) |
+
+### 4.3. Связь с типами статусов (`CrmPipelineStatus.statusTypes[]`)
+
+| Триггер | Соответствующий `StatusType` |
+|---|---|
+| `incomingMoveToStatus` | `INCOMING` |
+| `outgoingMoveToStatus` | `OUTGOING` |
+| `messageSentMoveToStatus` | `MESSAGE_SENT` |
+
+> `CrmPipelineStatus.statusTypes` — массив, **может содержать несколько типов**. Например, статус «Бот общается» может быть и `INCOMING`, и `MESSAGE_SENT`. UI Pipeline Builder использует это для отметки колонок.
+
+## 5. Глобальные правила
+
+### `alwaysMoveToAiStatus`
+
+Если `true`: после **любого** ответа AI сделка форсированно переходит в `aiResponseMoveToStatus`, даже если она уже в колонке с включённым `isBotActive`. Это полезно, когда у клиента 5-10 «AI-колонок» и важно сводить всё в одну для аналитики.
+
+### `preventBackwardMovement`
+
+Если `true`: автоматический move-to-status **не сработает**, если целевой статус имеет `sort` меньше текущего. Защита от бесконечного «маятника» (бот пишет → ai-response двигает назад → потом снова движение).
+
+> Работает per-pipeline (учитывается только в пределах одной воронки).
+
+## 6. `PlatformPipeline` (M2M связь)
+
+Платформа может работать с **несколькими активными воронками одновременно**:
+
+```json
+{
+  "id": "uuid",
+  "platformId": "<Platform.id>",
+  "pipelineId": 1234567,
+  "pipelineCrmId": "<Crm.id>",
+  "sort": 0
+}
+```
+
+Используется когда:
+- Один Telegram-бот ведёт лидов и в основную воронку, и в воронку «холодных».
+- Несколько воронок Bitrix24 (для разных продуктов).
+
+Без хотя бы одной записи `PlatformPipeline` все CRM-actions триггеров silently не сработают (платформа «не знает» в какую воронку кладть сделки).
+
+## 7. Что AI-сервис описывает клиенту
+
+Стандартный workflow настройки Pipeline Settings:
+
+1. **Подключите Crm** (AmoCRM/Bitrix24/GetCourse) — см. [12-crm-integration.md](12-crm-integration.md).
+2. **Создайте `PlatformPipeline`** для каждой воронки, в которой бот должен работать.
+3. **Включите `filterEnabled`** и выберите режим поиска (`filterByPhoneEnabled` для Wazzup/SMS, `filterByContactEnabled` для AmoCRM).
+4. **Задайте `actionOnFound`** — обычно `LINK` (продолжить с существующей сделкой).
+5. **Настройте 1-3 автоперехода**, которые вам реально нужны:
+   - Минимум: `aiResponseMoveToStatus` для трекинга «бот ответил».
+   - Часто: `incomingMoveToStatus` + `outgoingMoveToStatus` для разделения первичной воронки.
+   - Реже: `userBlockedMoveToStatus` для архивирования.
+6. **Не включайте всё подряд** — больше автопереходов = больше движений в воронке = операторы запутаются.
+7. **`preventBackwardMovement=true`** — почти всегда нужен, защищает от глюков.
+
+## 8. Граничные случаи
+
+| Ситуация | Поведение |
+|---|---|
+| `<X>MoveToStatus` указан, но не существует в CRM | Runtime логирует ошибку, переход не происходит |
+| `<X>MoveToStatusPipelineId` не совпадает с активной `PlatformPipeline` | Runtime отклонит переход (статус не из «своей» воронки) |
+| `filterByPhoneEnabled=true`, но у платформы нет телефона (Telegram Bot без shareContact) | Поиск не выполняется, ведёт себя как `filterEnabled=false` |
+| `actionOnFound=IGNORE` И `createNewLead=false` | Сделка не создаётся, бот общается «в воздух» — CRM-actions не сработают |
+| Несколько матчей в `filterByContactEnabled` | Берётся самая свежая сделка (по `updatedAt`) |
+| Клиент сменил `filterByFieldEnabled` на лету | Существующие связи `ChatUser ↔ Deal` не пересчитываются — только для новых |
+
+## 9. Связь с другими подсистемами
+
+| Подсистема | Связь |
+|---|---|
+| **Pipeline Builder** ([14-pipeline-builder.md](14-pipeline-builder.md)) | Базовая часть — UI и `CrmPipelineStatus.statusTypes` |
+| **CRM** ([12-crm-integration.md](12-crm-integration.md)) | `Crm`, `CrmPipeline`, `CrmPipelineStatus`, поля контакта |
+| **Платформы** ([11-platforms.md](11-platforms.md)) | `Platform.dealMarkerType`, `responsibleAssigneeStrategy`, `sendToCrm` |
+| **Триггеры** ([04-triggers-and-actions.md](04-triggers-and-actions.md)) | `CRM_MOVE_STAGE` action — ручное переключение, может конфликтовать с автопереходами |
+| **Routing** ([06-routing.md](06-routing.md)) | `LEAD_STATUS` маршрутизация работает поверх той же `CrmPipelineStatus` модели |