Arteggia Promo Bot

Telegram-бот для акції «Купи 2× Arteggia → безкоштовна Vertebra». Статус: MVP готовий, очікує bot token від BotFather.

Механіка

1. Користувач купує 2 упаковки Arteggia в аптеці
2. Ділиться фото чека з ботом
3. Bot → Gemini Vision OCR → витягує: фіскальний номер, дату, позиції
4. Валідація: ≥2 Arteggia + чек ще не зареєстровано + дата в період акції
5. Якщо ок → видається промокод (наразі placeholder ARTEGGIA-TEST-2026)
6. Користувач активує промокод на medizine.ua при оформленні Vertebra

Правила

• Період акції: 01.04.2026 – 31.12.2026
• 1 людина (унікальний номер телефону) = 1 промокод
• 1 фіскальний чек = 1 видача (anti-replay по fiscal_id)
• Dedup по SHA256 фото (anti-replay повторної фотки)

Стек

• aiogram 3 — Telegram bot framework
• Gemini 2.0 Flash — Vision OCR для чеків
• SQLite (локально) — MVP storage. При масштабуванні → Supabase/Postgres
• systemd — arteggia-bot.service

Структура

/srv/projects/arteggia-bot/
├── .env                     # BOT_TOKEN, GEMINI_API_KEY, ADMIN_IDS
├── requirements.txt
├── src/
│   ├── bot.py              # aiogram handlers + FSM
│   ├── vision.py           # Gemini Vision OCR
│   ├── validator.py        # 3 перевірки (SKU/period/duplicate)
│   └── db.py               # SQLite: participants, receipts, moderation_notes
├── data/
│   ├── db.sqlite
│   └── images/             # збережені фото чеків (для модерації)
└── logs/bot.log

Модерація (admin commands)

• /log — останні 15 чеків (усі статуси)
• /log approved / /log rejected / /log error — фільтр
• /comment <receipt_id> <текст> — додати коментар
• /stats — кількість approved / rejected / issued

Bot також пушить адміну:

• Успішна видача промокоду
• Нечитабельний чек (потребує людського погляду)
• Vision API errors

Flow (FSM)

1. /start → привітання → кнопка «Поділитись номером»
2. wait_phone → отримано Contact → зберігаємо номер
3. wait_name → введення ПІБ (мінімум 2 слова)
4. wait_receipt → фото → OCR → валідація → видача/відмова з деталями

Статуси fail (що видно користувачу)

• unreadable — «не розпізнав чек, надішли чіткіше»
• not_enough_sku — «знайдено N Arteggia, треба 2»
• bad_date — «не вдалося розпізнати дату»
• out_of_period — «чек датовано X, акція Y–Z»
• duplicate_fiscal — «чек вже реєстрували»
• duplicate_image — «це фото вже надсилали»
• error — vision API помилка → повідомлення адміну

Deploy

# .env вже готовий, GEMINI_API_KEY з passepartout
# Після отримання BOT_TOKEN:
sed -i 's/BOT_TOKEN=.*/BOT_TOKEN=YOUR_TOKEN_HERE/' /srv/projects/arteggia-bot/.env
systemctl enable --now arteggia-bot
systemctl status arteggia-bot
journalctl -u arteggia-bot -f

Open items

• 🔄 BOT_TOKEN від BotFather — створити @arteggia_promo_bot (або інша назва)
• 🔄 Реальні промокоди — MVP має placeholder. Після валідації OCR на живих чеках — додати CSV-loader + FIFO видачу з таблиці
• 🔄 Supabase/Postgres — коли SQLite почне муляти (сотні тисяч записів або multi-instance)
• 🔄 Web-interface — якщо захочемо відкрити поза Telegram (потрібна буде SMS-верифікація)

Оцінка якості OCR

Головна мета MVP — перевірити чи Gemini Vision нормально розпізнає укр фіскальні чеки. Після запуску бота:

1. Протестувати на 5-10 різних чеків з різних аптек
2. Порівняти extracted fiscal_id / date / items з реальними
3. Якщо точність <90% → посилити prompt або розглянути alternative (Claude 3.5 Sonnet Vision, OpenAI Vision)

Бренд (продукт)

• Каталог бренду у Deltamedical products — SKU + інші проекти що ним займаються