🤖CardForge - бот для автоматических поздравлений

Проект представляет собой автоматизированную систему для генерации персонализированных поздравлений и их отправки клиентам по email. Система использует GigaChat API для создания контента и работает в нескольких режимах.

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

🤖 Автономный режим

• Автоматическая проверка базы данных на новые события
• Генерация персонализированных поздравлений от лица Сбера
• Отправка писем клиентам с прикрепленными открытками
• Отправка копий всех писем оператору для контроля
• Автоматическое определение нового дня

🚀 Быстрая отправка

• Разовая отправка всех сегодняшних событий
• С копиями оператору
• Без ожидания следующей проверки

👁️ Ручной режим

• Предпросмотр каждого письма перед отправкой
• Возможность перегенерации изображений
• Ручное подтверждение отправки
• Управление клиентами в БД

📋 Команды бота

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

/start - Главное меню с выбором режима
/start_auto - Запуск автономного режима
/stop_auto - Остановка автономного режима
/quick_send - Быстрая отправка всех сегодняшних событий
/scan - Ручной режим с предпросмотром
/status - Статус системы

Управление данными

/clients - Показать всех клиентов из общей БД
/today - Показать сегодняшние события из JSON файла
/add - Добавить нового клиента в общую БД
/upcoming - Предстоящие события (14 дней)
/cleanup - Очистить старые JSON файлы
/help - Полная справка

🏗️ Архитектура проекта

Структура файлов

├── bot.py              # Основной файл бота (Telegram)
├── config.py           # Конфигурация и настройки
├── database.py         # Работа с SQLite БД клиентов
├── llm_service.py      # Генерация контента через GigaChat
├── email_service.py    # Отправка email через SMTP
├── file_manager.py     # Управление JSON файлами событий
├── add_client_manual.py # Скрипт для ручного добавления клиентов
├── clients.db          # База данных SQLite (создается автоматически)
└── data/              # Директория для данных
    ├── images/        # Сгенерированные изображения
    └── events_*.json  # JSON файлы событий

Ключевые компоненты

1. Telegram Bot (
   bot.py
   ) - интерфейс управления
2. GigaChat Service (
   llm_service.py
   ) - генерация текста и изображений
3. Database Manager (
   database.py
   ) - работа с клиентами
4. Email Service (
   email_service.py
   ) - отправка писем
5. File Manager (
   file_manager.py
   ) - управление файлами событий

🔧 Настройка

1. Установка зависимостей

2. Конфигурация переменных окружения

Создайте файл

3. Настройка GigaChat API

1. Получите учетные данные GigaChat API
2. Укажите их в файле
   .env
3. Убедитесь, что у вас есть доступ к GigaChat Pro для генерации изображений

4. Настройка SMTP

Проект поддерживает:

• Gmail (рекомендуется использовать App Password)
• Другие SMTP серверы
• SSL/TLS шифрование

🚀 Запуск бота

1. Запуск вручную

2. Автоматический запуск

Бот автоматически запускает автономный режим при старте, если задан

3. Команды для управления

После запуска отправьте боту

📊 База данных

Структура таблицы

clients

Добавление клиентов

1. Через команду
   /add
   в боте
2. Через скрипт
   add_client_manual.py
3. Непосредственно в SQLite

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

Хранение данных

• Учетные данные хранятся в переменных окружения
• База данных клиентов локально
• Файлы событий хранятся 7 дней

SMTP безопасность

• Использование SSL/TLS
• App Passwords вместо обычных паролей
• Ограниченные права доступа

⚙️ Кастомизация

Настройка автономного режима

В

Настройка генерации контента

В

• Шаблоны поздравлений от лица Сбера
• Промпты для генерации изображений
• Тон и стиль сообщений

Настройка SMTP

В

🐛 Устранение неполадок

Проблемы с GigaChat API

1. Проверьте учетные данные в
   .env
2. Убедитесь в наличии доступа к GigaChat Pro
3. Проверьте квоты API

Проблемы с SMTP

1. Для Gmail используйте App Password
2. Проверьте настройки порта и хоста
3. Убедитесь, что нет блокировки со стороны провайдера

Проблемы с базой данных

1. Проверьте права доступа к файлу
   clients.db
2. Убедитесь, что SQLite установлен
3. Проверьте структуру таблиц

📈 Мониторинг

Статус системы

Команда

• Статус автономного режима
• Количество клиентов в БД
• Информацию о файлах
• Статистику отправки

Логирование

• Все операции логируются в консоль
• Ошибки отправляются оператору
• Сохраняются JSON файлы с результатами

🔄 Технические детали

Генерация контента

1. Текст: GigaChat создает персонализированные поздравления от лица Сбера
2. Изображения: GigaChat Pro генерирует тематические открытки без лиц людей
3. Промпты: Адаптируются под тип события и описание клиента

Работа с изображениями

• Изображения сохраняются в
  data/images/
• Используются заглушки при ошибках генерации
• Поддерживается перегенерация изображений

Управление памятью

• Автоматическая очистка старых файлов
• Оптимизированные запросы к БД
• Кэширование токенов GigaChat

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

Сообщение об ошибках

1. Проверьте логи в консоли
2. Укажите команду, которая вызвала ошибку
3. Приложите конфигурацию (без паролей)

Предложения по улучшению

1. Форматирование генерации контента
2. Новые типы событий
3. Дополнительные интеграции

📄 Лицензия

Проект предназначен для внутреннего использования. Все права на использование GigaChat API принадлежат СберБанку.