Kartoshka Bot (Бот-Картошка) 🥔

О боте

Kartoshka Bot — это дружелюбный Telegram-бот для модерации и публикации мемов в вашем чате. Он создан, чтобы сделать процесс публикации мемов простым, безопасным и веселым!

Бот поддерживает два режима работы:

• Обычный режим (Единоличный Узурпатор): решения о публикации мемов принимает единоличный модератор.
• Криптоселектархическая олигархия: решения принимаются коллективно группой тайных модераторов (криптоселектархов), и для публикации или отклонения мема требуется определённое количество голосов.

---

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

• 📝 Возможность публикации текстовых, фото, видео и GIF-мемов
• 🎭 Два режима публикации через удобные кнопки:
  • 👤 От своего имени (с указанием автора)
  • 🥔 Анонимно (от имени "Картошки")
• 👥 Система модерации контента:
  • Обычный режим: модерация осуществляется единоличным модератором
  • Криптоселектархическая олигархия: решения принимаются коллективно группой криптоселектархов
• ⚡ Система срочной публикации:
  • Криптоселектархи могут использовать кнопку "Срочно" для важных мемов
  • Если 51% и более от требуемого числа голосов "Срочно" - мем публикуется немедленно
  • Например: при требуемых 3 голосах нужно минимум 2 срочных (3 × 0.51 ≈ 1.53, округляется вверх до 2)
  • При недостаточном количестве срочных голосов мем публикуется в общей очереди
• ✅ Кнопки модерации для редакторов: Одобр. / Срочно / Откл.
• 📊 Интерактивный виджет голосования с обновляемой статистикой в реальном времени
• 🏷️ Автоматические подписи для всех типов мемов (текстовых и медиа)
• ✨ Автоматическое уведомление авторов о статусе их публикаций
• 📢 Динамическое приветственное сообщение, которое меняется в зависимости от текущего режима бота

---

Как установить и настроить бота

1. Развёртывание на сервере

1. Клонируйте репозиторий:

   git clone git@github.com:kryuchenko/kartoshka_bot.git
   cd kartoshka_bot

2. Создайте файл .env:

   • Пример содержимого:

     BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
     EDITOR_IDS=123456789
     PUBLISH_CHAT_ID=-100123456789
     BOT_NAME="Картошка Бот"
     POST_FREQUENCY_MINUTES=180
     CRYPTOSELECTARCHY=true
     VOTES_TO_APPROVE=3
     VOTES_TO_REJECT=3

3. Запустите автоматический скрипт установки:

   sudo ./setup_kartoshka_service.sh

   Скрипт автоматически:

   • Установит виртуальное окружение (venv) и все зависимости из requirements.txt.
   • Настроит systemd для автоматического управления ботом.
   • Запустит и включит бота для автозапуска при старте системы.

4. Проверьте статус службы:

   sudo systemctl status kartoshka_bot

   Вы должны увидеть, что служба активна.

---

2. Ручной запуск (для отладки)

1. Активируйте виртуальное окружение:

   source venv/bin/activate

2. Запустите бота вручную:

   python3 kartoshka_bot.py

3. Для остановки нажмите Ctrl+C.

---

Управление ботом через systemd

• Перезапустить бота:

  sudo systemctl restart kartoshka_bot

• Остановить бота:

  sudo systemctl stop kartoshka_bot

• Отключить автозапуск:

  sudo systemctl disable kartoshka_bot

Пример интерактивного виджета

Пользователь видит только одно сообщение, которое обновляется:

Ваш мем отправлен на модерацию.
[Кнопка]: Голосование: (✅ 2 | ⚡ 1 | ❌ 2)

После принятия решения:

Ваш мем отправлен на модерацию.
[Кнопка]: ✅ Одобрен (✅ 3 | ⚡ 0 | ❌ 2) • Публикация: 15:30 UTC

---

Преимущества использования

• 🛡️ Защита чата от нежелательного контента
• 🎯 Централизованная модерация материалов
• 💫 Возможность анонимной публикации
• 👥 Выбор между единоличной и коллективной модерацией
• 📊 Прозрачный процесс модерации с интерактивным виджетом
• 📱 Чистый интерфейс с минимальным количеством сообщений
• 🏷️ Единое оформление всех типов мемов
• 🗳️ Настраиваемые пороги для принятия решений

---

Тестирование и разработка

Тесты

Проект включает комплексную систему тестирования:

Примечание: Общее покрытие кода составляет 66%, а классы DummyMessage и функции сериализации/десериализации покрыты на 100%.

1. Функциональные тесты:

   • test_caption.py - тесты для проверки правильности подписей к мемам
   • test_user_widget.py - тесты интерактивного виджета обновления статуса для пользователей

2. Комплексные тесты потока данных:

   • test_dataflow.py - тесты всего жизненного цикла мема от создания до публикации:
     • Создание мема (текстового/с фото, анонимного/от пользователя)
     • Процесс модерации (голосование, решения об одобрении/отклонении)
     • Планирование публикации (очередь, срочная публикация)
     • Обновление информации для пользователя через интерактивный виджет

3. Демонстрационные тесты:

   • test_user_widget_simple.py - демонстрация работы виджета
   • test_user_widget_visual.py - визуальная демонстрация обновлений виджета

Запуск тестов

Все тесты можно запустить следующими командами:

# Функциональные тесты
python -m pytest test_caption.py -v
python -m pytest test_user_widget.py -v

# Комплексные тесты жизненного цикла
python -m pytest test_dataflow.py -v

# Тесты сериализации и DummyMessage (только рабочие тесты)
python -m pytest test_kartoshka_bot.py -k "test_dummy_message or test_serialize or test_deserialize" -v

# Генерация отчета о покрытии
# Полный отчет со всеми тестами
python -m pytest --cov=kartoshka_bot --cov-report=term-missing test_*.py

# Только тесты DummyMessage и сериализации
python -m pytest --cov=kartoshka_bot.DummyMessage --cov=kartoshka_bot.serialize_message --cov=kartoshka_bot.deserialize_message test_kartoshka_bot.py -k "test_dummy_message or test_serialize or test_deserialize"

Непрерывная интеграция

Проект настроен для использования GitHub Actions для автоматического тестирования при каждом пуше в репозиторий. Файл конфигурации находится в .github/workflows/tests.yml.

Настройка динамического бейджа покрытия кода

Для отображения динамического бейджа с процентом покрытия кода, необходимо:

1. Создать GitHub Gist с любым содержимым
2. Получить ID Gist (последняя часть URL, например: bc9c19eda4b6ee92a19d17f4d02ffbea)
3. Создать Personal Access Token с разрешением на доступ к gist в настройках GitHub
4. Добавить секрет GIST_SECRET в настройки репозитория (Settings > Secrets and variables > Actions > New repository secret)
5. Обновить gistID в файле .github/workflows/tests.yml и ссылку на бейдж в README.md

После настройки, бейдж будет автоматически обновляться при каждом успешном запуске тестов.

---

С любовью к мемам и картошке! 🥔✨