Обзор системы¶

Система автоматизированного взыскания задолженностей через Telegram для компании Технофінанс. Использует 20 Telegram userbot-аккаунтов (Pyrogram/MTProto), каждый из которых автономно ведёт переговоры с должниками при помощи Anthropic SDK с CLI fallback.

Что делает система¶

flowchart LR
    A[Импорт должников<br>из Excel] --> B[Автоматический<br>первый контакт]
    B --> C[AI-переговоры<br>через Telegram]
    C --> D{Результат}
    D -->|Оплата| E[Закрытие]
    D -->|Обещание| F[Follow-up мониторинг]
    D -->|Отказ / молчание| G[Повторный контакт<br>через N дней]
    D -->|Сложный случай| H[Эскалация<br>на оператора]

Ключевая идея -- полная автоматизация процесса взыскания: от первого контакта с должником до эскалации на живого оператора, с адаптивным поведением AI-агента в зависимости от уровня кампании и реакций клиента. Все диалоги ведутся на украинском языке.

Два отдела (departments)¶

Система распределяет клиентов по двум отделам в зависимости от поля campaign_type (из Excel-импорта) или дней просрочки (overdue_days).

Level 1 -- Стягнення простроченої заборгованості¶

Параметр	Значение
Тон	Жорсткий діловий. Кожне повідомлення -- крок до фіксації оплати
Підхід	Перший контакт після купівлі боргу, з'ясування ситуації, розстрочка
Перший контакт	3 стилі (A/B/C) -- прямий, короткий, формальний
Follow-up	6-рівнева сходинкова ескалація
Кредитори	ЄГроші, ТОП1, Фінмаркет, Технофінанс
Гарантійний платіж	500 грн

Заборонено

Слова співчуття: «розумію», «шкода», «непроста ситуація» -- категорично заборонені у level1.

Level 2 -- Досудове стягнення¶

Параметр	Значение
Тон	Жорсткий формальний. Факт боргу, юридичні наслідки, дедлайн
Підхід	Ескалація після невдалого level1, тиск через юридичні наслідки
Правові посилання	Стаття 625 ЦК, стаття 1050 ЦК, виконавче провадження
Тактика	Мінімальні поступки, «керівництво чекає»

Основные компоненты¶

graph TB
    subgraph "Telegram Layer"
        AP["AccountPool<br>20 userbot-аккаунтов"]
        MS["MessageSender<br>Антибан-отправка"]
        AW["AccountWarmer<br>3-фазный прогрев"]
    end

    subgraph "AI Core"
        DM["DialogManager<br>Координатор диалогов"]
        AI["AIEngine<br>Anthropic SDK / CLI"]
        MM["MemoryManager<br>Персональная память"]
    end

    subgraph "Infrastructure"
        GOIP["4x GoIP16<br>SMS-шлюзы"]
        EMU["Android Emulator<br>Voice verification"]
        CELERY["Celery Workers<br>22 периодические задачи"]
    end

    subgraph "Management"
        API["FastAPI + React SPA<br>Веб-дашборд"]
        BOT["Admin Bot<br>aiogram 3.x"]
    end

    AP --> DM
    DM --> AI
    DM --> MM
    GOIP --> AP
    EMU --> AP
    CELERY --> DM

AI-движок¶

AIEngine работает в двух режимах:

Режим	Когда используется	Модель
Anthropic SDK (primary)	`ANTHROPIC_API_KEY` задан	`claude-sonnet-4-6` с Adaptive Thinking
Claude CLI (fallback)	API-ключ не задан	subprocess с `--output-format json`

AI возвращает структурированный JSON:

{
  "response": "Текст ответа клиенту",
  "reaction": null,
  "reply_to": null,
  "actions": [
    {"type": "schedule_followup", "data": {"hours": 24, "reason": "..."}}
  ]
}

Доступные действия (tools): запись обещания оплаты, причина неоплаты, планирование follow-up, эскалация на оператора, отправка ссылки на оплату, обновление памяти, закрытие беседы, flash call.

Персональная память клиентов¶

Каждый клиент имеет отдельный JSON-файл в memories/. Состав:

profile -- имя, фамилия, телефон, язык
debt_info -- сумма долга, дни просрочки, кредитор, номер договора
payment_promises -- обещания оплаты (сумма, дата, статус)
risk_flags -- флаги риска (агрессия, угрозы)
key_moments -- важные факты, сохраняемые AI между беседами

Кросс-диалоговый контекст

При повторном контакте через другой аккаунт AI получает полный контекст всех предыдущих бесед: статусы, ключевые обмены, key_moments. Система различает «первый контакт» и «повторный контакт», адаптируя стратегию.

Антибан-стратегия¶

Система защищает аккаунты от блокировки по трём осям:

Device Fingerprint -- 55+ устройств, 35+ версий Telegram, 12 языков. Назначается при регистрации, никогда не меняется
Proxy-изоляция -- до 10 аккаунтов на 1 прокси, мобильные 4G-прокси CyberYozh
Docker Worker Containers -- физическая изоляция процессов
3-фазный прогрев -- дни 1-2 (межботовый чат), дни 3-5 (roleplay), дни 6-7 (стандартная активность)

Жизненный цикл беседы¶

stateDiagram-v2
    [*] --> pending
    pending --> active: Первый контакт
    active --> waiting_response: Сообщение отправлено
    active --> promise_made: Клиент обещал оплату
    active --> escalated: Передано оператору
    waiting_response --> follow_up_scheduled: Планирование follow-up
    follow_up_scheduled --> active: Follow-up отправлен
    promise_made --> resolved: Оплата подтверждена
    active --> closed: close_conversation
    waiting_response --> closed: Исчерпаны попытки
    closed --> [*]
    resolved --> [*]

При закрытии с причиной unreachable или refused система автоматически планирует повторный контакт: до 3 попыток с эскалацией задержек (3/7/14 дней для unreachable, 5/10/21 для refused).

Юридическое лицо¶

Параметр	Значение
Компания	Технофінанс
ЄДРПОУ	43868852
IBAN	UA713281680000026508000000184
Банк	АТ КБ ПРИВАТБАНК
Географический фокус	Украина (Europe/Kyiv, UAH)

Технологический стек¶

Компонент	Технология
Telegram-клиенты	Pyrogram (MTProto userbot)
AI-движок	Anthropic SDK + Claude CLI fallback
База данных	PostgreSQL 15 + pgvector + SQLAlchemy 2.0 async
Кэш/очередь	Redis 7
Фоновые задачи	Celery (22 задачи)
API-дашборд	FastAPI + React 18 + TypeScript
Admin-бот	aiogram 3.x
SMS-шлюзы	4x GoIP16
Мобильные прокси	CyberYozh (LTE, Украина)
CI/CD	GitHub Actions (6 jobs)