LeadFlow Bot

LeadFlow Bot — production-minded MVP Telegram-бота для малого бизнеса, который помогает не терять лиды и заявки: быстро принимать новые обращения, брать их в работу, отслеживать SLA первого ответа, фиксировать заметки и смотреть понятную статистику.

Проект сделан как портфолио-решение, но с реальной прикладной ценностью: его можно развернуть, выдать менеджерам и использовать без лишней инфраструктуры.

Что решает

• Новые лиды не теряются в чате и не остаются без реакции.
• Менеджеры видят доступные заявки и берут их в работу.
• Администратор управляет менеджерами, нагрузкой и статусами.
• Просроченные лиды попадают в отдельный раздел.
• Есть короткая статистика по текущему состоянию воронки.

Возможности MVP

• 2 роли: администратор и менеджер.
• Создание лида через бота и через команду /newlead.
• Пошаговый сценарий создания лида на русском языке.
• Карточка лида с ответственным, SLA и последней заметкой.
• Действия по лиду:
  • взять в работу
  • назначить менеджера
  • сменить статус
  • добавить заметку
  • быстро закрыть как успешный или потерянный
• Разделы:
  • новые лиды
  • мои лиды
  • все лиды
  • просроченные
  • менеджеры
  • статистика
• SLA первого ответа с фоновой проверкой просрочки.
• Демо-данные после первого запуска.
• Минимальный защищённый API для внешнего создания лида:
  • POST /api/leads
  • Authorization: Bearer <token> или X-API-Key

Стек

• Python 3.12+
• aiogram 3
• SQLite
• SQLAlchemy 2
• FastAPI
• Docker / docker-compose

Архитектура

Проект intentionally простой:

• aiogram 3 работает в polling-режиме.
• FastAPI поднимается в том же процессе как небольшой HTTP API.
• SQLite хранит пользователей, лиды и заметки.
• Слой разделён на:
  • handlers — Telegram-сценарии
  • services — бизнес-логика
  • repositories — доступ к БД
  • models — SQLAlchemy-модели
  • keyboards и middlewares — UX и инфраструктура бота

Без Redis, Celery, PostgreSQL и лишнего enterprise-шума.

Структура проекта

.
├── app
│   ├── api.py
│   ├── main.py
│   ├── bot
│   │   ├── callbacks.py
│   │   ├── handlers
│   │   ├── keyboards
│   │   ├── middlewares
│   │   └── states.py
│   ├── config
│   ├── db
│   ├── models
│   ├── repositories
│   ├── services
│   └── utils
├── data
├── .env.example
├── docker-compose.yml
├── Dockerfile
├── README.md
└── requirements.txt

Быстрый запуск локально

1. Создайте бота через @BotFather и получите токен.
2. Узнайте свой Telegram ID, например через @userinfobot.
3. Скопируйте переменные окружения:

cp .env.example .env

4. Заполните минимум:

BOT_TOKEN=...
ADMIN_IDS=123456789
API_TOKEN=...

5. Создайте виртуальное окружение и установите зависимости:

python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

6. Запустите проект:

python -m app.main

После запуска:

• таблицы создадутся автоматически
• демо-лиды и 2 демо-менеджера добавятся автоматически
• бот начнёт принимать команды
• API поднимется на http://127.0.0.1:8000, если ENABLE_API=true

Запуск через Docker

1. Подготовьте .env.
2. Запустите:

docker compose up --build

SQLite будет храниться в папке ./data.

Как добавить администратора

Администраторы задаются через ADMIN_IDS.

Пример:

ADMIN_IDS=123456789,987654321

Если указанный пользователь напишет боту /start, он автоматически будет распознан как администратор.

Как пользоваться

Команды

• /start — открыть бота
• /help — подсказка
• /menu — главное меню
• /newlead — создать лид
• /myleads — мои лиды
• /overdue — просроченные лиды
• /stats — статистика

Основной сценарий

1. Администратор открывает бота и видит главное меню.
2. При необходимости добавляет менеджеров по Telegram ID.
3. Создаёт лид вручную или принимает его через API.
4. Менеджер видит новые лиды, берёт лид в работу и оставляет заметки.
5. Лид проходит статусы от Новый до Успешно закрыт или Потерян.
6. Просроченные заявки видны в отдельном разделе.

API

Создать лид

POST /api/leads

Заголовки:

Authorization: Bearer your_api_token

или

X-API-Key: your_api_token

Пример запроса:

curl -X POST http://127.0.0.1:8000/api/leads \
  -H "Authorization: Bearer your_api_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Иван Клиент",
    "phone": "+380671112233",
    "contact": "@ivan_client",
    "source": "Сайт",
    "description": "Хочет подключить Telegram-бота для заявок"
  }'

Пример успешного ответа:

{
  "id": 9,
  "status": "new",
  "responsible_manager_id": null,
  "is_overdue": false,
  "created_at": "2026-03-27T15:10:22.000000Z"
}

Дополнительно можно передать responsible_manager_telegram_id, если нужно сразу назначить менеджера.

Безопасность

• Секреты берутся только из .env.
• Токен бота не логируется.
• API защищён токеном.
• Все пользовательские поля валидируются по длине и формату.
• Telegram ID обрабатываются как числа и не доверяются напрямую.
• Ошибки пользователя возвращаются понятным текстом, без падения процесса.

Демо-данные

При первом запуске автоматически создаются:

• 2 демо-менеджера
• 8 демо-лидов
• разные статусы
• несколько заметок