feat(erp): plan payable exports and reconcile bookings

2026-08-23 17:53:23 +02:00
parent 2e327373ce
commit a12e096366
10 changed files with 1256 additions and 0 deletions
@@ -0,0 +1,54 @@
+# Payable export and booking reconciliation
+
+ERP is an integration boundary, not GovOPlaN's accounting system. Procurement,
+Payments, or Ledger remains authoritative for an approved payable. A configured
+external ERP remains authoritative for its booking identifier and booking
+status. The connector joins those facts only through explicit correlation and
+evidence.
+
+## Export plan
+
+`PayableExportInput` contains an immutable payable revision, stable invoice and
+creditor references, an invoice-document SHA-256, currency, and an amount in
+integer minor units. Floating-point amounts are rejected. Optional budget and
+cost-centre references and up to 100 unique evidence references are bound to the
+same projection.
+
+`ErpPayableProfile` names the target provider and company code, exact payable
+schema and version, mapping revision, non-secret connection reference, and a
+complete raw-to-normalized booking-status mapping. No provider or schema is
+selected by the module.
+
+The plan serializes this input as canonical JSON and binds profile, input,
+payload, payable revision, and idempotency identity with SHA-256. It is always
+marked `dispatch_allowed=False`. A later product adapter must prove its API,
+credentials, idempotency, outcome-unknown lookup, and recovery behavior before
+it can execute the plan.
+
+## Reconciliation
+
+An observation must identify the tenant, payable, provider, exact export-plan
+digest, external booking and revision, observation time, amount, currency, and
+evidence digest. The decision is deterministic:
+
+- `received` and `validated` wait for a terminal outcome;
+- `booked` records the correlated booking;
+- `rejected` and `cancelled` record a rejection;
+- `reversed` records a separate reversal;
+- unknown statuses and binding mismatches are quarantined.
+
+Missing responses and timeouts never mean that the export failed. Operators
+must query the target by the stable plan correlation before retrying.
+
+## Datenschutz und Betrieb
+
+ERP speichert in dieser Ausbaustufe weder Rechnungen noch Verbindlichkeiten,
+Pläne, Anbieterantworten oder Zugangsdaten. Das fachlich verantwortliche Modul
+bleibt für Aufbewahrung, Auskunft, Berichtigung und Löschung zuständig. Profile
+enthalten nur eine Verbindungsreferenz; Geheimnisse dürfen weder im Plan noch im
+Nachweis erscheinen.
+
+Vor einer echten Anbindung sind Produkt und Version, Schema und Transport,
+Buchungskreis, Anmeldedaten, Statusabbildung, Korrelationssuche, Stornoverhalten
+und eine Testumgebung festzulegen und gegen Erfolg, Ablehnung, Zeitüberschreitung,
+Doppelzustellung und Wiederherstellung zu prüfen.