Простой и удобный Telegram-бот для оформления заказов на доставку воды. Клиенты могут создать заявку прямо в чате, а менеджер получает уведомление с деталями заказа.
- Возможности
- Технологии
- Требования
- Установка
- Настройка
- Запуск
- Структура проекта
- Как это работает
- Частые ошибки
- Полезные команды
- 📍 Геолокация — клиент может отправить свою геопозицию, и бот автоматически определит адрес
- 📞 Контакт — запрос номера телефона через кнопку Telegram
- 📅 Календарь — выбор даты доставки через интерактивный календарь
- 🧾 Оформление заказа — указание количества бутылок
- 💾 База данных — все заказы сохраняются в SQLite
- 🔔 Уведомления — менеджер мгновенно получает информацию о новом заказе
| Технология | Версия | Описание |
|---|---|---|
| Python | 3.8+ | Язык программирования |
| python-telegram-bot | 20.8 | Библиотека для работы с Telegram Bot API |
| requests | 2.31.0 | HTTP-запросы к Nominatim API |
| sqlite3 | встроенный | База данных для хранения заказов |
Перед началом работы убедитесь, что у вас установлены:
- Python 3.8 или выше (проверьте командой:
python3 --version) - pip — менеджер пакетов Python (проверьте:
pip --version) - Токен бота — получите у @BotFather
- ID менеджера — узнайте через @userinfobot
cd WaterExpress-mainДля macOS/Linux:
python3 -m venv venv
source venv/bin/activateДля Windows:
python -m venv venv
venv\Scripts\activateЗачем нужно виртуальное окружение?
Оно изолирует зависимости проекта от системных пакетов Python.
pip install -r requirements.txtВ проекте уже есть файл config.py с заглушками. Заполните его своими данными:
# config.py
# Токен бота от @BotFather
TELEGRAM_TOKEN = "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz"
# ID менеджера (число без кавычек)
MANAGER_ID = 123456789- Откройте @BotFather в Telegram
- Отправьте команду
/newbot - Придумайте имя боту (например,
WaterDelivery Bot) - Придумайте юзернейм боту (должен заканчиваться на
bot, напримерwater_express_bot) - BotFather выдаст токен — скопируйте его в
config.py
- Откройте @userinfobot
- Нажмите Start
- Бот покажет ваш ID — скопируйте число в
config.py
python bot.pyЕсли всё настроено правильно, вы увидите:
2024-03-18 10:00:00 - __main__ - INFO - База данных проверена/создана
2024-03-18 10:00:00 - __main__ - INFO - Бот запущен...
Нажмите Ctrl + C в терминале.
WaterExpress-main/
├── bot.py # Точка входа (запуск бота)
├── config.py # Конфигурация (токен, ID менеджера)
├── database.py # Работа с базой данных SQLite
├── utils.py # Вспомогательные функции (геолокация, календарь)
├── handlers/ # Обработчики диалогов
│ ├── __init__.py
│ ├── start.py # /start и первое сообщение
│ ├── address.py # Ввод адреса и геолокация
│ ├── phone.py # Ввод телефона
│ ├── calendar.py # Календарь для выбора даты
│ └── order.py # Оформление заказа (бутылки, БД, менеджер)
├── requirements.txt # Зависимости проекта
├── README.md # Этот файл
└── baza.db # База данных (создаётся автоматически)
| Файл | Описание |
|---|---|
bot.py |
Точка входа: инициализация приложения, настройка ConversationHandler |
config.py |
Конфигурационные данные (токен, ID) — не коммитьте в репозиторий! |
database.py |
Функции для работы с SQLite: create_database(), save_order() |
utils.py |
Вспомогательные функции: get_address_from_location(), generate_calendar() |
handlers/start.py |
Обработчики команды /start и начального сообщения |
handlers/address.py |
Обработчик ввода адреса и геолокации |
handlers/phone.py |
Обработчик ввода номера телефона |
handlers/calendar.py |
Обработчик календаря для выбора даты |
handlers/order.py |
Обработчик количества бутылок, сохранение в БД, уведомление менеджера |
requirements.txt |
Список внешних библиотек для установки через pip |
baza.db |
SQLite-база с заказами — создаётся при первом запуске |
┌─────────────┐
│ /start │
└──────┬──────┘
│
▼
┌─────────────┐
│ Адрес │ ← Геолокация или текст
└──────┬──────┘
│
▼
┌─────────────┐
│ Телефон │ ← Контакт или ввод вручную
└──────┬──────┘
│
▼
┌─────────────┐
│ Дата │ ← Выбор из календаря
└──────┬──────┘
│
▼
┌─────────────┐
│ Бутылки │ ← Число
└──────┬──────┘
│
▼
┌─────────────┐
│ Сохранить │ → Запись в БД + уведомление менеджеру
└─────────────┘
Таблица clients создаётся автоматически:
CREATE TABLE clients (
id INTEGER PRIMARY KEY AUTOINCREMENT,
data_delivery TEXT, -- Дата доставки
client_name TEXT, -- Имя клиента
client_address TEXT, -- Адрес
number TEXT -- Телефон
);Решение: Установите зависимости:
pip install -r requirements.txtРешение: Проверьте, что файл config.py заполнен корректными данными.
Решение: Менеджер заблокировал бота. Разблокируйте @BotFather или проверьте ID.
Решение:
- Проверьте, что бот запущен (
python bot.py) - Убедитесь, что токен верный
- Попробуйте отправить
/start
Решение: Nominatim API может быть недоступен. Проверьте интернет-соединение.
| Команда | Описание |
|---|---|
/start |
Запустить бота заново |
Ctrl + C |
Остановить бота в терминале |
# Установите SQLite CLI (если нет)
# macOS: brew install sqlite
# Linux: sudo apt install sqlite3
sqlite3 baza.db "SELECT * FROM clients;"Проект разделён на логические модули для удобства поддержки:
bot.py (Точка входа)
│
├── config.py (Настройки)
├── database.py (БД)
├── utils.py (Утилиты)
└── handlers/ (Обработчики)
├── start.py
├── address.py
├── phone.py
├── calendar.py
└── order.py
Если хотите расширить функционал:
- Создайте новый файл в
handlers/(например,feedback.py) - Напишите асинхронную функцию-обработчик
- Добавьте импорт в
handlers/__init__.py - Зарегистрируйте в
ConversationHandler.states
Проект создан в учебных целях.
maxim-vdonsk — Junior Python Developer 🚰
- GitHub: @maxim-vdonsk
- Telegram: @maxim_vdonsk