diff --git a/README.md b/README.md index 8d1c8b6..d07d29b 100644 --- a/README.md +++ b/README.md @@ -1 +1,474 @@ - +# 🦋 Fly-Fly Team Bot + +Telegram-бот для детской игровой программы **«Ловец бабочек»** — образовательная игра с рейтингом, стаями и школой бабочковода для детей 9–12 лет. + +Бот: [@fly_fly_team_bot](https://t.me/fly_fly_team_bot) + +--- + +## 📋 Содержание + +- [Описание](#описание) +- [Возможности](#возможности) +- [Архитектура проекта](#архитектура-проекта) +- [Установка](#установка) +- [Конфигурация](#конфигурация) +- [Запуск](#запуск) +- [Как пользоваться ботом](#как-пользоваться-ботом) +- [Система очков](#система-очков) +- [Школа бабочковода](#школа-бабочковода) +- [Стаи](#стаи) +- [Реферальная система](#реферальная-система) +- [Модерация фото](#модерация-фото) +- [Проверка подписки на группу](#проверка-подписки-на-группу) +- [База данных](#база-данных) +- [Зависимости](#зависимости) +- [Структура проекта](#структура-проекта) +- [Лицензия](#лицензия) + +--- + +## Описание + +**Fly-Fly Team Bot** — это Telegram-бот, который: + +- Проводит детей через **5-урочную «Школу бабочковода»** с образовательными текстами и вопросами +- Позволяет создавать **стаи (команды)** и соревноваться в рейтинге +- Начисляет **очки** за прохождение школы, приглашение друзей и другие действия +- Проверяет **подписку на группу** Telegram перед доступом к функциям +- Отправляет **фото на модерацию** администратору для ручного начисления очков + +--- + +## Возможности + +| Возможность | Описание | +|---|---| +| 📚 **Школа бабочковода** | 5 уроков о бабочках с вопросами и объяснениями | +| 🦋 **Поймай друга** | Отправка GIF-анимации с реферальной ссылкой | +| 🏆 **Рейтинг** | Топ-10 пользователей и рейтинг стай | +| 📌 **Стая** | Создание/вступление в стаю, управление участниками | +| ⚙️ **Управление стаей** | Переименование, исключение участников, роспуск стаи | +| 📊 **Мои очки** | Персональная статистика + топ-10 ловцов | +| 🛒 **Бабочкарий** | Ссылка на покупку продукта | +| 🔒 **Проверка подписки** | Обязательная подписка на группу для доступа к функциям | +| 📸 **Модерация фото** | Фото → модератор → кнопки начисления 5/15 очков | +| 🎁 **Реферальный бонус** | +5 очков за каждого приглашённого друга | + +--- + +## Архитектура проекта + +``` +main.py + └── src/bot.py # Основная логика бота (telebot) + ├── database.py # Работа с JSON-базой данных + ├── school.py # Учебная программа (5 вопросов) + ├── admin_tools.py# Инструменты администратора + └── utils.py # Утилиты (валидаторы, форматирование) + └── config/config.py # Конфигурация (токен, очки, ID) + └── .env # Секреты (токен бота, ID группы) +``` + +**Ключевые технологии:** +- **pyTelegramBotAPI (telebot)** — библиотека для Telegram Bot API +- **JSON-файлы** — хранение данных пользователей +- **python-dotenv** — загрузка переменных окружения + +--- + +## Установка + +### 1. Клонирование репозитория + +```bash +git clone +cd fly-fly-team-bot +``` + +### 2. Создание виртуального окружения + +```bash +python -m venv venv +``` + +**Windows:** +```bash +venv\Scripts\activate +``` + +**Linux/macOS:** +```bash +source venv/bin/activate +``` + +### 3. Установка зависимостей + +```bash +pip install pyTelegramBotAPI python-dotenv requests +``` + +### 4. Настройка конфигурации + +```bash +# Скопируйте пример конфигурации +cp config/.env.example config/.env +# Или используйте корневой .env +cp .env.example .env +``` + +Заполните `.env` своими значениями (см. [Конфигурация](#конфигурация)). + +--- + +## Конфигурация + +### Переменные окружения (`.env`) + +| Переменная | Описание | Пример | +|---|---|---| +| `TELEGRAM_BOT_TOKEN` | Токен бота от @BotFather | `123456:ABC-DEF...` | +| `ADMIN_ID` | Telegram ID администратора-модератора | `7665285886` | +| `REQUIRED_GROUP_CHAT_ID` | ID группы для проверки подписки | `-1002395700013` | +| `TELEGRAM_PROXY_URL` | Прокси для Telegram API (опционально) | `socks5://user:pass@host:port` | +| `TELEGRAM_CONNECT_TIMEOUT` | Таймаут подключения (сек) | `30` | +| `TELEGRAM_READ_TIMEOUT` | Таймаут чтения (сек) | `120` | +| `DEBUG` | Режим отладки | `False` | +| `LOG_LEVEL` | Уровень логирования | `INFO` | + +### Константы системы (`config/config.py`) + +| Константа | Значение | Описание | +|---|---|---| +| `POINTS_SCHOOL_COMPLETE` | `10` | Очков за прохождение школы | +| `POINTS_REFERRAL_BONUS` | `5` | Очков за приглашённого друга | +| `POINTS_BUTTERFLY_ACTIVATION` | `30` | Очков за активацию Бабочкария | +| `REQUIRED_GROUP_LINK` | `https://t.me/+2RjGyDueqqAyM2Ey` | Ссылка на группу | + +--- + +## Запуск + +### Основной способ + +```bash +python main.py +``` + +### Альтернативный запуск (напрямую из src) + +```bash +python -m src.bot +``` + +### Вывод при запуске + +``` +🦋 Бот Fly-Fly запущен! +🤖 @fly_fly_team_bot +Ожидаю сообщений... +``` + +### Остановка + +`Ctrl+C` в терминале. + +--- + +## Как пользоваться ботом + +### Первый запуск + +1. Пользователь отправляет `/start` боту +2. Бот создаёт профиль пользователя +3. Отправляется приветственное сообщение с требованием подписки на группу +4. Пользователь подписывается и отправляет **«Готово»** +5. Бот подтверждает участие в конкурсе + +### Главное меню + +| Кнопка | Описание | +|---|---| +| 📚 Школа бабочковода | Пройти 5 уроков (если не пройдено) | +| 🦋 Поймать друга | Отправить реферальную ссылку друзьям | +| 📊 Мои очки | Персональная статистика + топ-10 | +| 🏆 Рейтинг | Общий топ-10 ловцов | +| 📌 Стая | Информация о стае (если участник) | +| ⚙️ Управлять стаей | Управление (только капитан) | +| 🛒 Купить Бабочкарий | Ссылка на покупку | +| ❓ Справка | Правила игры | + +--- + +## Система очков + +| Действие | Очки | +|---|---| +| Прохождение школы | +10 ⭐ | +| Приглашение друга | +5 ⭐ | +| Фото одобрено модератором | +5 или +15 ⭐ | +| Активация Бабочкария | +30 ⭐ | + +Очки суммируются и определяют позицию в рейтинге. + +--- + +## Школа бабочковода + +5 уроков о бабочках: + +| Урок | Тема | +|---|---| +| 1 | Кто такие бабочки? (4 крыла) | +| 2 | Что едят бабочки? (хоботок) | +| 3 | Жизненный цикл бабочки (4 стадии) | +| 4 | Где живут бабочки? | +| 5 | Как стать ловцом бабочек? | + +Каждый урок состоит из: +- **Обучающего текста** с интересными фактами +- **Вопроса** с 4 вариантами ответа +- **Объяснения** правильного/неправильного ответа + +После прохождения всех 5 вопросов пользователь получает **+10 очков** и отметку `school_completed`. + +--- + +## Стаи + +### Создание стаи + +> ⚠️ Возможность создания стаи отключена в текущей версии. Стаи создаются автоматически при определённых условиях. + +### Вступление в стаю + +Пользователь переходит по реферальной ссылке `/start ` и автоматически вступает в стаю. + +### Управление стаей (капитан) + +| Действие | Описание | +|---|---| +| ✏️ Изменить название | Переименовать стаю (до 30 символов) | +| 👥 Исключить участника | Удалить участника из стаи | +| 📊 Рейтинг участников | Внутренний рейтинг стаи | +| 🚫 Разойти стаю | Распустить стаю (все участники выходят) | + +### Выход из стаи (участник) + +Участник может покинуть стаю через меню **«📌 Стая → 🚪 Выйти из стаи»** с подтверждением. + +**Капитан не может покинуть стаю** — только распустить её. + +--- + +## Реферальная система + +### Как работает + +1. Пользователь нажимает **«🦋 Поймать друга»** +2. Получает GIF + реферальную ссылку вида: + ``` + https://t.me/fly_fly_team_bot?start= + ``` +3. Друг переходит по ссылке и регистрируется +4. Бот проверяет условия: + - Пригласитель существует + - Приглашённый ещё не учтён в `invited_friends` + - Если задан `REQUIRED_GROUP_CHAT_ID` — приглашённый состоит в группе +5. Пригласителю начисляется **+5 очков** + +### Проверка членства в группе + +При реферальном начислении бот проверяет, что приглашённый является участником группы через `bot.get_chat_member()`. + +--- + +## Модерация фото + +### Процесс + +1. Пользователь находится в состоянии `awaiting_photo` (ожидание фото) +2. Отправляет фото боту +3. Бот пересылает фото **администратору** (`ADMIN_ID`) с inline-кнопками: + - **«Дать 15 баллов»** — начислить +15 очков + - **«Дать 5 баллов»** — начислить +5 очков + - **«Отклонить»** — отклонить фото +4. Администратор нажимает кнопку +5. Бот начисляет очки пользователю и уведомляет обоих + +### Callback-данные кнопок + +| Callback | Действие | +|---|---| +| `award_15_` | Начислить 15 очков | +| `award_5_` | Начислить 5 очков | +| `award_reject_` | Отклонить фото | + +--- + +## Проверка подписки на группу + +### Механизм + +Бот проверяет подписку пользователя на группу перед каждым действием: + +```python +def is_user_subscribed(telegram_id, chat_id) -> bool: + if not check_user_in_group(telegram_id): + send_subscription_required(chat_id) + return False + return True +``` + +### Проверка членства + +```python +def check_user_in_group(telegram_id) -> bool: + member = bot.get_chat_member(REQUIRED_GROUP_CHAT_ID, telegram_id) + return member.status in ['member', 'administrator', 'creator'] +``` + +### Подтверждение подписки + +Пользователь отправляет **«Готово»** — бот повторно проверяет подписку и подтверждает участие. + +--- + +## База данных + +### Тип: JSON-файл + +Данные хранятся в `data/users.json` в формате: + +```json +{ + "123456789": { + "telegram_id": 123456789, + "first_name": "Иван", + "username": null, + "is_butterfly_owner": false, + "school_completed": true, + "total_points": 45, + "team_id": null, + "team_name": null, + "created_at": "2025-01-15T10:30:00", + "last_activation_date": null, + "invited_friends": [], + "referred_by": 987654321, + "profile_updated": false + } +} +``` + +### Класс `Database` + +| Метод | Описание | +|---|---| +| `get_user(telegram_id)` | Получить пользователя | +| `create_user(...)` | Создать пользователя | +| `update_user(telegram_id, **kwargs)` | Обновить данные | +| `add_points(telegram_id, points)` | Добавить очки | +| `get_team_members(team_id)` | Участники стаи | +| `get_users_ranking()` | Топ-10 пользователей | +| `get_teams_ranking()` | Топ-10 стай | +| `create_team(captain_id, team_name)` | Создать стаю | +| `get_team(team_id)` | Информация о стае | +| `add_member_to_team(team_id, user_id)` | Добавить в стаю | +| `remove_member_from_team(team_id, user_id)` | Удалить из стаи | +| `update_team_name(team_id, new_name)` | Переименовать стаю | +| `disband_team(team_id)` | Распустить стаю | +| `mark_school_completed(telegram_id)` | Отметить школу пройденной | + +### Дополнительные файлы + +- `data/points_log.json` — лог начислений очков (валидация повторных начислений) +- `data/teams.json` — данные о стаях (через `TeamManager`) + +--- + +## Зависимости + +| Пакет | Версия | Описание | +|---|---|---| +| `pyTelegramBotAPI` | любая | Telegram Bot API клиент | +| `python-dotenv` | любая | Загрузка .env файлов | +| `requests` | любая | HTTP-запросы (для прокси) | + +--- + +## Структура проекта + +``` +fly-fly-team-bot/ +├── main.py # Точка входа (запуск bot.infinity_polling()) +├── README.md # Документация +├── bot-cat.mp4 # GIF-анимация для «Поймай друга» +├── bot-cat.gif # GIF-анимация (альтернатива) +│ +├── config/ +│ ├── __init__.py # Экспорт конфигурации +│ ├── config.py # Загрузка .env и константы +│ ├── .env # Секреты (не коммитить!) +│ └── .env.example # Пример конфигурации +│ +├── src/ +│ ├── __init__.py # Экспорт bot и Database +│ ├── bot.py # Основная логика бота (~1140 строк) +│ ├── database.py # Класс Database (модель данных, CRUD) +│ ├── school.py # SCHOOL_CURRICULUM (5 вопросов) +│ ├── admin_tools.py # AdminTools, DebugTools +│ └── utils.py # PointsValidator, TeamManager, MessageFormatter +│ +├── data/ +│ ├── users.json # База пользователей +│ └── points_log.json # Лог начислений очков +│ +└── docs/ # Дополнительная документация +``` + +--- + +## Команды бота + +| Команда | Описание | +|---|---| +| `/start` | Регистрация / приветствие | +| `/start 0` | Регистрация как владелец Бабочкария | +| `/start ` | Регистрация по реферальной ссылке | + +--- + +## Обработчики сообщений + +### Команды +- `/start` — регистрация + +### Текстовые кнопки +- `📚 Школа бабочковода флай-флай` — начало школы +- `🦋 Поймать друга` — реферальная ссылка + GIF +- `📊 Мои очки` — статистика +- `🏆 Рейтинг` — топ-10 +- `📌 Стая` — меню стаи +- `⚙️ Управлять стаей` — управление (капитан) +- `🛒 Купить Бабочкарий` — ссылка на покупку +- `❓ Справка` — правила игры +- `Готово` — подтверждение подписки + +### Callback-запросы (inline-кнопки) +- `answer__` — ответ на вопрос школы +- `team_members`, `team_stats`, `team_link` — меню стаи +- `leave_team`, `leave_confirm`, `leave_cancel` — выход из стаи +- `award_15_`, `award_5_`, `award_reject_` — модерация фото +- `manage_rename`, `manage_remove`, `manage_rating`, `manage_disband` — управление стаей +- `remove_` — исключить участника +- `disband_confirm` — подтвердить роспуск +- `back_menu`, `back_to_main`, `back_to_main_menu` — назад + +### Контент +- **Фото** — пересылка модератору (если ожидается фото) + +--- + +## Лицензия + +© Fly-Fly Team. Все права защищены.