Руководство пользователя¶

Руководство по использованию системы автоматического взыскания долгов через Telegram --- от первого запуска до повседневной работы.

Первый запуск¶

Необходимые компоненты¶

Компонент	Описание
Docker + Docker Compose	Для запуска всех сервисов
`.env` файл	Настройки (см. `.env.example`)
Excel с должниками	Файл `.xlsx` для импорта
SOCKS5 прокси	Минимум 3-5 штук
GoIP шлюз	С SIM-картами для регистрации
Admin Bot токен	От @BotFather в Telegram

Минимальный `.env`¶

TELEGRAM_API_ID=12345678
TELEGRAM_API_HASH=abcdef1234567890
DATABASE_URL=postgresql+asyncpg://postgres:pass@db:5432/debt_collector
REDIS_URL=redis://redis:6379/0
CELERY_BROKER_URL=redis://redis:6379/1
ADMIN_BOT_TOKEN=123456:ABC-DEF...
ADMIN_USER_IDS=123456789

Шаги запуска¶

# 1. Поднять все сервисы
docker compose up -d --build

# 2. Применить миграции
docker compose exec bot alembic upgrade head

# 3. Создать кампании
docker compose exec bot python scripts/seed_campaigns.py

# 4. Проверить логи
docker compose logs -f bot

После запуска доступны:

Admin Bot --- в Telegram
Веб-портал --- http://localhost:8000/
Swagger UI --- http://localhost:8000/api/docs
Adminer --- http://localhost:8081 (с --profile tools)

Импорт должников¶

Формат Excel (.xlsx)¶

Колонка	Обязательная	Описание
phone	Да	Телефон (любой формат)
first_name	Да	Имя
last_name	Да	Фамилия
debt_amount	Да	Сумма долга (грн)
overdue_days	Да	Дней просрочки
creditor_name	Да	Кредитор
patronymic	Нет	Отчество
contract_number	Нет	Номер договора
campaign_type	Нет	level1 / level2

Способы импорта¶

# Через CLI
docker compose exec bot python scripts/import_clients.py clients.xlsx

Или через Admin Bot: Должники --> Импорт Excel --> отправить файл.

Нормализация телефонов

Любой формат автоматически преобразуется в +380XXXXXXXXX.

Назначение кампании¶

campaign_type	Стиль	Описание
level1	Деловой тон	0-60 дней просрочки, розстрочка
level2	Формальный тон	60+ дней, юридический тиск

Регистрация Telegram-аккаунтов¶

Система поддерживает 3 способа:

graph TD
    START[Регистрация аккаунта] --> SMS{SMS доступно?}
    SMS -->|Да| MANUAL[Способ 1: Ручная<br/>Admin Bot, SMS-код вручную]
    SMS -->|Да| AUTO[Способ 2: Авто GoIP<br/>SMS читается автоматически]
    SMS -->|Нет, APP| EMU[Способ 3: Эмулятор<br/>Голосовой звонок + STT]
    MANUAL --> WARM[Статус: warming<br/>14 дней прогрева]
    AUTO --> WARM
    EMU --> WARM
    WARM --> ACTIVE[Статус: active<br/>Полные лимиты]

Способ 1: Ручная (Admin Bot)¶

Аккаунты --> Подключить аккаунт
Ввести номер (+380...)
Ввести SMS-код
При 2FA --- ввести пароль

Способ 2: Авто-регистрация (GoIP)¶

Аккаунты --> Авто-регистрация (GoIP)
Выбрать шлюз и номер
Подтвердить --- бот автоматически читает SMS, входит, назначает fingerprint и прокси

Способ 3: Эмулятор (голосовой звонок)¶

Для SIM-карт, где SMS недоступно (Telegram возвращает APP). Требуется предварительная настройка Android SDK, Magisk и Asterisk.

После регистрации

Каждый аккаунт получает: уникальный device fingerprint, наименее загруженный прокси, статус warming (14 дней).

Импорт прокси¶

Прокси обязательны для антибана. Каждый прокси обслуживает до 10 аккаунтов.

# С проверкой доступности
docker compose exec bot python scripts/import_proxies.py proxies.txt --check

# Без проверки
docker compose exec bot python scripts/import_proxies.py proxies.txt

Формат proxies.txt:

socks5://user:pass@proxy1.com:1080
user:pass@proxy2.com:1080

Admin Bot --- управление через Telegram¶

Меню¶

graph TD
    MAIN[Главное меню] --> ACC[Аккаунты]
    MAIN --> CLI[Должники]
    MAIN --> STAT[Статистика]
    MAIN --> DIAL[Диалоги]
    MAIN --> SET[Настройки]
    SET --> PROXY[Прокси]
    SET --> WORK[Воркеры]
    SET --> GOIP[GoIP SIM]

Управление аккаунтами¶

Кнопка	Действие
Подключить аккаунт	Ручная регистрация
Авто-регистрация (GoIP)	Автоматическая через SMS
Регистрация через эмулятор	Голосовой звонок + STT
Список аккаунтов	Все аккаунты с статусами

Управление должниками¶

Кнопка	Действие
Импорт CSV	Загрузить из файла
Список должников	Просмотр с пагинацией
Очистить и импортировать	Удалить старых + импорт

Управление диалогами¶

Кнопка	Действие
Список	Активные диалоги
Детали	Последние сообщения, статус
Перехватить	Забрать управление (бот перестает отвечать)

Веб-дашборд¶

Доступ: https://fin-boost.com (или http://localhost:8000 локально).

Страницы оператора¶

URL	Страница	Возможности
`/dashboard`	Дашборд	Статистика: аккаунты, должники, диалоги
`/conversations`	Диалоги	Список с фильтрами по 9 статусам
`/conversations/:id`	Чат	Бабблы сообщений, статусы доставки, takeover
`/operator`	Operator Center	Очередь handoff, composer, контекст
`/clients`	Должники	Поиск, фильтры по 7 статусам
`/clients/:id`	Карточка	Риск, обещания, AI память, история

Страницы администратора¶

URL	Страница	Возможности
`/accounts`	Аккаунты	Таблица, inline-edit
`/departments`	Отделы	Промпты, секции, preview
`/workflows`	Сценарии	Диаграммы с live-статистикой
`/company`	Компания	Реквизиты, контакты, агент
`/settings`	Настройки	Env-переменные, AI, лимиты
`/employees`	Сотрудники	Приглашения, роли

Автоматическая работа¶

После настройки система работает полностью автономно.

Расписание Celery Beat¶

Интервал	Задача	Описание
Каждые 5 мин	Follow-ups	Повторные сообщения
Каждые 10 мин (9-21)	Первый контакт	Связь с новыми должниками
Каждые 30 мин	Health check	Проверка аккаунтов и прокси
Ежечасно (9-19)	Прогрев	Warming-активности
Полночь	Сброс счетчиков	Обнуление дневных лимитов
3x/день	Авто-регистрация	Пополнение аккаунтов
3x/день	Скан SIM	USSD обновление номеров

Как AI ведет диалог¶

sequenceDiagram
    participant D as Должник
    participant P as Pyrogram
    participant DM as DialogManager
    participant AI as Claude AI
    participant MS as MessageSender

    D->>P: Пишет сообщение
    P->>DM: Incoming message
    DM->>DM: Проверки (часы, лимиты, takeover)
    DM->>AI: История + память + правила кампании
    AI->>DM: JSON (response + actions)
    DM->>MS: Отправка с задержками
    MS->>D: Ответ (имитация живого человека)
    DM->>DM: Обновление памяти

Антибан (автоматически)¶

Механизм	Описание
Задержки	5-20 секунд между сообщениями
Typing simulation	Имитация набора текста
Сплит сообщений	Разбивка длинных текстов
Лимит 40 msg/day	На аккаунт
14-дневный прогрев	Постепенное увеличение лимитов
Fingerprint	Уникальный для каждого аккаунта
Прокси изоляция	До 10 аккаунтов на прокси
Рабочие часы	Пн-Пт, 9:00-20:00

Типичные сценарии¶

Должник не отвечает¶

Система автоматически: отправляет первое сообщение --> планирует follow-up (24-72ч) --> повторяет до max_attempts --> статус unreachable.

Должник обещал оплатить¶

AI фиксирует обещание (только при явном подтверждении суммы и даты) --> статус promise_made --> follow-up на день после обещания --> при неоплате --- напоминание.

Неопределенные ответы

Если должник пишет "позже", "через месяц" --- обещание не фиксируется. AI уточняет детали или планирует follow-up.

Эскалация на оператора¶

При агрессии или угрозах AI ставит risk_flag --> escalate_to_human --> диалог помечается taken_over_by --> автоматические ответы отключаются.

Перехват диалога¶

Через Admin Bot (Диалоги --> Перехватить) или через API (POST /api/conversations/{id}/takeover).

FAQ¶

Сколько аккаунтов нужно? Минимум 5 (MIN_ACTIVE_ACCOUNTS). Рекомендуется 10-20. Каждый ведет до 15 диалогов.

Сколько прокси? Минимум кол-во_аккаунтов / 3. Для 20 аккаунтов --- минимум 7.

Зачем прогрев 14 дней? Новый аккаунт при массовой рассылке будет забанен. Прогрев постепенно увеличивает лимиты: дни 1-3 (5 msg) --> 4-7 (10) --> 8-14 (20) --> 15+ (40).

Бот не отвечает должникам? Проверить: рабочие часы, статус аккаунта (active), диалог не перехвачен, лимиты не исчерпаны, AI Engine работает.

Перезагрузка .env

docker compose restart не перечитывает .env. Нужно docker compose up -d <service>.