[2026-06-21] taiga-vault: family/how-to/htpc-system.md personal/projects/budget-app/index.md

personal/projects/budget-app/index.md

@@ -2,6 +2,8 @@
 
 Персональный бюджет в виде веб-приложения. Замена Excel-таблицы `~/Downloads/Budget.xlsx`, в которой ведутся транзакции 2020–2024+ по нескольким счетам в разных валютах.
 
+**Solo на старте** (только Alex), но код пишем generic — с прицелом на public SaaS позже (multi-tenant, конфиги отделены).
+
 ## Источник: текущая Excel-таблица
 
 Файл: `~/Downloads/Budget.xlsx` (3.6 MB, 13 листов).
@@ -64,7 +66,7 @@
 
 ## Что таблица умеет уже сейчас
 
-1. **Учёт транзакций** в любой валюте, с автопересчётом в выбранную валюту отчёта (default — RUB).
+1. **Учёт транзакций** в любой валюте, с автопересчётом в выбранную валюту отчёта.
 2. **Остатки по счетам** в реальном времени (через `остаток деб` / `остаток кред`).
 3. **Категоризация** в иерархии (родитель/подкатегория) с эмодзи.
 4. **Годовые отчёты**: план vs факт, доход/расход/инвестиции, % отложено, накопленный капитал, долг.
@@ -91,67 +93,87 @@
 
 1. Принимает все те же транзакции (multi-currency, multi-account, double-entry).
 2. Считает аналитику и сводки **на лету** через SQL, а не через `VLOOKUP`.
-3. Импортирует банковские выписки (Альфа, Сбер, Demir, …) и категоризует автоматически.
+3. Импортирует банковские выписки (Альфа, Сбер, Demir, …) автоматически + AI-резолвер для неоднозначных случаев.
 4. Даёт мобильный UI для быстрого ввода трат на ходу.
-5. Моделирует **FIRE-сценарии**: при текущей норме сбережений и доходности портфеля — когда достигаешь точки пассивного дохода.
+5. Моделирует **FIRE-сценарии** (отдельная фаза после готового бюджетирования).
 6. Прогнозирует траты на N месяцев вперёд по сезонной модели (категории `🧱 Стройка`, `🏖️ Отдых` цикличны).
 
 ### Доменная модель (первая итерация)
 
 ```
+User (id, email, ...)                            -- для будущего multi-tenant SaaS
+Settings (user_id, base_currency_id, ...)        -- base currency выбирается в настройках
 Currency (code, name, symbol)
-Account (id, name, currency_id, type {cash, debit, credit, deposit, brokerage}, active, credit_limit, grace_period_days, monthly_payment)
-CategoryGroup (id, name, emoji)  -- родитель
-Category (id, name, group_id)    -- подкатегория
-ExchangeRate (currency_id, date, rate_to_base)  -- история по датам
+Account (id, user_id, name, currency_id, type {cash, debit, credit, deposit, brokerage}, active, credit_limit, grace_period_days, monthly_payment)
+CategoryGroup (id, user_id, name, emoji)         -- родитель
+Category (id, user_id, name, group_id)           -- подкатегория
+ExchangeRate (currency_id, date, rate_to_base, source {nbkr, manual, ...})  -- история по датам
 Transaction (
-  id, date, amount, 
-  source_account_id NULL,  -- дебет (откуда); NULL = доход извне
-  dest_account_id NULL,    -- кредит (куда); NULL = расход вовне
-  cross_rate NULL,         -- курс при internal transfer
+  id, user_id, date, amount,
+  source_account_id NULL,                        -- дебет (откуда); NULL = доход извне
+  dest_account_id NULL,                          -- кредит (куда); NULL = расход вовне
+  cross_rate NULL,                               -- курс при internal transfer
   category_id, comment, tax_amount NULL,
-  imported_from NULL       -- метаданные импорта банковской выписки
+  import_id NULL                                 -- ссылка на BankImport
 )
 TaxRecord (year, month, type {patent, ндфл, …}, amount, currency_id, paid_date NULL)
-FireGoal (id, target_amount, target_currency_id, expected_return_rate, target_date NULL)
-InvestmentSnapshot (date, account_id, value, currency_id)  -- для отслеживания капитала
+BankImport (id, user_id, account_id, source {alfa, sber, demir, ...}, fetched_at, raw_blob, status {pending, parsed, resolved, manual})
+Alert (id, user_id, type {manual_resolve_needed, parse_failed, ...}, payload, sent_at, ack_at NULL)  -- TG-уведомления
+FireGoal (id, user_id, target_amount, target_currency_id, expected_return_rate, target_date NULL)
+InvestmentSnapshot (date, account_id, value, currency_id)
 ```
 
-### Архитектура (черновик)
+Base currency не хардкодится — выбирается в `Settings`, и все пересчёты (остатки, отчёты, графики) автоматически приводятся к ней по `ExchangeRate.rate_to_base` на дату.
+
+### Архитектура
 
 - **Backend**: Python + FastAPI + SQLAlchemy + Postgres.
-- **Frontend**: Vue 3 + Vite + Pinia (либо SvelteKit). Адаптив для мобильного.
-- **БД**: Postgres (либо SQLite на старт, мигрировать позже).
-- **Деплой**: Docker на Kraken (есть свободный хост, WireGuard + nginx уже настроены).
+- **Frontend**: Vue 3 + Vite + Pinia. Адаптив для мобильного (PWA).
+- **БД**: Postgres.
+- **Деплой**: Docker Compose на Mac (Eagle). Конфиги в `~/docker/budget-app/` (по конвенции остальных сервисов). Код проекта — `~/Developer/budget-app/` с git.
+- **Внешний доступ**: `budget.qentra.top` через Cloudflare Tunnel (или существующий nginx-reverse-proxy). Auth — login/password + долгоживущий JWT-токен в localStorage/cookie. Один пользователь на старте, но схема готова под multi-tenant.
 - **Импорт Excel**: однократный скрипт миграции (`scripts/import-xlsx.py`), читает `Budget.xlsx`, заливает в БД.
-- **Импорт банков**: парсеры CSV/XLS на Python (Альфа, Сбер, Demir — у каждого свой формат).
-- **Категоризация**: rules-based (regex по комменту) + позже — лёгкая ML-модель (sklearn / LLM-классификатор).
-- **Аналитика**: SQL-агрегаты + Recharts/Apache ECharts на фронте.
-- **FIRE**: модуль с входами (текущий капитал, ежемесячные сбережения, ожидаемая доходность, инфляция, целевой пассивный доход) → калькулятор и графики.
+- **Курсы валют**: cron-джоб тянет курсы с НБ Кыргызстана (`nbkr.kg` XML feed) по расписанию (раз в день). Если на какую-то дату курса нет — автоматически дозаполняет (back-fill ближайшего рабочего дня). Источник по умолчанию для KGS-базы; для других валют — ручной override или дополнительные источники (ЦБ РФ, ECB).
+- **Импорт банков**: автоматический fetch выписок (где есть API/HTML-парсинг) + парсеры CSV/XLS на Python (Альфа, Сбер, Demir — у каждого свой формат). После парсинга — прогон через AI-агента (LLM) для резолва неоднозначных строк: категоризация, merge дубликатов, идентификация контрагентов.
+- **Telegram-бот для алертов**: оповещение, когда нужно ручное вмешательство (AI не смог однозначно категоризировать, парсер сломался на новом формате выписки, обнаружен дубль). Подтверждение/правка через инлайн-кнопки в TG → апдейт в БД.
+- **HTTP MCP-интеграция**: приложение экспонирует MCP-сервер (HTTP transport), чтобы Eagle/Hermes мог запрашивать сводки, добавлять транзакции голосом, дёргать прогнозы из чата.
+- **Аналитика**: SQL-агрегаты + Apache ECharts на фронте.
+- **FIRE / Инвестпортфели**: отдельная фаза после того, как бюджетирование готово. Не в MVP.
 
 ### Этапы
 
 1. **Phase 0 — Discovery & schema**. Полностью разобрать Excel, утвердить доменную модель. *(в процессе — этот док)*
-2. **Phase 1 — Import & read-only viewer**. Скрипт миграции из xlsx → Postgres. Простой viewer транзакций + остатков + годовые отчёты.
-3. **Phase 2 — Ручной ввод**. Форма добавления транзакции, CRUD категорий/счетов, ведение курсов.
-4. **Phase 3 — Импорт банков**. Парсеры CSV для актуальных счетов. Категоризация по правилам.
-5. **Phase 4 — Аналитика**. Дашборды: расход по категориям, динамика, бёрндаун по бюджету.
-6. **Phase 5 — FIRE-модуль**. Калькулятор, проекции, сценарии «что если».
+2. **Phase 1 — Skeleton + import**. Создать `~/Developer/budget-app/` (git init), FastAPI + Postgres в Docker Compose в `~/docker/budget-app/`, миграция xlsx → БД. Read-only viewer транзакций + остатков + годовые отчёты. Внешний доступ через `budget.qentra.top` с auth.
+3. **Phase 2 — Курсы и настройки**. Cron-джоб для НБ КР с back-fill. Базовая валюта в настройках. Все пересчёты привязаны к ней.
+4. **Phase 3 — Ручной ввод**. Форма добавления транзакции, CRUD категорий/счетов, ручная правка курсов.
+5. **Phase 4 — Импорт банков + AI-резолвер**. Автофетч/парсеры (Альфа, Сбер, Demir). LLM-резолвер. TG-бот для ручных подтверждений.
+6. **Phase 5 — Аналитика**. Дашборды: расход по категориям, динамика, бёрндаун по бюджету. Прогнозы.
 7. **Phase 6 — Mobile / PWA**. Быстрый ввод с телефона.
+8. **Phase 7 — MCP HTTP**. Экспонировать MCP-эндпоинт для Hermes.
+9. **Phase 8 — Инвестпортфели + FIRE**. Тикеры/цены/дивы. Калькулятор FIRE. *(отдельное планирование когда бюджетирование готово.)*
+
+### Multi-tenant readiness (для будущего public SaaS)
+
+Даже в solo-режиме на старте:
+
+- Все таблицы доменной модели имеют `user_id` (на solo — захардкожен на одного юзера).
+- Конфиги (домен, секреты, базовая валюта) — в `.env` / config-файле, не в коде.
+- AI-промпты, парсеры банков, источники курсов — pluggable, через интерфейсы/registry.
+- Никаких личных данных Alex в коде (имена счетов, категорий, комментарии) — всё через миграцию данных в БД.
+- Лицензия — выбрать перед публичным релизом (AGPL/MIT/коммерческая).
 
 ## Открытые вопросы
 
-- Какой выбрать base currency для отчётов по умолчанию? (В Excel — переменная.)
-- Хранить ли курсы Centroбанка/ECB как источник истины + ручные override, или только ручной ввод?
-- Нужна ли поддержка инвестиционных портфелей (тикеры, цены, дивиденды) — или это отдельный модуль?
-- Multi-user (только Alex, или с возможностью добавить семью)?
-- Self-hosted only, или может быть public SaaS позже?
+- Какой именно auth: самописный JWT, готовый Authlib, или Authelia/Authentik как внешний провайдер? (С прицелом на multi-tenant.)
+- AI-резолвер: какой провайдер по умолчанию? (Claude через openclaw / локальная LLM?)
+- Хранить ли raw blob банковской выписки навсегда (audit) или только парсенные транзакции?
+- Какой парсер xlsx использовать (openpyxl сейчас вызывал approval timeout — возможно perl/node-вариант)?
 
 ## Следующий шаг
 
-Обсудить доменную модель и архитектуру. После апрува — план Phase 1 (миграция Excel → БД, read-only viewer).
+Планирование Phase 1: структура `~/Developer/budget-app/`, скелет FastAPI + Postgres + Vue, миграция Excel → БД, базовый auth + nginx/tunnel для `budget.qentra.top`.
 
 ---
 
 **Создано:** 2026-06-21
-**Статус:** Phase 0 — Discovery
+**Статус:** Phase 0 — Discovery (правки внесены)