# 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)