# Budget Categories UX Sorting Pattern

Use this when FinanceManager Budget/Cashflow work touches `Kategorien & Tags`, category dropdown ordering, or planned income ordering.

## Durable lessons from the UX fix sprint

- Keep `income` and `expense` categories as separate user surfaces: separate tables, separate sort controls, separate actions, and separate dropdown option sets.
- Do not apply Expense cleanup/migration logic to Income categories. Expense cleanup remains Preview → Confirm → Audit and may mark catch-all categories such as `Sonstiges / Administration` as review-required.
- Prefer robust Up/Down controls plus an explicit `Sortierung speichern` action over fragile DataTable drag/drop when PrimeVue row reordering is unreliable. This works on desktop and mobile and is easier to test.
- Category reorder APIs should be type-scoped, e.g. payload includes `category_type`, and backend must reject/miss categories from the wrong type instead of silently reordering mixed rows.
- Persist `sort_order` and use it consistently for all normal dropdowns. Normal selection dropdowns show active categories only; archived categories remain visible in historical detail/read views but not as new selectable values.
- For planned income (`budget_plan_items` income plans), add/maintain a `sort_order` column via append-only migration, expose a typed reorder endpoint, write audit events, and reload after save to prove order persistence.
- Before starting the runtime server after a schema migration, create a runtime DB backup outside the repo. This is a schema-safety backup, not permission to run productive category cleanup.

## UX acceptance checklist

- `Kategorien & Tags` shows `Ausgaben-Kategorien` and `Einnahmen-Kategorien` separately.
- Both category tables have visible Up/Down controls and a save-order button.
- Category add/rename/archive/delete-empty remains Preview/Confirm/Audit or audited direct action.
- No raw category IDs are shown in User Mode.
- Planned income page shows order controls and save-order button.
- Plan-value edit panel is split into clear sections: Stammdaten, Planwert, Status, Review.
- Browser sanity checks `/planning/budget/categories`, `/planning/budget/income`, `/planning/budget/expenses/review`, and `/planning/budget/expenses/actual` through the browser-visible Tailscale frontend/API.

## Tests to add/keep

- Backend: type-scoped category reorder, active-only dropdown/list ordering, income not touched by expense cleanup, income-plan `sort_order` persistence and audit.
- Frontend: separate expense/income tables, archived categories not in normal tables/dropdowns, Up/Down controls visible, save-order API called with type, planned income reorder API called, edit panel renders the four sections.
- Safety: compile, full pytest, full vitest, Vue build, source/build secret scans, Git-safety, `git diff --check`, commit, push, remote hash verification.