# 📖 Руководство пользователя чат-бота «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.