Telegram Cashback Bot

Telegram-бот для выбора банковской карты с максимальным кэшбэком для выбранной категории покупки. Разработан на Python 3.11+, aiogram 3.x и PostgreSQL.

Особенности

• Динамические категории: загружаются администратором каждый месяц через JSON.
• Поиск лучшей карты: расчет суммы кэшбэка с учетом процента и суммы покупки.
• Админ-панель: управление картами и категориями прямо из бота.
• Транзакционная загрузка JSON: гарантирует целостность данных при импорте.
• Готовность к Production: Docker, systemd unit, логирование, глобальный обработчик ошибок.

Требования

• Python 3.11+
• PostgreSQL 15+
• Docker и Docker Compose (опционально, для запуска в контейнерах)

Установка и запуск (Локально)

1. Клонируйте репозиторий и перейдите в папку проекта.
2. Создайте виртуальное окружение и установите зависимости:

   python3.11 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

3. Скопируйте файл конфигурации и заполните его:

   cp .env.example .env
   # Отредактируйте .env, укажите BOT_TOKEN и данные для подключения к БД

4. Запустите бота (миграции БД применятся автоматически):

   python -m app.main

Запуск через Docker

1. Убедитесь, что .env файл заполнен.
2. Запустите контейнеры:

   docker-compose up -d --build

3. Просмотр логов:

   docker-compose logs -f bot

Деплой на сервер (Ubuntu / изолированная инфраструктура)

На сервере с другими проектами бот изолирован: свой пользователь ОС, каталог /opt/cashbackbot, отдельная БД PostgreSQL и свой systemd-сервис.

Пошаговая инструкция: deploy/README.md

Кратко:

1. Подключиться по SSH к серверу.
2. Установить Git, Python 3.11, PostgreSQL (если ещё нет).
3. Создать БД и пользователя PostgreSQL для бота: sudo DB_PASS='пароль' ./deploy/setup-db.sh
4. Клонировать репозиторий: git clone https://github.com/apodobe/cashbackbot.git /opt/cashbackbot && cd /opt/cashbackbot
5. Создать .env из .env.example, указать BOT_TOKEN и DB_PASS.
6. Запустить деплой: sudo ./deploy/deploy.sh
7. Выставить права на .env: chown cashbackbot:cashbackbot .env && chmod 600 .env
8. Запустить сервис: sudo systemctl start cashbackbot && sudo systemctl enable cashbackbot

После старта в Telegram отправьте боту /admin и загрузите JSON с картами и кэшбэком — иначе пользователи увидят сообщение об отсутствии данных.

Тестирование

Проект покрыт тестами более чем на 80%. Используется pytest с моками для базы данных (asyncpg).

# Установка dev-зависимостей
pip install -r requirements-dev.txt

# Запуск тестов с отчетом о покрытии
pytest

Формат JSON для импорта

Администратор может загрузить данные через команду /load_cashback. Пример формата:

{
  "month": "2026-04",
  "cards": [
    {
      "card_name": "Tinkoff Black",
      "bank": "Tinkoff",
      "owner": "Alexey",
      "card_number": "1111222233334444",
      "cashback": {
        "restaurants": 5,
        "hotels": 10
      }
    }
  ]
}

Архитектура

Проект построен по слоистой архитектуре (Clean Architecture / Modular Monolith):

• handlers/ — обработка Telegram-событий (aiogram).
• services/ — бизнес-логика (расчеты, обработка JSON).
• repositories/ — работа с базой данных (SQL запросы через asyncpg).
• domain/ — Pydantic схемы и DTO для типизации.