# Budget Planning Usability & Baseline Entry v2

Use when improving FinanceManager Budget Planning after the baseline/forecast model exists and the user asks for alltagstaugliche entry, validation, audit, or Excel-template preparation. This is a UX/productivity sprint pattern, not an import/fixkosten sprint.

## Scope boundaries

- Do **not** add new import sources, Fixkosten/Subscriptions, OCR/camera, tax forecasts, portfolio analytics, watchlists, or AI budget recommendations.
- Excel-template work is allowed only as prepared/coming-soon or controlled preview/mapping; no automatic productive takeover.
- Budget and prior-year values are plan/reference values, not real transactions.
- Actuals must still come only from confirmed `budget_transactions`; candidates, transfers and covered rows stay excluded.
- No real amounts, runtime DBs, spreadsheets, credentials, or build artefacts in Git or chat summaries.

## Recommended implementation pattern

1. Start from a clean accepted branch and create a focused branch such as `feat/budget-planning-usability-v2`.
2. Write RED tests before implementation for:
   - readable per-category audit timeline after budget and prior-year changes;
   - batch preview/confirm with multiple category edits;
   - invalid/negative values blocked;
   - prior-year annual value distribution over 12 months;
   - monthly prior-year sum and deviation;
   - data-care tiles/filtering;
   - plausibility checks and visible forecast methodology;
   - integration that Budgetstatus and Budget-vs-Ist reflect changed plan/reference values;
   - candidates/transfers still excluded.
3. Backend additions should be small service functions around existing planning tables:
   - `get_budget_planning_audit_timeline` returning user-readable entries, not raw JSON;
   - `preview_budget_planning_batch` / `confirm_budget_planning_batch` with per-category audit plus optional batch summary audit;
   - `preview_budget_planning_excel_template` as prepared/no-mutation unless a controlled seed preview already exists;
   - plausibility checks in the planning matrix DTO.
4. Audit timeline DTO should expose: timestamp, action/action label, changed field label, old value, new value, source, note, created_by/user-system, and only hide `audit_id` under a technical/detail object.
5. For annual prior-year distribution, avoid rounding drift: distribute rounded monthly values and put the remainder into December so the 12-month sum equals the annual value exactly.
6. Frontend Budget Planning page should support:
   - inline edit for monthly budget, annual budget, cadence;
   - dirty-row collection and `Änderungen prüfen` batch preview;
   - final batch confirm only from preview payload;
   - detail tabs for Budget 2026, Vorjahr 2025, Ist 2026, Verlauf/Audit;
   - prior-year annual value, Jan–Dec month inputs, live sum/deviation, distribute and clear buttons;
   - data-care filter tiles for no budget, no prior year, actuals without budget, budget without actuals, previous year without budget;
   - forecast help text explaining `linear_forecast` and `budget_adjusted_forecast`.
7. Charts can stay native SVG if no library is needed. Use consistent semantics: Ist 2026 blue, Budget dark line, Ist 2025 grey, exceedance orange/red, visible legend.

## Plausibility thresholds

- Budget year more than 20% above or below prior year => info/warning.
- Actual YTD already above budget year => warning.
- Forecast above 115% of budget => critical.
- Actuals without budget => warning.
- Budget without actuals => neutral info.
- Missing prior-year values => info.

## Verification gate

Run and report:

- Python compile.
- Full backend pytest.
- Full frontend Vitest.
- `npm run build`.
- Changed-file/source secret scan.
- Frontend build secret scan.
- Git-safety for runtime DBs/secrets/build artefacts.
- `git diff --check`.
- Restart backend/frontend with browser-visible Tailscale API base.
- Browser sanity for `/planning/budget/planning`, `/planning/budget/status`, `/planning/budget/analysis/budget-vs-actual`, `/planning/budget/analysis/data-explorer`, `/planning/budget/categories`.
- Commit, push, and verify remote hash with temporary authenticated askpass if needed.

## Pitfalls

- Do not call an Excel button an import if it only prepares a future flow; label it Prepared/Coming soon or Preview, and make `productive_mutation=false` explicit.
- Do not show audit as raw JSON; users need field labels and old/new values.
- Do not let batch tooling imply permission to mass-confirm real runtime data. Preview/Confirm/Audit remains the write boundary.
- Do not let `JARVIS_FINANCE_DB_PATH` leak into unit tests; unset it for pytest unless a fixed runtime DB is explicitly intended.
- Clean `.pytest_cache`, `__pycache__`, and build artefacts before Git-safety/staging.