vk-sales-bot/README.md

VK Sales Bot

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

Что умеет

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

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

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

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

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

Требования

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

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

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

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

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

Copy-Item .env.example .env

3. Заполните .env.

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

python start.py

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

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:

1. Включить Repository Actions в настройках репозитория.

2. Поднять runner с меткой ubuntu-latest. Если у runner другая метка, замените runs-on в workflow.

3. Добавить 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.

Документация

• Руководство оператора
• Документация разработчика