Go to file

Ivan Vetrov 7930ead4f1 readme.md		2026-04-15 14:08:37 +03:00
config	work	2026-04-15 14:00:23 +03:00
src	work	2026-04-15 14:00:23 +03:00
.gitignore	first commit: add README and gitignore	2026-04-15 13:58:25 +03:00
README.md	readme.md	2026-04-15 14:08:37 +03:00
bot-cat.gif	work	2026-04-15 14:00:23 +03:00
bot-cat.mp4	work	2026-04-15 14:00:23 +03:00
main.py	work	2026-04-15 14:00:23 +03:00

README.md

🦋 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 в терминале.

Как пользоваться ботом

Первый запуск

Пользователь отправляет /start боту
Бот создаёт профиль пользователя
Отправляется приветственное сообщение с требованием подписки на группу
Пользователь подписывается и отправляет «Готово»
Бот подтверждает участие в конкурсе

Главное меню

Кнопка	Описание
📚 Школа бабочковода	Пройти 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 символов)
👥 Исключить участника	Удалить участника из стаи
📊 Рейтинг участников	Внутренний рейтинг стаи
🚫 Разойти стаю	Распустить стаю (все участники выходят)

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

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

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

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

Как работает

Пользователь нажимает «🦋 Поймать друга»
Получает GIF + реферальную ссылку вида:
```
https://t.me/fly_fly_team_bot?start=<telegram_id>
```
Друг переходит по ссылке и регистрируется
Бот проверяет условия:
- Пригласитель существует
- Приглашённый ещё не учтён в invited_friends
- Если задан REQUIRED_GROUP_CHAT_ID — приглашённый состоит в группе
Пригласителю начисляется +5 очков

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

При реферальном начислении бот проверяет, что приглашённый является участником группы через bot.get_chat_member().

Модерация фото

Процесс

Пользователь находится в состоянии awaiting_photo (ожидание фото)
Отправляет фото боту
Бот пересылает фото администратору (ADMIN_ID) с inline-кнопками:
- «Дать 15 баллов» — начислить +15 очков
- «Дать 5 баллов» — начислить +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 — назад

Контент

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

README.md Unescape Escape