5 Bausteinsicht

5.1 Whitebox Gesamtsystem

Das e-gov-framework besteht aus einem Pflicht-Kernmodul und vier optionalen Erweiterungsmodulen. Fachapplikationen beziehen die Module als Maven-Dependencies über das BOM.

↗ Vollbild

Bildquelle Bausteinsicht Gesamtsystem (SVG)

5.1.1 Enthaltene Bausteine

Baustein	Verantwortung
e-gov-bom	Bill of Materials — zentrale Versionssteuerung aller Framework-Abhängigkeiten; kein ausführbarer Code
e-gov-framework	Kern: Persistence-Abstraktion, IAM (Rollen/RuleSets), Command-Pattern, Exception-Handling, OpenAPI-Integration
e-gov-mdm	Stammdatenverwaltung: Vokabulare (Codelisten), mehrsprachige Codes, erweiterbare Felddefinitionen
e-gov-mdm-api	REST-API-Layer für MDM; OpenAPI-Dokumentation; Maven-Plugin zur Ruleset-SQL-Generierung
e-gov-ai-rule-generation	LLM-gestützte Generierung von Validierungsregeln aus natürlicher Sprache (Azure OpenAI / gpt-4o)
e-gov-luid	Alternative ID-Generierungsstrategien: LUID (sortierbar, cluster-sicher), DB-Sequence, ULID
e-gov-framework-demo	Referenzimplementierung; zeigt korrekten Einsatz aller Module

5.1.2 Wichtige Schnittstellen

Schnittstelle	Beschreibung
`BaseRepositoryImpl<T>`	Abstrakte Basisklasse; consuming Apps erweitern sie für jede Domänen-Entity
`BaseExecutor`	Abstrakte Basis für Command-Executor; kapselt Validation + Persistierung
`UserIdProvider`	Interface; consuming Apps implementieren es, um `userId` aus dem `EGOV_TOKEN`-Cookie zu extrahieren
`DomainCommandFactory`	Abstrakte Fabrik; consuming Apps erzeugen domänenspezifische Commands
`@Ruleset` / `@Validation`	Annotationen auf DTOs; deklarieren Autorisierungs- und Validierungsregeln
`egov.*` Properties	Konfigurationspunkte in `application.yml` der consuming App

5.2 Ebene 2 — Detailzerlegung e-gov-framework (Kern)

Der Kern gliedert sich in vier interne Pakete.

5.2.1 Persistence (`ch.ti8m.egov.framework.persistence`)

Baustein	Verantwortung
`BaseRepositoryImpl`	Generische CRUD-Operationen; delegiert Query-Bau an `QueryBuilder`
`QueryBuilder`	Baut native SQL-Abfragen aus Filter-DSL, Sortierung, Paginierung und Permission-Filter
`FilterParser` / `Tokenizer`	Parsen den Filter-DSL-String in einen Abstract Syntax Tree
`PermissionBuilder`	Ergänzt jede SELECT-Abfrage um rollenbasierte WHERE-Klauseln
`ModifiableEntity`	Basis-JPA-Entity mit Audit-Feldern (`createdBy`, `modifiedBy`, Zeitstempel)
`DatabaseConfigurationService`	Liest `egov.persistence.database.type` und `naming.style`; konfiguriert Dialekt

5.2.2 IAM (`ch.ti8m.egov.framework.iam`)

Baustein	Verantwortung
`RuleSetService`	Ermittelt den passenden RuleSet für eine Action + Benutzerrolle
`PermissionService`	Prüft ob ein Benutzer eine Operation (READ/WRITE/DELETE) auf einer Entity ausführen darf
`RoleService`	Verwaltet Rollen und Rollenmitgliedschaften
`IAMController`	REST-Endpunkt `GET /iam/v1/permissions`
RuleSet-Entities	JPA-Entities in Tabellen `egov_iam_rule_set`, `egov_iam_condition`, `egov_iam_role*`

5.2.3 Command & Validation (`ch.ti8m.egov.framework.validation`)

Baustein	Verantwortung
`Command`	JPA-Entity; persistiert jede fachliche Aktion (Tabelle `egov_cmd_command`) mit Status-Lifecycle (`INITIATED → VALIDATED → EXECUTED / FAILED`)
`DomainCommandFactory`	Erzeugt und initialisiert Commands; setzt Audit-Informationen
`BaseExecutor`	Orchestriert Validation (via `ValidationEngine`) → Ausführung → Persistierung
`ValidationEngine`	Wertet RuleSet-Validierungsregeln rekursiv gegen DTO-Felder aus
`NonTxExecutor`	Führt Commands ausserhalb einer Spring-Transaktion aus

5.2.4 Exception Handling & Context (`ch.ti8m.egov.framework.exceptionhandling`)

Baustein	Verantwortung
`GenericExceptionHandler`	`@ControllerAdvice`; wandelt alle `EGovException`-Subklassen in strukturierte HTTP-Fehlerantworten um
`DataHolder`	ThreadLocal-Kontext; hält `userId` für den aktuellen Request
`ContextInterceptor`	HTTP-Interceptor; extrahiert `userId` aus `EGOV_TOKEN` und befüllt `DataHolder`
`EGovException`-Hierarchie	`ActionNotAllowedException`, `NoPermissionForEntityException`, `UnauthorizedException`, `SystemException`

5.3 Ebene 2 — Detailzerlegung e-gov-ai-rule-generation

Das KI-Modul ist als optionales Erweiterungsmodul konzipiert und enthält drei Bausteine, die den Workflow von der Freitext-Eingabe bis zur persistierten Validierungsregel abbilden.

Baustein	Verantwortung
`RuleModificationController`	REST-Endpunkt (POST); nimmt Freitext-Beschreibung entgegen und orchestriert Generierung und Persistierung der neuen Regel
`RuleGenerator`	Baut den Prompt aus Freitext + Regelgrammatik und ruft Azure OpenAI (gpt-4o) über Spring AI auf
`RuleTranslator`	Konvertiert die LLM-Antwort in das Framework-Regelformat und persistiert die Regel via `RuleSetService` in `egov_iam_rule_set`

Externe Abhängigkeit: RuleGenerator kommuniziert mit Azure OpenAI über HTTPS (Cloud-Egress); die übrigen Bausteine kommunizieren ausschliesslich mit dem e-gov-framework-Kern (→ Szenario 4 in Sektion 6).