a.gruzdev/bot_vk_ikp_prodagi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
377188a015b17eda726c2a73001755e0ef972b8f
bot_vk_ikp_prodagi/USER_GUIDE.md
T

18 KiB
Raw Blame History

📖 Руководство пользователя чат-бота «Cyber Pro»

Добро пожаловать в официальное руководство пользователя и техническую документацию для умного чат-бота ВКонтакте киберспортивной школы «Cyber Pro».

Этот бот спроектирован с учетом передовых практик UX/UI-дизайна, психологии продаж и оптимизации конверсии. Он помогает потенциальным клиентам быстро ознакомиться с услугами школы, получить привлекательный лид-магнит, заполнить безошибочную заявку на обучение и при необходимости мгновенно связаться с живым оператором.

Для владельцев бизнеса и администраторов бот предоставляет защищенную панель управления, позволяющую редактировать услуги и цены прямо из чата ВКонтакте в режиме реального времени.

🗺️ Содержание

  1. 🚀 Возможности для клиентов (Пользовательский интерфейс)
  2. ⚙️ Панель администратора и безопасность
  3. 🗄️ База данных и логирование
  4. 🛠️ Установка, настройка и запуск

🚀 Возможности для клиентов (Пользовательский интерфейс)

Главное меню

При старте (команда начать или приветствие привет) бот высылает красивое приветствие и открывает клавиатуру с тремя главными кнопками:

  • Заполнить заявку 📝 — запуск интерактивной анкеты.
  • Частые вопросы ❓ — переход в раздел 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 ₽/час
ред 2 описание Новое описание
**`доб [Имя] [Цена] [Описание]`**
удал [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). Заполните следующие переменные среды:

# Токен сообщества ВКонтакте
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:

python bot.py

Бот подключится к серверам VK API и начнет непрерывное прослушивание сообщений сообщества.

2. В режиме локального тестирования (Консольная эмуляция)

Если в config.py указаны стандартные заглушки, бот автоматически запустится в безопасном режиме консольного эмулятора:

  • Бот не будет обращаться к VK API.
  • В консоли запустится интерактивный чат: вы сможете писать боту сообщения с клавиатуры, тестировать воронку, проверять валидацию и точечное редактирование.
  • Для проверки админ-панели в консольном эмуляторе по умолчанию используется эмуляция ID администратора. Вы можете отправлять команды админка, ред, доб и удал и сразу видеть изменения.

Запуск автоматических тестов

Для проведения полной верификации кодовой базы и всех 13 сценариев (включая безопасность и CRUD) выполните команду:

python test_bot_suite.py

Результаты тестов и подробные транскрипты диалогов будут сохранены в файл test_suite_output.log в кодировке UTF-8.

Reference in New Issue View Git Blame Copy Permalink