telegram-wine-bot

Краткий обзор проекта

telegram-wine-bot — это мультибот-платформа для ресторанов, объединяющая три роли:

1. Гостевой бот (src/guest-bot.js)

   • Для посетителей ресторана.
   • Позволяет просматривать меню (напитки, блюда), получать AI-рекомендации, оставлять отзывы, узнавать информацию о заведении.
   • Все данные подгружаются из Google Sheets.
   • Удобная навигация по категориям, быстрый доступ к карточкам напитков.

2. Бот обучения сотрудников (src/index.js)

   • Для персонала.
   • Включает режим обучения, тесты, геймификацию, отслеживание прогресса, достижения.
   • Использует те же данные о напитках, что и гостевой бот.
   • Реализует расширенную навигацию, фильтры, поиск, интеграцию с мини-приложением (Web App).

3. Админ-бот (src/admin-bot.js)

   • Для управляющих и администраторов.
   • Позволяет модерировать отзывы, просматривать аналитику, управлять меню и пользователями, запускать рассылки и акции.
   • Может работать как через Telegram, так и через Web-интерфейс (при необходимости).

Технологии:

• Node.js (Cloudflare Workers)
• Telegram Bot API
• Google Sheets API (единая база данных для всех ролей)
• React/Vite (для Web App и, при необходимости, админки)

Особенности:

• Единая база напитков и меню для всех ролей.
• Гибкая архитектура: легко добавлять новые категории, фильтры, AI-функции.
• Простая интеграция с Google Sheets для обновления ассортимента.
• Современный UX для гостей, сотрудников и админов.

---

Проект подходит для ресторанов, баров и кафе, где важно быстро информировать гостей, обучать персонал и управлять меню через удобный интерфейс.

📚 Документация

�� Полная документация проекта находится в папке docs/

• 🏠 Обзор проекта
• 🎯 Геймификация
• 💪 Мотивация
• 🎨 Фронтенд
• 🌐 Miniweb
• 🤖 AI и обучение
• 🚀 Развертывание
• 🔒 Безопасность
• 🧪 Тестирование

📋 Краткое описание проекта

🎯 Назначение

Бот предназначен для обучения официантов ассортименту напитков ресторана. Система использует искусственный интеллект для персонализированного обучения и включает геймификацию для повышения мотивации.

🏗️ Архитектура системы

Проект состоит из двух независимых Cloudflare Workers:

1. Backend Worker

   • Обработка Telegram webhook'ов
   • API эндпоинты для статистики и данных
   • Управление базой данных D1
   • Система достижений и обучения

2. Frontend Worker

   • Мини-приложение Telegram WebApp
   • Современный интерфейс с Tailwind CSS
   • Темная тема с винной эстетикой
   • Интерактивные компоненты

📊 Источники данных

Данные о напитках загружаются из Google Sheets через API:

• Основной документ: Алкогольные напитки (вина, виски, ром, джин, водка, ликеры, пиво)
• Документ коктейлей: Коктейли, безалкогольные напитки, чай, кофе, премиксы
• Кеширование: Данные кешируются в Cloudflare KV на 1 час для быстрого доступа
• Fallback: При недоступности Google Sheets используются локальные тестовые данные

🏷️ Категоризация напитков

Система автоматически классифицирует напитки по категориям:

Алкогольные напитки:

• 🍷 Вина (название, сахар, крепость, страна, описание)
• 🥃 Виски (название, страна, крепость, тип, выдержка, описание)
• 🍺 Пиво (название, страна, плотность, крепость, описание)
• 🍸 Граппа, Порто, Коньяк, Вермут
• 🥃 Ром, Текила
• 🍶 Джин, Водка, Ликеры

Коктейли и напитки:

• 🍹 Коктейли (название, метод, посуда, лед, состав)
• 🥤 Микс дринк (название, метод, посуда, лед, состав)
• 🧃 Лимонады и Милкшейки (название, метод, посуда, лед, состав)
• ☕ Кофе (название, метод, посуда, лед, состав)
• 🍵 Чай (название, состав, метод)
• 🍯 Премиксы (название, состав)
• 📋 ПФ (категория, название, состав, описание)
• ❌ нет в меню (категория, название, метод, посуда, лед, состав)

🤖 ИИ система

Cloudflare AI используется для:

• Генерации вопросов: Создание персонализированных вопросов на основе данных о напитках
• Консультаций: Экспертные ответы на вопросы официантов
• Адаптации сложности: Автоматическое изменение уровня сложности на основе прогресса
• Персонализации: Учет слабых сторон и предпочтений пользователя

Как ИИ понимает что делать:

1. Контекст напитка: ИИ получает полную информацию о конкретном напитке
2. Тип вопроса: Система указывает тип вопроса (сочетание с блюдами, температура подачи, посуда и т.д.)
3. Сложность: Уровень сложности адаптируется к прогрессу пользователя
4. Структурированный ответ: ИИ возвращает вопрос, 4 варианта ответа, правильный ответ и объяснение

🎓 Система обучения

Режимы обучения:

1. 🎯 Быстрый тест - 5 случайных вопросов для быстрой проверки
2. 📚 Урок по категории - изучение конкретной категории напитков
3. 🤖 ИИ-обучение - персонализированные вопросы от искусственного интеллекта
4. 🎯 Персонализированный тест - вопросы на основе слабых сторон пользователя

Типы вопросов:

• Сочетание с блюдами (wine_pairing)
• Температура подачи (serving_temp)
• Выбор посуды (glassware)
• Описание и характеристики (description)
• Страна происхождения (country)
• Крепость напитка (alcohol_content)
• Состав и ингредиенты (ingredients)
• Метод приготовления (method)

Система прогресса:

• Уровни: Новичок → Знаток → Эксперт → Легенда
• Очки опыта: Начисляются за правильные ответы
• Серии: Отслеживание последовательных правильных ответов
• Аналитика: Детальная статистика по категориям и типам вопросов

Достижения:

• 🎯 Первые шаги (10 правильных ответов)
• 🔥 Серия побед (5 ответов подряд)
• 💎 Стобалльник (100 баллов)
• 🤖 ИИ-мастер (10 ИИ-вопросов)
• 📚 Категорийный эксперт (все категории)
• 🏆 Чемпион (1000 баллов)

Ежедневные задания:

• 5 типов заданий с автоматической генерацией
• Система наград за выполнение
• Прогресс-трекинг в реальном времени
• Статистика выполнения за неделю

💾 Хранение данных

• Cloudflare D1 (SQLite): Пользователи, сессии, ответы, достижения
• Cloudflare KV: Кеширование данных о напитках
• Аналитика: Детальная статистика обучения и прогресса

🔒 Безопасность

• Проверка User-Agent
• Блокировка подозрительных IP
• Rate limiting
• CAPTCHA для подозрительной активности
• Сессионные токены
• Исключения для Telegram webhook

📁 Структура проекта

telegram-wine-bot/
├── db/                    # Скрипты и файлы базы данных
│   ├── schema.sql         # Схема базы данных
│   ├── init-db.js         # Инициализация БД
│   └── reset-user.sql     # Сброс данных пользователя
├── docs/                  # Документация по категориям
│   ├── ai/               # Документация по ИИ
│   ├── security/         # Документация по безопасности
│   ├── deployment/       # Руководство по развертыванию
│   ├── migration/        # Миграции и структура данных
│   ├── learning/         # Система обучения
│   ├── overview/         # Общая структура и описание
│   ├── changelog/        # История изменений и фиксов
│   ├── troubleshooting/  # Руководства по устранению неполадок
│   └── miniweb/          # Документация по мини-приложению
├── frontend/             # Frontend Worker (мини-приложение)
│   ├── src/
│   │   ├── handlers/     # Обработчики API
│   │   └── utils/        # Утилиты
│   ├── package.json
│   └── wrangler.toml
├── scripts/              # Все тестовые и вспомогательные скрипты
├── src/                  # Backend Worker (основной бот)
│   ├── handlers/         # Обработчики команд и API
│   ├── miniweb/          # HTML страницы мини-приложения
│   ├── utils/            # Утилиты и вспомогательные функции
│   └── index.js          # Основной файл воркера
├── package.json          # Зависимости backend
├── wrangler.toml         # Конфигурация backend воркера
└── README.md             # Этот файл

✨ Новые возможности

🏆 Система достижений

• 10 типов достижений с прогрессивной системой наград
• Система уровней от Новичка до Легенды
• История достижений с датами получения
• Уведомления о новых достижениях

📊 Расширенная аналитика

• Постоянное хранение всех данных в Cloudflare D1
• Статистика по категориям и типам вопросов
• Детальная аналитика сессий обучения
• Экспорт данных пользователя

📅 Ежедневные задания

• 5 типов заданий с автоматической генерацией
• Система наград за выполнение
• Прогресс-трекинг в реальном времени
• Статистика выполнения за неделю

💎 Система опыта

• Очки опыта за каждый ответ
• Множители для выходных и серий
• Бонусы за идеальные тесты
• Прогресс уровней с визуализацией

🎨 Современный интерфейс

• Темная тема с винными градиентами
• Tailwind CSS для стилизации
• Адаптивный дизайн для всех устройств
• Анимации и эффекты для лучшего UX

🚀 Быстрый старт

1. Клонирование и установка

git clone <repository-url>
cd telegram-wine-bot
npm install
cd frontend && npm install

2. Настройка базы данных

# Создание базы данных D1
npx wrangler d1 create wine-bot-db

# Обновление wrangler.toml с полученным database_id
# Применение схемы
npx wrangler d1 execute wine-bot-db --file=db/schema.sql

3. Настройка секретов

# Backend секреты
npx wrangler secret put TELEGRAM_BOT_TOKEN
npx wrangler secret put GOOGLE_SHEETS_API_KEY
npx wrangler secret put GOOGLE_SHEETS_SPREADSHEET_ID
npx wrangler secret put GOOGLE_SHEETS_COCKTAIL_SPREADSHEET_ID
npx wrangler secret put CLOUDFLARE_ACCOUNT_ID
npx wrangler secret put CLOUDFLARE_AI_TOKEN

# Frontend секреты (те же самые)
cd frontend
npx wrangler secret put TELEGRAM_BOT_TOKEN
npx wrangler secret put GOOGLE_SHEETS_API_KEY
npx wrangler secret put GOOGLE_SHEETS_SPREADSHEET_ID
npx wrangler secret put GOOGLE_SHEETS_COCKTAIL_SPREADSHEET_ID
npx wrangler secret put CLOUDFLARE_ACCOUNT_ID
npx wrangler secret put CLOUDFLARE_AI_TOKEN

4. Развертывание

# Развертывание backend
npm run deploy

# Развертывание frontend
cd frontend
npm run deploy

5. Настройка Telegram Bot

# Установка webhook для backend
curl -X POST https://your-domain/set-webhook

# Обновление Web App URL в BotFather
# Установить URL: https://your-domain/

📱 Использование

Главное меню

🍷 Открыть Web App
🍽️ Меню          🍷 Алкоголь
🎓 Обучение      🔍 Поиск
📋 Все напитки   🔄 Обновить данные
🤖 Спросить у ИИ 👨‍💻 Автор разработки

Система обучения

• 🎯 Быстрый тест - 5 вопросов для быстрой проверки
• 📚 Урок по категории - изучение конкретных категорий
• 🧠 ИИ-обучение - персонализированные вопросы с ИИ
• 🎯 Персонализированный тест - на основе вашего прогресса

Профиль пользователя

👤 Ваш профиль

🏆 Уровень: 3 Знаток (75%)
📊 Общий счет: 450 баллов
💎 Очки опыта: 1,250 XP
📝 Всего вопросов: 89
✅ Правильных ответов: 67
🎯 Точность: 75%
🔥 Лучшая серия: 8 ответов
📅 Дней подряд: 5

Достижения

• 🎯 Первые шаги - 10 правильных ответов
• 🔥 Серия побед - 5 ответов подряд
• 💎 Стобалльник - 100 баллов
• 🤖 ИИ-мастер - 10 ИИ-вопросов
• 📚 Категорийный эксперт - все категории
• 🏆 Чемпион - 1000 баллов

🔧 API эндпоинты

Backend Worker (your-domain)

Статистика пользователя

GET /user-stats?chatId=123456789

Достижения пользователя

GET /user-achievements?chatId=123456789

Ежедневные задания

GET /daily-challenges?chatId=123456789

Статус бота

GET /bot-status

Управление webhook

POST /set-webhook
POST /delete-webhook
GET /webhook-info

Frontend Worker (your-domain)

Мини-приложение

• Главная страница: /
• Меню: /menu.html
• Алкоголь: /alcohol.html
• Обучение: /learning.html
• Достижения: /achievements.html
• ИИ: /ai.html
• Поиск: /search.html
• Коктейли: /wines.html
• Задания: /challenges.html

🔧 Технические детали

Backend Worker

• Платформа: Cloudflare Workers
• База данных: Cloudflare D1 (SQLite)
• Кеширование: Cloudflare KV
• ИИ: Cloudflare AI
• Webhook: Telegram Bot API

Frontend Worker

• Платформа: Cloudflare Workers
• Стили: Tailwind CSS
• Тема: Темная с винными градиентами
• Адаптивность: Мобильные устройства
• Интерактивность: JavaScript

База данных (Cloudflare D1)

Файлы и скрипты для работы с базой данных находятся в папке db/.

Модули системы

• src/handlers/database.js - Управление базой данных
• src/handlers/achievements.js - Система достижений и уровней
• src/handlers/dailyChallenges.js - Ежедневные задания
• src/handlers/learning.js - Обновленная система обучения

🐛 Известные проблемы и решения

Проблема: Пустые ответы от API

Решение: Проверьте подключение к базе данных D1 и убедитесь, что схема применена корректно.

Проблема: Webhook возвращает 404

Решение: Убедитесь, что backend worker развернут и доступен по адресу your-domain.

Проблема: Frontend не загружается

Решение: Проверьте, что frontend worker развернут и доступен по адресу your-domain.

📈 Мониторинг и логи

Логирование

Система включает подробное логирование для отладки:

• Запросы к API
• Операции с базой данных
• Ошибки и исключения
• Статистика использования

Метрики

• Количество активных пользователей
• Статистика обучения
• Популярные категории
• Эффективность ИИ-вопросов

🤝 Вклад в проект

1. Форкните репозиторий
2. Создайте ветку для новой функции
3. Внесите изменения
4. Создайте Pull Request

📄 Лицензия

Этот проект лицензирован под MIT License.

👨‍💻 Автор

Максим Ланиес - разработчик системы обучения для ресторана KETCH UP.

---

Последнее обновление: 23 июля 2025 Версия: 2.0.0 Статус: ✅ Работает стабильно

🛠️ Новые функции админской панели (2025)

Массовые и индивидуальные действия над пользователями

• 🚫 Блокировка/разблокировка пользователя: через кнопки в карточке пользователя или команды:
  • /block_user <ID> — заблокировать пользователя
  • /unblock_user <ID> — разблокировать пользователя
• 🔄 Сброс прогресса пользователя:
  • /reset_user <ID> — сбросить прогресс пользователя (очки, опыт, достижения, сессии)
• 📢 Массовая рассылка сообщений:
  • /broadcast <текст> — отправить сообщение всем незаблокированным пользователям

Работа с отзывами

• ✉️ Ответ на отзыв:
  • Кнопка "Ответить" в детальном просмотре отзыва
  • /reply_feedback <feedback_id> <текст> — отправить ответ пользователю
• ✅ Метка "обработано" для отзывов:
  • Кнопка "Обработано" в детальном просмотре отзыва
  • /mark_feedback <feedback_id> — отметить отзыв как обработанный

Быстрый переход к действиям

• Все действия доступны через кнопки в админке (карточка пользователя, детальный отзыв)
• Массовые действия доступны через команды

---

🎁 Магазин призов (Reward Shop)

Магазин призов позволяет пользователям обменивать накопленные XP на призы, а администраторам — управлять ассортиментом через админ-бота.

Для сотрудников (UX)

• В магазине отображается ваш текущий XP.
• Список призов начинается с заголовка 'Товары:'.
• Для каждого приза показывается название, стоимость XP, остаток.
• Кнопка 'Купить' появляется только если хватает XP.
• Если не хватает XP — появляется кнопка 'Недостаточно XP'.
• Если приз закончился — он не отображается.
• Пример:

🎁 Магазин призов

Ваши XP: 75

Товары:
• Кофе — 150 XP
Осталось: 5

Для администраторов

• Добавление призов через раздел "Призы" в админ-боте.
• Многошаговый диалог: название → стоимость XP → количество → описание.
• Состояние диалога хранится в Cloudflare KV (WINE_CACHE), что гарантирует стабильную работу в serverless-архитектуре.
• После завершения приз появляется в списке, доступен для пользователей.
• Управление остатками и деактивация призов через интерфейс админ-бота.

---

Гостевой бот для Telegram

Гостевой бот предназначен для посетителей ресторана:

• Просмотр меню (безалкогольные и алкогольные напитки)
• AI-диалог для подбора блюд по предпочтениям
• Оставить отзыв
• Получить информацию о заведении

Подробнее: docs/guest-bot.md