Open Cashback Advisor

Система для управления и оптимизации кэшбэков, состоящая из Telegram-бота и REST API сервера.

🚀 Быстрый старт

# Клонирование репозитория
git clone <repository-url>
cd Bot

# Настройка окружения
cp env.example .env
# Отредактируйте .env файл

# Запуск через Docker
docker-compose -f docker-compose.full.yml up -d

Подробнее: Установка и настройка

📖 Документация

Полная документация проекта находится в папке docs/:

Основные разделы

1. Обзор проекта

   • Что такое Open Cashback Advisor
   • Основные возможности
   • Технологический стек
   • Ключевые концепции

2. Архитектура системы

   • Общая архитектура
   • Компоненты системы
   • Потоки данных
   • Управление состояниями

3. Установка и настройка

   • Требования
   • Быстрая установка (Docker)
   • Установка для разработки
   • Первоначальная настройка

4. Справочник API

   • Все эндпоинты REST API
   • Примеры запросов и ответов
   • Валидация данных
   • Fuzzy-поиск

5. Команды бота

   • Все команды Telegram бота
   • Примеры использования
   • Форматы данных
   • Обработка опечаток

6. База данных и миграции

   • Схема базы данных
   • Миграции
   • Индексы и оптимизация
   • Резервное копирование

7. Развертывание

   • Подготовка сервера
   • Настройка продакшн окружения
   • Обновление приложения
   • Мониторинг и резервное копирование

8. Разработка

   • Настройка окружения разработки
   • Структура проекта
   • Добавление новых функций
   • Тестирование

9. Решение проблем

   • Типичные проблемы и решения
   • Диагностика
   • Часто задаваемые вопросы

10. Вклад в проект

    • Как внести вклад
    • Стандарты кода
    • Процесс разработки
    • Pull Request процесс

🎯 Основные возможности

Telegram Бот

• ✅ Интуитивный интерфейс для работы с кэшбэками
• ✅ Поддержка групп пользователей
• ✅ Автоматическая валидация и исправление опечаток
• ✅ Поиск лучших кэшбэков по категориям
• ✅ Управление кэшбэками (создание, обновление, удаление)

REST API

• ✅ Полнофункциональный REST API
• ✅ Поддержка fuzzy-поиска
• ✅ Валидация данных
• ✅ Пагинация
• ✅ CORS поддержка

База данных

• ✅ PostgreSQL с расширением pg_trgm
• ✅ Оптимизированные индексы
• ✅ Автоматическое обновление временных меток
• ✅ Миграции для управления схемой

🛠 Технологический стек

• Язык: Go 1.22
• База данных: PostgreSQL 15
• Telegram Bot API: go-telegram-bot-api/v5
• HTTP Router: Chi v5
• Контейнеризация: Docker и Docker Compose

📋 Требования

• Docker 20.10+ и Docker Compose 2.0+ (для быстрого запуска)
• Или Go 1.22+ и PostgreSQL 15+ (для разработки)

🚀 Быстрая установка

Через Docker (рекомендуется)

# 1. Клонирование
git clone <repository-url>
cd Bot

# 2. Настройка
cp env.example .env
# Отредактируйте .env и укажите:
# - TELEGRAM_BOT_TOKEN (получите от @BotFather)
# - DB_PASSWORD (надежный пароль)

# 3. Запуск
docker-compose -f docker-compose.full.yml up -d

# 4. Проверка
curl http://localhost:8080/health

Подробнее: Установка и настройка

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

Команды бота

После запуска найдите вашего бота в Telegram и отправьте:

/start - Начало работы
/help - Справка по командам
/creategroup Семья - Создать группу
/add - Добавить кэшбэк
/best - Найти лучший кэшбэк

Полный список команд: Команды бота

API

# Health check
curl http://localhost:8080/health

# Создание кэшбэка
curl -X POST http://localhost:8080/api/v1/cashback \
  -H "Content-Type: application/json" \
  -d '{
    "group_name": "Семья",
    "category": "Такси",
    "bank_name": "Тинькофф",
    "user_id": "123456789",
    "user_display_name": "Иван",
    "month_year": "2024-12",
    "cashback_percent": 5.5,
    "max_amount": 3000.0
  }'

Полная документация API: Справочник API

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

Bot/
├── cmd/                    # Точки входа
│   ├── bot/               # Telegram бот
│   └── server/            # HTTP API сервер
├── internal/              # Внутренние пакеты
│   ├── bot/              # Логика бота
│   ├── config/           # Конфигурация
│   ├── database/          # Работа с БД
│   ├── handlers/         # HTTP обработчики
│   ├── models/            # Модели данных
│   ├── service/           # Бизнес-логика
│   └── validator/         # Валидация
├── migrations/            # SQL миграции
├── docs/                  # Документация
├── scripts/               # Вспомогательные скрипты
└── docker-compose.yml     # Docker конфигурация

🧪 Разработка

# Установка зависимостей
make deps

# Запуск тестов
make test

# Форматирование кода
make fmt

# Запуск в режиме разработки
make dev

Подробнее: Разработка

📝 Лицензия

[Укажите лицензию проекта]

🤝 Вклад в проект

Мы приветствуем вклад от всех желающих! См. Вклад в проект для деталей.

🐛 Сообщить о проблеме

Если вы нашли баг или хотите предложить новую функцию, создайте Issue.

📞 Поддержка

• Документация: docs/
• Решение проблем: Решение проблем
• Вопросы: создайте Discussion на GitHub

🔗 Полезные ссылки

• Обзор проекта
• Архитектура
• Установка
• API Справочник
• Команды бота
• База данных
• Развертывание
• Разработка
• Решение проблем
• Вклад в проект

---

Версия: 1.0.0
Статус: В активной разработке