Loop Telegram Bot

Производственный Telegram-бот (aiogram v3) для подбора очков с интеграцией каталога через Google Sheets CSV.

Требования

• Python 3.10+
• SQLite

Установка

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

Настройка окружения

Скопируйте .env.example → .env и заполните значения. В шаблоне у каждой переменной есть комментарий:

• токен бота, ссылка на Google Sheets CSV и URL лендинга;
• лимиты, TTL кэша, параметры напоминаний;
• переключатель мок-генерации и креды NanoBanana;
• пути к папкам uploads/ и results/.

Все переменные подхватываются через load_config (app/config.py) и превращаются в dataclass Config, так что никаких «спрятанных» параметров нет — правки делаются только в .env.

Коллажи

Подборка моделей теперь отправляется одним сообщением-коллажем формата 1×3 (три плитки в ряд) поверх Pillow. Коллаж и логика выдачи настраиваются через переменные окружения:

# Параметры выдачи
BATCH_SIZE=3             # сколько моделей показываем за один коллаж
BATCH_LAYOUT_COLS=3      # количество колонок (1×3)
PICK_RULE=2_1            # 2 карточки выбранного пола + 1 унисекс

# Геометрия и визуал
CANVAS_WIDTH=1800        # ширина итогового полотна
CANVAS_HEIGHT=600        # высота полотна
CANVAS_BG="#FFFFFF"       # цвет фона
TILE_MARGIN=30           # отступы слева/справа и сверху/снизу
DIVIDER_WIDTH=4          # толщина вертикальных разделителей
DIVIDER_COLOR="#E5E5E5"  # цвет разделителей
JPEG_QUALITY=88          # качество JPEG (Telegram-friendly)

Параметры отвечают за итоговый размер, отступы, цвет фона и качество JPEG. Изображения вписываются «letterbox» с сохранением пропорций: свободные плитки остаются белыми, если моделей меньше BATCH_SIZE.

Переменная	Назначение	Значение по умолчанию
BATCH_SIZE	Сколько моделей показываем в одной выдаче	3
BATCH_LAYOUT_COLS	Количество колонок в коллаже	3
PICK_RULE	Квоты по полу: 2_1 = 2 выбранный пол + 1 унисекс	2_1
CANVAS_WIDTH	Ширина итогового полотна в пикселях	1800
CANVAS_HEIGHT	Высота итогового полотна в пикселях	600
CANVAS_BG	Цвет фона (HEX)	#FFFFFF
TILE_MARGIN	Отступ по краям полотна	30
DIVIDER_WIDTH	Толщина разделителей между плитками	4
DIVIDER_COLOR	Цвет вертикальных разделителей (HEX)	#E5E5E5
JPEG_QUALITY	Качество JPEG (баланс между размером файла и артефактами)	88

Разделитель

• DIVIDER_WIDTH + DIVIDER_COLOR задают вертикальные полосы между плитками.
• Отступы TILE_MARGIN применяются и по горизонтали, и по вертикали.
• Для аккуратной нейтральной палитры подходит #E5E5E5 — он не отвлекает от самих оправ.

Рекомендации по исходным кадрам:

• Старайтесь хранить фотографии очков в одинаковом соотношении сторон (идеально — квадрат или схожие «ландшафтные»).
• Добивайтесь, чтобы сама оправа занимала 70–85% ширины — так итоговый коллаж получится читаемым.
• PNG с прозрачным фоном подходят: при конвертации в JPEG фон зальётся цветом CANVAS_BG.
• Лучше использовать источники от 1200 px по длинной стороне — Telegram всё равно пережмёт, но детализация сохранится.

Как работает каталог

• GoogleSheetCatalog подтягивает CSV по ссылке публикации Google Таблицы.
• Ответ кэшируется на 60 секунд (можно настроить через CSV_FETCH_TTL_SEC), чтобы не ддосить источник.
• Для устойчивости реализован повтор запросов (до CSV_FETCH_RETRIES попыток) с экспоненциальной задержкой.
• Каждая карточка преобразует Google Drive view-ссылку к прямому URL (/uc?export=view&id=...) перед отправкой пользователю.
• Фильтрация идёт по колонке «Пол»; если моделей мало, добавляются «Унисекс».
• Кнопки «Подробнее о модели» открывают ссылку из таблицы.

⚠️ Telegram не позволяет программно открыть системный выбор файлов, поэтому пользователю всё равно нужно отправлять фото вручную через стандартную «скрепку» в чате.

Запуск

python -m app.main

Бот использует long polling. При старте создаются директории uploads/ и results/, а каталог очков подгружается из Google Sheets.

Тесты

pytest

Архитектура

• app/services/catalog_google.py — сервис каталога с кэшем и retry.
• app/services/repository.py — SQLite-хранилище пользователей и дневных лимитов.
• app/services/tryon_mock.py — mock-генерация результатов (белые изображения).
• app/fsm.py — конечный автомат aiogram, который обращается к каталогу и управляет UX.
• app/texts/messages.py — единый файл с текстами и подписями для нетехнарей.
• app/utils/drive.py — преобразование ссылок Google Drive.

План развития

• Интеграция NanoBanana вместо mock-сервиса.
• Подключение реального стора для выдачи превью пользователю.