Feature: Trustee

Ueberblick

Das Trustee-Feature digitalisiert Spesenbelege und synchronisiert sie in ein externes Buchhaltungssystem (ABACUS, Bexio, Banana, ...). Es kombiniert eine Workflow-Method (trustee mit fuenf typisierten Actions) mit einer Feature-Domain (features/trustee/ -- Datenmodelle, Interface, Routes, AccountingBridge).

Datenfluss:

SharePoint / Upload
        |
        v
trustee.extractFromFiles    (AI extrahiert Belegtyp + Felder -> ActionDocument-Liste)
        |
        v
trustee.processDocuments    (legt TrusteeDocument + TrusteePosition an, verlinkt Bankkonten)
        |
        v
trustee.syncToAccounting    (pusht Positions via AccountingBridge ins Zielsystem)

Alle drei Actions konsumieren featureInstanceId als typisierten FeatureInstanceRef-Envelope (Typed Action Architecture). Sub-Action trustee.refreshAccountingData und Read-only trustee.queryData erweitern den Funktionsumfang fuer Sync-Refresh und AI-Tool-Zugriffe.

Module

Modul	Pfad	Verantwortung
Method (Workflow)	`gateway/modules/workflows/methods/methodTrustee/`	`MethodTrustee` registriert die fuenf Actions; jede Action liegt in `actions/<name>.py` mit eigener typisierter Eingabe + `ActionResult`-Output.
Feature-Domain	`gateway/modules/features/trustee/`	Datenmodell (`datamodelTrustee.py`), Interface (`interfaceTrustee.py`), Route-Module (`routeFeatureTrustee*.py`), `AccountingBridge` (`accountingBridge.py`).
Editor-Adapter	`gateway/modules/features/graphicalEditor/nodeDefinitions/trustee.py`	Bindet die fuenf Actions als Editor-Nodes (`trustee.extractFromFiles`, ...) -- Ports + Pflicht-Felder werden via `registerNodeWithMethod` aus den Action-Signaturen abgeleitet.
Frontend	`frontend_nyla/src/components/Trustee/` + `TrusteeDataTablesView`	UI fuer Document/Position-Verwaltung, Daten-Tabellen, Connector-Konfiguration.

Actions (typisierte Inputs + Outputs)

Action	Eingabe (Pflicht)	Output	Zweck
`trustee.extractFromFiles`	`featureInstanceId` (FeatureInstanceRef), entweder `fileIds: List[str]` oder `sourceFolder`	`DocumentList` (`documents: List[ActionDocument]`)	AI extrahiert Belegtyp + Strukturdaten aus PDFs / JPGs (SharePoint oder Upload).
`trustee.processDocuments`	`featureInstanceId`, `documentList: DocumentList`	`ActionResult` (mit `documents: List[ActionDocument]`)	Legt `TrusteeDocument`-Records + zugehoerige `TrusteePosition`-Eintraege an, auto-verlinkt Bankauszuege via `_linkBankPositions`.
`trustee.syncToAccounting`	`featureInstanceId`, `documentList: DocumentList` (typisch DataRef auf `processDocuments.documents`)	`ActionResult` (mit `documents`)	Pusht alle gebuchten Positions per `AccountingBridge.pushBatch` ins Zielsystem; markiert erfolgreiche Sync-Records.
`trustee.refreshAccountingData`	`featureInstanceId`	`ActionResult` (`success`, `error`)	Refresht Kontenplan + Saldo + Kontakte aus dem Buchhaltungssystem.
`trustee.queryData`	`featureInstanceId`, freie Filter-Argumente	`ActionResult` mit Query-Resultat	Read-only Zugriff fuer den AI-Agent (`dynamicMode=True`).

Schemas leben in gateway/modules/datamodels/datamodelWorkflowActions.py + gateway/modules/features/trustee/datamodelTrustee.py. Single source of truth fuer Editor + AI-Agent + Adapter ist die Action-Signatur (/api/automation2/catalog).

Datenmodell

Modell	Datei	Kommentar
`TrusteeOrganisation`	`datamodelTrustee.py`	Buchhaltungs-Mandant innerhalb der FeatureInstance.
`TrusteeRole`, `TrusteeAccess`	dito	Rollen + Zugriffsregeln je Organisation.
`TrusteeContract`	dito	Vertragsdatensatz je Mieter / Kontakt.
`TrusteeDocument`	dito	Originaldokument + AI-Klassifikation + Statusfelder; Quelle fuer Positionen.
`TrusteePosition`	dito	Buchungszeile (Debit/Kredit, Konto, Betrag, Datum, Sync-Status).
`TrusteeData*` (Account, JournalEntry, JournalLine, Contact, AccountBalance)	dito	Read-only Spiegel des Buchhaltungssystems (Kontenplan, Buchungen, Saldenliste).
`TrusteeAccountingConfig`	dito	Connector-Konfiguration (Bridge-Typ, Secrets via Encryption).
`TrusteeAccountingSync`	dito	Audit-Eintrag pro Sync-Lauf.

FeatureInstanceRef (Typed Action Architecture)

Seit Phase 5 ist featureInstanceId ueberall als typisierter Envelope persistiert:

{ "$type": "FeatureInstanceRef",
  "id": "11111111-1111-1111-1111-111111111111",
  "featureCode": "trustee" }

Schreiben: materializeFeatureInstanceRefs (automation2/featureInstanceRefMigration.py) wandelt rohe UUIDs bei jedem Run automatisch ins Envelope-Format. Optional persistiert gateway/scripts/script_migrate_feature_instance_refs.py die Aenderung in der DB (--dry-run Default).
Lesen: _unwrapTypedRef (graphUtils) entpackt den Envelope vor dem Action-Call -- Trustee-Actions sehen weiterhin featureInstanceId: "<uuid>" und brauchen keinen Patch.
Discriminator: featureCode = "trustee" macht die Trustee-Variante eindeutig (Editor zeigt [trustee] <Label> im Picker).

Pick-not-Push fuer DocumentList

Die typische Spesenbelege-Kette ist:

trigger.manual -> trustee.extractFromFiles -> trustee.processDocuments -> trustee.syncToAccounting

trustee.processDocuments und trustee.syncToAccounting ziehen ihren documentList-Input ueber DataRef-Bindings aus dem Vorgaengerknoten:

{ "type": "ref", "nodeId": "process", "path": ["documents"] }

*-Wildcard-Bindings (["documents", "*", "name"]) werden vom Resolver iteriert und liefern eine Liste -- noetig fuer Loop-Vorschlaege im DataPicker.

AccountingBridge

gateway/modules/features/trustee/accountingBridge.py ist die einheitliche Abstraktion ueber alle Buchhaltungssysteme. AccountingBridge.pushBatch(positions, config) validiert + pusht; konkrete Adapter (abacus.py, bexio.py, banana.py, ...) implementieren das Protokoll. Sync-Ergebnisse landen als TrusteeAccountingSync-Audit-Eintraege.

trustee.refreshAccountingData ruft AccountingBridge.fetchSnapshots -- die Tabellen TrusteeDataAccount, TrusteeDataJournal*, TrusteeDataContact, TrusteeDataAccountBalance werden read-only befuellt.

Saldenliste (`TrusteeDataAccountBalance`)

Die Tabelle TrusteeDataAccountBalance enthaelt pro Konto + Periode (13 Buckets: Annual periodMonth=0 + 12 Monate) einen Datensatz mit openingBalance, debitTotal, creditTotal, closingBalance.

Datenquelle (Prioritaet):

Connector (getAccountBalances): Jeder Accounting-Connector kann ueber die optionale Methode BaseAccountingConnector.getAccountBalances(config, years, accountNumbers) echte Salden liefern. AccountingPeriodBalance (Pydantic) ist der einheitliche Rueckgabetyp.
- RMA: Dedizierter Endpunkt GET /gl/saldo -- liefert den echten, durch RMA berechneten Schlusssaldo inkl. Vorjahresvortrag und Jahresabschluss-Buchungen. Pro Konto + Stichtag ein API-Call. Wildcard-Pattern (xxxx, xxxxx) aus Kontenplan abgeleitet fuer Bulk-Abfrage.
- Bexio: Kein Saldo-Endpunkt verfuegbar; Aggregation aus GET /3.0/accounting/journal mit korrekter kumulativer Berechnung (Bilanzkonten 1xxx-2xxx carry-over, Erfolgskonten 3xxx-9xxx jaehrlicher Reset).
- Abacus: Aggregation aus GET GeneralJournalEntries (OData V4). Code-Hinweis fuer optionale AccountBalances-Entity (instanzabhaengig).
Lokaler Fallback (_buildLocalBalanceFallback): Wenn der Connector [] zurueckgibt (kein Endpunkt oder Fehler), aggregiert accountingDataSync die bereits importierten TrusteeDataJournalLine-Zeilen kumulativ. openingBalance der ersten Periode = 0 (kein Vortrag aus fehlenden Daten erfindbar).

Quelle wird im Log pro Sync dokumentiert: source=connector bzw. source=local-fallback.

REST-Endpunkte (Auswahl)

Liste in wiki/b-reference/gateway/architecture.md (Abschnitt "Feature: Trustee -- Daten-Tabellen-Endpunkte"); zentral:

Endpunkt	Modell	Zweck
`GET /api/trustee/{instanceId}/documents`	`TrusteeDocument`	Paginierte Document-Liste (RBAC + Filter).
`GET /api/trustee/{instanceId}/positions`	`TrusteePosition`	Paginierte Position-Liste.
`GET /api/trustee/{instanceId}/data/...`	`TrusteeData*`	Read-only Spiegel (Konten, Journal, Saldo, Kontakte).
`GET /api/trustee/{instanceId}/accounting/configs`	`TrusteeAccountingConfig`	Connector-Konfiguration (Secrets maskiert).
`GET /api/trustee/{instanceId}/accounting/syncs`	`TrusteeAccountingSync`	Audit der Sync-Laeufe.

UI-Sichtbarkeit der Daten-Tabellen-Seite haengt am Permission-Eintrag ui.feature.trustee.data-tables (Template-Rollen trustee-viewer, trustee-user, trustee-accountant).

Tests

Test	Datei	Was er beweist
Unit	`gateway/tests/unit/methods/test_methodTrustee.py` (sofern vorhanden)	Action-Schemas + Pflicht-Felder.
Adapter-Drift	`gateway/tests/unit/graphicalEditor/test_adapter_validator.py`	Editor-Nodes synchron zu Method-Signaturen (`assert report.errors == []`).
FeatureInstanceRef	`gateway/tests/unit/workflows/test_featureInstanceRefMigration.py`	Materialisierung + Auto-Unwrap, Idempotenz.
Live-E2E	`gateway/tests/integration/trustee/test_spesenbelege_workflow_e2e.py`	`executeGraph` durch `processDocuments + syncToAccounting` mit In-Memory-Fakes.
DB-CLI	`gateway/tests/unit/scripts/test_migrate_feature_instance_refs.py`	Dry-run + Live-Migration des persistierten Graphs.
Balance RMA	`gateway/tests/unit/features/trustee/test_accountingConnectorRma_balances.py`	`getAccountBalances` via gemocktem `/gl/saldo` (BuHa-SoHa-Szenario + ER-Reset).
Balance Bexio	`gateway/tests/unit/features/trustee/test_accountingConnectorBexio_balances.py`	Kumulative Aggregation aus Journal (BS carry-over + ER-Reset).
Balance Abacus	`gateway/tests/unit/features/trustee/test_accountingConnectorAbacus_balances.py`	OData-Aggregation (BS carry-over + ER-Reset).
Balance Sync	`gateway/tests/unit/features/trustee/test_accountingDataSync_balances.py`	Connector-Pfad (verbatim persist) + Local-Fallback (kumulative Berechnung).

11 KiB Raw Blame History