UniClubs Bot

Max-бот для управления студенческими клубами и мероприятиями в университетах

⚠️ Важно: Проект разработан с использованием maxigo — полноценного самописного фреймворка для создания ботов на платформе Max. Фреймворк был создан командой специально для этого проекта и представляет собой готовое решение для разработки Max-ботов на Go. Обратите внимание на архитектуру и возможности фреймворка.

Возможности

• Для студентов: регистрация, просмотр клубов и мероприятий, QR-коды для посещения
• Для владельцев клубов: управление клубом, создание мероприятий, рассылки, статистика в Grafana
• Для админов университета: управление клубами, инвайт-коды, статистика университета в Grafana
• Для супер-админа: управление университетами, глобальная статистика в Grafana

Требования

• Docker и Docker Compose
• Go 1.23+ (для запуска super_admin_cli) либо можно использовать готовый билд

Быстрый запуск

1. Настройка

# Клонировать репозиторий
git clone https://github.com/hsp-team/UniClubs.git
cd UniClubs

# Создать .env файл
cp .env.example .env
# Отредактировать .env и указать пароли

# Создать конфигурацию
cp config/config.yaml.example config/config.yaml
# Отредактировать config/config.yaml и указать токен бота

2. Запуск

# Собрать и запустить
make build
make start
# Или
make dev

# Посмотреть логи
make logs

3. Получить права Super Admin

# 1. Написать боту /get_my_id и получить свой ID (например: 123456789)

# 2. Выдать права через CLI (замените 123456789 на ваш ID)
cd bot/cmd/super_admin_cli
go run main.go -userID=123456789 -userFIO="Имя Фамилия Отчество" -dbhost=localhost -dbport=5432 -dbuser=user -dbpass=password -dbname=database
# либо можно использовать готовый билд (тогда установленный Go не нужен)
./super_admin_cli -userID=123456789 -userFIO="Имя Фамилия Отчество" -dbhost=localhost -dbport=5432 -dbuser=user -dbpass=password -dbname=database

Готово! Права выданы моментально, перезапуск не требуется.

Доступные сервисы

После запуска доступны:

• Max Bot - сам бот в Max
• Grafana - http://localhost:3000 (дашборды статистики)
• PostgreSQL - localhost:5432
• Redis - localhost:6379

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

UniClubs/
├── bot/
│   ├── cmd/
│   │   ├── app/                    # Основное приложение
│   │   └── super_admin_cli/        # CLI для управления супер-админами
│   ├── internal/                   # Бизнес-логика
│   └── pkg/                        # Общие пакеты
├── config/
│   ├── grafana/                    # Настройки и дашборды Grafana
│   └── config.yaml.example         # Пример конфигурации
├── docker-compose.yml              # Docker Compose конфигурация
├── Dockerfile                      # Dockerfile для бота
└── .env.example                    # Пример переменных окружения

Основные команды

# Запуск
make start

# Остановка
make stop

# Перезапуск
make restart

# Логи
make logs

# Статус
make status

Зависимости

Go (см. bot/go.mod)

• maxigo - Разработанный фреймворк для ботов под max
• Ent - ORM для PostgreSQL
• Redis - для сессий
• Viper - конфигурация
• Logrus - логирование

Docker Images

• golang:1.23-alpine - сборка приложения
• postgres:16.2-alpine3.19 - база данных
• redis:latest - кеш и сессии
• grafana/grafana:latest - аналитика

Послесловие: Проблемы Max Chat Bot API

В процессе разработки были обнаружены следующие проблемы в API мессенджера Max:

1. Некорректная работа метода PUT для редактирования сообщений

Метод PUT на /messages/{id} работает как PATCH для inline-клавиатур. Проблема: невозможно удалить клавиатуру у сообщения через edit:

• Если не передавать клавиатуру в запросе - она сохраняется (поведение PATCH)
• Если передать пустую клавиатуру - возвращается ошибка 400
• Ожидаемое поведение: метод PUT должен полностью заменять сообщение, включая удаление клавиатуры

2. Долгие проблемы с эндпоинтом /uploads

Эндпоинт /uploads длительное время возвращал ошибку 500 вместо корректных кодов ошибок. Только недавно проблема была исправлена, и теперь API возвращает корректные 400 ошибки с описанием проблемы, что позволило правильно обработать ошибки на стороне клиента.

3. Неконсистентность при работе с файлами

После успешной загрузки файла через /uploads нельзя сразу использовать его в attachment - API возвращает ошибку, что файл не найден. Это указывает на неконсистентность данных между сервисами Max.

• Workaround: пришлось добавить time.Sleep() после загрузки файла перед его использованием
• Ожидаемое поведение: файл должен быть доступен сразу после успешного ответа от /uploads

4. Невозможность удаления сообщений пользователя

Бот не может удалить сообщение пользователя, даже если у него есть соответствующие права в чате. Неясно, является ли это ограничением API или багом в клиенте Max.

---

Эти проблемы были выявлены в процессе разработки полноценного production-ready бота и требуют внимания со стороны команды Max для улучшения стабильности и предсказуемости API.