a.gruzdev
194 lines
18 KiB
Markdown
194 lines
18 KiB
Markdown
# 📖 Руководство пользователя чат-бота «Cyber Pro»
|
|
|
|
Добро пожаловать в официальное руководство пользователя и техническую документацию для умного чат-бота ВКонтакте киберспортивной школы **«Cyber Pro»**.
|
|
|
|
Этот бот спроектирован с учетом передовых практик UX/UI-дизайна, психологии продаж и оптимизации конверсии. Он помогает потенциальным клиентам быстро ознакомиться с услугами школы, получить привлекательный лид-магнит, заполнить безошибочную заявку на обучение и при необходимости мгновенно связаться с живым оператором.
|
|
|
|
Для владельцев бизнеса и администраторов бот предоставляет **защищенную панель управления**, позволяющую редактировать услуги и цены прямо из чата ВКонтакте в режиме реального времени.
|
|
|
|
---
|
|
|
|
## 🗺️ Содержание
|
|
1. [🚀 Возможности для клиентов (Пользовательский интерфейс)](#-возможности-для-клиентов-пользовательский-интерфейс)
|
|
* [Главное меню](#главное-меню)
|
|
* [Интеллектуальная воронка заявок (FSM)](#интеллектуальная-воронка-заявок-fsm)
|
|
* [Экран проверки данных и точечное редактирование](#экран-проверки-данных-и-точечное-редактирование)
|
|
* [Упрощенное согласие и оферта](#упрощенное-согласие-и-оферта)
|
|
* [Интерактивный раздел FAQ и лид-магнит](#интерактивный-раздел-faq-и-лид-магнит)
|
|
* [Режим связи с живым оператором](#режим-связи-с-живым-оператором)
|
|
2. [⚙️ Панель администратора и безопасность](#-панель-администратора-и-безопасность)
|
|
* [Разграничение прав доступа](#разграничение-прав-доступа)
|
|
* [Управление услугами в реальном времени (CRUD)](#управление-услугами-в-реальном-времени-crud)
|
|
3. [🗄️ База данных и логирование](#%EF%B8%8F-база-данных-и-логирование)
|
|
4. [🛠️ Установка, настройка и запуск](#%EF%B8%8F-установка-настройка-и-запуск)
|
|
|
|
---
|
|
|
|
## 🚀 Возможности для клиентов (Пользовательский интерфейс)
|
|
|
|
### Главное меню
|
|
При старте (команда `начать` или приветствие `привет`) бот высылает красивое приветствие и открывает клавиатуру с тремя главными кнопками:
|
|
* **Заполнить заявку 📝** — запуск интерактивной анкеты.
|
|
* **Частые вопросы ❓** — переход в раздел FAQ.
|
|
* **Позвать оператора 🧑💼** — мгновенное переключение на человека.
|
|
|
|
---
|
|
|
|
### Интеллектуальная воронка заявок (FSM)
|
|
Процесс заполнения заявки оптимизирован для максимальной конверсии и состоит из 3 простых шагов:
|
|
|
|
1. **Ввод Имени (`FORM_NAME`)**:
|
|
* Бот просит пользователя представиться.
|
|
* *Валидация*: Имя проверяется на длину (от 2 до 50 символов) во избежание отправки пустых или некорректных строк.
|
|
2. **Ввод Номера телефона (`FORM_PHONE`)**:
|
|
* Бот принимает номер в любом формате.
|
|
* *Умная нормализация*: Бот автоматически удаляет пробелы, скобки, дефисы и приводит номера, начинающиеся с `8` или `7`, к единому международному стандарту `+7XXXXXXXXXX`.
|
|
* *Валидация*: Некорректный ввод (например, буквы или слишком короткий номер) блокируется с просьбой ввести верный телефон.
|
|
3. **Выбор Услуги (`FORM_QUESTION`)**:
|
|
* Бот высылает динамически сформированный из базы данных список услуг с актуальными ценами и описаниями.
|
|
* *Нечеткий поиск и сленг*: Пользователю не обязательно кликать по кнопке — бот распознает текстовый ввод и сленговые синонимы. Например:
|
|
* Ввод `"дота"`, `"дотка"`, `"dota"` $\rightarrow$ распознается как **Dota 2**.
|
|
* Ввод `"кс"`, `"ксго"`, `"контра"`, `"cs"` $\rightarrow$ распознается как **CS2**.
|
|
* Ввод `"пакет Pro"` $\rightarrow$ распознается по вхождению подстроки.
|
|
|
|
---
|
|
|
|
### Экран проверки данных и точечное редактирование
|
|
Вместо мгновенной отправки заявки, бот перенаправляет пользователя на **Экран проверки данных (`FORM_REVIEW`)**:
|
|
|
|
* Бот выводит аккуратную сводную карточку с введенными Именем, Телефоном и Услугой.
|
|
* Если пользователь заметил опечатку, ему **не нужно отменять всю заявку и заполнять её заново**.
|
|
* При клике на кнопку **«Изменить данные 🔄»** открывается меню точечного редактирования (`FORM_EDIT_MENU`), где за один клик можно изменить конкретное поле:
|
|
* *Изменить Имя 👤*
|
|
* *Изменить Телефон 📞*
|
|
* *Изменить Услугу 🎮*
|
|
* После изменения поля бот мгновенно возвращает пользователя на экран проверки с обновленной карточкой.
|
|
|
|
---
|
|
|
|
### Упрощенное согласие и оферта
|
|
При нажатии «Да, всё верно! ✅» бот переходит к этапу получения юридического согласия (`FORM_CONSENT_1`):
|
|
* Вместо простыни юридического текста бот отправляет лаконичное и психологически комфортное сообщение с просьбой дать согласие на обработку персональных данных и условия оферты.
|
|
* Бот **автоматически прикрепляет к сообщению файл оферты** `Dogovor_oferty_kibersport.docx` как нативное вложение ВКонтакте. Пользователь может скачать его в один клик прямо из чата.
|
|
* При нажатии кнопки **«Согласен(а) и подтверждаю ✅»** заявка завершается, отправляется менеджеру, а сессия сбрасывается в главное меню.
|
|
|
|
---
|
|
|
|
### Интерактивный раздел FAQ и лид-магнит
|
|
В меню частых вопросов пользователь может быстро ознакомиться со справочной информацией:
|
|
* **Цены 💰**: Выводит тарифы на тренировки. Содержит **лид-магнит** — купон на скидку 10% на первое занятие при немедленном оформлении заявки.
|
|
* **Услуги ⚙️**: Детальное описание тренировочного процесса, разбора реплеев и тактики.
|
|
* **Контакты 📞**: Номер телефона, email, адрес киберарены Cyber Pro и график работы.
|
|
* **О компании 🏢**: Информация о школе, MMR тренеров (7000+) и истории побед с 2022 года.
|
|
|
|
---
|
|
|
|
### Режим связи с живым оператором
|
|
Если у клиента нестандартный вопрос, он может нажать кнопку **«Позвать оператора 🧑💼»**:
|
|
1. Бот переходит в состояние `OPERATOR_CHAT` и полностью отключает автоматические ответы.
|
|
2. Бот мгновенно отправляет оператору (на ID, указанный в `OPERATOR_PEER_ID`) уведомление о вызове с **историей последних 10 сообщений клиента для контекста**.
|
|
3. Все последующие сообщения клиента пересылаются оператору напрямую.
|
|
4. В любой момент клиент может нажать кнопку **«Завершить диалог 🚪»**, чтобы отключить оператора и вернуться к автоматическому боту.
|
|
|
|
---
|
|
|
|
## ⚙️ Панель администратора и безопасность
|
|
|
|
Бот оснащен полноценной административной консолью, встроенной прямо в чат ВКонтакте.
|
|
|
|
### Разграничение прав доступа
|
|
* Безопасность бота базируется на списке уникальных идентификаторов ВКонтакте, хранящихся в переменной `ADMIN_IDS` файла `config.py`.
|
|
* Если ID пользователя нет в этом списке, бот никогда не среагирует на управляющие команды, а воспримет их как обычные сообщения, защищая систему от взлома.
|
|
|
|
---
|
|
|
|
### Управление услугами в реальном времени (CRUD)
|
|
Администраторы могут отправлять боту специальные команды. Бот распознает их, записывает изменения в базу данных SQLite и мгновенно сбрасывает кэш в оперативной памяти.
|
|
|
|
```
|
|
Администратор База Данных SQLite Активные Клиенты
|
|
[ ред 1 цена 1 800 ₽ ] ──> [ bot.py ] ──> [ Таблица services ] ──> [ Обновление в чате клиента ]
|
|
```
|
|
|
|
#### Доступные команды:
|
|
|
|
| Команда | Описание | Пример использования |
|
|
| :--- | :--- | :--- |
|
|
| **`админка`** (или `/admin`, `услуги`) | Выводит список всех активных услуг (ID, Название, Цена, Описание) и справку по командам. | `админка` |
|
|
| **`ред [ID] [поле] [значение]`** | Изменяет указанное поле у существующей услуги. Доступные поля: `имя`, `цена`, `описание`. | `ред 1 цена 1 800 ₽/час` <br> `ред 2 описание Новое описание` |
|
|
| **`доб [Имя] | [Цена] | [Описание]`** | Добавляет новую услугу. Поля должны разделяться вертикальной чертой `|`. | `доб Тренировка по Valorant 🎯 | 1 200 ₽/час | Разбор aim.` |
|
|
| **`удал [ID]`** | Мягко удаляет услугу (переключает статус `is_active = 0`). Она перестает отображаться в списке выбора у клиентов. | `удал 4` |
|
|
|
|
---
|
|
|
|
## 🗄️ База данных и логирование
|
|
|
|
Вся информация хранится в локальной базе данных SQLite в файле `bot_database.db`. Архитектура состоит из трех таблиц:
|
|
|
|
1. **`user_states`**:
|
|
* Хранит текущие состояния диалога пользователей (FSM-схема) и временно сохраненные данные анкеты (имя, телефон, выбранная услуга, юридические согласия).
|
|
2. **`dialogue_logs`**:
|
|
* Ведет полный сквозной хронологический лог всех входящих и исходящих сообщений (`user` / `bot`).
|
|
* Используется для передачи контекста оператору при переключении диалога.
|
|
3. **`services`**:
|
|
* Хранит динамический список услуг школы. Содержит поля `id`, `name`, `price`, `description`, `is_active`.
|
|
* Автоматически заполняется базовыми услугами кибершколы при первом создании БД (авто-сидинг).
|
|
4. **`web_registrations`**:
|
|
* Хранит все заявки, заполненные клиентами через веб-форму на сайте (поля: `id`, `name`, `phone`, `email`, `vk_link`, `agree_oferta`, `agree_policy`, `agree_newsletter`, `created_at`). Это обеспечивает единое централизованное хранилище заявок из всех каналов в SQLite.
|
|
|
|
---
|
|
|
|
## 🛠️ Установка, настройка и запуск
|
|
|
|
### Системные требования
|
|
* Python 3.8 или выше.
|
|
* Установленная библиотека `vk_api`.
|
|
|
|
---
|
|
|
|
### Настройка конфигурации
|
|
### Настройка конфигурации (.env)
|
|
Перед запуском создайте или отредактируйте файл `.env` в корневой директории проекта (вы можете скопировать настройки из шаблона `.env.example`). Заполните следующие переменные среды:
|
|
|
|
```env
|
|
# Токен сообщества ВКонтакте
|
|
VK_TOKEN=ваш_токен_сообщества_vk
|
|
|
|
# ID Вашей группы ВКонтакте (целое число)
|
|
VK_GROUP_ID=123456789
|
|
|
|
# ID Вашей личной страницы VK (куда будут приходить лиды и вызовы оператора)
|
|
OPERATOR_PEER_ID=987654321
|
|
|
|
# Список ID администраторов через запятую для доступа к админ-меню через чат
|
|
ADMIN_IDS=987654321,111222333
|
|
```
|
|
|
|
Файл `.gitignore` настроен на игнорирование локального файла `.env`, базы данных `bot_database.db` и таблиц Excel, чтобы защитить конфиденциальные данные от попадания в публичные репозитории.
|
|
|
|
---
|
|
|
|
### Запуск бота
|
|
|
|
#### 1. В режиме продакшена (LongPoll)
|
|
Для работы в реальном сообществе ВКонтакте запустите файл `bot.py`:
|
|
```bash
|
|
python bot.py
|
|
```
|
|
Бот подключится к серверам VK API и начнет непрерывное прослушивание сообщений сообщества.
|
|
|
|
#### 2. В режиме локального тестирования (Консольная эмуляция)
|
|
Если в `config.py` указаны стандартные заглушки, бот **автоматически запустится в безопасном режиме консольного эмулятора**:
|
|
* Бот не будет обращаться к VK API.
|
|
* В консоли запустится интерактивный чат: вы сможете писать боту сообщения с клавиатуры, тестировать воронку, проверять валидацию и точечное редактирование.
|
|
* Для проверки админ-панели в консольном эмуляторе по умолчанию используется эмуляция ID администратора. Вы можете отправлять команды `админка`, `ред`, `доб` и `удал` и сразу видеть изменения.
|
|
|
|
---
|
|
|
|
### Запуск автоматических тестов
|
|
Для проведения полной верификации кодовой базы и всех 13 сценариев (включая безопасность и CRUD) выполните команду:
|
|
```bash
|
|
python test_bot_suite.py
|
|
```
|
|
Результаты тестов и подробные транскрипты диалогов будут сохранены в файл [test_suite_output.log](file:///m:/bot_vk_ikp_prodagi/test_suite_output.log) в кодировке UTF-8.
|