cf7-spam-to-telegram/docs/superpowers/specs/2026-04-17-cf7-spam-to-telegram-design.md

# CF7 Spam → Telegram — дизайн-документ

**Дата:** 2026-04-17
**Автор:** Владимир Брызгалов
**Статус:** утверждён к планированию реализации

---

## 1. Цель и предпосылки

На сайтах Владимира (27 доменов на Beget, тематика — сиделки/няни/работа) через формы Contact Form 7 регулярно приходит спам. Встроенные фильтры (Akismet, honeypot, `wpcf7_spam`) отсекают его от обычного канала уведомлений — но среди отсечённых **иногда бывают реальные заявки клиентов**. Их теряют.

**Цель плагина:** пересылать в общую Telegram-группу все submissions CF7, помеченные как спам, с полным содержимым формы и эвристической оценкой «похоже клиент / неясно / похоже спам», чтобы менеджеры могли бегло просмотреть отсечённое и не упустить реальные обращения.

**Не-цели:**
- Замена существующего плагина `cf7-telegram` (он остаётся и шлёт обычные «не-спам» заявки своим чередом).
- Борьба со спамом (уменьшение количества) — плагин пассивный наблюдатель.
- Двусторонний канал (ответ клиенту/пометка «не спам» из Telegram). Отложено на потенциальную v2.

## 2. Целевая среда

| Параметр | Значение |
|---|---|
| Хостинг | Beget shared (пилот — `washanyanya.ru`, затем остальные 26 сайтов аккаунта `pasha072`) |
| WordPress | 6.9.4+ |
| PHP | 7.4+ (все целевые сайты имеют доступ до 8.3) |
| Расширения PHP | `intl`, `curl`, `mbstring` (проверено — есть на всех версиях Beget) |
| Зависимости | Contact Form 7 + Flamingo (обязательны). Composer НЕ используется в проде |
| Локализация | Только русский, строки хардкодятся без `__()` |

## 3. Архитектурный выбор

Рассмотрены три подхода:

1. **Независимый плагин** — собственная конфигурация, не зависит от `cf7-telegram`.
2. **Форк `cf7-telegram`** — доработка чужой кодовой базы. Отклонён: дорого в поддержке на 27 сайтах, автообновления ломают форк.
3. **Надстройка над `cf7-telegram`** — переиспользование его опций. Отклонён: он не предоставляет публичного API, залезание в его внутренности хрупко; нельзя разделить спам и обычный поток по разным чатам.

**Выбран подход 1.** Дублирование ~50 строк HTTP-кода приемлемо ради изоляции, независимой конфигурации и свободы выбора отдельной TG-группы для спама.

## 4. Слаг и идентификация

- **Слаг плагина / папка:** `cf7-spam-to-telegram`
- **Текстовый префикс функций/опций/таблицы:** `cf7stg_`
- **Префикс WP-фильтров/хуков расширения:** `cf7stg_`
- **Константы wp-config (опциональные override'ы):** `SPAM2TG_BOT_TOKEN`, `SPAM2TG_CHAT_ID`

## 5. Структура файлов

```
cf7-spam-to-telegram/
├── cf7-spam-to-telegram.php         # Главный файл с WP-заголовком, bootstrap
├── uninstall.php                     # Удаление опций и таблицы очереди
├── includes/
│   ├── class-plugin.php              # Singleton, регистрация хуков, автолоадер
│   ├── class-activator.php           # Создание таблицы, дефолтные опции
│   ├── class-settings.php            # Чтение/запись опций, приоритет констант
│   ├── class-crypto.php              # Шифрование токена через AUTH_KEY
│   ├── class-queue.php               # CRUD очереди, dedup, retention
│   ├── class-dispatcher.php          # WP-Cron тики, отправка, backoff
│   ├── class-telegram-client.php     # wp_remote_post, обработка кодов TG API
│   ├── class-telegram-exception.php  # TelegramException с флагом is_permanent
│   ├── class-classifier.php          # Эвристика, score → label, reasons
│   ├── class-phone-parser.php        # Нормализация RU-телефонов
│   ├── class-domain-formatter.php    # Punycode → кириллица (idn_to_utf8)
│   ├── class-field-detector.php      # Fallback поиск имени/email когда ключи формы нестандартны
│   ├── class-message-formatter.php   # Сборка HTML-сообщения
│   ├── class-retro-importer.php     # Ретро-выгрузка из Flamingo
│   ├── class-flamingo-helper.php    # Извлечение полей и reason из Flamingo
│   └── sources/
│       ├── interface-spam-source.php
│       └── class-cf7-source.php      # Хуки wpcf7_spam / wpcf7_submission
├── admin/
│   ├── class-settings-page.php       # Страница Настройки → CF7 Spam → TG
│   ├── class-dashboard-widget.php    # Виджет, показ только при ошибках
│   └── views/
│       ├── settings.php
│       └── dashboard-widget.php
├── tests/
│   ├── bootstrap.php                 # Автолоадер для юнит-тестов
│   ├── ClassifierTest.php
│   ├── PhoneParserTest.php
│   ├── DomainFormatterTest.php
│   └── MessageFormatterTest.php
├── composer.json                     # Только dev-зависимости (phpunit)
├── phpunit.xml
├── .gitignore
└── readme.txt                        # Стандартный WP readme (краткий)
```

**Автолоадер:** простой `spl_autoload_register` в `class-plugin.php`, маппинг `Cf7stg\ClassName` → `includes/class-class-name.php`. Composer используется только для dev (PHPUnit).

## 6. Поток обработки входящего spam-события

```
┌────────────────────────────────────────────────────────────────┐
│ CF7 form submit                                                 │
└─────────────┬──────────────────────────────────────────────────┘
              ▼
   [ filter wpcf7_spam, priority 9999 ]          ←── основной триггер
              │
              │ если $spam === true:
              ▼
     CF7Source::handle_spam_submission($submission)
              │
              ├─► Flamingo сохраняет запись (priority 10,
              │   до или после нашего хука — неважно)
              │
              ▼
     ┌───────────────────────────────────────┐
     │ Сбор полей: $submission->get_posted_data() │
     │ Определение reason (Akismet/Honeypot/…)     │
     │ Извлечение IP, UA, UTM, Referer            │
     │ Classifier::classify(fields) → label       │
     │ MessageFormatter::build(...) → text + markup│
     │ Flamingo post ID (через Flamingo_Helper)   │
     │ Queue::enqueue(payload)                    │
     └───────────────────────────────────────┘
              │
              ▼
         return $spam (без изменений)
```

Fallback — `action wpcf7_submission, priority 20`: если `$submission->get_status() === 'spam'` и очередь ещё не содержит соответствующий `flamingo_post_id` — добавляем запись (страховка на случай honeypot'ов, которые ставят статус напрямую, минуя фильтр `wpcf7_spam`).

```
┌────────────────────────────────────────────────────────────────┐
│ WP-Cron (кастомный интервал every_minute)                       │
└─────────────┬──────────────────────────────────────────────────┘
              ▼
      Dispatcher::tick()
              │
              ▼
     Queue::fetch_pending(limit=5, where next_try_at <= NOW)
              │
              ▼
     Для каждой записи:
       TelegramClient::send_message(text, reply_markup)
       ├─ success → Queue::mark_sent(id, now)
       ├─ temp fail (5xx/429/network) → Queue::reschedule(id, attempts+1,
       │                                   backoff[60, 300, 1800, 3600])
       └─ perm fail (401/403/400 chat not found) или attempts>=5
                                            → Queue::mark_failed(id, err)

       usleep(100ms) между отправками (TG rate-limit ~30 msg/s)
```

## 7. Схема БД

Таблица `{prefix}cf7stg_queue`:

| Поле | Тип | Комментарий |
|---|---|---|
| `id` | `BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY` | |
| `flamingo_post_id` | `BIGINT UNSIGNED NULL` | id записи Flamingo; NULL если не создалась |
| `form_id` | `BIGINT UNSIGNED NULL` | id CF7-формы |
| `source_key` | `VARCHAR(40) NOT NULL` | `'cf7'` (задел под другие источники) |
| `payload_json` | `LONGTEXT NOT NULL` | `{text, reply_markup}` в JSON |
| `label` | `VARCHAR(10) NOT NULL` | `client` / `unclear` / `spam` |
| `is_retro` | `TINYINT(1) NOT NULL DEFAULT 0` | 1 если из ретро-выгрузки |
| `status` | `VARCHAR(20) NOT NULL DEFAULT 'pending'` | `pending` / `sent` / `failed` |
| `attempts` | `SMALLINT UNSIGNED NOT NULL DEFAULT 0` | |
| `last_error` | `TEXT NULL` | последняя ошибка TG |
| `next_try_at` | `DATETIME NULL` | для backoff |
| `created_at` | `DATETIME NOT NULL` | |
| `sent_at` | `DATETIME NULL` | |

**Индексы:**
- `KEY idx_status_next (status, next_try_at)` — для Dispatcher
- `UNIQUE KEY uq_flamingo (flamingo_post_id, is_retro)` — dedup

**Retention:** ежедневный WP-Cron `cf7stg_cleanup` удаляет записи `status='sent'` старше 30 дней.

## 8. Classifier — эвристика

Метод: `Classifier::classify(array $fields, array $meta): array` возвращает:

```php
[
    'score'   => int,                       // итоговый балл
    'label'   => 'client' | 'unclear' | 'spam',
    'reasons' => [                           // причины со знаком и весом
        ['sign' => '+', 'weight' => 3, 'text' => 'телефон RU'],
        ['sign' => '-', 'weight' => 2, 'text' => 'ключевое слово: SEO'],
        ...
    ],
]
```

**Веса (дефолт):**

| Признак | Вес |
|---|---|
| Телефон парсится как RU (+7/8, 10-11 цифр) | **+3** |
| Имя — только кириллица, без цифр/URL | +1 |
| E-mail на ру-домене (yandex.ru, mail.ru, gmail.com, rambler.ru, ya.ru) | +1 |
| Текст — кириллица, > 10 симв., не одна ссылка | +1 |
| URL в любом поле (`http://`, `https://`, `www.`) | **−3** |
| Ключевое слово (см. список) — `−2` за вхождение, капается на **−6** | −2 × min(n, 3) |
| Имя или текст — только латиница | −1 |
| Honeypot сработал (reason='Honeypot') | **−5** *(и hard override: label=spam)* |

**Ключевые слова (дефолт, матчинг по подстрокам через `mb_stripos`, регистронезависимо):**

- SEO/продвижение: `SEO`, `СЕО`, `продвижение сайта`, `backlinks`, `обратные ссылки`, `позиции в поиске`
- Финансы: `bitcoin`, `биткоин`, `crypto`, `криптовалют`, `forex`, `форекс`, `trading`, `трейдинг`, `loan`, `займ`, `микрозайм`, `инвестиции`, `заработок онлайн`, `удалённая работа без`, `MLM`, `сетевой маркетинг`
- Казино: `casino`, `казино`, `ставки`, `betting`, `букмекер`
- БАДы/диеты: `бад`, `биодобав`, `супер фуд`, `super food`, `детокс`, `похудение`, `похудет`, `диетическ`, `жиросжиг`
- Мед. препараты: `viagra`, `виагра`, `cialis`, `сиалис`, `pharmacy`, `фарма`, `дженерик`
- Порно/эскорт: `porn`, `xxx`, `adult`, `porno`, `порно`, `эскорт`, `проститу`, `секс-знакомств`, `интим-услуг`

**Пороги:**
- если `reason === 'Honeypot'` → `label = 'spam'` **(hard override, всегда)**
- иначе, если `score >= 3` → `label = 'client'` (🟢 похоже клиент)
- иначе, если `score <= -2` → `label = 'spam'` (🔴 похоже спам)
- иначе → `label = 'unclear'` (🟡 неясно)

**Кастомизация** — через WP-фильтры:
```php
apply_filters('cf7stg_classifier_weights', $default_weights);
apply_filters('cf7stg_classifier_keywords', $default_keywords);
apply_filters('cf7stg_classifier_thresholds', ['client' => 3, 'spam' => -2]);
```

**Поиск полей формы.** Сначала пробуются известные CF7-ключи — `your-name`, `name`, `имя`, `fio` для имени; `your-email`, `email`, `e-mail`, `mail` для e-mail; `your-message`, `message`, `comment`, `сообщение`, `вопрос` для текста. Если ничего не нашлось (например, на сайте форма с кастомными именами полей `text-211`, `name_user` и т.п.), подключается `FieldDetector`:

- `find_name(fields)` — первое значение без цифр/URL/@, длиной 2..80, состоящее только из letter-characters (любой скрипт), пробелов, дефисов и апострофов.
- `find_email(fields)` — первое значение, матчащее `^\S+@\S+\.\S+$`.

Телефон всегда ищется `PhoneParser::parse()` по конкатенации всех полей — имена ключей не важны.

## 9. MessageFormatter — формат сообщения в Telegram

- **parse_mode:** `HTML` (строже и предсказуемее, чем MarkdownV2).
- Все пользовательские значения прогоняются через `esc_html()` перед вставкой.
- Лимит 4096 символов. Переполнение отсекается в теле `💬`, остаток заменяется `…[обрезано]`.
- Для ретро-выгрузки добавляется префикс `📂 Ретроспектива  ·  ` перед меткой классификации.

**Шаблон:**

```
{retro_prefix}{label_emoji} {label_text}
🌐 {site_title}  ·  форма «{form_title}»
🗓 {submitted_at}

📱 {phone_formatted | "(не указан)"}
👤 {name | "(не указано)"}
📧 {email | "(не указан)"}

💬 {message | "(пусто)"}

⚙️ Попало в спам: {reason}
📊 Классификация: {reasons_joined_by_comma}
🌍 IP {ip} · UA {user_agent_short}
{utm_block_if_any}
{other_fields_block_if_any}
```

**Inline-клавиатура:**
- `reply_markup = null` всегда. Telegram Bot API отклоняет `tel:` URLs в inline_keyboard с ошибкой HTTP 400 `Wrong port number specified in the URL`. Номер показывается в теле сообщения (строка `📱 ...`), мобильный TG-клиент автоматически делает его кликабельным.

**Site title:** `Settings::get_site_title()` возвращает либо оверрайд из настроек, либо декодированный через `idn_to_utf8()` host из `home_url()`. Например, `xn--80aae0ca7d8bb.xn--p1ai` → `вашаняня.рф`.

## 10. Ретроспективная выгрузка

**UI:** на странице настроек — блок «Ретроспективная выгрузка из Flamingo»:
- `count` (int, default 10, max 50)
- `days` (int, default 0; 0 = без ограничения)
- `allow_repeat` (checkbox)
- кнопка «Добавить в очередь»

**Обработка (синхронно при нажатии):**

```php
RetroImporter::import(int $count, int $days, bool $allow_repeat): array {
    // WP_Query по flamingo_inbound со статусом flamingo-spam,
    //   orderby=date DESC, posts_per_page=min(count, 50),
    //   фильтр по дате если $days > 0
    //
    // Для каждой записи:
    //   if (!$allow_repeat && Queue::exists_for_flamingo($post->ID)) skip;
    //   извлечь поля → Classifier → MessageFormatter (is_retro=true) → Queue::enqueue
    //
    // return ['added' => N, 'skipped' => M]
}
```

UI сообщает: «Добавлено 8, пропущено 2 (уже отправлено ранее)». Собственно доставка в TG — через общий WP-Cron цикл, в течение минуты.

## 11. Страница настроек

Путь: **Настройки → CF7 Spam → Telegram** (`Settings API`).

**Поля:**
- Bot Token — `password`, шифруется при сохранении (см. §12). Если задан `SPAM2TG_BOT_TOKEN` — поле readonly с подсказкой.
- Chat ID — `text`. Если задан `SPAM2TG_CHAT_ID` — readonly.
- Заголовок сайта — `text`, пустое значение = авто-декодированный домен.
- Кнопка «Отправить тестовое сообщение» — шлёт пробный текст в настроенный чат, показывает статус.
- Блок «Ретроспективная выгрузка» — см. §10.
- Блок «Состояние очереди» — счётчики pending/sent-за-сутки/failed + кнопки «Повторить все ошибочные» и «Очистить отправленные».

**Capability:** `manage_options`. Все POST-формы — с `wp_nonce_field` + проверка `check_admin_referer`.

## 12. Безопасность

- **Токен в БД шифруется** алгоритмом `openssl_encrypt('AES-256-CBC', ...)`, ключ — `hash_hmac('sha256', 'cf7stg_token', AUTH_KEY)`, IV хранится рядом с шифротекстом. При чтении:
  - попытка дешифровать. Если ключ изменился (`AUTH_KEY` перевыпустили) — дешифровка упадёт; UI показывает «Токен повреждён, введите заново».
- **Константы wp-config** (`SPAM2TG_BOT_TOKEN`, `SPAM2TG_CHAT_ID`) имеют приоритет над БД. Когда активны — поля в UI readonly.
- Все входы админки — через `capability manage_options` + nonce.
- Все внешние значения в TG-сообщениях — через `esc_html()`.
- `TelegramClient` — через `wp_remote_post` (автоматически использует настройки прокси WP, timeout=10s). Никаких `curl_exec`/`fopen`/`exec`.

## 13. WP-Cron

**Регистрация при активации (`register_activation_hook`):**

```php
if (!wp_next_scheduled('cf7stg_dispatch')) {
    wp_schedule_event(time(), 'cf7stg_every_minute', 'cf7stg_dispatch');
}
if (!wp_next_scheduled('cf7stg_cleanup')) {
    wp_schedule_event(time() + 3600, 'daily', 'cf7stg_cleanup');
}
```

**Кастомный интервал** — через `cron_schedules` фильтр:
```php
$schedules['cf7stg_every_minute'] = ['interval' => 60, 'display' => 'Раз в минуту (CF7 Spam → TG)'];
```

**Деактивация (`register_deactivation_hook`):** снимаем оба события через `wp_unschedule_event`.

**Ограничения shared-хостинга:** WP-Cron срабатывает при HTTP-запросах к сайту. При малом трафике события могут опаздывать. В UI настроек — короткая подсказка: «Для точности можно настроить внешний cron на `wp-cron.php`».

## 14. Dashboard-виджет

`add_action('wp_dashboard_setup', ...)` регистрирует виджет `cf7stg_dashboard_status` **всегда** (после пилота: пользователь ожидает увидеть быстрый статус, а не ориентироваться только на появление «тревожной» лампы).

Заголовок зависит от состояния:
- `failed > 0` → `⚠️ CF7 Spam → Telegram: ошибки доставки`
- иначе → `CF7 Spam → Telegram`

Содержимое:

```
[если !is_configured: ⚙️ Плагин не настроен — укажите Bot Token и Chat ID в настройках.]

⏳ В очереди: N · ✅ За сутки: M · [✖|⚠️] Ошибки: K

[если K > 0:
Последние ошибки доставки (TG-API):
• {created_at} — {last_error}
• ...
]

[Открыть настройки →]
```

## 15. Обработка ошибок Telegram API

`TelegramClient::send_message()` бросает `TelegramException`, у которого метод `is_permanent(): bool`.

**Перманентные (сразу `failed`, без ретраев):**
- HTTP 401 — токен неверный
- HTTP 403 — бот забанен/удалён из группы
- HTTP 400 + описание `chat not found` — неправильный chat_id
- HTTP 400 + `bot was blocked by the user` (если кто-то случайно настроил личный чат)

**Временные (ретрай с backoff):**
- HTTP 429 — чтимо `retry_after` из ответа (не меньше заданного backoff)
- HTTP 500/502/503/504 — ошибка сервера TG
- сетевой таймаут / `WP_Error` от `wp_remote_post`

**Backoff:** попытки 1→2→3→4→5 → паузы 60/300/1800/3600/3600 секунд. После 5 попыток — `failed`.

## 16. Тесты (PHPUnit, без WP)

**Запуск:** `composer install`, `vendor/bin/phpunit`. На проде composer не нужен, в `.gitignore` — `vendor/` и `composer.lock`.

**Покрываются (целевые классы):**

| Класс | Кейсов | Темы |
|---|---|---|
| `ClassifierTest` | ~15 | реальная заявка → client; спам с URL+SEO → spam; honeypot перекрывает положительные сигналы; пустые поля → unclear; несколько ключевых слов капаются на −6; фильтры кастомизации |
| `PhoneParserTest` | ~10 | форматы `+7(...)...`, `8...`, зарубежный → is_russian=false, несколько телефонов → первый, мусор → null |
| `DomainFormatterTest` | ~5 | xn-- → кириллица, обычные домены → без изменений, некорректный IDN → как есть без exception |
| `MessageFormatterTest` | ~8 | полный набор полей → ожидаемый HTML; без телефона → без inline-кнопки; длинное сообщение → обрезается; HTML-инъекция в поле → экранирование; префикс ретро |

**Не покрываются автотестами:**
- `Queue`, `Dispatcher`, `CF7Source`, `TelegramClient`, админ-страницы — требуют WP-окружения.
- Проверяются вручную: кнопка «Тестовое сообщение», пилот на `washanyanya.ru`, отправка реальной спам-формы.

## 17. Жизненный цикл плагина

**Activation (`register_activation_hook`):**
1. Проверка минимальной версии PHP (7.4) и WP (6.0+). При несоответствии — `wp_die` с понятным сообщением.
2. Создание таблицы `{prefix}cf7stg_queue` через `dbDelta`.
3. Установка дефолтных опций, если не заданы.
4. Регистрация WP-Cron событий.

**Deactivation (`register_deactivation_hook`):**
1. Снятие WP-Cron событий.
2. Таблица и опции остаются (на случай реактивации).

**Uninstall (`uninstall.php`):**
1. Удаление таблицы.
2. Удаление всех `cf7stg_*` опций.

## 18. Деплой на сайты (за рамками MVP спеки)

Плагин — стандартный WP-плагин, упаковывается в `.zip` командой вида `git archive` или ручным zip-ом папки. Установка через wp-admin «Плагины → Добавить → Загрузить». Массовая раскатка на 27 сайтов — отдельная задача, в текущий спек не входит.

## 19. Открытые вопросы (решаем во время реализации)

1. ~~**`tel:`-ссылки в inline-кнопках Telegram.**~~ **РЕШЕНО (2026-04-17 пилот).** Telegram Bot API отклонил `tel:` URLs (HTTP 400, `Wrong port number specified in the URL`). Inline-кнопки полностью убраны; номер показывается в теле сообщения, мобильные клиенты сами делают его кликабельным.
2. **Извлечение `flamingo_post_id`.** Flamingo не даёт прямой ссылки submission→post после сохранения. План: после сохранения Flamingo (`wpcf7_submission` priority 20) искать в `wp_posts` записи `post_type=flamingo_inbound`, sort by date DESC, limit 1, фильтр по содержимому `post_content` (сравнение с полями submission). Если совпадение ненадёжное — плагин всё равно работает (`flamingo_post_id = NULL`, dedup ретро-выгрузки пропускается для этой записи, но основной поток не зависит от наличия id).
3. **Акцент HTML vs MarkdownV2.** Если в процессе пилота выяснится, что клиенты часто пишут символы, ломающие HTML даже после экранирования — рассмотреть переход на plain text (без форматирования, эмодзи — unicode-символы, не требуют разметки).