cinnabarflower/mnemo_cards
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
mnemo_cards/mnemo_cards_telegram_bot/BOT_SHARE_IMAGE_PLAN.md
Dmitry 0c9247f276 deploy
2025-11-16 19:31:22 +03:00

7.8 KiB
Raw Blame History

Telegram Bot Share Image Feature Plan

Objetivo

Добавить в телеграм-бота команду /share которая генерирует красивое сообщение и изображение для приглашения друзей использовать бот и приложение.

Требования

1. Ограничение частоты запросов

  • Максимум 1 сообщение на пользователя в день
  • Лимит должен быть настраиваемым через переменные окружения или config
  • Хранение последних запросов пользователей в Isar БД

2. Получение исходной карточки

  • Случайный выбор карточки из бэкенда (из всех доступных карточек)
  • Получение через Isar (DBManager будет иметь доступ к карточкам через isar.gameCardModels)
  • Если нет карточек, использовать placeholder или default изображение

3. Обработка изображения

  • Загрузка оригинального PNG изображения карточки из файловой системы бэкенда
  • Добавление красивой рамки вокруг изображения
  • Размер рамки: ~30-50px с обеих сторон
  • Цвет рамки: тёмный или с градиентом (TBD в процессе разработки)
  • Замена текста на карточке или добавление наложения с названием приложения "mnemo cards"

4. Формирование сообщения

  • Текст без эмодзи
  • Включение referral code пользователя
  • Профессиональный, дружеский тон
  • Примерный формат: 
    Приветствую! Я тестирую приложение mnemo cards для изучения языков.

Присоединяйся и начни учиться вместе со мной!

Referral code: [CODE_HERE]

5. Отправка результата

  • Отправить сообщение с текстом
  • Отправить сгенерированное изображение к сообщению
  • Удобство: в одном сообщении или отдельно (TBD)

Архитектура решения

Структура данных Isar

// Для отслеживания количества поделиться за день
class ShareRequestModel {
  Id? id;
  late String telegramUserId;
  late DateTime requestedAt;
  
  // Возможные поля для будущего аналитика
  late String? generatedCardId;
}

Компоненты для реализации

1. ImageGenerator (lib/image_generator.dart)

Класс для генерации изображения с рамкой

  • Future<List<int>> generateShareImage(GameCardModel card) - генерирует PNG с рамкой
  • Использует image package для обработки изображений
  • Работает с файловой системой для чтения оригинальных карточек

2. ReferralCodeManager (в db_manager.dart)

Методы для работы с referral кодами

  • Future<String> getUserReferralCode(String telegramUserId) - получить или сгенерировать код
  • Хранение в Isar или вызов бэкенда

3. ShareRateLimiter (в db_manager.dart)

Контроль частоты запросов

  • Future<bool> canShareToday(String telegramUserId) - проверка лимита
  • Future<void> recordShareRequest(String telegramUserId, int? cardId) - сохранение запроса
  • Конфигурируемый лимит (дефолт 1 раз в день)

4. ShareCommand (в main.dart)

Новая команда /share

  • Обработка команды в teledart.onCommand('share')
  • Проверка лимита
  • Получение случайной карточки
  • Генерация изображения
  • Отправка сообщения с изображением

Этапы реализации

Этап 1: Подготовка инфраструктуры

  1. Добавить зависимость image: ^4.0.0 в pubspec.yaml
  2. Создать миграцию Isar: добавить ShareRequestModel
  3. Расширить DBManager методами для율 лимитирования и referral кодов

Этап 2: Реализация обработки изображений

  1. Создать ImageGenerator класс
  2. Реализовать:
    • Загрузку карточки из файловой системы
    • Добавление рамки
    • Добавление текста с названием приложения
  3. Написать unit тесты

Этап 3: Реализация rate limiting

  1. Реализовать методы в DBManager
  2. Написать unit тесты

Этап 4: Реализация команды /share

  1. Добавить команду в main.dart
  2. Интегрировать все компоненты
  3. Обработка ошибок

Этап 5: Конфигурация

  1. Добавить переменные окружения
  2. Обновить BotConfig
  3. Документация

Этап 6: Тестирование и отладка

  1. Ручное тестирование в Telegram
  2. Проверка лимитирования
  3. Проверка качества изображения

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

# Количество поделиться в день (дефолт: 1)
BOT_SHARE_DAILY_LIMIT=1

# Путь к бэкенду для получения referral кода (опционально)
BACKEND_URL=http://localhost:8443

Возможные улучшения (Future)

  • Выбор темы рамки (светлая/тёмная)
  • Кастомизация текста приложения
  • Сохранение сгенерированных изображений для кэширования
  • Аналитика использования feature
  • Поддержка мультиязычного текста

Технические заметки

Получение случайной карточки

final allCards = await isar.gameCardModels.where().findAll();
final random = Random();
final card = allCards[random.nextInt(allCards.length)];

Пути к изображениям

  • Оригинальные изображения хранятся в: ../mnemo_cards_backend/data/cards/
  • Имя файла в карточке: GameCardModel.image (например: "1234_word.png")

Обработка изображений в Dart

  • Package image для обработки PNG
  • Методы: copyResize(), drawString(), drawRect() и т.д.
  • Примеры использования есть в mnemo_cards_backend/lib/packs/pack_manager.dart

Деньги на: Quality Assurance

  • Проверить работу при отсутствии карточек
  • Проверить работу при отсутствии файла изображения
  • Проверить корректность rate limiting через несколько дней
  • Проверить качество генерируемого изображения на мобильных устройствах
  • Проверить производительность при работе с большим количеством карточек