GR2-0 Community Bot

Описание

Контекст

Мы развиваем GR2-0 - локальное коммьюнити людей, интересующихся IT, технологиями и всем, что с ними связано. С ростом GR2-0 появилась потребность в автоматизации процессов его управления и развития, а именно:

1. Оценка вклада каждого участника для
   1. ранжирования фидбека,
   2. поощрения активности по развитию GR2-0,
   3. принятия решений по развитию в соответствии с потребностями наиболее активных участников, а не просто людей, формально числящихся в GR2-0.
2. Приёму фидбека от участников для адаптации коммьюнити.
3. Приёму предложений от участников для последующего рассмотрения админами.

Архитектура и структура проекта

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

gr2_bot/
├── data/
│   ├── private/          # Приватные данные (в .gitignore)
│   │   ├── config/       # Конфигурационные файлы
│   │   ├── users/        # База пользователей
│   │   ├── meetups/      # База митапов
│   │   └── bot/          # Токены и настройки бота
│   └── public/           # Публичные данные (в репозитории)
│       └── messages/     # Текстовые сообщения бота
├── src/                  # Исходный код
├── tests/                # Тесты
├── requirements.txt       # Зависимости
└── README.md

Технический стек

• Python - основной язык. Архитектура асинхронная.
• python-telegram-bot - библиотека для взаимодействия с Telegram API
• JSON - формат хранения данных
• File-based storage - хранение данных в файлах (не БД)

Конфигурация

Все конфигурационные данные хранятся в data/private/config/:

• bot_config.json - токены бота, ID групп
• points_config.json - настройки системы поинтов
• community_config.json - настройки коммьюнити

Сущности и модели данных

1. Бот

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

2. Пользователь

{
    "id": "telegram_user_id",
    "username": "имя_для_обращения",
    "registration_date": "YYYY-MM-DD",
    "role": "user|admin|dead",
    "points": 0,
    "info": "опциональная_информация"
}

3. Админ

Пользователь с расширенными правами и командами по управлению ботом. Может:

• Создавать/редактировать/удалять митапы
• Управлять списком админов
• Просматривать статистику
• Получать уведомления о проблемах

4. Митап

{
    "id": "unique_meetup_id",
    "name": "название_митапа",
    "date": "YYYY-MM-DD",
    "start_time": "HH:MM",
    "end_time": "HH:MM",
    "location": "место_проведения",
    "capacity": "вместимость",
    "status": "planned|active|completed|archived",
    "attendees": [
        {
            "user_id": "telegram_id",
            "registration_time": "HH:MM:SS"
        }
    ],
    "presentations": [
        {
            "title": "название_доклада",
            "speaker": "username_докладчика"
        }
    ]
}

Основные юз-кейсы и бизнес-логика

1. Регистрация пользователей

Триггер: Пользователь пишет боту сообщение Алгоритм:

1. Бот проверяет, состоит ли пользователь в группе коммьюнити
2. Если да - запускается скрипт регистрации
3. Если нет - бот приглашает вступить в группу
4. После вступления пользователь повторяет попытку
5. Бот запрашивает имя для обращения и опциональную информацию
6. Пользователь добавляется в базу с ролью "user"
7. Начисление поинтов: +1 за регистрацию

Обработка ошибок:

• Пользователь не в группе → приглашение вступить
• Дублирование регистрации → игнорирование

2. Сбор статистики посещения митапов

Триггер: Админ даёт команду старта митапа Алгоритм:

1. Админ использует /meetup_add для создания митапа
2. Вводятся: название, дата, время начала/конца, место, вместимость
3. Добавляются доклады (название + докладчик из членов группы)
4. Бот генерирует QR-коды с диплинками каждые 30 секунд
5. Старые коды и файлы удаляются автоматически
6. Админ транслирует чат с ботом через проектор
7. Посетители сканируют QR-коды или переходят по ссылкам для регистрации
8. Валидация: один пользователь = одна регистрация на митап
9. Начисление поинтов: +7 за посещение

Обработка ошибок:

• Повторная регистрация → "Ты уже отметился. Рады, что ты с нами!"
• Просроченный код → "Извини, код просрочен."

3. Управление митапами

Команды админа:

• /meetup → выбор действия: add/edit/delete
• /meetup_add → создание нового митапа
• /meetup_edit → редактирование незавершённых митапов
• /meetup_delete → удаление незавершённых митапов

Ограничения:

• Завершённые митапы нельзя редактировать/удалять через бота
• Архивирование происходит автоматически при изменении статуса

4. Сбор фидбека

Триггер: Завершение митапа Алгоритм:

1. Бот отправляет личные сообщения всем участникам
2. Запрашивается оценка каждого доклада (1-5)
3. Запрашивается общий фидбек о митапе
4. Начисление поинтов: +1 за каждый развёрнутый ответ (>128 символов)
5. Короткие ответы → предложение расширить для получения поинта
6. Время сбора: 24 часа после завершения митапа

5. Система поинтов

Начисление:

• Регистрация в боте: +1
• Посещение митапа: +7
• Фидбек (развёрнутый ответ): +1 за каждый ответ

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

• Покупка мерча коммьюнити
• Поинты не сгорают со временем
• Пользователь может оставить заявку админам на использование

6. Администрирование

Управление админами:

• Добавление: существующие админы через команду
• Удаление: через команду редактирования
• Роли: пока только "admin"

Мониторинг:

• Ежедневная проверка активности пользователей (21:00)
• Уведомления в админскую группу о проблемах
• Автоматическое изменение роли на "dead" для неактивных

Технические детали

Хранение данных

• Файловая система: JSON файлы для каждой сущности
• Синхронизация: Приложение читает файлы при старте и записывает изменения
• Резервное копирование: Ручное копирование папки data/private

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

• Ожидаемая нагрузка: до 1000 пользователей
• QR-коды: генерация каждые 30 секунд
• Проверки: ежедневные в 21:00

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

• Приватные данные в .gitignore
• Проверка прав доступа по Telegram ID
• Валидация всех входящих данных

Команды бота

Пользовательские команды

• /start - регистрация/приветствие
• /help - справка по командам
• /profile - профиль пользователя
• /points - баланс поинтов

Админские команды

• /meetup - управление митапами
• /admin - управление админами
• /stats - статистика коммьюнити
• /users - управление пользователями
• /qr_start - запуск QR-регистрации на митап
• /qr_stop - остановка QR-регистрации
• /qr_status - статус QR-регистраций

Обработка ошибок

Типичные сценарии

1. Пользователь не в группе → приглашение вступить
2. Просроченный QR-код → сообщение об ошибке
3. Дублирование регистрации → игнорирование
4. Недоступность пользователя → уведомление админов
5. Ошибки API Telegram → логирование и уведомление админов

Логирование

• Все действия пользователей
• Ошибки и исключения
• Админские операции
• Системные события

Планирование разработки

Этап 1: Базовая функциональность

• Структура проекта и конфигурация
• Система регистрации пользователей
• Базовая админская панель
• Хранение данных в файлах

Этап 2: Управление митапами

• Создание/редактирование/удаление митапов
• Система QR-кодов для регистрации
• Отслеживание посещений
• Статистика митапов

Этап 3: Система поинтов и фидбека

• Начисление поинтов за действия
• Сбор фидбека после митапов
• Управление поинтами
• Админские уведомления

Этап 4: Мониторинг и оптимизация

• Ежедневные проверки активности
• Система уведомлений
• Логирование и аналитика
• Тестирование и отладка

To-Do

• Чекин по диплинку из QR кода, логгирует посещение юзером митапа
• После митапа всем участникам рассылается запрос фидбека
  • Оценка мероприятия от 1 до 5
  • Фидбек в свободной текстовой форме
• Админское меню
  • Добавить митап(дата проведения)
  • Добавить доклады митапа(с хендлами докладчиков)
  • Сгенерить QR код для чекина
• Голосование за лучший доклад квартала
• Поинты за посещение
• Поинты за доклад
• Поинты за голосование
• Поинты за фидбек
• Добавить параметр запуска в тестовом окружении (-test) - используется тестовый бот, который работает в тестовых группах
• Перейти от текстовых команд к кнопкам