Реализация чат бота в МАХе для ДФК клуба

Автоматизировать запись, оплату, сбор игроков на регулярные матчи

1. Постановка задачи. Исходно — ТЗ на бота для мессенджера MAX: автозапись на футбол по пн/пт в 9:00, основа на 10 мест с резервом, команды +Имя/-Имя, инлайн-кнопки, голосование за MVP и накопительный рейтинг.

2. Выбор архитектуры. Осознанно отказался от сторонних SDK и работаю напрямую с официальным REST API MAX — проще отлаживать, нет зависимости от версии обёртки. Стек: Node.js 18+ (нативный fetch), TypeScript, Express для вебхука, node-cron для планировщика, better-sqlite3 для хранения.

3. Хранение. Всё состояние (текущая и архивная запись, голосование, открытые вопросы, рейтинг, расписание, настройки чатов) — в SQLite в режиме WAL, переживает перезапуск. В памяти только кэш и незаконченный диалог. Предусмотрен одноразовый автоперенос старых JSON-файлов в базу.

4. Бизнес-логика. Разбита на модули: sessionLogic (запись, резерв, закрытие), voteLogic (голосование, итоги до 3 MVP, очистка чата), scheduleLogic/gameSlotsLogic (расписание и пары «публикация → игра»), rolesLogic (легенда, манишкаНосец), paymentLedger/receiptLogic (оплата, PDF-чеки), gameSeasons/seasonLogic (сезоны, игровой год с 1 декабря). Параллельно — инфраструктура: rateLimiter (≤2 RPS на чат), компактные payload кнопок с userId, разбивка длинных инструкций под лимит 4000 символов, «прилипание» дележки/голосования вниз чата.

5. Интерфейсы. Проработано разделение прав: участники видят только свои команды, админские вынесены в личку с ботом (панель администратора), т.к. в групповом чате MAX кнопки видны всем. Инструкции приходят в личку и различаются для участника и админа.

6. Тестирование. Сквозные тесты (npm test): бот запускается отдельным процессом против подставного MAX API, сценарии шлют настоящие апдейты вебхука и нажимают присланные ботом кнопки. Покрыты запись, голосование, расписание, панель, рестарт, оплата, /Всем, миграция JSON → SQLite.

7. Развёртывание. Локально — Cloudflare quick tunnel с --protocol http2 (QUIC рвётся), скрипт сам обновляет URL и перерегистрирует вебхук. Прод — сервер Timeweb Cloud в режиме polling (без домена и SSL), установка одной командой, systemd с автовосстановлением, бэкапы базы.

8. Допущения. Документация MAX местами скупа, поэтому ряд деталей (имя поля уведомления в /answers, поле ID чата в recipient, лимит payload кнопки, право удалять сообщения старше 24 ч, формат упоминаний) выведен из связанных источников и вынесен в чек-лист для проверки на боевом боте.

9. Итерации. Проект рос итерациями: от базовой записи и голосования — к нескольким чатам со своими настройками, сезонам и легенде года, дележке, оплате с чеками и раздельным инструкциям. Каждая итерация сопровождалась обновлением README и тестов, обратная совместимость — миграциями базы и сохранением старых значений .env.

Результат проекта max-football-bot

Готовый к эксплуатации бот для MAX, полностью закрывающий цикл любительского футбола. Реализован напрямую поверх REST API MAX (без SDK) на Node.js + TypeScript, состояние — в SQLite.

Что умеет:

• Запись по расписанию (пн/пт 9:00), основа 10 + резерв с автоподъёмом, +/+Имя/-/-Имя, удаление только своих записей.

• Гибкое расписание: /расписание (диалог), /игры (своя пара «публикация → игра»), /описание (шаблон шапки с автодатой).

• Голосование за MVP: авто/ручной старт, только основа, голоса по числу записей, прогресс-бар на кнопках, автоитоги до 3 MVP с поздравлениями и очисткой чата.

• Рейтинг и сезоны: сезон / игровой год / всё время, автопереключение сезонов, легенда года 1 декабря, сбросы с подтверждением, /объединить.

• Роли: легенда (1-й) и манишкаНосец (2-й) в каждой записи.

• Дележка на команды с капитанами и выбором по очереди.

• Оплата: напоминания по часам с упоминаниями, проверка PDF-чеков, /должники, /оплатил.

• Объявления /Всем / @all с упоминанием всех.

Инфраструктура: всё в SQLite (WAL) с миграцией старых JSON, рейт-лимитер (≤2 RPS на чат), мультичатность (CHAT_IDS) со своими настройками у каждого чата, раздельные инструкции для участника и админа, админ-панель в личке. Локально — Cloudflare-туннель с автообновлением URL, прод — сервер в режиме polling без домена и SSL, systemd + бэкапы.

Проверка: сквозные тесты (npm test) против подставного MAX API — запись, голосование, расписание, панель, рестарт, оплата, /Всем, миграция.

Ограничения: ряд деталей API MAX (поле уведомления в /answers, ID чата в recipient, лимит payload кнопки, удаление старше 24 ч, формат упоминаний) вынесен в чек-лист для сверки на боевом боте; финальную сборку нужно прогнать в целевом окружении (в песочнице npm был заблокирован).

Итог: модульная кодовая база (~30 модулей), README с шпаргалкой команд и инструкцией по деплою, обратная совместимость через миграции.