# Finance Command Center & Monthly Close v1

Use this reference when building FinanceManager dashboard/management-cockpit or monthly-close/reporting features that summarize Budget, Cashflow, Portfolio, Crypto, Fixkosten/Abos, Imports, To-dos, and reports.

## Scope boundaries

- Do not add new import sources, OCR/camera, auto-booking, watchlists, backtesting, rebalancing, analyst ratings, or AI recommendations unless explicitly authorized.
- Dashboard render must use local DB/cache DTOs only; no live provider calls on page render.
- Productive finance writes remain Preview → Confirm → Audit.
- Do not put runtime DBs, CSV/XLSX/PDF files, report exports, API keys, or real financial data into Git or frontend code.
- Chat/Telegram reports should use yes/no status, counts, hashes and links; avoid real amounts.

## Command Center DTO pattern

Build a dedicated read-model/DTO with an explicit purpose such as `finance_command_center`. Include compact sections instead of raw tables:

- KPI cards: total wealth, cash, portfolio, crypto, monthly income/expense/net cashflow/savings rate/budget consumption, open review candidates, missing price/FX count, critical alerts.
- Monthly close checklist: per task status, last run if known, open count, and target link.
- Import status per source: AKB, Raiffeisen, VISA, Migros with latest import/session status, new/processed/duplicates/errors, links to Monatsimport and Buchungen prüfen.
- Budget compact: top overruns, categories without budget, categories without prior-year value, forecast risks, links to Budgetplanung and Budget vs Ist.
- Fixed costs/subscriptions compact: active fixed costs, active subscriptions, expected payments this month, missing expected payments, changed/abnormal amounts, link to Fixkosten & Abos.
- Portfolio/Crypto compact: asset allocation, largest positions, missing/stale prices, last price update, links to Portfolio/Crypto.
- Central To-dos: priority, description, target link, status.
- Data Quality summary.

## Confirmed-only accounting rule

Monthly actual values must count only confirmed domain rows:

- Count: confirmed income, confirmed expenses, confirmed investment/portfolio/cash states as applicable.
- Exclude: candidates, ignored rows, duplicates, covered-by-source rows, internal transfers, credit-card settlements, and investment transfers as consumption/income.
- Keep imports/review rows as work items until explicit Confirm.

## Month handling hardening

Avoid month-boundary bugs:

- Validate month input strictly as `YYYY-MM` using a date parser, not string slicing alone.
- Query actuals with `date >= first_day` and `date < first_day_of_next_month`; never use synthetic `YYYY-MM-31` because SQLite normalizes invalid dates into the next month.
- Derive budget/status year from the selected month, not a hard-coded year.
- When fixed-cost/subscription dashboards accept a date context, pass a date inside the selected month so monthly-close views do not silently use today's month.
- In frontend defaults, build `YYYY-MM` from local date parts (`getFullYear()`, `getMonth()+1`), not `toISOString().slice(0, 7)`, which is UTC and can be wrong near local month boundaries.

## Runtime-only monthly report pattern

For `Reports > Monatsreport`:

- Start with Markdown or HTML; PDF is optional only if a renderer already exists.
- Write only under the configured runtime reports directory, outside the repo.
- Validate the month before using it in a filename.
- Resolve the target path and assert it stays under the runtime reports directory before writing.
- Reject repo paths and invalid months with user-facing 400-style errors from API routers.
- Include period, income, expense, net cashflow, Budget vs Ist, top categories, top merchants, fixed costs/subscriptions, open review points, portfolio/crypto summary, data quality, and disclaimer.

## Verification checklist

Minimum gate before commit/push:

- Python compile and full pytest.
- Frontend Vitest and `npm run build`.
- Source secret scan and frontend build secret scan.
- Git-safety scan blocking runtime DBs, CSV/XLSX/PDF, generated reports, secrets, `frontend/dist`, caches.
- `git diff --check`.
- Browser/Tailscale sanity for `/`, Monatsimport, Buchungen prüfen, Budgetplanung, Budget vs Ist, Fixkosten & Abos, Reports.
- JS console empty.
- Independent reviewer pass; if it finds blockers and you fix them, rerun a focused re-review on the exact blockers plus new-regression search.
- Commit, push, and verify local/remote hash equality.