Skip to content

README.MD

Latest commit

 

History

History
186 lines (148 loc) · 9.68 KB

README.MD

File metadata and controls

186 lines (148 loc) · 9.68 KB

Bestoic Bot

Telegram bot для ежедневной рассылки цитат из книг по стоицизму.

Описание

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

Возможности

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

  • Получение ежедневных цитат по стоицизму
  • Система подписок - подпишитесь на несколько категорий одновременно
  • Категории цитат:
    • 💭 Цитаты - вдохновляющие мысли стоиков
    • 📅 Стоицизм на каждый день - ежедневные размышления (366 дней)
  • Гибкое расписание для каждой категории:
    • Утро (8:00)
    • День (14:00)
    • Вечер (20:00)
  • Управление подписками:
    • Добавление/удаление подписок
    • Изменение времени для каждой категории
    • Каждая категория отправляется раз в день
  • ❤️ Избранное - сохраняйте понравившиеся цитаты и просматривайте их в любое время
  • 🔗 Поделиться - делитесь цитатами с друзьями через Telegram
  • 📚 Библиотека книг - скачивайте книги по стоицизму в разных форматах (fb2, epub, pdf), фильтрация по категориям (Классика / Современные)

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

  • Управление через Telegram - /admin_add, /admin_edit, /admin_delete, /admin_users, /admin_quote_stats
  • CLI интерфейс - добавление цитат и управление
  • Библиотека книг - загружайте книги с категориями (Классика / Современные авторы)
  • Статистика пользователей - просмотр подписчиков и их настроек
  • Статистика по избранному - топ цитат, которые добавляют в избранное
  • Поиск и удаление дубликатов
  • 📖 Подробное руководство администратора

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

  • SETUP.md - Установка и настройка проекта
  • ADMIN_GUIDE.md - Полное руководство для администратора
  • DEPLOY.md - Деплой на VPS (Beget)

Технологии

  • Python 3.10+
  • python-telegram-bot - Telegram Bot API
  • SQLite - база данных
  • APScheduler - планировщик задач
  • Click - CLI интерфейс
  • pytest - тестирование

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

bestoic_bot/
├── bot.py                  # Главный файл запуска бота
├── admin.py                # CLI интерфейс для администратора
├── config.py               # Конфигурация приложения
├── migrate_db.py           # Миграция базы данных
├── requirements.txt        # Python зависимости
├── .env.example            # Пример файла с переменными окружения
│
├── src/
│   ├── bot/
│   │   ├── handlers.py         # Обработчики команд Telegram
│   │   ├── library_handlers.py # Обработчики библиотеки книг
│   │   ├── scheduler.py        # Планировщик отправки цитат
│   │   └── admin/              # Админские обработчики
│   │       ├── quotes.py       # Добавление/редактирование/удаление цитат
│   │       ├── stats.py        # Статистика пользователей и цитат
│   │       └── broadcast.py    # Рассылка сообщений
│   │
│   ├── cli/
│   │   ├── admin.py       # Точка входа CLI
│   │   ├── quotes.py      # CLI команды для цитат
│   │   ├── library.py     # CLI команды для библиотеки
│   │   └── users.py       # CLI команды для пользователей
│   │
│   ├── database/
│   │   ├── models.py      # Основной класс Database (миксины)
│   │   ├── books.py       # Операции с книгами
│   │   ├── quotes.py      # Операции с цитатами
│   │   ├── users.py       # Операции с пользователями
│   │   ├── favorites.py   # Операции с избранным
│   │   ├── library.py     # Операции с библиотекой
│   │   └── statistics.py  # Статистика
│   │
│   └── utils/
│       └── quote_parser.py # Парсер цитат с атрибуцией
│
├── tests/
│   ├── test_quote_parser.py # Тесты парсера цитат
│   └── test_database.py     # Тесты базы данных
│
└── data/
    └── books/              # Файлы книг для библиотеки (fb2, epub, mobi)

Основные функции

📬 Система подписок - подписывайтесь на несколько категорий с разным временем доставки 📅 Стоицизм на каждый день - 366 уникальных размышлений, по одному на каждый день года ⏰ Гибкое расписание - утро (8:00), день (14:00), вечер (20:00) для каждой категории отдельно 🎯 Умная отправка - не повторяет цитаты пока все не будут показаны 🔍 Поиск дубликатов - быстрый алгоритм TF-IDF для обнаружения похожих цитат 📱 Управление через Telegram - добавляйте, редактируйте и удаляйте цитаты прямо в боте 🛠️ Удобный CLI - полное управление через командную строку с поддержкой русского языка 📚 Библиотека книг - скачивайте книги в форматах fb2, epub, mobi, pdf

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

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

  1. Найдите бота в Telegram: @bestoic_bot
  2. Отправьте /start
  3. Используйте /settings для управления подписками:
    • Добавьте подписку на категорию и выберите время
    • Подпишитесь на обе категории с разным временем
    • Изменяйте время или удаляйте подписки
  4. Получайте ежедневные цитаты!

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

# Установка
pip install -r requirements.txt

# Настройка
cp .env.example .env
# Отредактируйте .env файл

# Управление цитатами
python admin.py stats                      # Статистика
python admin.py quote add                  # Добавить цитату
python admin.py quote find-duplicates      # Найти дубликаты

# Запуск бота
python bot.py

Подробнее: ADMIN_GUIDE.md

Тесты

Проект содержит тесты для парсера цитат и базы данных.

# Запуск всех тестов
pytest tests/ -v

# Запуск только тестов парсера
pytest tests/test_quote_parser.py -v

# Запуск только тестов базы данных
pytest tests/test_database.py -v

Покрытие:

  • test_quote_parser.py — парсинг цитат, конвертация дат, форматирование для Telegram
  • test_database.py — книги, цитаты, пользователи, подписки, избранное (in-memory SQLite)

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

✅ Бот запущен и работает на VPS (Beget)

  • Сервер: Ubuntu 24.04
  • Автозапуск через systemd
  • Часовой пояс: Europe/Moscow

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

🔒 Сервер защищен:

  • UFW Firewall - разрешен только SSH (порт 22)
  • fail2ban - защита от брутфорса (бан на 1 час после 3 попыток)
  • SSH Hardening - root login отключен, используются SSH ключи
  • Автоматические обновления - установка критических патчей безопасности
  • Автоматический бэкап - ежедневное резервное копирование БД (хранятся 7 дней)

Вход на сервер: ssh botuser@YOUR_SERVER_IP

Подробнее о резервном копировании: DEPLOY.md - Резервное копирование

Лицензия

MIT