Telegram Event Bot (async, SQLite)

Что сделано

• Полный рефактор: модульная структура (bot/handlers, services, storage, utils).
• SQLite с репозиториями и миграцией из legacy Excel/JSON.
• Роли (admin/moderator/user) и единая проверка прав.
• Профиль и согласие на ПДн, постоянная клавиатура главного меню.
• CMS внутри бота: редактирование контента, меню и шаблонов без перезапуска.
• Перезапуск процесса и мягкая перезагрузка данных.

Требования

• Python 3.10+
• Telegram Bot API token (ревокните старый токен из исходника!)
• pip install -r requirements.txt

Установка и запуск

1. Скопируйте env.example → .env и заполните:

BOT_TOKEN="000:PUT_YOUR_TOKEN"
ADMIN_IDS="12345678,87654321"
ADMIN_PASSWORD="change-me"
PERSONAL_DATA_LINK="<ВСТАВЬТЕ_ССЫЛКУ_ТУТ>"
DATABASE_PATH="data/bot.db"
LOG_LEVEL="INFO"
LOG_FILE="data/bot.log"
LOG_MAX_BYTES="5242880"
LOG_BACKUP_COUNT="3"
RESTART_ENABLED="true"
RESTART_EXIT_CODE="1"

2. Установите зависимости: pip install -r requirements.txt
3. Запуск локально: python -m bot.main

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

• bot/config.py — загрузка конфига из env.
• bot/main.py — сборка Application, DI сервисов, error handler.
• bot/storage/ — SQLite и репозитории (users, roles, events, registrations, content).
• bot/services/ — бизнес-логика (profiles, events, content, restart, permissions, migrations).
• bot/handlers/ — start/consent, profile, events, admin, info (CMS).
• bot/keyboards/ — inline-клавиатуры для админки.
• env.example — пример переменных окружения.
• requirements.txt — зависимости.

Данные и миграции

• Основное хранилище: SQLite (DATABASE_PATH).
• При старте выполняется миграция из старых файлов, если найдены:
  • events.xlsx, registrations.xlsx, bot_users.json.
• После успешной миграции создаётся маркер data/.legacy_migration_done, чтобы не перечитывать Excel/JSON на каждом рестарте. Чтобы принудительно прогнать миграцию снова — удалите этот файл.
• Экспорт в Excel доступен из админки.
• Изменение схемы: добавляйте новые таблицы/поля в Database.init_db и миграцию в MigrationService.

Права и роли

• Роли в таблице roles: admin > moderator > user.
• ADMIN_IDS из .env автоматически получают роль admin при старте.
• Админка → «Роли»: назначить admin/moderator/user другим пользователям.
• Доступ:
  • admin: всё, включая CMS, роли, перезапуск.
  • moderator: мероприятия, рассылки, экспорт, напоминания.
  • user: клиентские функции.

UX сценарии

• /start: приветствие + ссылка ПДн. Пока нет согласия — только кнопка согласия.
• Главное меню — ReplyKeyboardMarkup (всегда «под рукой»).
• Профиль: просмотр ФИО/email/consent, изменение полей.
• Мероприятия: список активных, карточка, регистрация с подтягиванием профиля, подтверждение участия.
• Подтверждение участия: кнопка в напоминании/карточке.
• Админка: статистика, экспорт, CRUD мероприятий, рассылки (всем/по мероприятию), напоминание неподтвердившим, CMS (контент/меню/шаблоны), роли, перезагрузка/перезапуск.

CMS (контент из БД)

• Разделы (content_sections): добавлять/редактировать/удалять из админки → «CMS».
• Меню (menu_items): админка → «Меню» (формат key|Текст|позиция).
• Шаблоны (templates): база заготовок, можно расширять аналогично (см. ContentService).

Перезапуск и перезагрузка

• Кнопка «🔄 Перезапуск» в админке: graceful shutdown + os._exit(RESTART_EXIT_CODE). Код завершения по умолчанию не 0, чтобы супервизор/Restart=on-failure перезапускали процесс.
• «🔁 Перезагрузить данные»: перечитывает контент/меню/шаблоны из БД без рестарта.
• Рекомендация: systemd unit с Restart=always или Docker restart: unless-stopped.

Админ-диагностика (для сопровождения)

Команды (доступны роли moderator+):

• /admin_status — аптайм, конфигурация (без секретов), счётчики таблиц, (на Linux — loadavg/meminfo).
• /admin_health — быстрые проверки SQLite (query/foreign_keys/наличие таблиц).
• /admin_logs — последние строки логов из LOG_FILE (обрезается по размеру).

Пример systemd unit

[Unit]
Description=Telegram Event Bot
After=network.target

[Service]
WorkingDirectory=/opt/bot
ExecStart=/usr/bin/python -m bot.main
EnvironmentFile=/opt/bot/.env
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Пример docker-compose

services:
  bot:
    image: python:3.11-slim
    working_dir: /app
    volumes:
      - ./:/app
    command: python -m bot.main
    env_file:
      - .env
    restart: unless-stopped

Как редактировать контент/меню/мероприятия

• Админка → CMS: список разделов, редактирование текста.
• Админка → Меню: добавить/переименовать пункты главного меню.
• Админка → Добавить/Редактировать/Удалить мероприятие: все поля управляются из мессенджера.

Добавление новых разделов/шаблонов

• Используйте ContentService/ContentRepository для чтения/записи.
• Добавьте новый key и текст в админке, без изменения кода.

Troubleshooting

• «BOT_TOKEN is required»: проверьте .env.
• «Нет доступа»: проверьте роли/ADMIN_IDS.
• Перезапуск не сработал: убедитесь в настройке systemd/docker restart policy или выставьте RESTART_EXIT_CODE=1 для Supervisor/Restart=on-failure.
• Нет разделов/меню: вызовите «🔁 Перезагрузить данные» или пересоздайте через CMS.

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

• Секреты только через env. Токен и пароль из исходного файла надо немедленно отозвать/сменить.
• Минимальный сбор данных: ФИО и email, согласие фиксируется.
• Логирование без персональных данных в сообщениях.