# Budget Phase 1.7 — UX-/Workflow-Refactor für Review, Ausgaben und Kategorien

Use this reference when the user complains that the Budget dashboard is confusing, import review and category assignment are blurred, or visible actions are unreliable/fake. This is a UX/workflow stabilization class, not an import-source or analytics expansion.

## Scope guard

- Do not add new import sources.
- Do not add large analytics features.
- Do not commit runtime DBs, real CSV/XLS/XLSX/PDF/DOCX, reports, or build artifacts.
- Do not print real financial values in chat; local dashboard display is allowed.
- Do not create silent mutations. Writes must cross Preview/Confirm or explicit user action and write Audit.
- Import candidates remain candidates until Confirm creates a budget transaction.
- Confirmed expenses are real `budget_transactions` and must live in a separate effective-expenses workflow.
- Category changes, candidate status changes, transaction edits, and merges must be audit-visible.
- Undo is via reopen/reverse/status transition/audit trail, not destructive hidden overwrite.

## Recommended workflow shape

1. Re-check repo state before editing: branch, HEAD, `git status --short`, and changed files.
2. Inventory existing Budget API/services/pages before patching.
3. Separate the navigation into clear groups:
   - Budget: overview, status, monthly/yearly/plans.
   - Ausgaben: effective expenses, import review, manual expense, category assignment.
   - Einkommen: actual/planned/forecast.
   - Setup: categories, tags, accounts, seed review.
   - Später: rules, fixed costs, duplicates, provider/detail pages not ready yet.
4. Add a short “Wofür ist diese Seite?” explanation to each work page.
5. Replace dominant read-only badges on work pages with explicit Review-Modus/Arbeitsmodus wording.
6. Make visible actions real. If a button cannot work now, hide it or mark it disabled with a reason.

## Import Review pattern

The Import Review page is only for `budget_transaction_candidates`. It should show at least:

- Datum
- Quelle / source file label / row or range
- Händler / Beschreibung
- Betrag and Währung in the local UI
- category suggestion as an editable dropdown
- confidence
- rule/classification/review reason
- status
- actions

Expected actions:

- Confirm creates a real `budget_transaction` and audits the candidate.
- Ignore marks candidate ignored and audits.
- Reopen moves ignored/review candidates back to a reviewable state and audits.
- Category dropdown updates `proposed_category_id` and audits.
- Bulk category assignment is allowed for selected candidates and audits.
- Safe auto candidates need a Preview endpoint and a later explicit Confirm; no blind batch booking.
- Transfer and split flows may be prepared/marked, but must not silently book expense/income.

## Effective expenses pattern

Confirmed expenses need a separate page over `budget_transactions`, not a mixed import-review list. Recommended controls:

- Filter by month, account, category, merchant/source/search/tag/status.
- Table shows confirmed transaction rows with local amounts.
- Row click opens a detail drawer.
- Category/description/tag changes call audited update endpoints.
- Amount overwrites should be rejected; use adjustment/reversal flows instead.

## Category assignment pattern

Create a dedicated page for categorizing:

- review-required/open candidates (updates candidate proposal only), and
- confirmed uncategorized transactions (updates transaction category).

Support bulk assignment and quick category creation, with audit. Keep it distinct from both Import Review and Category Tree management.

## Category tree + merge pattern

The Categories page should manage the tree:

- Create category/subcategory via Preview → Confirm.
- Rename/change parent/type through an audited update endpoint.
- Delete only truly empty categories.
- Archive non-empty categories.
- Show transaction count / active budget plan count / active status.
- Category merge must be Preview → Confirm: move transactions, budget plans and children to target, archive sources, and audit the merge.

## Backend service patterns

- Keep `list_budget_transactions` filters table-qualified when joins exist (`t.category_id`, `t.status`, etc.).
- Support `category_id='__uncategorized'` as an explicit filter for confirmed but uncategorized transactions.
- Use `record_audit_event` for category updates/deletes/archives/merges, candidate status/proposal changes, and transaction edits.
- Idempotent category creation can return the existing category, but still audit as idempotent confirm.

## Tests and verification

Add focused unit tests for:

- Import Review: bulk category, ignore, reopen, safe preview, confirm creates transaction only at confirm boundary.
- Effective expenses: filters, category update with audit, amount overwrite rejected.
- Category tree: delete empty, archive/merge non-empty, moved transactions/plans after merge.
- Frontend: navigation copy, work-mode wording, table/drawer/category controls.

Run and report:

- `unset JARVIS_FINANCE_DB_PATH`
- `python -m compileall src tests`
- `pytest -q`
- from `frontend/`: `npm test -- --run`
- from `frontend/`: `npm run build`
- `git diff --check`
- source and build-artifact secret scans
- Git-safety scan for runtime/build/data artifacts
- cleanup: `frontend/dist`, `.pytest_cache`, `__pycache__`, `.vite` before final Git-safety/commit
- commit, push, and verify local `HEAD` equals remote branch hash via authenticated `git ls-remote` when needed.

## Pitfalls learned

- Do not let tests depend on wall-clock freshness with fixed timestamps. If a fixture timestamp crosses the stale threshold, update the fixture or make the test deterministic.
- Vue unit tests that mount route-aware components without router injection may warn; either provide a router or make route reads null-safe.
- After `npm run build`, scan `frontend/dist` before deleting it; then delete it before Git-safety and commit.
- Do not keep old test assertions for removed/relocated workflows such as tags on the Categories page when Phase 1.7 deliberately separates setup concerns.