User
161 lines
6.4 KiB
Markdown
161 lines
6.4 KiB
Markdown
# 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. Создайте виртуальное окружение и установите зависимости:
|
|
|
|
```powershell
|
|
python -m venv .venv
|
|
.venv\Scripts\activate
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
2. Скопируйте пример конфигурации:
|
|
|
|
```powershell
|
|
Copy-Item .env.example .env
|
|
```
|
|
|
|
3. Заполните `.env`.
|
|
|
|
4. При желании проверьте токен:
|
|
|
|
```powershell
|
|
python start.py
|
|
```
|
|
|
|
5. Запустите бота:
|
|
|
|
```powershell
|
|
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](./.env.example).
|
|
|
|
## Административные команды
|
|
|
|
Команды доступны только пользователям из `ADMIN_IDS`:
|
|
|
|
- `/status` — проверить, что бот работает;
|
|
- `/export` — создать копию файла с лидами;
|
|
- `/backup` — создать резервную копию вручную;
|
|
- `/stats` — показать статистику по лидам;
|
|
- `/reload` — перезагрузить тексты из `config/phrases.py` без перезапуска.
|
|
|
|
## Docker
|
|
|
|
Для запуска через Docker:
|
|
|
|
```powershell
|
|
docker compose up --build -d
|
|
```
|
|
|
|
Контейнер монтирует локальные каталоги:
|
|
|
|
- `./data -> /app/data`
|
|
- `./logs -> /app/logs`
|
|
|
|
## CI/CD
|
|
|
|
В репозитории добавлен workflow для Gitea Actions: [`.gitea/workflows/ci-cd.yml`](./.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 на том же сервере.
|
|
|
|
## Тесты
|
|
|
|
В репозитории есть базовые тесты для валидации и логики проекта.
|
|
|
|
```powershell
|
|
pip install pytest
|
|
pytest tests/
|
|
```
|
|
|
|
## Структура проекта
|
|
|
|
- [main.py](./main.py) — основная точка входа;
|
|
- [start.py](./start.py) — быстрая проверка токена VK;
|
|
- [config](./config) — настройки и текстовые фразы;
|
|
- [core](./core) — FSM, модели, валидация и экспорт;
|
|
- [services](./services) — интеграция с VK API;
|
|
- [utils](./utils) — логирование, middleware и бэкапы;
|
|
- [tests](./tests) — тесты;
|
|
- [docs](./docs) — дополнительные инструкции.
|
|
|
|
## Данные и логи
|
|
|
|
- лиды сохраняются в `data/leads.xlsx`;
|
|
- резервные копии создаются в `data/backups/`;
|
|
- логи пишутся в `logs/bot.log`.
|
|
|
|
## Документация
|
|
|
|
- [Руководство оператора](./docs/user_guide.md)
|
|
- [Документация разработчика](./docs/developer_guide.md)
|