🕌 Hadith Study Bot

Hadith Study Bot — это мощный, полнофункциональный Telegram-бот для изучения хадисов, написанный на Python (Aiogram 3 + FastAPI).

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

🖼 Скриншоты

Desktop	Mobile

---

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

👤 Для пользователей

• Мультиязычность: Полная поддержка 8 языков (RU, EN, AR, TR, FR, BN, ID, TA).
• Режимы изучения:
  • 🎲 Случайный: Бот присылает случайный хадис из выбранного сборника.
  • 📋 По порядку: Последовательное изучение книг хадисов.
• 6 Сборников (Кутуб ас-Ситта): Сахих аль-Бухари, Муслим, Абу Дауд, Тирмизи, Ан-Насаи, Ибн Маджа.
• Прогресс: Бот запоминает, какие хадисы пользователь уже изучил.
• Аудио: Поддержка прослушивания озвучки хадисов.
• Напоминания: Пользователь может настроить время и частоту автоматических напоминаний.
• Поиск: Поиск хадиса по номеру внутри книги.

👑 Для администраторов (Функционал)

Управление ботом осуществляется двумя способами: через Веб-панель (основной инструмент) и через Секретную команду в боте.

1. 🖥 Веб-панель управления

Панель работает на FastAPI и доступна в браузере. Возможности:

• Дашборд: Общая статистика (количество пользователей, хадисов, активных студентов, заблокировавших бота).
• Управление хадисами:
  • Добавление новых хадисов с поддержкой HTML-разметки.
  • Редактирование и удаление существующих.
  • Загрузка аудио: Специальный раздел для прикрепления аудиофайлов к хадисам (загружаются в Telegram для получения file_id).
• Пользователи:
  • Просмотр списка всех пользователей.
  • Поиск по ID или имени.
  • Просмотр подробной статистики конкретного человека (какие книги изучает, прогресс в %).
  • Отправка личного сообщения конкретному пользователю от имени бота.
• Модерация (Предложенные хадисы): Если вы назначите помощников (роль participant), они могут предлагать хадисы. Главный админ может их редактировать, одобрять или отклонять.
• Рассылка (Broadcast):
  • Массовая отправка сообщений всем пользователям.
  • Поддержка текста, фото, видео и документов.
  • Загрузка файлов напрямую с компьютера или использование file_id.
• Бэкапы: Экспорт и импорт базы данных одной кнопкой.
• Управление админами: Создание учетных записей для помощников с ограниченными правами.

2. 🤖 Секретная команда /sheri

Специальная команда, доступная только главному администратору (чей ID указан в config.py). Введите её в личные сообщения боту.

Меню /sheri позволяет:

1. Добавить хадис: Быстрое добавление текста хадиса прямо через Telegram, не заходя в веб-панель.
2. Сделать рассылку (Forward/Copy): Переслать сообщение из канала в бота, и бот разошлет его всем пользователям.
   • Режим Forward: Пересылка (видно источник).
   • Режим Copy: От имени бота (источник скрыт).
3. Статистика: Быстрый просмотр количества пользователей и хадисов сообщением в чате.

---

🛠 Технологический стек

• Язык: Python 3.11+
• Бот: Aiogram 3.x (асинхронный)
• Веб-сервер: FastAPI + Uvicorn + Jinja2 (шаблонизатор)
• База данных: PostgreSQL (рекомендуется Supabase) + asyncpg
• Кэширование/FSM: Redis
• Контейнеризация: Docker & Docker Compose

---

🚀 Инструкция по установке и запуску

Предварительные требования

1. Установленный Docker и Docker Compose.
2. База данных PostgreSQL (можно использовать облачную Supabase или локальную).
3. Токен бота от @BotFather.
4. Создайте в Telegram публичный канал или группу и добавьте туда бота администратором. Узнайте ID этой группы (например, через @userinfobot). Это нужно для технического хранения аудиофайлов (AUDIO_GROUP_ID).

Шаг 1. Клонирование репозитория

Скачайте проект к себе на сервер или компьютер:

git clone https://github.com/ВАШ_ЮЗЕРНЕЙМ/РЕПОЗИТОРИЙ.git
cd РЕПОЗИТОРИЙ

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

В проекте есть файл config.py.example. Переименуйте его в config.py:

Linux/macOS:

cp config.py.example config.py

Windows: Скопируйте файл вручную и назовите копию config.py.

Откройте config.py и заполните данные:

import os
from pathlib import Path

# --- Основные настройки бота ---
TOKEN = "123456:AAH..."            # Токен от BotFather
ADMIN_ID = 123456789               # ВАШ Telegram ID (для доступа к /sheri)
AUDIO_GROUP_ID = -1001234567890    # ID группы/канала для кэширования аудио

# --- Redis (Для Docker оставьте 'redis', для локального запуска 'localhost') ---
REDIS_HOST = os.getenv('REDIS_HOST', 'redis') 
REDIS_PORT = 6379

# --- База данных (Пример для Supabase) ---
DB_CONFIG = {
    'user': 'postgres',
    'password': 'ВАШ_ПАРОЛЬ_ОТ_БД',
    'database': 'postgres',
    'host': 'db.xyz.supabase.co',  # Хост базы данных
    'port': 6543                   # Порт (обычно 5432 или 6543)
}

# --- Доступ к Веб-Админке ---
WEB_USERNAME = "admin"             # Логин для входа в браузер
WEB_PASSWORD = "password123"       # Пароль для входа
SECRET_KEY = "придумайте_сложный_ключ_для_безопасности" 

# --- Остальное ---
PER_PAGE = 30 
UPLOAD_DIR = Path("uploads")
# ... ниже идут переводы книг, их не трогаем

Шаг 3. Запуск через Docker (Рекомендуется)

Это самый простой способ. Бот и Redis запустятся в изолированных контейнерах.

docker-compose up -d --build

После успешного запуска:

1. Бот начнет работать в Telegram.
2. Админ-панель будет доступна по адресу: http://localhost:8000 (или IP вашего сервера).

Полезные команды:

• Посмотреть логи: docker-compose logs -f
• Остановить: docker-compose down
• Перезагрузить: docker-compose restart

---

Шаг 3 (Альтернатива). Локальный запуск (без Docker)

Если вы хотите запустить для разработки на своём ПК:

1. Убедитесь, что установлен Python 3.11, Redis и FFmpeg.
2. Создайте виртуальное окружение:

   python -m venv venv
   source venv/bin/activate  # Mac/Linux
   venv\Scripts\activate     # Windows

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

   pip install -r requirements.txt

4. В config.py измените REDIS_HOST на 'localhost'.
5. Запустите бота:

   python hadith_bot.py

---

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

• hadith_bot.py — Главный файл запуска.
• bot_handlers.py — Логика бота (обработка сообщений, команда /sheri).
• web_app.py — Логика веб-панели (FastAPI маршруты).
• database.py — Все запросы к базе данных (SQL).
• utils.py — Фоновые задачи, рассылка, работа с файлами.
• keyboards.py — Кнопки (меню) Telegram.
• translations.py — Тексты на всех языках.
• templates/ — HTML файлы админки.
• static/ — Стили (CSS) и скрипты (JS) админки.

---

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

Если вы хотите улучшить проект:

1. Сделайте Fork репозитория.
2. Создайте ветку для новой фичи (git checkout -b feature/AmazingFeature).
3. Закоммитьте изменения (git commit -m 'Add some AmazingFeature').
4. Сделайте Push (git push origin feature/AmazingFeature).
5. Откройте Pull Request.

---

📄 Лицензия

Project is distributed under the MIT License.