# Budget Analytics & Data Explorer v1

Use this reference for FinanceManager Budget/Cashflow analytics sprints that build interactive analysis from confirmed budget transactions without opening new import/provider modules.

## Trigger

User asks for analytics/statistics/data explorer over Budget/Cashflow: Einnahmen, Ausgaben, Kategorien, Händler, Monatsverlauf, Budgetabweichungen, or Data Explorer.

## Scope guard

- Count only `budget_transactions` with `status='confirmed'`.
- Analytics actuals are only `income`/`refund` and `expense`/`fee`.
- Exclude import candidates, ignored/superseded/duplicate candidates, transfers, credit-card payments, investment transfers, and `covered_by_migros`/covered source rows.
- Do not add OCR/camera, new import sources, new providers, portfolio analytics/backtests, news/analyst features, or runtime DB/export artifacts in Git.
- Keep exports runtime-only. In early v1, a disabled button with a clear Roadmap/runtime-only hint is safer than writing files.

## Backend pattern

Create a dedicated service/viewmodel layer rather than overloading existing overview pages:

- Data Explorer endpoint with filters: year, month/date range, type, category, merchant, account, source, tag, amount range, search.
- KPI DTOs: income sum, expense sum, net cashflow, transaction count, average transaction, largest transaction, top category, top merchant.
- Transaction rows join account/category/merchant/tags and include user labels, not raw internals.
- Merchant analysis: count, sum, average, last date, most common category, previous-month delta when a month filter exists.
- Category analysis: Top 10 + Andere, donut/bar data, monthly trend for top categories, explorer drilldown URL.
- Monthly comparison: income/expense/net, savings rate, cumulative income/expense, top categories/merchants, largest transactions, Data Explorer month URL.
- Budget deviation: over budget, under budget, categories with confirmed actuals but no budget plan.
- Fix/variable preparation can infer only from existing plan/category/notes metadata; show `noch nicht klassifiziert` rather than inventing classifications.

## Frontend pattern

- Route: `Analyse > Daten-Explorer` (`/planning/budget/analysis/data-explorer`). Add desktop and mobile/fallback navigation.
- PrimeVue/Aura components: Card KPI grid, FilterToolbar, Select/InputText/DatePicker where available, DataTable, Chart, Tag/Badge, Dialog/Drawer.
- Row click opens a detail dialog/drawer. If audited category/tag edit is not implemented, say so as an info message; never show fake action buttons.
- Category drilldowns should point to the Data Explorer with filters, not legacy effective-expense pages, once the explorer exists.
- Keep real amounts visible in the local UI, but final chat reports must not repeat real amounts.

## Tests to add

Backend:
- confirmed-only income/expense counting;
- candidates/transfers/covered rows excluded;
- filters and KPIs;
- merchant aggregate/average/top category/month delta;
- category Top 10 + Andere and trend;
- monthly savings/cumulative/detail URL;
- over/under/no-budget categories.

Frontend:
- Data Explorer filter/KPI/table render;
- row click opens detail;
- category drilldown points to Data Explorer;
- monthly cards show savings/cumulative/largest transactions;
- Budget-vs-Ist shows categories without budget.

## Verification and operational pitfalls

- Run backend compile/full pytest, frontend vitest/build, source/build secret scans, `git diff --check`, Git-safety.
- Build/test runs recreate `frontend/dist`, `frontend/node_modules`, `.pytest_cache`, and `__pycache__`; remove them before Git-safety/commit, then reinstall dependencies if a dev server must continue running.
- Stale Vite/uvicorn processes can mask new routes. If a new route shows the old Command Center/catch-all, kill the process bound to the port and restart from the current checkout.
- For Tailscale browser sanity, verify the browser-visible route and critical API endpoints; localhost-only checks are insufficient.