Пробую ещё раз залить, т.к. прошлый раз залилось с ошибкой

2026-06-15 09:16:37 +03:00
commit f38324645e
14 changed files with 2935 additions and 0 deletions
@@ -0,0 +1,193 @@
+# 📖 Руководство пользователя чат-бота «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.