# 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 (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](architecture.md) — домен, модули, потоки данных, API.
- [conventions.md](conventions.md) — деньги, валюты, идемпотентность, стиль.
- [plan.md](plan.md) — фазы и чек-листы проверки.
- [ops.md](ops.md) — деплой на VPS, бэкапы, секреты.
- [links.md](links.md) — внешние API и референсы.
- [offline-cache.md](offline-cache.md) — офлайн-кэш Flutter-клиента: контракт `Cached<T>`,
  `CacheInterceptor`, баннер «данные на …» (фаза 5).
- [design-system.md](design-system.md) — визуальный язык Flutter-клиента по образцу Snowball: токены
  темы, верхняя панель навигации, сетка карточек на Обзоре, таблица активов, вкладки Аналитики.