VK-бот для сбора заявок в личных сообщениях сообщества. Бот проводит пользователя по сценарию диалога, сохраняет лиды в Excel, пишет логи и делает резервные копии.

Что умеет

запрашивает согласие на обработку персональных данных;
собирает ФИО, телефон и удобное время звонка;
умеет сохранить данные родителя или опекуна;
обрабатывает базовые возражения пользователя;
сохраняет заявки в data/leads.xlsx;
делает резервные копии в data/backups/;
поддерживает административные команды в VK.

Как работает сценарий

Диалог построен на FSM и проходит по шагам:

согласие -> ФИО -> данные родителя (опционально) -> телефон -> удобное время -> подтверждение

После подтверждения лид записывается в Excel-файл. При отказе или возражениях бот может сохранить заявку со статусом postponed или rejected.

Требования

Python 3.11+
access token сообщества VK с правами messages и groups
ID группы VK

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

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

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

Скопируйте пример конфигурации:

Copy-Item .env.example .env

Заполните .env.
При желании проверьте токен:

python start.py

Запустите бота:

python main.py

Переменные окружения

Переменная	Описание
`VK_GROUP_ID`	ID сообщества VK
`VK_TOKEN`	токен группы VK
`ADMIN_IDS`	список ID администраторов через запятую
`DATA_DIR`	директория для рабочих данных
`LEADS_FILE`	путь к Excel-файлу с лидами
`BACKUP_DIR`	директория для резервных копий
`LOG_LEVEL`	уровень логирования
`TIMEZONE`	часовой пояс приложения

Пример уже есть в .env.example.

Административные команды

Команды доступны только пользователям из ADMIN_IDS:

/status — проверить, что бот работает;
/export — создать копию файла с лидами;
/backup — создать резервную копию вручную;
/stats — показать статистику по лидам;
/reload — перезагрузить тексты из config/phrases.py без перезапуска.

Docker

Для запуска через Docker:

docker compose up --build -d

Контейнер монтирует локальные каталоги:

./data -> /app/data
./logs -> /app/logs

CI/CD

В репозитории добавлен workflow для Gitea Actions: .gitea/workflows/ci-cd.yml.

Что делает pipeline:

на push и pull_request запускает тесты;
если у runner есть доступ к Docker, дополнительно проверяет сборку образа;
на push в main деплоит проект на сервер по SSH и выполняет docker compose up -d --build.

Что нужно настроить в Gitea:

Включить Repository Actions в настройках репозитория.
Поднять runner с меткой ubuntu-latest. Если у runner другая метка, замените runs-on в workflow.
Добавить secrets репозитория:
- SSH_PRIVATE_KEY — приватный ключ для входа по SSH;
- SSH_KNOWN_HOSTS — публичный host key сервера, рекомендуется для безопасной проверки хоста.

Требования на сервере:

установлен docker и docker compose;
установлен rsync;
проект деплоится в /opt/vk-sales-bot;
в /opt/vk-sales-bot уже есть рабочий .env, потому что workflow его не перезаписывает;
workflow подключается как root на infocyber.pro.

Важно:

workflow уже привязан к root@infocyber.pro и пути /opt/vk-sales-bot;
локальный alias для подключения к серверу у вас называется ea2go;
бот не публикует порты в compose.yaml, поэтому сам по себе не должен конфликтовать с Gitea на том же сервере.

Тесты

В репозитории есть базовые тесты для валидации и логики проекта.

pip install pytest
pytest tests/

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

main.py — основная точка входа;
start.py — быстрая проверка токена VK;
config — настройки и текстовые фразы;
core — FSM, модели, валидация и экспорт;
services — интеграция с VK API;
utils — логирование, middleware и бэкапы;
tests — тесты;
docs — дополнительные инструкции.

Данные и логи

лиды сохраняются в data/leads.xlsx;
резервные копии создаются в data/backups/;
логи пишутся в logs/bot.log.

README.md

VK Sales Bot