fin-tracker/docs/ai

docs/ai — обзор проекта

Назначение

fin-tracker объединяет два мира личных финансов:

• ZenMoney — повседневные счета и транзакции (синкается с банками сам), читаем через POST /v8/diff/;
• брокеры — T-Invest по gRPC API, Сбер и ВТБ через загрузку отчётов, прочее вручную/CSV;

и считает поверх них то, за что раньше платили Snowball Income: позиции по всем брокерам, P&L, XIRR/TWR, аллокацию, календарь дивидендов и купонов с прогнозом, ребалансировку, бенчмарки, налоги — плюс net worth, cash flow и runway по ZenMoney.

Система в общих чертах

sources/* ──sync──▶ raw_* (JSONB, идемпотентно) ──map──▶ core (account, instrument, event, cash_txn…)
                                                          │
worker (APScheduler, advisory locks)                      ▼
                                              ledger (лоты FIFO, дедуп, матчинг ZM↔брокер)
                                                          │
                                              analytics (polars, pyxirr) ──▶ metric_* ──▶ api ──▶ Flutter

• backend/src/fintracker/sources/ — по одному пакету на источник, контракт в base.py.
• worker/ — планировщик и запуск синков (runner.run_source): lock, sync_run, курсор.
• api/ — FastAPI, /api/v1, ошибки RFC 7807, деньги строками.
• app/ — Flutter, клиент сгенерирован из openapi/openapi.json.

Документы

• architecture.md — домен, модули, потоки данных, API.
• conventions.md — деньги, валюты, идемпотентность, стиль.
• plan.md — фазы и чек-листы проверки.
• ops.md — деплой на VPS, бэкапы, секреты.
• links.md — внешние API и референсы.
• offline-cache.md — офлайн-кэш Flutter-клиента: контракт Cached<T>, CacheInterceptor, баннер «данные на …» (фаза 5).
• design-system.md — визуальный язык Flutter-клиента: токены темы, SectionHeader/TileCarousel, группированный NavSidebar (обкатано на Обзоре).