# MAX CF7 Routing Add-on

## Назначение

Допуслуга позволяет в рамках одного сайта и одной интеграции `max_cf7` направлять разные формы в разные получатели MAX:
- в личные сообщения,
- в приватные чаты,
- в группы.

Базовый принцип остается прежним:
- на клиентском WordPress-сайте хранится один `integration_key`;
- текущий получатель интеграции остается получателем по умолчанию;
- правила маршрутизации работают на стороне `cacr.ru`;
- если правило не совпало или у него не настроен собственный получатель, используется fallback на получателя по умолчанию.

## Почему так

Это не ломает текущую модель:
- `1 сайт = 1 интеграция = 1 ключ`;
- не требуется заводить несколько подключений на один и тот же сайт;
- текущая доставка продолжает работать даже без правил маршрутизации.

## Что уже уходит с сайта

Плагин передает на портал данные, пригодные для маршрутизации:
- `source` (`cf7` или `generic_mail_form`);
- `form_id`;
- `form_title`;
- `page_url`;
- `fields`.

Этого достаточно для правил вроде:
- `form_id = 123 -> чат продаж`;
- `page_url contains /contacts/ -> чат поддержки`;
- `field route_key = franchise -> отдельная группа`.

## Рекомендуемая схема разметки форм

### Contact Form 7

Рекомендуется одно из двух:
1. Маршрутизировать по `form_id`.
2. Добавить hidden-поле `route_key`.

Пример:

```text
[hidden route_key default:sales]
```

### Кастомные формы через `wp_mail`

Если используется hidden-поле, оно должно:
1. попадать в `POST`,
2. попадать в тело письма.

Важно: generic mail-поток на клиентском сайте разбирает не весь `POST`, а уже готовое письмо. Если `route_key` не включен в письмо, портал его не увидит.

## Рекомендуемая модель правил

Минимальная безопасная логика:
1. Проверить правила сверху вниз.
2. Первое совпавшее правило побеждает.
3. Если ни одно правило не совпало, использовать получателя по умолчанию.

Поддерживаемые поля условий:
- `source`
- `form_id`
- `form_title`
- `page_url`
- `field` + `field_key`

Поддерживаемые операторы:
- `equals`
- `not_equals`
- `contains`
- `exists`

## Как это настраивается в CACR

На стороне CACR маршруты редактируются в визуальном builder'е внутри подключения `max_cf7`:
- маршрут = карточка правила;
- внутри карточки задаются приоритет, получатель и набор условий;
- порядок проверки остается прежним: сверху вниз по приоритету, первое совпадение побеждает;
- если правило совпало, но у него нет валидного получателя, используется fallback на получателя по умолчанию.

## Пример JSON конфигурации

JSON ниже нужен как технический референс для хранения и отладки. Основной способ настройки для менеджера или администратора сайта: визуальный builder в кабинете CACR.

```json
{
  "rules": [
    {
      "id": "sales_cf7",
      "name": "Продажи CF7",
      "is_active": true,
      "priority": 10,
      "fallback_to_default": true,
      "conditions": [
        {
          "field": "form_id",
          "operator": "equals",
          "value": "123"
        }
      ],
      "recipient": {
        "mode": "bound_group"
      }
    },
    {
      "id": "franchise_field",
      "name": "Франшиза по route_key",
      "is_active": true,
      "priority": 20,
      "fallback_to_default": true,
      "conditions": [
        {
          "field": "field",
          "field_key": "route_key",
          "operator": "equals",
          "value": "franchise"
        }
      ],
      "recipient": {
        "mode": "custom_group",
        "id": "-1001234567890",
        "label": "Franchise MAX Group"
      }
    }
  ]
}
```

## Режимы получателя в правилах

- `default` — получатель по умолчанию интеграции.
- `bound_direct` — текущая привязанная личка интеграции.
- `bound_group` — текущий привязанный чат/группа интеграции.
- `custom_direct` — произвольный `user_id`.
- `custom_group` — произвольный `chat_id`.

## Что важно помнить

- Если нужна маршрутизация без риска поломки, оставляйте рабочий получатель по умолчанию.
- Для generic-form потока добавляйте `route_key` и в форму, и в шаблон письма.
- Не используйте `form_title` как единственный стабильный идентификатор, если форму могут переименовать.
- Для долгой поддержки лучше опираться на `form_id` или `route_key`.