Telegram Bot - Contact, Order, Survey, and Phone Validation

Описание проекта

Многофункциональный Telegram бот на Python, реализующий 4 основных сценария работы:

1. Сбор контактных данных - Заполнение анкеты с именем, телефоном и email
2. Обработка заявок/заказов - Выбор типа услуги, сбор деталей и отправка уведомлений
3. Анкетирование/опрос - Проведение опроса с серией вопросов
4. Валидация телефонов - Проверка и нормализация номеров телефонов

Архитектура

• Язык: Python 3.8+
• Библиотека: aiogram 3.4.1
• База данных: SQLite3
• Валидация: phonenumbers (если доступно), email-validator
• Управление состоянием: Простой FSM (Finite State Machine)

Функционал

📝 Сценарий 1: Сбор контактных данных

Команды:

• /start - Начало диалога
• /contact - Заполнение анкеты
• /cancel - Отмена текущего действия

Процесс:

1. Запрос имени пользователя
2. Проверка имени (2-50 символов)
3. Запрос номера телефона
4. Валидация и нормализация номера
5. Запрос email (опционально)
6. Сохранение данных
7. Подтверждение регистрации

📋 Сценарий 2: Обработка заявок/заказов

Команды:

• /order - Начало оформления заявки
• /cancel - Отмена текущего действия

Процесс:

1. Выбор типа услуги (inline клавиатура)
2. Сбор деталей заказа
3. Запрос контактных данных
4. Подтверждение заявки

Типы услуг:

• IT-услуги
• Дизайн
• Маркетинг
• Ремонт
• Обучение

📊 Сценарий 3: Анкетирование/опрос

Команды:

• /survey - Начало опроса
• /cancel - Отмена текущего действия

Процесс:

1. Последовательный опрос
2. Сбор ответов
3. Сохранение результатов

📱 Сценарий 4: Валидация телефонов

Команды:

• /validate - Начало валидации
• /cancel - Отмена текущего действия

Процесс:

1. Запрос номера телефона
2. Валидация формата
3. Нормализация номера
4. Сохранение проверенного номера

🛠️ Технические возможности

✅ Поддерживаемые функции:

• Прием текстовых сообщений
• Отправка форматированных ответов (HTML, Markdown)
• Обработка команд
• Логирование событий
• Работа с inline клавиатурами
• Работа с reply клавиатурами

⏳ Реализованные возможности:

• Кнопки для навигации
• Inline клавиатуры для выбора опций
• Состояния диалога
• База данных SQLite

📋 Валидация данных

Телефон:

• Формат: международный (+7...)
• Длина: 10-15 цифр
• Нормализация в E164 формат
• Определение страны

Email:

• Базовая проверка формата
• Проверка длины (максимум 254 символа)
• Проверка на одноразовые домены

🚀 Установка и запуск

1. Клонирование репозитория

git clone https://github.com/your-repo/telegram-bot
cd telegram-bot

2. Установка зависимостей

pip install -r requirements.txt

3. Настройка окружения

cp .env.example .env
# Отредактируйте .env файл с вашим токеном

4. Запуск бота

python bot.py

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

telegram-bot/
├── bot.py              # Основной файл бота
├── database.py          # Работа с базой данных
├── validators.py        # Валидация данных
├── keyboards.py         # Клавиатуры
├── requirements.txt      # Зависимости
├── .env.example        # Пример конфигурации
├── test_bot.py        # Тестовый скрипт
└── README.md           # Этот файл

🔧 Конфигурация

Создайте файл .env на основе .env.example:

BOT_TOKEN=your_telegram_bot_token_here
DATABASE_URL=sqlite:///bot.db
DEBUG=True
DEFAULT_REGION=RU
ALLOW_DELIVERY_DOMAIN=True

📊 База данных

Бот использует SQLite3 для хранения:

• Контактных данных
• Заявок
• Результатов опросов
• Валидированных номеров телефонов

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

• Токен бота хранится в переменных окружения
• Валидация всех входных данных
• Защита от SQL-инъекций
• Обработка ошибок без раскрытия информации

📈 Мониторинг

Бот логирует все важные события:

• Запуск и остановка
• Обработка команд
• Ошибки валидации
• Сохранение данных

🔄 Разработка

Добавление новых сценариев

Для добавления нового сценария:

1. Добавьте команду в get_main_keyboard()
2. Создайте обработчик с декоратором @router.message(Command("new_command"))
3. Реализуйте логику обработки в новом файле
4. Добавьте состояние в классы ContactForm, OrderForm и т.д.

Пример добавления нового обработчика

@router.message(Command("status"))
async def status_handler(message):
    """Handle /status command"""
    await message.answer("Бот работает нормально! ✅")

📞 Поддержка

При возникновении проблем:

1. Проверьте логи бота
2. Убедитесь, что токен правильный
3. Проверьте подключение к базе данных
4. Проверьте настройки валидации

📝 Лицензия

MIT License - свободное использование и модификация

🧪 Тестирование

Запустите тестовый скрипт для проверки функциональности:

python test_bot.py

Тест проверяет:

• Инициализацию базы данных
• Валидацию номеров телефонов
• Корректность работы FSM

🎯 Рекомендации по улучшению

Приоритеты:

1. ✅ Стабильность - Обработка ошибок и граничных случаев
2. 🔒 Безопасность - Валидация всех входных данных
3. 📊 Масштабируемость - Эффективная работа с базой данных
4. 🎨 UX - Интуитивные интерфейсы и понятные сообщения

Возможные улучшения:

• Добавить webhook режим для повышения надежности
• Реализовать систему администрирования
• Добавить аналитику и статистику
• Интеграция с внешними CRM системами
• Поддержка многоязычности
• Кэширование частых запросов

📞 Контакты поддержки

При возникновении проблем с реализацией:

1. Технические вопросы - архитектура, алгоритмы
2. Проблемы с aiogram - использование библиотеки, обработчики
3. Вопросы по базе данных - SQLite, запросы
4. Общие вопросы - развёртывание, отладка

---

Бот готов к работе! 🚀