rem_it_bot

Telegram бот для напоминаний - твой личный библиотекарь для важного.

Подробный разбор архитектуры, всего функционала и технологических решений (в т.ч. почему без домена и на long polling) - в docs/PROJECT_OVERVIEW.md.

Как работает

1. Пользователь отправляет боту текст или картинку
2. Бот сохраняет их в БД
3. Настраивается расписание отправки (количество в день, временной интервал, часовой пояс)
4. Бот отправляет сохраненные сообщения по расписанию
5. PROFIT

---

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

Корневая директория

• app/ - основной код приложения
• docker/ - конфигурация Docker
  • php/Dockerfile - образ PHP 8 CLI
  • mysql/my.cnf - конфигурация MySQL
• docker-compose.yml - конфигурация контейнеров
• Makefile - команды для управления проектом
• .github/workflows/ - CI/CD
  • deploy-prod.yml - деплой на продакшн
  • backup.yml - автоматические бэкапы

app/ - основной код

Точка входа:

• main.php - главный цикл бота (бесконечный цикл, обрабатывает сообщения, проверяет расписание)
• config.php - загрузка .env, инициализация Sentry, настройка таймзоны

core/ - базовые классы:

• Action.php - роутер команд (разбирает /command/method, загружает нужный класс из command/)
• DB.php - работа с БД (запросы для messages, schedule, schedule_daily, command_waiting, chat_history)
• Model.php - базовый класс для моделей (инициализирует telegram и db)

model/ - бизнес-логика:

• Processing.php - обработка входящих сообщений (получает апдейты из Telegram, вызывает нужные команды)
• Schedule.php - управление расписанием (генерирует расписание на день, проверяет что пора отправить)

command/ - обработчики команд бота:

• Start.php - /start - приветствие, создание расписания по умолчанию
• Message.php - сохранение/редактирование сообщений, работа с изображениями
• Catalog.php - /catalog - просмотр сохраненных сообщений
• Setting.php - /setting - настройка расписания (количество, время, часовой пояс)
• Now.php - /now или /_id - немедленная отправка конкретного сообщения
• Change.php - /change - изменение текста сообщения
• Help.php - /help - помощь
• Faq.php - /faq - FAQ
• Menu.php - /menu - главное меню
• Error.php - обработка ошибок (неизвестные команды)
• Test.php - /test - тестовые команды

db/ - работа с базой данных:

• migrations/ - миграции Phinx
  • 20200101010101_start.php - создание таблиц (message, schedule, schedule_daily, command_waiting, chat_history)
  • 20230908145401_change_chatId_type.php - изменение типа chat_id
  • 20230919145401_convert_tables_to_utf8mb4.php - конвертация в utf8mb4
• dump/RIB_test.sql - тестовый дамп БД

lib/ - вспомогательные функции:

• helper.php - утилиты (shorten_text, shorten_link, heartbeat, ddf)
• logs.php - логирование через Logtail/Monolog

file/ - сохраненные изображения от пользователей (структура: chat_id/filename.jpg)

logs/ - логи приложения

• main.log - основной лог

---

Основные таблицы БД

• message - сохраненные сообщения пользователей (текст, изображения)
• schedule - расписание отправки для каждого пользователя (количество в день, интервал времени, часовой пояс)
• schedule_daily - расписание на текущий день (генерируется каждый день, когда отправлять каждое сообщение)
• command_waiting - команды в ожидании (когда пользователь вводит параметры)
• chat_history - история активности пользователей

---

Работа с проектом

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

Файл app/.env содержит:

• ENVIRONMENT - окружение (developer/production)
• MYSQL_* - параметры подключения к БД
• TELEGRAM_* - токен бота, имя, admin_chat_id
• MAX_OF_MESSAGES_PER_DAY - максимум сообщений в день (по умолчанию)
• MAX_LINE_LENGTH - максимальная длина строки для обрезки текста
• PERIOD_MESSAGE_CHECKED - период проверки сообщений в секундах (в main.php)
• BETTERSTACK_TOKEN - для логирования и heartbeat
• SENTRY_DNS - опционально, для отслеживания ошибок
• BACKUPS_FOLDER - путь для бэкапов

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

• make help - список всех команд
• make init - инициализация проекта (сборка, запуск, миграции)
• make update - пересобрать контейнер, обновить composer и миграции
• make restart - перезапуск контейнеров
• make log - просмотр логов
• make php-bash - вход в контейнер PHP
• make migrate - применить миграции
• make rollback - откатить последнюю миграцию
• make backup-db - бэкап БД
• make backup-file - бэкап файлов
• make import-dump - импорт тестового дампа БД

Логика работы main.php

1. Спит 60 сек (для инициализации БД)
2. Бесконечный цикл:
   • Каждую секунду: Processing::check() - проверка новых сообщений
   • Каждые 20 циклов: heartbeat() - отправка сигнала в BetterStack
   • Каждые 60 циклов: Schedule::check() - проверка расписания, отправка сообщений
   • Каждые 600 циклов: Schedule::generate() - генерация расписания на день

---

Технологии

• PHP 8.2 (CLI)
• MySQL 8.2
• Composer - управление зависимостями
• Phinx - миграции БД
• Docker Compose - контейнеризация
• Telegram Bot API (eleirbag89/telegrambotphp)
• Monolog/Logtail - логирование
• Sentry - отслеживание ошибок (опционально)

---

CI/CD

• .github/workflows/deploy-prod.yml - автоматический деплой при push в main

  • Создает .env из secrets/vars
  • Копирует файлы на сервер
  • Запускает make update
  • Проверяет что контейнеры запущены
  • Отправляет уведомление в Telegram

• .github/workflows/backup.yml - ежедневные бэкапы в полночь UTC