# Budget UX v2 – Transaktionsliste, Navigation & Analyse-Hub

Use this reference for FinanceManager Budget/Cashflow UX sprints that adapt ideas from external bookkeeping tools without copying code/assets or expanding import scope.

## Scope guard

- Vue remains the User Dashboard; Streamlit remains Admin/Fallback.
- Do not add new import sources, large new data models, Heatmap/Sunburst/Explorer, calendar views, or Import Wizard expansions in this sprint class.
- Do not copy foreign code/assets. External app analyses are design references only.
- No real data, Runtime DBs, CSV/XLS/XLSX, provider keys, or real amounts in Git or chat.
- Preview → Confirm → Audit remains the write boundary. Batch tooling can be implemented/tested on synthetic data, but real runtime mass-confirm requires explicit current-turn user approval.

## Recommended workflow

1. **Commit accepted reference analysis with the sprint**
   - If a prior external-reference analysis document is accepted and untracked, include it in the feature commit rather than leaving it as local-only documentation.
   - Keep any follow-up Merchant/UX notes under `docs/budget/` as non-secret Markdown.

2. **RED first**
   - Add targeted backend unit tests for confirmed-only transaction lists, category shares, monthly comparison, Budget-vs-Ist excluding candidates, category bucket/merge-preview behavior.
   - Add frontend Vitest coverage for navigation groups, no duplicate Import Review/Kategoriezuordnung pages, date grouping, detail drawer, technical-field hiding, category/month analysis pages.
   - Run the focused tests and verify they fail for missing services/pages before implementation.

3. **Navigation shape**
   - Main groups should be: `Budget`, `Transaktionen`, `Analyse`, `Setup`.
   - Central review page is **Buchungen prüfen**. `Import Review` and `Kategoriezuordnung` should redirect to it or disappear from User Mode.
   - Confirmed rows belong under `Effektive Ausgaben` / `Effektive Einnahmen`, not in review/debug views.

4. **Effective transaction lists**
   - Query only `budget_transactions.status='confirmed'` and active-year defaults, normally 2026.
   - Expense list: only real confirmed expenses/fees; exclude candidates, UAT/test rows, `covered_by_migros`, and line items as main rows.
   - Income list: confirmed income/refund rows analogous to expenses.
   - Provide date grouping, previous/current/next month controls, date range, search, filters for account/category/tag/source/merchant, top summaries, and row-click detail drawer.
   - Prefer display merchant field order: `merchant_display_name`, then `payee`, then `description`; raw description remains detail/subtext, not primary everyday label.
   - Category/tag changes must call audited update endpoints and require a change note/default audit reason.

5. **Buchungen prüfen UX**
   - Make it compact and list-oriented, not a technical import debugger.
   - Tabs: `Alle offenen`, `Auto-zugeordnet`, `Review nötig`, `Migros`, `Galaxus/Digitec`, `Abos`, `Unklar`, `Ignoriert`.
   - Group candidates by date and show date, source, merchant/description, amount, category suggestion, confidence, status, actions.
   - Filter technical fields from User Mode/details: `rule_id`, `raw_fingerprint`, `dedupe_key`, `internal_status`, source hashes, etc.

6. **Analysis Hub v1**
   - `Analyse > Kategorieanalyse`: period/year, income/expense toggle, simple donut/pie/progress visualization, legend/table with amount/share/count, category drilldown link to transaction list.
   - `Analyse > Monatsvergleich`: year default 2026, income/expense/net per month, click month for top categories/top merchants and transaction-list link.
   - `Analyse > Budget vs Ist`: keep separate from review; use confirmed transactions and budget plans/status rows, not candidates.

7. **Category setup**
   - Visually show two buckets: `Einnahmen` and `Ausgaben`.
   - Canonical leaves for income: Lohn Marcel, Lohn Melanie, Gratifikation, Sonstige Einnahmen, Rückerstattungen.
   - Canonical leaves for expense: Essen & Haushalt, Wohnen, Versicherungen, Gesundheit / Medizin, Mobilität / Auto / Transport, Kinder / Familie, Freizeit / Abos / Ausflüge, Hausrat / Möbel & Garten, Shopping / Kleidung & Elektronik, Haustiere, Steuern / Behörden, Sonstiges / Administration, Review nötig.
   - Detect duplicates and show Merge Preview only; never silently merge.

8. **Merchant entity**
   - Do not build a full Merchant Engine unless explicitly authorized.
   - It is useful to document the future shape: display name, aliases, default category, rule suggestions.
   - In this sprint class only improve merchant display in lists.

## Verification gate

Run and report:

- `python -m compileall src tests`
- `pytest -q`
- `npm test -- --run` from `frontend/`
- `npm run build` from `frontend/`
- source/docs secret scan excluding tests/fixtures when false positives are expected
- frontend build secret scan
- `pytest tests/unit/test_git_safety.py -q`
- `git diff --check`
- commit and push
- remote-hash equality, using temporary authenticated URL if normal HTTPS origin cannot prompt
- restart backend/frontend from the committed checkout and verify both local and Tailscale frontend/API routes

## Deployment pitfall

For iPhone/Tailscale access, the Vite client must use a browser-visible API base, commonly `VITE_API_BASE_URL=http://<tailscale-ip>:5173`, so `/api` calls go through the Vite proxy to local FastAPI. If set to `http://127.0.0.1:8000`, the iPhone browser will call its own localhost and fail. Verify `http://<tailscale-ip>:5173/api/...` returns 200 after restart.