# Budget Workflow Clarification & Help UX Sprint

Use this reference when the FinanceManager Budget/Cashflow work is about navigation reliability, transfer semantics, household cashflow modelling, money-flow visibility, or page-level help UX — especially before starting Fixkosten/Subscriptions.

## Scope guard

- Do **not** build Fixkosten/Subscriptions, new import sources, OCR/camera, Data Explorer v2, Reports v1, portfolio backtests, watchlists, or tax logic in this class of sprint.
- Keep Preview → Confirm → Audit as the write boundary.
- Do not silently mutate runtime rows. If a real account such as `True Wealth Cash` is missing, prepare the UI/model and report the absence; only create it after explicit Preview → Confirm → Audit approval.
- Never commit runtime DBs, real CSV/XLS/PDF files, secrets, or frontend API keys.
- Do not report real amounts in chat/summary, even if browser sanity sees them.

## Navigation regression pattern

For `/planning/budget/expenses/actual` or similar Budget work pages:

1. Verify the route exists in the Vue router and lazy import resolves.
2. Verify Desktop Sidebar link, Mobile Bottom link, and Fullscreen/Fallback mobile menu native anchor.
3. Verify direct browser route returns 200.
4. Verify API endpoint returns 200.
5. Browser sanity must include JS console check.
6. The page must render confirmed data or a clear Empty State, never fail silently.

Tests should include the route/menu links and Empty State; for fallback menus remember the link may only exist after opening the menu.

## Transfer semantics

Budget household transfers are not income and not expenses:

- AKB ↔ Raiffeisen / Marcel ↔ Melanie: internal transfer; household wealth does not increase/decrease.
- Bank → VISA: credit-card settlement; not an expense if VISA/Migros detail rows are imported, to prevent double counting.
- AKB/Raiffeisen → True Wealth: investment/depot transfer; not consumer expense and not income. Prefer `investment_transfer` or transfer subtype with target account `True Wealth Cash`.

Useful implementation shape:

- Keep confirmed transfers in a separate transfer table/API such as `GET /api/budget/transfers`.
- Add `transfer_type` values such as `internal_transfer`, `credit_card_payment`, `investment_transfer`, `other_transfer`.
- Keep Budgetstatus, income, expense analytics and Data Explorer actuals based on confirmed `budget_transactions` excluding transfer rows/candidates.
- True Wealth Cash is an investment-cash staging account for later ETF buys/rebalancing; do not infer ETF purchases during this sprint.

Regression tests should prove:

- AKB ↔ Raiffeisen does not change income/expense totals.
- Credit-card settlement does not appear as expense.
- True Wealth transfer does not appear as expense/income and suggests `True Wealth Cash`.
- Transfer Confirm writes audit.

## Household 2026 model

Model Budget reporting as a shared household view, not as one physical account:

- Default Budget views aggregate `Haushalt 2026`.
- Physical/reported sources stay visible and filterable: Raiffeisen, AKB, VISA, Migros, Manuell, True Wealth Cash, later more.
- Income remains visible by person/source (Lohn Marcel, Lohn Melanie, Bonus, 13. Monatslohn, solar refunds, other income) but aggregates in household summaries.

## Money-flow visibility

User-facing lists should answer: where did money come from, where did it go, which source/account produced it, and who was the counterparty?

Minimum display:

- Expenses: Datum, Von Konto/Quelle, Händler/Empfänger, Kategorie, Betrag, Währung, Status, Herkunft.
- Income/Geld Eingang: Datum, Eingang auf Konto, Von/Absender/Arbeitgeber, Einkommenskategorie, Betrag, Währung, Status, Herkunft.
- Transfers: Datum, Von Konto, Zu Konto, Gegenpartei/Beschreibung, Betrag, Währung, Typ, Status, Audit/Verlauf.

## Transfer review UX

In **Buchungen prüfen**, transfer candidates should explain:

- why recognized as transfer/settlement/investment transfer,
- from which account/source,
- suggested target account,
- whether a counterbooking was found,
- that it does not count in Budget income/expenses,
- available audited actions: confirm as transfer, treat as expense, treat as income, ignore, details.

For True Wealth rows, show `Investment Transfer` and suggested target `True Wealth Cash`.

## Help UX pattern

Add page-level help as a shared shell/component, not duplicated prose in every page:

- Central data file, e.g. `frontend/src/help/pageHelp.ts` with `pageKey`, `title`, `purpose`, `visibleData`, `actions`, `exclusions`, `warnings`.
- Shared component, e.g. `PageHelpButton` / dialog/drawer in the app shell.
- Every user-facing page should answer:
  1. Wofür ist diese Seite?
  2. Was sehe ich hier?
  3. Was kann ich hier tun?
  4. Was zählt hinein?
  5. Was zählt nicht hinein?
  6. Worauf muss ich achten?

Critical help text examples:

- Buchungen prüfen: candidates become productive only after Confirm; transfers are excluded from income/expenses; covered-by-Migros prevents double counting; do not blindly confirm unclear rows.
- Effektive Ausgaben: confirmed-only expenses; candidates excluded; transfers/credit-card settlement/investment transfers excluded; category changes affect Budgetstatus.

## Verification checklist

Run and report:

- Python compile.
- Full `pytest`.
- Frontend tests from `frontend/`.
- `npm run build` from `frontend/`.
- Source secret scan.
- Frontend build secret scan before deleting `dist`.
- Git-safety after deleting `dist`, `.pytest_cache`, `__pycache__`, `.vite` as appropriate.
- `git diff --check`.
- Local and Tailscale route sanity.
- Browser sanity with JS console check.
- Commit, push, remote-hash equality.

Do not claim physical iPhone verification unless a real mobile/Safari/device-emulation test actually ran.