🗳 WUBRG Voting Bot

Telegram бот для создания и проведения голосований с поддержкой inline-режима.

🚀 Возможности

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

• ✅ Создание голосований через диалог (/createpoll)
• ✅ Голосование с помощью inline-кнопок
• ✅ Отображение результатов в реальном времени
• ✅ Сохранение всех данных в PostgreSQL
• ✅ Просмотр списка активных голосований (/listpolls)
• ✅ Публикация голосований в чаты (/publishpoll)

📲 Inline-режим

• ✅ Вызов бота через @bot_name в любом чате
• ✅ Поиск голосований по названию
• ✅ Быстрая публикация голосований без добавления бота в группу
• ✅ Автоматическое обновление результатов

🛠 Технологии

• Go 1.21+
• PostgreSQL - хранение данных
• telebot.v4 - библиотека для работы с Telegram Bot API
• pgx/v5 - драйвер PostgreSQL

📋 Требования

1. Go 1.21 или выше
2. PostgreSQL 12 или выше
3. Telegram Bot Token (получить через @BotFather)

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

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

# Клонируйте репозиторий
git clone <your-repo-url>
cd wubrg-voting-bot

# Установите зависимости
go mod download

2. Настройка базы данных

# Запустите PostgreSQL
brew services start postgresql  # macOS
# или
sudo systemctl start postgresql # Linux

# Создайте базу данных
createdb wubrg_voting

# Примените схему
psql -U postgres -d wubrg_voting -f db-schema/schema.sql

3. Настройка бота

# Установите переменные окружения
export BOT_TOKEN="your_telegram_bot_token"
export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/wubrg_voting"

4. Включение inline-режима

1. Откройте @BotFather в Telegram
2. Отправьте команду /setinline
3. Выберите вашего бота
4. Введите текст подсказки: "Поиск голосований..."

5. Запуск

go run main.go

Вы увидите:

Hello from PostgreSQL!
✅ Успешное подключение к PostgreSQL через pgx!
✅ Telegram бот успешно запущен!
🤖 Бот начал прослушивание сообщений...

📖 Использование

Создание голосования

1. Откройте личный чат с ботом
2. Отправьте /createpoll
3. Следуйте инструкциям:
   • Введите заголовок
   • Добавьте варианты ответа (минимум 2)
   • Напишите готово
   • Подтвердите создание

Публикация через команду

/listpolls                    # Посмотреть список голосований
/publishpoll <ID>             # Опубликовать голосование в текущем чате

Публикация через inline-режим

В любом чате введите:

@your_bot_name                # Показать все голосования
@your_bot_name командир       # Поиск по названию

Выберите голосование из списка и отправьте в чат.

📱 Команды бота

Команда	Описание
/start	Начать работу с ботом
/help	Показать справку
/createpoll	Создать новое голосование
/listpolls	Показать список активных голосований
/publishpoll <ID>	Опубликовать голосование в чат
/status	Проверить статус подключения к БД
/cancel	Отменить текущий диалог

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

wubrg-voting-bot/
├── main.go                 # Точка входа приложения
├── bot/
│   ├── bot.go             # Основная логика бота
│   ├── dialog.go          # Управление состоянием диалогов
│   └── poll.go            # Логика голосований и inline-режима
├── db-schema/
│   ├── schema.sql         # Схема базы данных
│   ├── queries.sql        # Примеры запросов
│   └── sample_data.sql    # Тестовые данные
├── CHANGELOG.md           # История изменений
├── INLINE_MODE.md         # Документация inline-режима
├── INTEGRATION.md         # Детали интеграции с БД
└── TESTING.md             # Инструкции по тестированию

🗄 Структура базы данных

• voting.polls - голосования
• voting.poll_options - варианты ответов
• voting.votes - голоса пользователей
• voting.poll_chats - чаты с опубликованными голосованиями
  • Поддерживает обычные публикации (chat_id, message_id)
  • Поддерживает inline-публикации (inline_message_id, message_hash)
• voting.vote_log - лог всех нажатий на кнопки (append-only)

Подробнее: см. db-schema/schema.sql

Миграции

• db-schema/add_vote_log_table.sql - Добавление таблицы логирования
• db-schema/add_emoji_column.sql - Добавление поддержки эмодзи
• db-schema/add_inline_support_to_poll_chats.sql - Поддержка inline-публикаций (NEW!)

🧪 Тестирование

# Создать тестовое голосование
go run main.go

# В Telegram:
/createpoll

# Проверить в БД:
psql -U postgres -d wubrg_voting
SELECT * FROM voting.polls;
SELECT * FROM voting.votes;

Подробные инструкции:

• TESTING.md - базовое тестирование
• INLINE_MODE.md - тестирование inline-режима

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

• CHANGELOG.md - История изменений
• INLINE_MODE.md - Inline-режим
• INTEGRATION.md - Интеграция с БД
• TESTING.md - Тестирование
• db-schema/README.md - Документация БД
• db-schema/APPLY_INLINE_SUPPORT.md - Миграция inline-поддержки (NEW!)
• db-schema/INLINE_SUPPORT_QUICKSTART.md - Быстрый старт inline-поддержки

🔧 Настройка для продакшена

Переменные окружения

# Обязательные
export BOT_TOKEN="your_bot_token"
export DATABASE_URL="postgresql://user:password@host:5432/dbname"

# Опциональные
export LOG_LEVEL="info"          # debug, info, warn, error
export CACHE_TIME="10"           # Время кеширования inline-результатов (секунды)

Рекомендации

1. Безопасность:

   • Никогда не коммитьте токены в git
   • Используйте сильные пароли для БД
   • Ограничьте доступ к БД по IP

2. Производительность:

   • Настройте connection pooling для PostgreSQL
   • Используйте индексы на часто запрашиваемых полях
   • Мониторьте количество inline-запросов

3. Резервное копирование:

   # Бэкап БД
   pg_dump wubrg_voting > backup.sql
   
   # Восстановление
   psql -U postgres -d wubrg_voting < backup.sql

🐛 Устранение неполадок

Бот не отвечает

1. Проверьте, что бот запущен
2. Проверьте токен: echo $BOT_TOKEN
3. Проверьте логи на наличие ошибок

Ошибка подключения к БД

1. Проверьте, что PostgreSQL запущен:

   brew services list | grep postgresql

2. Проверьте строку подключения
3. Проверьте права доступа к БД

Inline-режим не работает

1. Убедитесь, что inline-режим включен в BotFather (/setinline)
2. Перезапустите бота
3. Проверьте наличие активных голосований: /listpolls

📊 Метрики и мониторинг

Логи включают:

• ✅ Создание голосований
• ✅ Голоса пользователей
• ✅ Inline-запросы
• ✅ Ошибки БД

Пример:

✅ Пользователь 123456 создал голосование ID=1: Выбор командира с 3 вариантами
✅ Голосование 1 опубликовано в чат -1001234567890
❌ Ошибка получения списка голосований для inline: connection timeout

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

Приветствуются pull requests и issues!

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

📝 Лицензия

MIT License - см. LICENSE файл

👥 Авторы

• Ваше имя - начальная разработка Initial development assisted by Claude (Anthropic)

🙏 Благодарности

• telebot.v4 - отличная библиотека для Telegram Bot API
• pgx - производительный драйвер PostgreSQL

🔮 Планы развития

• Команды управления: /mypolls, /results, /close, /delete
• Анонимное/неанонимное голосование
• Ограничение по времени голосования
• Экспорт результатов в CSV/Excel
• Графики и визуализация результатов
• Множественный выбор вариантов
• Права доступа (только администраторы могут создавать голосования)
• Webhook вместо long polling
• Docker-контейнеризация

---

Сделано с ❤️ для Magic: The Gathering сообщества