Sheets Lead Bot

Telegram-бот, который собирает заявки и складывает их в Google Таблицу. Клиент отвечает на четыре вопроса (услуга, имя, телефон, комментарий), строка появляется в таблице, менеджер сразу получает уведомление в Telegram.

Возможности

• Пошаговая анкета с кнопками: выбор услуги, имя, телефон (можно отправить контакт одной кнопкой), комментарий или «Пропустить»
• Телефон приводится к одному виду: 050 123 45 67, (050) 123-45-67 и 380501234567 в таблице станут +380501234567; номера других стран (+48 ...) тоже принимаются
• Неправильный ответ объясняется, анкета остаётся на том же шаге
• Заявка не теряется, если Google недоступен или кончилась квота: строка ложится в локальную очередь (SQLite) и дописывается в таблицу автоматически, в исходном порядке. Менеджер получает уведомление сразу, с пометкой, что в таблицу запись ещё не попала
• Защита от дублей: та же услуга с того же телефона в течение 30 минут не создаёт вторую строку и второе уведомление
• Несколько менеджеров; если один заблокировал бота, остальные всё равно получают заявку
• Текст клиента записывается в таблицу как есть (RAW): строка, начинающаяся с =, не превратится в формулу
• Список услуг задаётся в .env, код менять не нужно

Как это устроено

leadbot/
  core.py      анкета, проверка имени и телефона, дубли, текст для менеджера (чистая логика)
  service.py   запись в таблицу, очередь неотправленных строк, уведомления
  sheets.py    адаптер Google Sheets (gspread, сервисный аккаунт)
  bot.py       сценарий в Telegram (aiogram 3)
  config.py    настройки из .env
  main.py      запуск
tests/         41 тест

Ядро не знает ни про Telegram, ни про Google. В тестах таблица и Telegram заменены заглушками: бот проходит анкету через настоящий роутер aiogram, но без сети и без токена; адаптер Google проверяется на поддельном модуле gspread.

Быстрый старт

1. Таблица и доступ Google

1. В Google Cloud Console создайте проект, включите Google Sheets API.
2. «IAM и администрирование» → «Сервисные аккаунты» → создать → вкладка «Ключи» → «Добавить ключ» → JSON. Скачанный файл положите в папку проекта как service_account.json (он уже в .gitignore).
3. Создайте Google Таблицу и откройте к ней доступ на редактирование для e-mail сервисного аккаунта (вида ...@...iam.gserviceaccount.com).
4. Скопируйте ID таблицы из ссылки: https://docs.google.com/spreadsheets/d/<ВОТ ЭТО>/edit.

Лист «Заявки» и строка заголовков создаются ботом сами.

2. Запуск

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env             # BOT_TOKEN, MANAGER_IDS, SPREADSHEET_ID
python -m leadbot.main

Тесты

pip install -r requirements-dev.txt
python -m pytest

Колонки таблицы

Дата	Имя	Телефон	Услуга	Комментарий	Telegram ID	Username	Источник

Лицензия

MIT