dashboard/.claude/plans/2026-03-28-buchhaltung-design.md

Buchhaltung System — Design

Date: 2026-03-28 Status: Approved

---

Overview

A budget and transaction tracking system for the Feuerwehr. Tracks money flows against budget pots and real bank accounts, scoped by fiscal year. Integrates with the existing Bestellungen system and permission matrix.

---

Full Cycle

Budget Plan → Fiscal Year → Freigaben → Bestellungen → Pending Transactions → Booked Transactions

---

1. Data Model

buchhaltung_konto_typen

Dynamic list of bank account types (Girokonto, Tagesgeldkonto, Handkasse, PayPal, …). Managed in settings by users with manage_settings.

Column	Type	Notes
id	serial PK
name	varchar
beschreibung	text	nullable
created_at	timestamptz

---

buchhaltung_bankkonten

Real bank accounts (where money physically is).

Column	Type	Notes
id	serial PK
name	varchar
typ_id	FK konto_typen
iban	varchar	nullable
opening_balance	decimal(12,2)	starting balance when first added
aktiv	bool	default true
created_at	timestamptz

Balance = opening_balance + SUM(booked transactions).

---

buchhaltung_haushaltsjahre

Fiscal years. Bank accounts are not year-scoped; budget accounts are.

Column	Type	Notes
id	serial PK
jahr	int	unique (e.g. 2026)
start_datum	date
end_datum	date
abgeschlossen	bool	default false; manually closed by manage_settings user

Closing a year locks all its transactions (no edits, no new bookings).

---

buchhaltung_konten

Budget accounts / pots. Scoped per fiscal year.

Column	Type	Notes
id	serial PK
haushaltsjahr_id	FK haushaltsjahre
name	varchar
beschreibung	text	nullable
budget	decimal(12,2)
alert_threshold	int	% (0-100); falls back to global setting if null
aktiv	bool	default true
created_at	timestamptz

---

buchhaltung_transaktionen

Core transaction table.

Column	Type	Notes
id	serial PK	internal DB key
haushaltsjahr_id	FK haushaltsjahre
laufende_nummer	int	sequential per fiscal year; display as 2026/0001
datum	date
beschreibung	text
betrag	decimal(12,2)	nullable for variable recurring transactions
typ	enum	einnahme, ausgabe, transfer
konto_id	FK konten	nullable (null for transfers)
bankkonto_id	FK bankkonten	source bank account
transfer_ziel_bankkonto_id	FK bankkonten	nullable; only for typ=transfer
bestellung_id	FK bestellungen	nullable; set when auto-created from order
split_gruppe_id	uuid	nullable; groups split transactions from same Bestellung
gebucht	bool	false = pending, true = booked
erstellt_von	FK users
gebucht_von	FK users	nullable
gebucht_am	timestamptz	nullable
created_at	timestamptz

Display ID: ${jahr}/${laufende_nummer.toString().padStart(4, '0')} e.g. 2026/0001. laufende_nummer is unique per haushaltsjahr_id, incremented per new transaction.

---

buchhaltung_belege

Receipt/invoice attachments per transaction.

Column	Type	Notes
id	serial PK
transaktion_id	FK transaktionen
dateiname	varchar
pfad	varchar	disk path
mime_type	varchar
erstellt_von	FK users
created_at	timestamptz

Uses same multer disk storage pattern as Bestellungen (uploads/buchhaltung/).

---

buchhaltung_wiederkehrend

Recurring transaction templates.

Column	Type	Notes
id	serial PK
beschreibung	varchar
betrag	decimal(12,2)	nullable (e.g. variable energy bills)
typ	enum	einnahme, ausgabe
konto_id	FK konten	nullable
bankkonto_id	FK bankkonten	nullable
frequenz	enum	monatlich, vierteljaehrlich, jaehrlich
naechste_faelligkeit	date	advanced by job after each creation
aktiv	bool
erstellt_von	FK users

Job runs daily → creates pending transaction → advances naechste_faelligkeit. Betrag null → pending transaction has null betrag → Kassenwart fills it in before booking.

---

buchhaltung_freigaben

Budget delegation — authorizes a user to spend against a budget account.

Column	Type	Notes
id	serial PK
konto_id	FK konten	budget account
user_id	FK users	authorized user
beschreibung	text	what this covers
betrag_limit	decimal(12,2)	nullable; max spending allowed
planposition_id	FK planpositionen	nullable; source plan item
aktiv	bool
erstellt_von	FK users
created_at	timestamptz

Amount is editable after creation (plan may change mid-year). Users with a Freigabe can create Bestellungen against that account even without buchhaltung:create.

---

buchhaltung_audit

Append-only audit log.

Column	Type	Notes
id	serial PK
transaktion_id	FK transaktionen
aktion	enum	erstellt, gebucht, bearbeitet, geloescht
benutzer_id	FK users
details	jsonb	before/after snapshot
created_at	timestamptz

---

buchhaltung_einstellungen

Key/value store for global settings.

Key	Default	Notes
default_alert_threshold	80	% budget used before notification
pdf_footer	''	reuses PDF settings pattern

---

Budget Planning Tables

buchhaltung_planung

A plan for a future fiscal year.

Column	Type	Notes
id	serial PK
ziel_jahr	int	the year being planned
name	varchar	e.g. "Haushaltsplan 2027"
status	enum	entwurf, genehmigt
erstellt_von	FK users
created_at	timestamptz

Starts pre-populated from current open budget accounts. New accounts can be added. Approving locks the plan. Only approved plans can be used for fiscal year rollover.

buchhaltung_plankonten

Planned budget pots within a plan.

Column	Type	Notes
id	serial PK
planung_id	FK planung
konto_referenz_id	FK konten	nullable; links to existing account if carried over
name	varchar
beschreibung	text	nullable
sort_order	int

buchhaltung_planpositionen

Line items within a planned pot. Sum = pot total.

Column	Type	Notes
id	serial PK
plankonto_id	FK plankonten
beschreibung	text	what it's for
betrag	decimal(12,2)
sort_order	int

From approved plan items → manual Freigaben creation flow (UI, not automatic). Amount editable on Freigabe creation and after.

---

2. Permissions

New buchhaltung feature group in the existing permission matrix:

Permission	Description
buchhaltung:view	See transactions, accounts, bank accounts
buchhaltung:create	Add transactions manually
buchhaltung:edit	Edit unbooked transactions
buchhaltung:delete	Delete unbooked transactions
buchhaltung:manage_accounts	Create/edit/archive budget accounts, bank accounts, Freigaben
buchhaltung:manage_settings	Global settings, account types, fiscal year management, recurring templates
buchhaltung:export	PDF and CSV export
buchhaltung:widget	See the dashboard widget

manage_settings ≠ dashboard_admin — a dedicated Kassenwart can have this without being a global admin.

---

3. Backend Architecture

Follows the existing project pattern (service → controller → routes → app.ts).

Routes mounted at /api/buchhaltung/:

Route	Description
bankkonten	CRUD bank accounts
konten	CRUD budget accounts (scoped by fiscal year)
transaktionen	list, create, book, edit, delete
transfers	create bank-to-bank transfers
freigaben	CRUD budget delegations
wiederkehrend	CRUD recurring templates
haushaltsjahre	create new year, close year, list
planung	CRUD budget plans and plan items
einstellungen	key/value settings
export/pdf	annual report PDF
export/csv	transaction CSV export
audit/:transaktionId	audit trail for one transaction

Jobs:

• buchhaltung-recurring.job.ts — runs daily; creates pending transactions from due recurring templates; advances naechste_faelligkeit
• Budget alert fires inline after each booking: recalculates account total → if crosses threshold → notificationService.createNotification() for manage_accounts users (deduped by DB constraint)

---

4. Bestellungen Integration

Costs on positions

• bestellpositionen gets an einzelpreis / gesamtpreis field (if not already present)
• Status change to vollstaendig/abgeschlossen is blocked until all positions have costs entered
• Attempting the status change without costs → showWarning snackbar: "Bestellung kann erst abgeschlossen werden, wenn Kosten für alle Positionen eingetragen wurden."
• Backend enforces the same rule (400 response)
• The order creator/manager enters costs — not the Kassenwart

Pending transaction creation

When a Bestellung reaches abgeschlossen:

1. buchhaltungService.createPendingFromBestellung(bestellung) is called
2. Creates a pending ausgabe transaction: betrag = sum of position costs, beschreibung = order title, bestellung_id = FK
3. Notifies users with buchhaltung:create or buchhaltung:manage_accounts

Split booking

When booking a pending transaction from a Bestellung, the Kassenwart can split it into N parts:

• Each part: betrag, budget konto, bankkonto, Beleg (receipt)
• Parts sum to ≤ total (partial booking allowed; remainder stays pending)
• Each part becomes its own booked transaction with its own <year>/<id>
• All parts share the same bestellung_id and split_gruppe_id (visually grouped in audit trail)

---

5. Frontend Pages

Navigation

New "Buchhaltung" sidebar group:

• Übersicht
• Transaktionen
• Bankkonten
• Konten & Haushaltsjahre
• Freigaben (only with manage_accounts)
• Haushaltsplan (only with manage_settings)

Pages

Buchhaltung.tsx — overview. Year selector at top. Budget account cards: name, budget, spent, remaining, % bar, alert indicator. Pending transactions count with link.

Transaktionen.tsx — full list. Filter by year / account / bank account / typ. Columns: ID (2026/0001), Datum, Beschreibung, Konto, Bankkonto, Betrag, Status. Click → booking dialog.

BankkontoDetail.tsx — statement view. Running balance column per row. Date range filter. CSV/PDF export.

BuchhaltungKonten.tsx — tabs: Konten (current year) | Bankkonten | Haushaltsjahre. Year-end actions: "Jahr abschließen" (manual, locks year) + "Neues Haushaltsjahr" (from approved plan or copy previous).

BuchhaltungEinstellungen.tsx (or AdminDashboard tab) — Kontentypen list, default alert threshold, recurring templates.

Haushaltsplan.tsx — plan management. Pre-populated from current accounts. Add/edit/remove plankonten and planpositionen. Approve plan. From approved items → create Freigaben (manual flow, amounts editable).

Booking Dialog

Used from pending transaction list:

• Pre-filled from Bestellung (amount, description, reference)
• "Split" button adds a row
• Each row: betrag, budget konto, bankkonto, Beleg upload
• Sum validation
• Confirm → books all rows at once

Widget

BuchhaltungWidget.tsx — compact card in Status group. Shows pending transaction count. Tap → filtered pending list. Only shown with buchhaltung:widget.

---

6. PDF Export

Uses existing addPdfHeader / addPdfFooter from frontend/src/utils/pdfExport (same red header, logo, org name as Bestellungen and Kalender).

Content of annual report TBD (separate discussion).

---

7. Fiscal Year Rollover

1. Close current year — manual action by manage_settings user → sets abgeschlossen = true → all transactions locked
2. Create new year — choose source:
   • From approved plan — plankonten become new konten, plankonto totals (sum of planpositionen) become budgets
   • Copy previous year — all active konten copied with same budget amounts (editable before confirming)
3. Bank accounts carry over automatically (not year-scoped)
4. Old year remains readable/exportable forever

---

8. Future: Sub-Budget Flow from Plan Items

(Planned feature — not in initial implementation)

From an approved plan's items, a manual UI flow to create Freigaben:

• User selects plan items
• Sets/adjusts amount per Freigabe (editable at creation and later — plan may change mid-year)
• Assigns a user
• Creates the Freigabe linked to planposition_id

This closes the full loop: Plan item → Freigabe → Bestellung → Pending transaction → Booked transaction.