spacy
/
Fly.team.bot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Fly.team.bot/README.md

19 KiB
Raw Blame History

🦋 Fly-Fly Team Bot

Telegram-бот для детской игровой программы «Ловец бабочек» — образовательная игра с рейтингом, стаями и школой бабочковода для детей 9–12 лет.

Бот: @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. Клонирование репозитория

git clone <repository-url>
cd fly-fly-team-bot

2. Создание виртуального окружения

python -m venv venv

Windows:

venv\Scripts\activate

Linux/macOS:

source venv/bin/activate

3. Установка зависимостей

pip install pyTelegramBotAPI python-dotenv requests

4. Настройка конфигурации

# Скопируйте пример конфигурации
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 Ссылка на группу

Запуск

Основной способ

python main.py

Альтернативный запуск (напрямую из src)

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 <team_id> и автоматически вступает в стаю.

Управление стаей (капитан)

Действие Описание
✏️ Изменить название Переименовать стаю (до 30 символов)
👥 Исключить участника Удалить участника из стаи
📊 Рейтинг участников Внутренний рейтинг стаи
🚫 Разойти стаю Распустить стаю (все участники выходят)

Выход из стаи (участник)

Участник может покинуть стаю через меню «📌 Стая → 🚪 Выйти из стаи» с подтверждением.

Капитан не может покинуть стаю — только распустить её.

Реферальная система

Как работает

  1. Пользователь нажимает «🦋 Поймать друга»
  2. Получает GIF + реферальную ссылку вида: 
    https://t.me/fly_fly_team_bot?start=<telegram_id>
  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_<user_id> Начислить 15 очков
award_5_<user_id> Начислить 5 очков
award_reject_<user_id> Отклонить фото

Проверка подписки на группу

Механизм

Бот проверяет подписку пользователя на группу перед каждым действием:

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

Проверка членства

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 в формате:

{
  "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 <id> Регистрация по реферальной ссылке

Обработчики сообщений

Команды

  • /start — регистрация

Текстовые кнопки

  • 📚 Школа бабочковода флай-флай — начало школы
  • 🦋 Поймать друга — реферальная ссылка + GIF
  • 📊 Мои очки — статистика
  • 🏆 Рейтинг — топ-10
  • 📌 Стая — меню стаи
  • ⚙️ Управлять стаей — управление (капитан)
  • 🛒 Купить Бабочкарий — ссылка на покупку
  • ❓ Справка — правила игры
  • Готово — подтверждение подписки

Callback-запросы (inline-кнопки)

  • answer_<num>_<idx> — ответ на вопрос школы
  • team_members, team_stats, team_link — меню стаи
  • leave_team, leave_confirm, leave_cancel — выход из стаи
  • award_15_<id>, award_5_<id>, award_reject_<id> — модерация фото
  • manage_rename, manage_remove, manage_rating, manage_disband — управление стаей
  • remove_<user_id> — исключить участника
  • disband_confirm — подтвердить роспуск
  • back_menu, back_to_main, back_to_main_menu — назад

Контент

  • Фото — пересылка модератору (если ожидается фото)

Лицензия

© Fly-Fly Team. Все права защищены.