---

name: Expense Bot — Фінбот @Finance_vereschak_family_bot description: Особистий Telegram-бот трекінгу витрат родини; AI parsing (Gemini 2.5 Flash) → Google Sheets. Зараз на GCP e2-micro, міграція на VPS у травні 2026. type: project originSessionId: 256f068c-ce5f-41dd-917f-a62a834b8c2a

Expense Bot (Фінбот) — особистий проект

Що це

Telegram-бот для родини Сергія, який приймає текст / голос / фото чека → парсить через Gemini 2.5 Flash (text/image/voice) → зберігає рядок у Google Sheet «Expense_Tracker».

ConversationHandler з кнопками-підтвердженнями перед записом — щоб AI не записував зайве.

Стек

• Python 3.12, python-telegram-bot 21.8
• google-genai SDK (Gemini 2.5 Flash, thinking_budget: 0, regex JSON extraction)
• gspread + service account → Google Sheets
• Fernet AES для секретів у .env

Структура коду (зараз на Windows у Сергія: D:/Claude Code/expense-bot/)

• bot.py — ConversationHandler: text/voice/photo → parse → confirm → save
• expense_parser.py — Gemini-клієнт
• config.py — розшифровує секрети з .env через MASTER_PASSWORD env var
• sheets.py — gspread service account, worksheet "Expenses"
• crypto_utils.py — Fernet encrypt/decrypt з SHA-256 key derivation

Категорії (Sheet headers)

Date, Amount, Currency, Category, Comment. Категорії: Food, Transport, Housing, Utilities, Health, Entertainment, Clothing, Education, Subscriptions, Other.

Зараз працює тут

• GCP project: expense-bot-492610
• VM: expense-bot-vm (e2-micro, europe-west1-b, IP 35.187.42.215)
• Container: klt-expense-bot-vm-venu, restart=always
• Artifact Registry: us-central1-docker.pkg.dev/expense-bot-492610/expense-bot-repo/expense-bot
• Витрати: ~$3.64/міс
• Сервіс-акаунт: expense-bot@expense-bot-492610.iam.gserviceaccount.com

Усі секрети винесено в passepartout: /srv/passepartout/expense-bot/secrets.env — Telegram bot token, Gemini API key, Sheets ID, MASTER_PASSWORD, GCP-конфіг (chmod 600 + .meta).

Заплановано: міграція на VPS (травень 2026)

1. Зняти з GCE → перенести runtime у /srv/services/expense-bot/
2. systemd unit (поллінг, не webhook) — за зразком arteggia-bot.service
3. Підтягнути секрети з passepartout/expense-bot/secrets.env через EnvironmentFile
4. Перевірити що Gemini API key ще валідний (на проекті expense-bot-492610 не повинно бути 403/429 — інший проект ніж основний gemini.key)
5. Після verify — вимкнути billing у GCP-проекті, $3.64/міс зупиняться

Питання до Сергія перед стартом міграції:

• Чи репо є в git? (URL?) Чи живе тільки локально на D:/Claude Code/expense-bot/?
• Тип сховища даних: Sheets залишаємо чи мігруємо в Supabase/SQLite?
• MASTER_PASSWORD оновити чи лишити як є?

Known issues (вже вирішені у production коді)

• gemini-2.0-flash deprecated → перейшли на gemini-2.5-flash
• Gemini 2.5 thinking blocks ламали JSON → thinking_budget: 0 + regex extraction
• Multiple bot instances → 409 Conflict; перед deploy треба killнути локальний Python
• max_output_tokens: 256 був замалий → 1024
• gcloud з пробілом у path → export CLOUDSDK_PYTHON=... у bash

Контакти і доступ

• Бот: @Finance_vereschak_family_bot
• Allowed user: Telegram ID 312194208 (Сергій)
• Власник GCP: sergey.vereschak@gmail.com

Категоризація — 2-рівнева (схвалено Сергієм 2026-05-02)

Базується на аналізі квітневих витрат (/srv/reports/expense-april-2026-analysis.md). Замість 10 плоских категорій — 2-рівнева структура: 7 макро × 2-4 sub = ~22 категорії.

Макро	Підкатегорії
🏠 Дім	Ремонт / Побут-хімія / Меблі / Комуналка
🚗 Авто	Паливо / Обслуговування / Кредит
🍔 Їжа	Продукти (закупка тижня) / Кафе-ресторани / Кава (закупка зерен)
🚬 Шкідливі звички	Алкоголь / IQOS
🎁 Соціальне	Подарунки / Тусовки / Друзі
👨‍👩‍👧 Родина	Освіта дітей / Здоров'я (діти) / Допомога батькам / Дитячі речі
💪 Спорт і здоров'я	Басейн / Вітаміни / Особистий догляд
📱 Технології	Гаджети / Електроніка / Підписки

Спостереження з квітневого аналізу:

• «Кава (закупка зерен)» — це CAPEX, не recurring (Сергій бере 2 кг ~раз на 2-3 міс).
• «Продукти на тиждень» — recurring 2-3к ₴/тиждень.
• «Авто/Кредит» — фіксований 11500 ₴/міс, окремо від обслуговування.

Як впровадити у бот:

1. Оновити Gemini-промпт у expense_parser.py — давати йому 2-рівневу таксономію + просити вибрати макро+sub
2. Google Sheet headers: додати колонки Macro_Category + Sub_Category поряд з оригінальною Category
3. Backward-compatibility — старі записи лишаються з flat Category, нові пишуться з обома

How to apply

Коли Сергій каже «фінбот», «expense bot», «трекер витрат» — це той самий проект. Технічна інтеграція з VPS — окрема задача (див. open-tasks.md). Інфа джерело: імпортовано з desktop/memory/expense_bot.md (Desktop Claude, 29.04).