Belegfreigabe-Cockpit (Document Approval)

Zweck

Das Belegfreigabe-Cockpit (/document-approval) ist die Prüf- und Freigabe-Oberfläche für eingehende Rechnungen (Bestellbelege vom Typ incomingInvoice). Hier prüfen Sie pro Beleg Vollständigkeit, KI-Bewertung und Zuordnungen und geben den Beleg frei oder lehnen ihn ab.

Wichtig — Freigabe ≠ Verbuchung: Die Belegfreigabe ist ein eigener Workflow vor der eigentlichen Verbuchung. Ein freigegebener Beleg ist fachlich geprüft; gebucht wird er weiterhin über das Transaktions-Cockpit bzw. den Buchungs-Workflow.

Voraussetzungen

- Berechtigung `view:FE_PurchaseDocument` + `view:PurchaseDocument` (Cockpit öffnen, Status lesen). - Für Freigeben/Ablehnen zusätzlich `update:PurchaseDocument`. - Mindestens eine eingehende Rechnung (`documentType = incomingInvoice`). - Die Freigabe-Voraussetzungen werden unter [Belegfreigabe-Einstellungen](/settings/belegfreigabe) festgelegt.

Berechtigungen (CASL)

Frontend-Page-Guard (requiredAbility):

Action	Subject	Wirkung
view	FE_PurchaseDocument	Cockpit-Route aufrufbar
view	PurchaseDocument	Belege + Status sichtbar

API-Datenzugriff:

Action	Subject	Endpoint(s)	Wirkung
view	PurchaseDocument	GET /purchase-documents, …/:id/approval-status, /belegfreigabe/flags	Liste, Status-Aggregat, Vollständigkeits-Flags
update	PurchaseDocument	POST …/:id/approve, POST …/:id/reject	Freigeben / Ablehnen

Aufbau (3 Zonen)

Das Cockpit ist dreigeteilt:

Zone	Inhalt
Links — Auswahl	Queue der eingehenden Rechnungen mit Suche und Filtern (Freigabe-Status, Lieferant, Nummer, Datum, „ohne Konto", „KI-Warnung", Belegdokument/Zuordnung vorhanden).
Mitte — Beleg	Umschaltbar zwischen Belegvorschau (Belegbild/PDF) und Belegdaten-Tabelle.
Rechts — Detail	KI-Bewertung, Verknüpfungs-Panel (EntityLink-Vorschläge) und die Freigeben/Ablehnen-Buttons.

Status-Ampeln (Pills)

Pro Beleg liefert GET /purchase-documents/:id/approval-status ein Status-Aggregat aus mehreren Ampeln (grün = ok, gelb = prüfen, grau = fehlt). Sie decken ab:

• Belegdaten — Pflichtfelder (Betrag, Datum, Lieferant) vorhanden?
• Belegdokument — ist ein Beleg-PDF/-Bild angehängt?
• Konto / Steuer — Aufwandskonto und Steuersatz gesetzt? (Steuersatz kann am Beleg via taxRateId überschrieben werden.)
• Verbuchung — ist der Beleg bereits gebucht?
• Zahlung — Zahlungsstatus des zugehörigen offenen Postens.
• KI-Bewertung — Qualitäts-/Plausibilitäts-Score der KI.

Aus diesen Ampeln ergibt sich das canApprove-Flag — ist eine in den Einstellungen geforderte Voraussetzung nicht erfüllt, ist der Freigabe-Button gesperrt.

Schritt-für-Schritt-Anleitung

Beleg freigeben

1. Belegfreigabe (/document-approval) öffnen.
2. In der Queue links einen Beleg mit Status pending wählen (Filter „Freigabe-Status").
3. In der Mitte die Belegvorschau mit den Belegdaten abgleichen.
4. Rechts die KI-Bewertung prüfen und über das Verknüpfungs-Panel die vorgeschlagenen Zuordnungen (Auftrag, Projekt, Fahrzeug, …) bestätigen oder ergänzen.
5. Sind alle geforderten Ampeln grün, Freigeben klicken → approvalStatus = approved (mit approvedByEmployeeId + approvedAt).

Beleg ablehnen

1. Beleg wählen → Ablehnen.
2. Eine Begründung ist Pflicht — sie wird als approvalNote gespeichert (approvalStatus = rejected).

Sammel-Aktionen

Mehrere Belege markieren → Bulk-Freigabe / Bulk-Ablehnung für geprüfte Stapel.

Verknüpfungs-Vorschläge (EntityLink)

Das Cockpit schlägt über das generische EntityLink-System Zuordnungen vor — z. B. „diese Rechnung gehört zu Auftrag X / Projekt Y / Fahrzeug Z". Die Vorschläge entstehen über eine Referenz-Engine: zuerst Muster-/Regex-Suche (Auftrags-/Belegnummer, tolerante Kennzeichen-Suche), bei Fehlschlag ein KI-Fallback (inkl. Vision-Analyse des Belegbilds). Bestätigte Vorschläge werden als EntityLink gespeichert. Details zum Modell siehe Transaktionen → EntityLink.

Verknüpfungen zu anderen Modulen

• Bestellbelege — Datengrundlage; Freigabe-Felder (approvalStatus usw.) liegen am PurchaseDocument.
• Belegfreigabe-Einstellungen — legt fest, welche Voraussetzungen für die Freigabe Pflicht sind.
• Transaktions-Cockpit — die Verbuchung freigegebener Belege.
• Digitaler Rechnungseingang — liefert die eingehenden Rechnungen.

Wiederverwendbare Konzepte

• Buchhaltungskonten
• Berechtigungen verstehen (CASL)

Häufige Fehler und Lösungen

Fehler	Lösung
Freigabe-Button gesperrt	Eine in den Einstellungen geforderte Voraussetzung (Belegdokument und/oder Zuordnung) fehlt — fehlende Ampel grün machen.
Ablehnen nicht möglich	Begründung (approvalNote) ist Pflicht — Text eingeben.
Beleg fehlt in der Queue	Filter prüfen — z. B. ist er bereits approved/rejected oder gesperrt (lockedAt).

API/Schnittstellen

Methode	Endpoint	Zweck	CASL
GET	/api/purchase-documents	Queue (Filter documentType=incomingInvoice, approvalStatus, …)	view PurchaseDocument
GET	/api/purchase-documents/:id/approval-status	Status-Aggregat (Pills, canApprove)	view PurchaseDocument
GET	/api/belegfreigabe/flags	Bulk-Flags (Belegdokument + Zuordnung vorhanden) je Beleg-ID	view PurchaseDocument
POST	/api/purchase-documents/:id/approve	Beleg freigeben	update PurchaseDocument
POST	/api/purchase-documents/:id/reject	Beleg ablehnen (Begründung Pflicht)	update PurchaseDocument
GET	/api/entity-links/bulk	Verknüpfungen/Vorschläge je Beleg	—

Versionshinweise

• 2026-06-12: Initiale Veröffentlichung — Belegfreigabe-Cockpit aus dem rechnungsfluss-v2-Umbau (Freigabe ≠ Verbuchung, Status-Ampeln, EntityLink-Vorschläge, Approve/Reject). Verifiziert an purchaseDocumentApproval.service.ts, purchaseDocument.router.ts, purchaseDocument.model.ts (approvalStatus/approvalNote/approvedByEmployeeId/approvedAt), DocumentApprovalPage.tsx.