Initial clean history

README.md

@@ -0,0 +1,160 @@
+# 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)