---

type: project name: Фінбот (Expense Bot) slug: finbot status: active readiness_pct: 75 owner_agent: TODO products: [] created: 2026-05-01 last_updated: 2026-05-03 aliases: [expense-bot, фінбот, expense bot, трекер витрат]

Фінбот (Expense Bot) — @Finance_vereschak_family_bot

Особистий Telegram-бот трекінгу витрат родини Сергія: text/voice/photo чека → Gemini 2.5 Flash → Google Sheets.

Meta

Why this exists:

• Систематизувати фін-облік родини без рутинного ручного вводу.
• Розпізнавати з фото чека, з голосового, з тексту — одним інтерфейсом у Telegram.
• AI парсить → юзер підтверджує кнопкою → запис у Google Sheet.

KPIs:

• К-сть транзакцій / місяць (квітень 2026: 91, всього 141 659 ₴).
• % auto-категоризації (без правки користувача): TODO заміряти.
• Uptime: ~99% на GCP e2-micro з restart=always.

Status snapshot: Бот працює у проді на GCP e2-micro (~$3.64/міс), родина його використовує. У процесі міграції на VPS (#37) — чекає handoff коду від Desktop Claude. Категоризація апгрейднута до 2-рівневої 2026-05-02.

Stakeholders:

• Owner: Сергій
• Allowed users: Telegram ID 312194208 (Сергій). Дружина — TODO додати.

---

Design

Стек

• Python 3.12, python-telegram-bot 21.8
• google-genai SDK — Gemini 2.5 Flash (text/image/voice), thinking_budget: 0, regex JSON extraction
• gspread + Google Service Account → Google Sheets Expense_Tracker
• Fernet AES для секретів у .env через MASTER_PASSWORD

Flow

Telegram вхід (text / voice / photo чека)
    │
    ▼
expense_parser.py — Gemini 2.5 Flash
    │
    ▼
ConversationHandler — підтвердження inline-кнопками
    │
    ▼
sheets.py — gspread → worksheet "Expenses"

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

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

---

Implementation

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

Замість плоских 10 категорій (Food/Transport/Housing/...) — 8 макро × 2-4 sub = ~22 категорії. Підтверджено Сергієм після аналізу квітневих витрат.

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

Чому виокремили 🚬 Шкідливі звички — Сергій захотів бачити ці витрати окремою макро-категорією (а не всередині «Соціального» або «Здоров'я»), щоб мати чесний show-down.

Спостереження з квітневого аналізу (/srv/reports/expense-april-2026-2level.md):

• «Кава (закупка зерен)» — це 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 залишаються, нові пишуться з обома

Поточний хостинг (GCP)

• 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/міс
• SA: expense-bot@expense-bot-492610.iam.gserviceaccount.com
• Секрети: /srv/passepartout/expense-bot/secrets.env (chmod 600 + .meta)

Cross-references

• Memory: personal_expense_bot.md
• Аналіз квітень-2026: http://31.131.26.203/reports/expense-april-2026-2level.md
• Outbox handoff (міграція): /root/.claude/projects/-/memory/outbox-to-desktop/2026-05-02T052100Z-expense-bot-vps-migration.md
• Passepartout: /srv/passepartout/expense-bot/secrets.env

---

Notes & Backlog

Активні задачі

• [x] 2026-05-02: Аналіз квітня (141 659 ₴, 91 транзакція) → таксономія 8×2-4
• [x] 2026-05-02: 🚬 Шкідливі звички виокремлено
• [x] 2026-05-02: Outbox handoff для Desktop Claude (з кодом) — pending response
• [ ] #37 Міграція на VPS — чекає handoff від Desktop (репо/код, оновлений Sheet headers)
• [ ] Оновити Gemini-промпт під 2-рівневу таксономію
• [ ] Sheet headers: додати Macro_Category + Sub_Category
• [ ] Після verify на VPS — вимкнути billing у GCP-проекті

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

---

Questions for human (waiting for Сергій)

High-priority

1. Репо — є git? URL? Чи живе тільки локально на D:/Claude Code/expense-bot/?
2. Сховище — Sheets залишаємо чи мігруємо в Supabase/SQLite? (При міграції на VPS — момент, коли можна перейти на щось більш query-friendly).
3. MASTER_PASSWORD — оновити на новій інсталяції чи лишити як є?

Medium

4. Дружина як другий користувач — додати її Telegram ID у ALLOWED_USERS?
5. Authority of edits — якщо AI неправильно категоризував і юзер виправив через кнопку — це фідбек-сигнал у промпт?

---

Legacy

• Початкова Idea-версія wiki (2026-05-01): порожня, була stub.
• Вся інфа була у /root/.claude/projects/-/memory/personal_expense_bot.md (імпорт з Desktop Claude, 29.04).
• Після цього апгрейду — wiki стає canonical, memory залишається легасі-бекапом (rule #14).