01. Einführung und Ziele

Aufgabenstellung

Das RAL Gütezeichen Anhörungsportal (CAF.Applications.RAL.QualityMarks.HearingPortal) bildet das Anhörungsverfahren für RAL-Gütezeichen digital ab: Ein Verfahren wird angelegt, Institutionen und deren Kontakte werden als Teilnehmer aufgenommen, Unterlagen werden zusammengestellt und nach Vier-Augen-Freigabe versendet, Teilnehmer geben über ihr Institutionskonto (Zielzustand) oder, solange dessen Ablösung läuft, noch über einen befristeten Gastlink Stellungnahmen ab, das Verfahren wird intern beantwortet, beschieden und schließlich abgeschlossen und archiviert. Der Lebenszyklus verzweigt je nach gewählter Abschlussvariante (US-33):

Draft → PendingApproval → Approved → Dispatched → Adjudication → Completed        (zweistufig)
Draft → PendingApproval → Approved → Dispatched ─────────────→ Completed          (einstufig)
  └────────────────────── benannte Rücksprünge/Abbruch nach Fachregel ──────────────────────┘

Bei der einstufigen Variante entfällt der eigene Adjudication-Status: Bescheidung und Endfassung gehen in einem Vorgang hinaus. Details zur Wahl der Variante stehen in Laufzeitsicht.

Die Anwendung ist Teil des CAF-Monorepos: eines modularen ABP-/.NET-10-Monolithen mit wiederverwendbaren, anwendungsneutralen Bausteinen (CAF.Modules.Authentication, CAF.Modules.Documents[.Contracts], CAF.Modules.UI.Blazor) und der einzigen aktuell existierenden Anwendung, dem Anhörungsportal, unter src/Applications/RAL/QualityMarks/HearingPortal/. Das Portal ist damit gleichzeitig Referenzanwendung für die No-Layer-Architektur des Monorepos und Träger der eigentlichen Fachlogik. Details zu Modulschnitt und Abhängigkeitsrichtung stehen im Bausteinsicht; die noch offenen Bereiche und ihre Nachweislücken benennt Risiken und technische Schulden.

Wesentliche fachliche Ziele

• Durchgängiger, nachvollziehbarer Anhörungsprozess: Von der Anlage über Vier-Augen-Freigabe, zuverlässigen Versand, Fristen/Erinnerungen, Stellungnahmen und internen Kritikdialog bis zu Bescheidung, Abschluss/Archiv oder kontrolliertem Abbruch — jeder Statuswechsel läuft über benannte Operationen, nie über einen frei setzbaren Status.
• Sicherer, kontobasierter Teilnehmerzugang: Zielzustand ist ein ausschließlich an das Institutionskonto gebundener Zugang ohne anonym erreichbaren Link, ohne Rückfallweg und mit sofort wirksamem Entzug (Bereich „Institutionszugang neu“, US-22/US-22a/US-22b/US-22c). Der bisherige ablaufende Gastlink ist der Übergangspfad bis zur vollständigen Ablösung, kein gleichwertiger Dauerzugang; interne Rollen (Administrator, Referent, Geschäftsführung) erhalten nur die ihnen erlaubten Aktionen.
• Verlässliche Institutions- und Kontaktverwaltung: Institutionen mit Anschrift, Typ, Pflichtpartnerstatus und mehreren Kontakten pflegen, samt CSV-Import/-Export und geschütztem Löschen erst nach Nutzungsprüfung.
• Kontrollierte Kontoprovisionierung: Institutionskontakte und Mitarbeitende werden über explizite, auditierte Wege zu Keycloak-Konten und genau einer Produktrolle zugeordnet — ohne Dublettenkonten oder automatische Rollenvergabe.
• Betriebsfähigkeit ab Tag eins: Health-Endpunkte, PII-arme Kennzahlen mit Korrelationsverfolgung vom Versandfehler bis zur Nachricht, sowie ein bei jedem Commit laufendes automatisches Qualitätsgate.

Qualitätsziele (Top-Prioritäten)

Diese Rangfolge steuert Zielkonflikte: Sicherheits- und Integritätsanforderungen sind nicht verhandelbar und gehen im Zweifel vor Bedienkomfort oder Implementierungsaufwand. Die geforderte Nachweistiefe je Änderungsart steht im Entwicklungsleitfaden §15.1; Qualitätsszenarien mit konkreten Ereignis/Antwort-Paaren stehen im Qualitätsanforderungen.

Stakeholder-Überblick

Weiterführend: Randbedingungen, Kontextabgrenzung, Lösungsstrategie sowie die Betriebs- und Startpfade in ../GETTING-STARTED.md und im Portal-README.

02. Randbedingungen

Dieses Kapitel fasst die Vorgaben zusammen, innerhalb derer Architektur- und Implementierungs- entscheidungen getroffen werden. Sie sind größtenteils verbindlich gesetzt (Technologie-, Team- und Prozessvorgaben) und nicht das Ergebnis einer freien Architekturwahl. Details zu Ownership und Modulschnitt stehen im Entwicklungsleitfaden; Begründungen je Einzelkonvention in docs/conventions-decisions.md.

1. Technische Randbedingungen

Diese Vorgaben sind in Architekturtests kodifiziert (z. B. Verbot CAF.Modules.* → CAF.Applications.RAL.QualityMarks.HearingPortal.*, InteractiveServer-only, Cohesion-only-UI) — sie werden nicht gelockert, nur Pfad-Literale bei struktureller Umbenennung nachgezogen.

2. Organisatorische Randbedingungen

Sprache

• UI-Texte: Deutsch (Produktsprache), über IStringLocalizer<T> und paritätische DE-/EN-Localization-JSON je owning Modul — keine hartkodierten UI- oder Business-Exception-Texte.
• Code-Identifier und Kommentare: Englisch.
• Logs: strukturiert und Englisch (ILogger<T> mit Templates, nie String-Interpolation, nie direkte Serilog-Referenz).

Diese Dreiteilung gilt repositoryweit, siehe conventions/baseline.md.

Konventionen und Entscheidungsprozess

• Themenspezifische Coding-Konventionen liegen in conventions/ (C#, EF Core, Blazor, ABP, Tests, Git, Security, PowerShell, CI/CD, MSBuild/NuGet) und sind bewusst knapp gehalten.
• Die repo-spezifische Adopt/Reject-Entscheidung je Konvention — inklusive Vor-/Nachteil — steht in docs/conventions-decisions.md; das ist die maßgebliche Quelle, welche geteilte Konvention hier tatsächlich gilt (z. B. explizite Typen statt var und das StyleCop-Set sind bewusst abgelehnt, IClock/IGuidGenerator, ConcurrencyStamp und die Security-Baseline sind übernommen).
• Quellenpriorität bei Konflikten: aktuelle Benutzeranweisung → nächstgelegene AGENTS.md → repositoryweite Arbeitsgrundlage → aktuelle Architektur/Entwicklungsleitfaden. Nur dieses verlinkte Kernset gibt Repository-Regeln vor; Code und ausführbare Nachweise bestimmen den Implementierungsstand.
• Strukturelle Änderungen (Modulgrenze, Sicherheit, Persistenz, Abhängigkeit, Betrieb) ziehen Architektur, Arbeitsgrundlage und durchsetzende Tests im selben Änderungssatz mit; es wird keine parallele Entscheidungsdokumentation gepflegt.

Git-Workflow

• Conventional Commits: feat|fix|refactor|docs|test|chore(scope): subject, imperativ, Subject ≤ 50 Zeichen.
• main ist geschützt: kein Direct-Push, kein Force-Push; Änderungen ausschließlich per Merge Request mit Review.
• Branch-Namen kebab-case (feature/…, fix/…, chore/…), nach Merge gelöscht.
• AGENT_CHANGELOG.md wird von jedem Agent-Turn gepflegt (neuester Eintrag oben, ≤ 1000 Zeichen) — diese Pflicht gilt für Menschen und Agents gleichermaßen.
• Qualitäts-Gate bei jedem Commit: versionierte Git-Hooks (tools/git-hooks, aktiviert über setup.cmd) führen Invoke-QualityGate.ps1 ohne -IncludeBrowserGate gegen die volle CAF.slnx aus und blockieren den Commit bei rotem Gate; übersprungene Pflichttests gelten als Fehlschlag. git commit --no-verify ist eine dokumentierte Ausnahme, kein Arbeitsweg. Details: DEVELOPMENT-GUIDE.md Abschnitt 15.2 und GETTING-STARTED.md.

Agenten als Mitwirkende

• Claude Code und Codex arbeiten nach denselben Quellen wie menschliche Entwickler; es gibt bewusst kein tool-spezifisches Regel-Duplikat. Claude Code liest CLAUDE.md, einen reinen Zeiger auf AGENTS.md; Codex liest diese Root-AGENTS.md direkt, weil seine Projekt-Discovery im Repositorywurzelverzeichnis beginnt.
• Jeder Implementierungs- oder Prüfagent liest vor einer Codeänderung die repositoryweite Arbeitsgrundlage, die aktuelle Architektur, den Entwicklungsleitfaden und die nächstgelegene AGENTS.md.

3. Namens- und Strukturkonventionen (Randbedingung für jede Erweiterung)

• Anwendungsspezifische persistierte Identifier tragen den Präfix RALQM (Tabellen RALQMHearings/RALQMInstitutions, Error Codes RALQM.<Feature>:, Permission-Gruppe RALQM, Rollen RALQMAdministrator/RALQMCaseOfficer/RALQMManagement).
• Technische Slugs bleiben lowercase (ral-qualitymarks).
• Wiederverwendbare CAF-Module behalten den CAF-Präfix (CAFDocuments*).
• src/Modules/* darf nicht von der Anwendung abhängen — durch Architekturtests erzwungen.
• Umbenennungen sind stets datenerhaltend; historische EF-Migrationen behalten ihre alten Identifier bei.

Diese Randbedingungen sind Grundlage für die Lösungsstrategie und die Bausteinsicht; technische Details zu Setup und Betrieb stehen im Schnelleinstieg und im Entwicklungsleitfaden.

03. Kontextabgrenzung

Dieses Kapitel zieht die Systemgrenze um das eine fachliche Deployable CAF.Applications.RAL.QualityMarks.HearingPortal (RAL Gütezeichen Anhörungsportal, „RALQM") und benennt seine externen Nachbarn — fachlich (wer interagiert wozu) und technisch (über welche Schnittstelle). Die Modul-interne Gliederung folgt in der Bausteinsicht; die Begründung für „ein Deployable, eine Anwendungsdatenbank" steht in der Lösungsstrategie.

3.1 Systemgrenze

Es gibt genau ein fachliches Anwendungs-Deployable: den RALQM-Host, eine ASP.NET-Core-/Blazor- Web-App mit Interactive Server. Keycloak, SQL Server und der SMTP-Provider sind Infrastruktur — keine weiteren GZ-Fachservices. Die Anwendung besitzt genau einen HearingPortalDbContext und einen Migration-Host im Host-Projekt; Feature-Application-Services laufen im selben Prozess wie die Blazor-UI (kein separater API-Tier). Details zum Ablauf eines Requests innerhalb der Grenze stehen in der Laufzeitsicht.

flowchart LR
    Staff["Interne Mitarbeitende\nAdministrator / CaseOfficer / Management"] --> App
    Guest["Externe Teilnehmer\nKontozugang (Ziel), Gastlink (Übergang)"] --> App
    ShareRecipient["Empfänger eines\ndirekten Dokumentenlinks"] --> App
    App["RALQM HearingPortal\nBlazor Web App (Interactive Server)"] <-->|"OIDC Code + PKCE"| Keycloak["Keycloak\nIdentity Provider"]
    App -->|"schmaler Admin-Port"| Keycloak
    App --> GzDb[("RALQM-Anwendungsdatenbank\nSQL Server")]
    Keycloak --> KcDb[("Keycloak-Datenbank\nSQL Server, separat")]
    App --> Mail["SMTP-Provider\nlokal: Mailhog"]

Lokal liegen die RALQM- und die Keycloak-Datenbank auf derselben SQL-Server-Instanz; fachlich und technisch bleiben es getrennte Datenbanken mit getrennten Principals (Keycloak-eigener Login vs. dedizierter qualitymarks-Datenbankprincipal für die Anwendung).

3.2 Fachlicher Kontext

Objektzugriff, Verfahrensstatus und Teilnehmerzuordnung werden zusätzlich je Feature geprüft; Details zu Rollen, Grants und den vier getrennten Dokument-Zugriffswegen stehen in den querschnittlichen Konzepten (Kapitel 8).

3.3 Technischer Kontext

Lokale Development-Endpunkte (siehe GETTING-STARTED): Anwendung https://localhost:44356, Keycloak http://localhost:8080 (Realm caf), Mailhog UI http://127.0.0.1:8025 / SMTP 127.0.0.1:1025, SQL Server 127.0.0.1:1433. Alle Compose-Ports sind nur an Loopback gebunden (siehe etc/docker/docker-compose.yml); Produktionsendpunkte und -zugangsdaten werden außerhalb dieser lokalen Dateien betrieben.

3.4 Bewusst keine weiteren Nachbarn

Die Systemgrenze umfasst keinen zweiten Anwendungsservice, kein externes DMS, keine Microservice-Nachbarn und keine zweite GZ-Datenbank — ein neuer externer Nachbar braucht zuerst einen konkreten, getesteten Anwendungsfall. Details zu bewusst nicht vorhandener Infrastruktur stehen in den Randbedingungen.

04. Lösungsstrategie

Dieses Kapitel bündelt die grundlegenden Entscheidungen, die den Lösungsraum aufspannen und in allen Folgekapiteln als gesetzt vorausgesetzt werden. Die begründete Langform je Entscheidung steht in den Architekturentscheidungen; die Abwägung gegen externe Konventionsvorlagen in docs/conventions-decisions.md.

4.1 Modularer Monolith statt Microservices

Genau ein Deployable (CAF.Applications.RAL.QualityMarks.HearingPortal) und eine Anwendungsdatenbank bilden die gesamte Lösung. Microservices, ein zweites GZ-Datenbankschema, Message-Broker (RabbitMQ/Kafka) oder ein API-Gateway sind bewusst nicht Teil der Architektur (siehe Qualitätsanforderungen §10.3 und Risiken §Bewusst nicht als Schulden geführt). Der Grund ist Betriebsökonomie für ein Fachportal dieser Größe: ein Deploy-Artefakt, eine Migration Pipeline, ein Health-Check. Die fachliche und im Quellcode erzwungene Modultrennung (siehe 4.3) hält die Option auf spätere Auskopplung offen, ohne sie vorwegzunehmen — Cross-Modul-Kommunikation läuft bereits heute über schmale Contracts und IDs, nicht über gemeinsame Entities.

4.2 „No-Layer" statt klassischer 8-Projekt-ABP-Schichtung

Die strikte ABP-Standardaufteilung (Domain.Shared/Domain/Application.Contracts/Application/ EntityFrameworkCore/HttpApi/…​) ist für dieses Repo explizit N/A (conventions-decisions.md ABP-11). Domain, Application und Persistence bleiben logische Schichten, aber materialisiert in einer kompakten Runtime-Assembly je Modul statt in sieben eigenen Projekten. Eine weitere Assembly-Grenze wird erst gezogen, wenn sie unabhängig konsumiert, versioniert oder ausgetauscht werden muss (ADR-01). Das reduziert Projekt- und Verkabelungsaufwand, ohne die fachliche Kapselung aufzugeben — die Kapselung sitzt in Feature-Slices, nicht in Assembly-Zahl.

4.3 Feature-Slices: Contracts / Runtime / Blazor

Jedes Fachmodul zerfällt in bis zu drei Projekte mit einseitiger Abhängigkeitsrichtung:

<Modul>.Contracts   DTOs, AppService-Interfaces, Permissions, Localization, öffentliche IDs
<Modul>              Runtime: Domain, Application Services, EF-Mapping
<Modul>.Blazor       optionale Feature-Seiten/Komponenten (konsumiert nur Contracts)

• Contracts kennt keine EF-Entities und keine Implementierungsdetails; sie ist die einzige Fläche, die andere Module referenzieren dürfen.
• Runtime implementiert die Contracts, besitzt die eigenen Tabellen und darf nie fremde Runtime, fremde Entities oder fremde DbSets referenzieren.
• Blazor referenziert die eigene und ggf. fremde Contracts sowie Shell-Contracts, niemals eine Runtime.

Diese Grenzen sind eine Compile-Time-Eigenschaft, durchgesetzt über Architekturtests, nicht nur eine Ordnerkonvention (Abhängigkeitstabelle in Bausteinsicht §5.2.4). Cross-Modul-Referenzen erfolgen ausschließlich über IDs (z. B. InstitutionId, DocumentId), nie über relationale Foreign Keys oder Navigation über Modulgrenzen hinweg (Querschnittliche Konzepte §2).

4.4 Zwei Bausteinklassen: wiederverwendbare CAF-Module vs. GZ-Fachmodule

Der Quellcode trennt zwei fachlich unterschiedliche Verantwortungsebenen strikt:

CAF.Modules.* darf laut ADR-06 keinen GZ-Namespace und keinen GZ-Fachbegriff referenzieren; die Regel gilt nie umgekehrt (CAF.Modules.* → CAF.Applications.RAL.QualityMarks.HearingPortal.* ist verboten). Konkret sichtbar wird das an den Modul-READMEs:

• src/Modules/Authentication/README.md beschreibt einen OIDC-/PKCE-Client ohne Produktrouten oder Berechtigungen der Anwendung.
• src/Modules/Documents/README.md beschreibt einen mandantenfähigen Dokument-Adapter über ABP File Management, ebenfalls ohne Abhängigkeit auf das Portal.

Beide Bausteine behalten dabei bewusst das Präfix CAF in ihren persistierten Bezeichnern (CAFDocumentShareGrants), unabhängig vom RALQM-Präfix der Anwendung (siehe 4.5). Diese Trennung macht die Framework-Module potenziell in einem anderen ABP-Host wiederverwendbar, ohne dass GZ- Fachlogik mitgezogen wird.

4.5 RALQM-Präfixstrategie für persistierte Kennungen

Anwendungsspezifische Kennungen tragen konsequent das Präfix RALQM: Tabellen (RALQMHearings, RALQMInstitutions), Fehlercode-Namespaces (RALQM.<Feature>:), die Permission-Gruppe RALQM und die Rollen RALQMAdministrator/RALQMCaseOfficer/ RALQMManagement. Technische Slugs bleiben demgegenüber lowercase (ral-qualitymarks). Wiederverwendbare CAF-Module behalten ihr eigenes CAF-Präfix (CAFDocuments*) und werden von der Umbenennung nicht erfasst — der Präfix markiert Ownership, nicht Technologie. Renames sind grundsätzlich daten­erhaltend: Migrationen, die einen Rename umsetzen (z. B. 20260825174437_RenamePersistedIdentifiersToRALQM), erzeugen keinen Datenverlust, und historische EF-Migrationen behalten ihre alten Identifiers, statt rückwirkend umgeschrieben zu werden (conventions-decisions.md EF-03). Diese Strategie hält die Grenze zwischen „Framework" und „Anwendung" auch im Datenbankschema sichtbar, ohne die Migrationshistorie zu verfälschen.

4.6 Cohesion als verbindliche Fach-UI

Eigene CAF-/GZ-Oberflächen rendern ausschließlich über Cohesion (Syncfusion); MudBlazor, rohes Syncfusion oder Blazorise dürfen von Fachcode nicht direkt aufgerufen werden (conventions-decisions.md BL-01, Querschnittliche Konzepte §5). Ausgenommen sind die unverändert übernommenen ABP-Administrations- und LeptonX-Seiten, die ihren eigenen Vendor-UI-Stack behalten. Träger dieser Entscheidung ist CAF.Modules.UI.Blazor: zentrale Cohesion-Registrierung, Lizenzprüfung, Assets/Bundles und die Interactive-Server-Policy an einer Stelle. Das Cohesion-Paket kommt aus dem GitLab-Gruppen-Feed; Quelle, Versionsbereich und Auth-Wege stehen in Getting Started, Cohesion-Paketquelle. Feature-Seiten liegen im jeweils owning .Blazor-Projekt, bleiben render-mode-neutral (kein @rendermode in Feature-Code) und erfüllen WCAG 2.1 AA als Pflichtkriterium — fachlich relevant für ein Behördenportal.

4.7 Konsequenzen für Cross-Cutting-Themen

• Auth: Keycloak bleibt alleiniger Identity Provider; CAF.Modules.Authentication kapselt den OIDC-Client, GZ Authorization komponiert Rollen/Grants aus featureeigenen Permissions (Querschnittliche Konzepte §1).
• Dokumente: ABP File Management/BLOB Storing bleibt Descriptor- und Inhalts-Owner; CAF.Modules.Documents liefert nur den neutralen Vertrag plus Share-Grants, Hearings trägt die fachliche Bedeutung einer Datei (Laufzeitsicht §6.4).
• Persistenz: ein gemeinsamer HearingPortalDbContext, aber jedes Modul liefert seine eigene Model-Konfiguration; Migrationen entstehen ausschließlich im Host.
• Tests: die Modulgrenzen werden nicht nur dokumentiert, sondern durch Architekturtests erzwungen und sind damit Teil des Qualitätsnetzes (Querschnittliche Konzepte §7).

Siehe auch

• Randbedingungen — die gesetzten Vorgaben, die diese Strategie motivieren.
• Kontextabgrenzung — Systemgrenze und externe Nachbarn.
• Bausteinsicht — Detailschnitt der hier benannten Module.
• Querschnittliche Konzepte — Vertiefung von Auth, Dokumenten und Konfiguration.
• Architekturentscheidungen — ADR-Langform je Grundsatzentscheidung.
• docs/conventions-decisions.md — Konventions-Entscheidungsregister mit Status je Regel.
• DEVELOPMENT-GUIDE.md — verbindliche Arbeitsweise bei Änderungen.

05. Bausteinsicht

Dieses Kapitel zerlegt die statische Struktur des Systems in Bausteine: zuerst auf Ebene 1 (Module/Projekte), dann auf Ebene 2 (Feature-Slices der Anwendung). Motivation und Zielsetzung der No-Layer-Architektur stehen im Kontextabgrenzung und in der Lösungsstrategie; dieses Kapitel beschreibt nur, was existiert und **wer wen abhängen darf. Details zu Laufzeitabläufen liefert die Laufzeitsicht.

Quelle der Wahrheit für alle hier genannten Grenzen sind die Architekturtests (siehe ADR-06); dieses Kapitel fasst sie arc42-konform zusammen und verlinkt auf die READMEs der Bausteine.

5.1 Ebene 1: Gesamtsystem in Module und Anwendung

Das System ist ein modularer Monolith: ein Deployable (CAF.Applications.RAL.QualityMarks.HearingPortal), eine gemeinsame SQL-Server-Datenbank, aber strikt getrennte Bausteine im Quellcode und im Abhängigkeitsgraphen. Die .slnx gliedert dies in vier Gruppen: 01 Anwendung, 02 CAF-Bausteine, 03 GZ-Fachmodule, 04 Tests.

flowchart TB
    subgraph App["Anwendung: RAL Gütezeichen Anhörungsportal"]
        Host["Host\nCAF.Applications.RAL.QualityMarks.HearingPortal"]
        Shell["Shell\n…HearingPortal.Shell"]
        AppContracts["Contracts\n…HearingPortal.Contracts"]
        Auth["Features/Authorization"]
        Inst["Features/Institutions"]
        Hear["Features/Hearings"]
    end
    subgraph Modules["Wiederverwendbare CAF-Module (anwendungsneutral)"]
        ModAuthn["CAF.Modules.Authentication"]
        ModUI["CAF.Modules.UI.Blazor"]
        ModDocC["CAF.Modules.Documents.Contracts"]
        ModDoc["CAF.Modules.Documents"]
    end

    Host --> ModAuthn
    Host --> ModUI
    Host --> Shell
    Host --> Auth
    Host --> Inst
    Host --> Hear
    Auth --> Inst
    Auth --> Hear
    Auth --> ModDocC
    Hear --> Inst
    Hear --> ModDocC
    ModDoc --> ModDocC

Pfeile bedeuten „referenziert/verwendet“. Die zentrale, architekturtestlich abgesicherte Regel: die Anwendung hängt von den Modulen ab, nie umgekehrt. Kein CAF.Modules.*-Projekt darf ein CAF.Applications.RAL.QualityMarks.HearingPortal.*-Projekt, einen GZ-Namespace oder einen GZ-Fachbegriff referenzieren.

5.1.1 Anwendungs-Bausteine

Details zur Anwendungsstruktur: ../../src/Applications/RAL/QualityMarks/HearingPortal/README.md.

5.1.2 Wiederverwendbare CAF-Module

Alle vier Bausteine liegen unter src/Modules/ und sind Quellcode-Bausteine, keine NuGet-Pakete (IsPackable=false, keine PackageId/Version). Der Host konsumiert sie ausschließlich über ProjectReference. Je Baustein gilt trotzdem die Vertragsdatei VERTRAG.md als Quelltext-Vertrag — arch-getestet, siehe ADR-03.

Die folgende Tabelle fasst zusammen, wie dieses Produkt die Bausteine nutzt. Maßgeblich für Zweck, Abgrenzung und zugesicherte Fläche der Bausteine selbst ist docs/CAF/ bzw. die VERTRAG.md am jeweiligen Baustein — diese Tabelle ersetzt beides nicht.

Geplant (Bereich „Unterlagen Dateiablage“, US-15/US-15b/US-15c/US-16/US-16b, größtenteils offen): eine von einzelnen Verfahren entkoppelte, persönliche/gemeinsame Dateiablage mit Ordnerstruktur, Upload, Umbenennen/Verschieben/Kopieren und einem zweistufigen Papierkorb (Wiederherstellen/ endgültig löschen); eine Ablagedatei kann später unveränderlich als Version in ein Verfahren übernommen werden. Wächst das Documents-Modul selbst um diesen Umfang, oder entsteht ein eigener Baustein darauf, ist bei Umsetzungsbeginn zu entscheiden — dieses Kapitel ist dann nachzuziehen.

Persistierte Kennungen der Module behalten das Präfix CAF (CAFDocuments*), unabhängig vom RALQM-Präfix der Anwendung. Details je Modul: Authentication, Documents, UI.Blazor.

5.1.3 Cohesion-Referenz-Ausnahme für Razor-UI-Assemblies

Die vier Razor-UI-Assemblies dieser Anwendung — die Produkt-Shell und die drei Features/*/Blazor — referenzieren das Cohesion-Paket direkt per PackageReference und gerade nicht über CAF.Modules.UI.Blazor. Sie erzwingen dazu RZ10012 als Fehler (WarningsAsErrors), damit ein unaufgelöstes Cohesion-Tag den Build bricht statt still als leeres HTML-Element zu rendern. Der Host bindet zusätzlich CAF.Modules.UI.Blazor für Registrierung, Lizenzierung und Bundles ein.

Das ist eine bewusste, Razor-bedingte Ausnahme und keine aufzuräumende Redundanz — Regel, Begründung (Compile-Time-Razor-Assets) und Rollenteilung stehen in docs/CAF/ §02 Bausteine. Verbindliche Arbeitsfassung: src/Modules/AGENTS.md und Shell/AGENTS.md.

5.2 Ebene 2: Feature-Slices der Anwendung

Jedes der drei fachlichen Features gliedert sich intern in bis zu drei Teilprojekte — Contracts, Runtime und optional Blazor. Diese Dreiteilung besteht nur dort, wo die Grenze echten Nutzen stiftet: Abhängigkeitsrichtung, serverseitige Interception und spätere Auskopplung. Weitere Layerprojekte (z. B. separates Domain/Application) werden nicht vorsorglich angelegt — Domain, Application und EF-Persistenz bleiben logische Schichten innerhalb der Runtime-Assembly.

Features/<Feature>/
  Contracts/   DTOs, AppService-Interfaces, Permissions, Localization, öffentliche IDs
  Runtime/     Aggregate, Application Services, EF-Mapping (Domain/Application/EF in einer Assembly)
  Blazor/      optionale Razor-Class-Library: Seiten, Komponenten, Navigation (nur bei eigener UI)

5.2.1 Authorization

Die Authorization-Runtime referenziert Feature-Contracts von Institutions und Hearings, um Rollen zu komponieren, besitzt aber keine Feature-Permissions und keine Hearing-Daten.

5.2.2 Institutions

Geplant (US-07, US-13, US-41 — größtenteils offen): eine Institutionsgruppe als verfahrensübergreifend wiederverwendbarer, benannter Beteiligtenkreis (Mitglieder pflegen, umbenennen, auflösen) — bindbar als Ganzes in ein Verfahren (US-13) und adressierbar für Rundnachrichten (US-41), statt Institutionen je Verfahren einzeln zusammenzustellen. Siehe auch Glossar.

Institutions kennt Hearings nur über einen von außen implementierten Nutzungsport (keine Rückabhängigkeit).

5.2.3 Hearings

5.2.4 Abhängigkeitsrichtung der Feature-Slices

Die Tabelle nennt Projektabhängigkeiten. Die drei *.Blazor-Projekte referenzieren zusätzlich das Cohesion-Paket direkt und CAF.Modules.UI.Blazor gerade nicht — Begründung in 5.1.3.

Immer verboten: Contracts → Runtime/EF/Host, Feature-Blazor → Feature-Runtime oder eine fremde Runtime, GZ-Runtime → fremde GZ-Runtime oder deren Entities/Repositories/Tabellen, sowie jedes Modul → ausführbarer Host. Über Modulgrenzen (auch zwischen Features) werden nur IDs gespeichert, keine Foreign Keys — siehe Datenmodell in der Verteilungssicht und Persistenzregeln in Querschnittliche Konzepte §2.

Diese Trennung ist eine Compile-Time-Eigenschaft, durch Architekturtests abgesichert, keine bloße Ordnerkonvention.

5.3 Direkt verwendete ABP-Bausteine

Ergänzend zu den eigenen Modulen nutzt die Anwendung ABP-Vertikalen als Implementierungssubstrat, ohne sie zu eigenen CAF-Modulen zu machen: Account Public/Admin und Identity Pro (Login, lokale Benutzer/Rollen), Permission Management, Setting Management, Audit Logging, Text Template Management, Language Management/GDPR, File Management (Domain/EF/Application; keine generische UI/API) sowie BLOB Storing Database, Emailing/Background Workers und LeptonX/MudBlazor für Produktshell und ABP-Administrationsseiten.

5.4 Zusammenspiel im Request

Wie ein Blazor-Seitenaufruf durch Contract, Application Service, Aggregate und Persistenz läuft, beschreibt die Laufzeitsicht. Betriebs- und Deployment-Aspekte (ein Deployable, eine Datenbank, lokale Infrastruktur) stehen in der Verteilungssicht.

Weiterführend: Entwicklungsleitfaden, Getting Started, Konventionen.

06. Laufzeitsicht

Dieses Kapitel zeigt das dynamische Verhalten der in der Bausteinsicht beschriebenen Module anhand der vier wichtigsten Laufzeitszenarien: Anmeldung, Anhörungs-Lebenszyklus, externe Kontoprovisionierung und Dokumentfreigabe. Alle vier Abläufe sind im aktuellen Stand implementiert — mit den in Risiken und technische Schulden benannten offenen Nachweisen und der noch laufenden Ablösung des Gastzugangs. Details zu Modulgrenzen und Ownership stehen in der Bausteinsicht und den Querschnittlichen Konzepten, verbindliche Bauregeln im Entwicklungsleitfaden.

6.1 Login und Authentifizierung

Keycloak ist Token-Issuer und Identitätsquelle; CAF.Modules.Authentication (src/Modules/Authentication) ist der anwendungsneutrale OIDC-Client. Er registriert Cookie- und OIDC-Authentifizierung (CAFAuthenticationServiceCollectionExtensions), setzt eine Cookie-Session- Policy (CAFApplicationCookieSessionPolicy, CAFApplicationCookieTokenPropagation) und hält die Session über einen revalidierenden AuthenticationStateProvider (CAFRevalidatingAuthenticationStateProvider, CAFSecurityStampRevalidationPolicy) periodisch aktuell.

sequenceDiagram
    actor U as Benutzer
    participant App as Blazor Web App (Shell)
    participant Auth as CAF.Modules.Authentication
    participant Kc as Keycloak
    participant Id as ABP Identity (lokal)

    U->>App: Aufruf einer geschützten Seite
    App->>Auth: Challenge auslösen
    Auth->>Kc: Redirect Authorization Code + PKCE (code_challenge)
    U->>Kc: Anmeldung (Credentials/2FA)
    Kc-->>Auth: Redirect mit Code
    Auth->>Kc: Code-Tausch inkl. code_verifier
    Kc-->>Auth: ID-/Access-/Refresh-Token
    Auth->>Auth: Pflicht-Claims prüfen (u. a. sub)
    Auth->>Id: lokalen IdentityUser über sub finden/verknüpfen
    Id-->>Auth: GZ-Rolle(n) und Grants
    Auth-->>App: Cookie-Session gesetzt
    App-->>U: Zielseite mit gewährten Permissions

Wesentliche Punkte:

1. Die Verknüpfung zwischen Keycloak-Identität und lokalem IdentityUser verwendet ausschließlich den stabilen OIDC-Subject-Identifier sub, niemals die E-Mail-Adresse.
2. Rollen (RALQMAdministrator, RALQMCaseOfficer, RALQMManagement) sind lokale ABP-Grants; sie werden aus den Feature-Contracts komponiert (siehe Authorization und Autorisierung).
3. Die Cookie-Session wird nicht nur beim Login geprüft: CAFRevalidatingAuthenticationStateProvider und die Security-Stamp-Policy erzwingen eine periodische Neuprüfung, sodass eine serverseitig gesperrte oder geänderte Identität in laufenden Circuits zeitnah wirkt.
4. Abmeldung läuft über CAFAuthenticationSignOut lokal und bei Keycloak; Multi-Tenancy ist deaktiviert, Keycloak-Gruppen ersetzen keine GZ-Rolle oder ABP-Permission.
5. Jeder nachfolgende Application-Service-Aufruf prüft serverseitig erneut seine Permission — die Anmeldung allein gewährt keinen Fachzugriff.

6.2 Anhörungs-Lebenszyklus

Der Hauptstatus einer Anhörung (RALQMHearings, Feature Hearings) ist:

Draft → PendingApproval → Approved → Dispatched → Adjudication → Completed        (zweistufig)
Draft → PendingApproval → Approved → Dispatched ─────────────→ Completed          (einstufig)
  └────────────────────── benannte Rücksprünge/Abbruch nach Fachregel ──────────────────────┘

Die Wahl der Abschlussvariante (US-33) entscheidet, ob Adjudication als eigener Status durchlaufen wird — siehe Punkt 7 unten und Einführung und Ziele.

sequenceDiagram
    actor R as Referent (RALQMCaseOfficer)
    actor M as Geschäftsführung (RALQMManagement)
    participant H as Hearings AppService
    participant Out as Hearing-Outbox
    participant W as ABP Background Worker

    R->>H: Anhörung anlegen (Draft)
    R->>H: Teilnehmer zuordnen (InstitutionId aus Institutions.Contracts)
    R->>H: Dokumente zuordnen (DocumentId aus Documents.Contracts)
    R->>H: Zur Freigabe einreichen (PendingApproval)
    M->>H: Freigeben (Approved, andere Person als Einreichung, Composition Hash sperrt Stand)
    H->>Out: Versand enqueuen (RALQMHearingOutboxMessages)
    Out->>Out: Sendeversuche mit Retry und Idempotency Key (RALQMHearingSendAttempts)
    H-->>H: Dispatched
    Note over H: Adjudication-Fenster: nur Endfassungen neu/ersetzt
    W->>H: Fristen als Due Actions verarbeiten (RALQMHearingDueActions)
    H->>H: Rückmeldungen/Antworten der Teilnehmer (RALQMHearingResponses, ...Replies)
    M->>H: Bescheidung versenden (Fenster schließt, Komposition fixiert)
    H-->>H: Completed

1. Anlegen: Draft entsteht über den owning Application Service; jede Statustransition ist eine benannte Aggregate-Operation (kein SetStatus).
2. Teilnehmer/Institution: Hearings referenziert Institutionen nur über die InstitutionId aus Institutions.Contracts — keine Cross-Module-Navigation oder -Foreign-Key.
3. Freigabe: Der Wechsel nach Approved erzwingt eine andere handelnde Person als die Einreichung und sperrt die geprüfte Dokumentzusammensetzung über einen Composition Hash.
4. Versand: Kein "Best effort" im Request — eine persistente Hearing-Outbox mit Sendeversuchen, Retry und Idempotency Keys entkoppelt Versand von der HTTP-Antwort.
5. Fristen/Antworten: Persistente Due Actions und ABP Background Workers lösen fällige Aktionen aus; Konto- und (Übergangsweise noch) Gastpfad legen ihre Stellungnahme innerhalb der wirksamen Frist an oder ändern sie mit dem zuletzt gelesenen Concurrency-Stand.
6. Adjudication-Fenster (nur zweistufige Abschlussvariante): Ab Eintritt in Adjudication dürfen bis zum ersten Bescheidungsversand nur als Endfassung markierte Dokumente additiv angelegt, ersetzt oder freigegeben werden; die ursprünglich freigegebene Komposition bleibt nachvollziehbar.
7. Abschluss: Bei zweistufiger Variante schließt der Bescheidungsversand das Fenster, fixiert die versendete Komposition samt Prüfsumme und überführt die Anhörung nach Completed. Bei einstufiger Abschlussvariante (US-33) gehen Bescheidung und Endfassung in einem Vorgang hinaus, ohne den Adjudication-Status gesondert zu durchlaufen.
8. Neben ABP Audit Logging führt Hearings eine PII-arme fachliche Historie (RALQMHearingHistoryEntries); Freitexte, Dokumentinhalte und Zugangstokens erscheinen dort nie.

Details zu Datenownership und Tabellen stehen in Querschnittliche Konzepte §2.

6.3 Externe Kontoprovisionierung

Zwei getrennte, beide fail-closed arbeitende Pfade nutzen denselben kontrollierten Keycloak-Admin-Port (IKeycloakAdminClient/KeycloakAdminHttpClient im Feature Authorization) über den dedizierten vertraulichen Client caf-qualitymarks-provisioning (nur Rolle manage-users, kein Browser-/Direktzugriffs-Flow).

sequenceDiagram
    actor U as Berechtigter Benutzer
    participant UI as Institutions/Authorization.Blazor
    participant Auth as Authorization AppService
    participant Kc as Keycloak Admin API

    alt Kontakteinladung (aus Kontaktsuche)
        U->>UI: Kontakt in institutionsübergreifender Suche wählen
        UI->>Auth: stabile Kontakt-ID übergeben
        Auth->>Kc: Konto per E-Mail suchen
        alt kein/eindeutiges Match
            Auth->>Kc: Konto anlegen bzw. Subject bestätigen
            Kc-->>Auth: sub
            Auth-->>UI: Einladung versendet (keine automatische Fachrolle)
        else mehrdeutig
            Auth-->>UI: Fehler AmbiguousEmail (geschlossen abgelehnt)
        end
    else Mitarbeitendenkonto (/administration/mitarbeitendenkonten)
        U->>UI: Name, E-Mail, genau eine GZ-Produktrolle
        UI->>Auth: Anlage-/Wiedereinladungsauftrag
        Auth->>Kc: Subject strikt bestätigen
        Kc-->>Auth: sub
        Auth->>Auth: lokale ABP-Projektion + Rollen-Grant setzen
        Auth-->>UI: Konto aktiv, ggf. Wiedereinladung nur bei ausdrücklicher Wahl
    end

1. Kontaktbasierte Einladung: ausgelöst aus der institutionsübergreifenden Kontaktsuche; die UI übergibt nur die stabile Kontakt-ID an den Provisionierungsport. E-Mail-Gleichheit erteilt keine Fachberechtigung — Identitäten werden über sub korreliert. Ein bereits vorhandenes eindeutiges Konto erhält eine erneute Einladung statt eines Dublettenkontos; es wird keine automatische Hearing-Teilnahme oder Fachrolle vergeben.
2. Mitarbeitendenkonto: einziger Anlage-/Wiedereinladungseinstieg ist die GZ-Seite /administration/mitarbeitendenkonten. Sie verlangt Name, E-Mail und genau eine Produktrolle, bestätigt das Keycloak-Subject strikt und weist die Rolle erst der lokalen ABP-Projektion zu. Wiederholte Aufrufe versenden ohne ausdrücklich gewählte Wiedereinladung keine neue E-Mail. Rollenwechsel, Sperren und Entsperren sind optimistisch concurrency-geschützte, auditierte GZ-Writes und wirken nur lokal (keine globale Keycloak-Sperre).
3. Fehlerfälle scheitern geschlossen und sind stabil kodiert: ExternalAccountProvisioningErrorCodes (RALQM.Authorization:Provisioning:Disabled| AmbiguousEmail|SubjectConfirmationFailed|InvalidSubject) für den Kontaktpfad, StaffAccountErrorCodes (RALQM.Authorization:StaffAccounts:InvalidInput|InvalidRole| LocalUserNotFound|ProductRoleNotFound|NotExternallyLinked|ConcurrencyConflict) für Mitarbeitendenkonten.
4. Die ABP-eigene Benutzerseite ist für keinen der beiden Pfade ein unterstützter GZ-Weg und wird von den GZ-Seiten nicht verlinkt.

6.4 Dokumentfreigabe

ABP File Management besitzt Dateimetadaten und BLOB-Inhalt; CAF.Modules.Documents (src/Modules/Documents) kapselt sie hinter dem neutralen, permission-freien Port IDocumentContentPort. Permission-Freiheit bedeutet: Der aufrufende GZ-Use-Case muss die Objektberechtigung vollständig geprüft haben, bevor er den Port aufruft — eine DocumentId, URL oder ein Dateiname verleiht selbst nie Zugriff. Vier Zugriffswege bleiben strikt getrennt; der Gastlink ist dabei der auslaufende Übergangspfad zur kontogebundenen Teilnahme als Zielzustand (siehe Einführung und Ziele):

sequenceDiagram
    actor P as Zugreifende Partei
    participant F as Feature-Prüfung (Hearings/Institutions)
    participant Grant as Hearing-Dokument + Teilnehmergrant
    participant Port as IDocumentContentPort
    participant Fm as ABP File Management + BLOB

    alt Interner Benutzer
        P->>F: Permission + Hearing-Objektprüfung
    else Gastlink
        P->>F: Einladung, Hearing-Status, aktiver Teilnehmer neu validieren
        F->>Grant: Dokumentgrant prüfen
    else Angemeldeter Teilnehmer
        P->>F: aktive Kontobindung + Teilnehmerprüfung
        F->>Grant: Dokumentgrant prüfen
    else Direkter CAF-Share
        P->>F: Token-Hash + Ablauf + Widerruf prüfen (DocumentShareGrantStore)
    end
    F->>Port: OpenAsync(DocumentId) — erst nach vollständiger Autorisierung
    Port->>Fm: Descriptor + BLOB lesen
    Fm-->>P: Inhalt (no-store, Rate Limiting bei anonymen Pfaden)

1. Intern: ABP Permission plus Hearing-/Dokumentprüfung vor dem Aufruf des Content-Ports.
2. Gastlink (Übergangspfad): Einladung, Ablauf/Widerruf, Hearing-Status, aktiver Teilnehmer und Dokumentgrant werden bei jedem Zugriff neu geprüft — der geschützte Browser-/Circuit-Kontext ist nur Transportmittel. Eine gültige Einladung darf in mehreren Sitzungen verwendet werden; parallele Einlösungen laufen in einer frischen, begrenzt wiederholten Transaktion mit vollständiger Revalidierung.
3. Kontogebunden (Zielzustand): aktueller ABP-Benutzer, aktive Kontobindung und derselbe Objekt-/Grant-Pfad werden erneut geprüft. Kanonischer Einstieg ist /portal/zugang-uebernehmen (/portal/teilnahme-beanspruchen bleibt Kompatibilitätsalias).
4. Direkter CAF-Share: eigenständiger, bewusst anonymer Use Case über CAFDocumentShareGrants/DocumentShareGrantStore — Secret wird nur gehasht gespeichert, läuft ab, ist einzeln widerrufbar und rate-limitiert. Er ersetzt nie den Hearing-Gastlink.
5. Stellungnahme-Anhänge folgen denselben drei Mustern (intern: Responses.Read + ID-Kette; Gast/ Konto: Revalidierung plus Beschränkung auf die eigene Rückmeldung), bevor die interne DocumentId an den Content-Port übergeben wird.
6. Jeder abgelehnte Binärzugriff liefert eine nicht enumerierbare 404-Antwort mit no-store und nosniff; Descriptor-ID und Dateiname autorisieren nie.

Weiterführend: Sicherheitskonzepte, Bausteinsicht und die Betriebssicht für Kennzahlen/Korrelation in GETTING-STARTED.md §10a.

07. Verteilungssicht

1. Überblick

CAF.Applications.RAL.QualityMarks.HearingPortal (RALQM, "RAL Gütezeichen Anhörungsportal") läuft lokal als Zweiknoten-Deployment: ein nativer .NET-Prozess (der Blazor-Server-Host) und eine Docker-Compose-Infrastruktur mit SQL Server, Keycloak und Mailhog. Es gibt keine separate Web-/API-/Worker-Trennung — Host, Application Services, Blazor-UI, EF-Migrationen und Hintergrundarbeiter laufen im selben Prozess (siehe Bausteinsicht für die fachliche Modulaufteilung, Kontextabgrenzung für die Nachbarsysteme).

┌─────────────────────────────── Windows-Workstation ───────────────────────────────┐
│                                                                                     │
│  dotnet-Prozess (Kestrel, Blazor Interactive Server)                               │
│  CAF.Applications.RAL.QualityMarks.HearingPortal (Host)                            │
│  https://localhost:44356                                                           │
│    - Shell, Features/{Authorization,Hearings,Institutions}, Contracts              │
│    - CAF.Modules.{Authentication, Documents, UI.Blazor}                            │
│    - EF Core (SQL Server Provider), ABP Background Worker                          │
│                                                                                     │
│         │ SQL (TCP 127.0.0.1:1433)     │ OIDC (HTTP 127.0.0.1:8080)   │ SMTP        │
│         ▼                              ▼                              ▼            │
│  ┌───────────────────────── Docker Compose: backend-Netzwerk ──────────────────┐   │
│  │                                                                              │   │
│  │  sqlserver            keycloak                 mailhog                      │   │
│  │  mssql/server:2022    keycloak:26.7.0           mailhog:v1.0.1               │   │
│  │  DBs: RALQM, keycloak  Realm "caf", start-dev    SMTP-Fänger, In-Memory      │   │
│  │  Volume: sqlserver_data (extern, persistent)                                │   │
│  │                                                                              │   │
│  │  sqlserver-init (init-Container, läuft einmalig)                            │   │
│  │  keycloak-provisioner (init-Container, läuft einmalig)                      │   │
│  │                                                                              │   │
│  └──────────────────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────────────┘

Alle Compose-Ports sind ausschließlich an 127.0.0.1 gebunden; es gibt keinen produktiven Cloud- oder Cluster-Knoten in diesem Repository. Produktionsbetrieb, Backupstrategie und Monitoring werden aus dieser lokalen Development-Umgebung nicht abgeleitet (siehe DEVELOPMENT-GUIDE.md, Abschnitt "Docker-Compose-Umgebung ist ausschließlich für lokale Development-Daten").

2. Knoten und Erreichbarkeit

APP_URL, KEYCLOAK_PUBLIC_URL und SQLSERVER_PORT kommen aus etc/docker/.env; obige Werte sind die mitgelieferten Development-Defaults. Die Mailhog-Ports liegen fest im Compose-File. Der Host bindet Kestrel über launchSettings.json (src/Applications/RAL/QualityMarks/HearingPortal/Host/Properties/launchSettings.json) an denselben Port 44356, mit dem APP_URL übereinstimmen muss — beide Werte werden beim Start gegeneinander geprüft (siehe GETTING-STARTED.md, Abschnitt 1 und 6).

3. Docker-Compose-Dienste

Definiert in etc/docker/docker-compose.yml (Compose-Projekt ral-qualitymarks-hearing-portal):

Alle Dienste hängen am Bridge-Netzwerk ral-qualitymarks-hearing-portal-backend und schreiben begrenztes JSON-File-Logging (max-size: 10m, max-file: 3). Die kausal abhängige Kette SQL → Principal → Keycloak → Reconcile → Migration läuft laut DEVELOPMENT-GUIDE.md (Abschnitt 13) nie parallel; lediglich Keycloak und Mailhog starten beim Kaltstart gleichzeitig.

Persistentes Volume

Genau ein externes, benanntes Volume trägt den gesamten Datenbankzustand:

volumes:
  sqlserver_data:
    name: ral-qualitymarks-hearing-portal-sqlserver-data
    external: true

external: true bedeutet: Compose legt es nicht implizit an — die Lifecycle-Skripte (start.cmd/setup.cmd) erzeugen und besitzen es explizit. Es überlebt stop.cmd und restart.cmd. Der einzige destruktive Standardpfad ist reset.cmd, strikt begrenzt auf ENVIRONMENT_NAME=Development und exakt dieses Volume (siehe GETTING-STARTED.md, Abschnitt 5).

.env-gesteuerte Konfiguration

Die einzige lokale, nicht versionierte Compose-Konfigurationsdatei ist etc/docker/.env (Vorlage: etc/docker/.env.example). Sie legt Image-Digests, Ports, SQLSERVER_SA_PASSWORD, RALQM_DB_PASSWORD, KEYCLOAK_ADMIN_PASSWORD, KEYCLOAK_DB_PASSWORD, KEYCLOAK_CLIENT_SECRET, KEYCLOAK_PROVISIONING_CLIENT_SECRET, KEYCLOAK_DEV_ADMIN_PASSWORD, KEYCLOAK_DEV_USER_PASSWORD, APP_URL und TIME_ZONE fest. setup.cmd erzeugt die Datei aus der Vorlage und ersetzt jeden CHANGEME-Platzhalter durch einen zufälligen lokalen Wert, ohne bestehende Werte zu überschreiben. Secrets erscheinen nie im Repository; Diagnosewege (doctor.cmd) melden nur SET/MISSING (siehe Abschnitt 13 im DEVELOPMENT-GUIDE.md und Querschnittskonzepte für die vollständige Secret-Regel).

4. Der Host-Prozess

Der ausführbare Knoten ist ein einzelner .NET-Prozess: das Projekt src/Applications/RAL/QualityMarks/HearingPortal/Host/CAF.Applications.RAL.QualityMarks.HearingPortal.csproj, gestartet nativ auf Windows (kein Container). Er bündelt in einem Prozess:

• Kestrel-Endpunkt mit Blazor Interactive Server Rendering (kein WASM-Bootstrap),
• die Composition Root, die Shell, Contracts und alle Features/*- sowie CAF.Modules.*-Bausteine referenziert (siehe Bausteinsicht), entsprechend der No-Layer-Architektur aus dem Root-AGENTS.md,
• den EF-Core-DbContext samt Migrations-Host (src/Applications/RAL/QualityMarks/HearingPortal/Host/Migrations),
• ABP Background Worker für Postausgang/Fristenaktionen (Outbox, Due Actions).

Konfigurationsquellen werden in fester Priorität zusammengeführt (siehe DEVELOPMENT-GUIDE.md, Abschnitt 13):

versionierte appsettings-Dateien
  < abgebildete etc/docker/.env (nur Development-Workstation)
  < appsettings.local.secrets.json
  < Umgebungsvariablen
  < Kommandozeilenargumente

Host/Configuration/DevelopmentDockerEnvironmentConfiguration.cs liest dafür nur in IsDevelopment() die Datei etc/docker/.env (relativ zum per CAF.slnx-Marker gefundenen Repository-Root) und leitet daraus App:SelfUrl, App:RedirectAllowedUrls, ConnectionStrings:Default (Server 127.0.0.1,<SQLSERVER_PORT>, Datenbank RALQM, Login ralqm), Authentication:Authority (<KEYCLOAK_PUBLIC_URL>/realms/caf) sowie die Keycloak-Provisioning-Werte ab. Damit liest F5 aus Visual Studio dieselbe Laufzeitkonfiguration wie start.cmd, ohne einen vorgeschalteten PowerShell-Prozess zu benötigen. Fehlt .env oder ist ein Pflichtwert noch CHANGEME, bricht der Start fail-closed mit einer expliziten Meldung ab.

5. Migration und Seed (--migrate-database)

Schema und Demodaten werden nicht implizit beim normalen Start ausgeführt, sondern über denselben Host-Prozess mit einem expliziten Kommandozeilenschalter:

dotnet run --project src/Applications/RAL/QualityMarks/HearingPortal/Host -- --migrate-database

Program.cs erkennt --migrate-database (IsMigrateDatabase), schaltet auf ein Migrations-Logging-Profil um und ruft nach InitializeApplicationAsync() den HearingPortalDbMigrationService auf. Dieser läuft in drei Schritten:

1. EnsureMigrationsExist() — der HearingPortalMigrationPathGuard sucht ab dem Startverzeichnis nach dem CAF.slnx-Repository-Marker und verlangt, dass src/Applications/RAL/QualityMarks/HearingPortal/Host/Migrations existiert und mindestens eine echte Migrationsklasse enthält (kein .Designer.cs, kein ModelSnapshot.cs) — ein Schutz gegen einen falsch aufgesetzten Arbeitsbaum.
2. MigrateDatabaseSchemaAsync() — führt die EF-Core-Migrationen über den HearingPortalDbSchemaMigrator gegen die RALQM-Datenbank aus.
3. SeedDataAsync() — ruft ABPs IDataSeeder mit einem zufällig erzeugten, deaktivierten Bootstrap-Administratorpasswort auf (kein festes Secret im Code).

Praktisch läuft dieser Schritt in den Lifecycle-Skripten mit einem separaten, nur für den Bootstrap privilegierten SQL-Zugang; danach reconciliiert start.cmd den dauerhaften, eingeschränkten qualitymarks-Datenbankprincipal (siehe GETTING-STARTED.md, Abschnitt 6, Schritt 9). Migration und Seed sind idempotent: ein wiederholter Lauf legt keine Duplikate an und überschreibt keine vorhandenen Demodaten (setup.cmd -WithDemoData erzwingt den Abgleich bewusst erneut).

6. Lokaler Start- und Betriebsweg

Der schlanke, skriptlose Pfad — vorausgesetzt etc/docker/.env und appsettings.local.secrets.json liegen bereits vor:

# 1. Infrastruktur (SQL Server, Keycloak, Mailhog)
docker compose -f etc/docker/docker-compose.yml up -d

# 2. Schema/Seed (nur beim ersten Start bzw. nach neuen Migrationen)
dotnet run --project src/Applications/RAL/QualityMarks/HearingPortal/Host -- --migrate-database

# 3. Anwendung starten
dotnet run --project src/Applications/RAL/QualityMarks/HearingPortal/Host

Der komfortable, empfohlene Weg sind die Root-.cmd-Wrapper (setup.cmd, start.cmd, status.cmd, stop.cmd, restart.cmd, reset.cmd, doctor.cmd, logs.cmd), dünne Aufrufer der kanonischen PowerShell-Skripte unter tools/scripts. start.cmd führt deterministisch aus: SDK-/Zertifikatsprüfung → Restore → Docker-/Volume-Prüfung → SQL Server + Init-Container → Keycloak + Mailhog parallel → Keycloak-Reconciliation → Migration/Seed → qualitymarks-Principal-Reconciliation → Start des Host-Prozesses als versteckter Windows-Prozess (PID-Datei unter %LOCALAPPDATA%\CAF.Applications.RAL.QualityMarks.HearingPortal). Details, Idempotenz-Garantien und alle Kommandovarianten stehen in GETTING-STARTED.md, Abschnitte 4–6.

7. Zuordnung Bausteine → Infrastruktur

Es gibt keine eigenständig deploybaren Knoten je Feature-Modul: die No-Layer-Architektur (Root-AGENTS.md) bündelt alle Fachmodule im selben Host-Prozess; nur die Infrastrukturdienste (SQL Server, Keycloak, Mailhog) sind eigene Container. Ein produktiver Mehrknotenbetrieb, Load Balancing oder eine Cloud-Zielumgebung sind nicht Bestandteil dieses Repositories.

8. Siehe auch

• Bausteinsicht — fachliche und technische Modulaufteilung innerhalb des Host-Prozesses.
• Laufzeitsicht — Ablauf einzelner Anwendungsfälle über diese Knoten hinweg.
• Querschnittskonzepte — Secret-Handling, Konfigurationspriorität, Auditierung.
• GETTING-STARTED.md — vollständiger Einstieg inkl. Lifecycle-Skripten, Diagnose und Kennzahlen.
• DEVELOPMENT-GUIDE.md — Konfigurationsregeln (Abschnitt 13) und Qualitätsgate (Abschnitt 15).
• etc/docker/docker-compose.yml — normative Dienstdefinition.

08. Querschnittliche Konzepte

Dieses Kapitel bündelt Konzepte, die mehrere Module gleichermaßen betreffen: Authentifizierung/ Autorisierung, Persistenz, persistierte Kennungen, Lokalisierung, UI-Grenzen, Fehlerbehandlung und Teststrategie. Die Modulgrenzen selbst stehen in Bausteinsicht, der konkrete Ablauf eines Requests in Laufzeitsicht.

1. Authentifizierung und Autorisierung

Keycloak (OIDC, Authorization Code + PKCE)
  → CAF.Modules.Authentication (Cookie-Session, Claim-Mapping, Revalidierung)
    → lokaler ABP IdentityUser, gebunden über den stabilen OIDC-Subject "sub"
      → RALQM-Rolle (Administrator/CaseOfficer/Management)
        → ABP Permission (RALQM.<Feature>…)
          → Application Service + Objektprüfung

• Keycloak ist alleiniger Token-Issuer und Identitätsquelle; die Anwendung betreibt keinen lokalen OpenIddict-Server.
• CAF.Modules.Authentication ist der wiederverwendbare, anwendungsneutrale OIDC-Client (Authorization Code mit PKCE, Cookie-Session-Policy, Token-Propagierung, revalidierender AuthenticationStateProvider, Sign-out). Er kennt weder GZ-Rollen noch Permissions — siehe src/Modules/Authentication/README.md.
• ABP Identity speichert das lokale Benutzerabbild. Die Verknüpfung verwendet ausschließlich den stabilen sub, niemals die E-Mail-Adresse.
• HearingPortal.Authorization definiert die produktweiten Rollen (HearingPortalRoles: RALQMAdministrator, RALQMCaseOfficer, RALQMManagement) und komponiert deren Grants aus den Permissions der Feature-Contracts. Ein neues Feature-Recht wird nicht zentral in Authorization deklariert, sondern im owning {Feature}.Contracts-Projekt.
• Die Permission-Gruppe heißt RALQM (HearingPortalPermissions.GroupName); Feature-Permissions hängen sich darunter an, zum Beispiel RALQM.Hearings.Approve oder RALQM.Accounts.Invite.
• Jeder Application Service prüft seine Permission serverseitig; Objektzugriff, Status und Teilnehmerzuordnung werden zusätzlich im owning Feature geprüft. Ein versteckter Button ist keine Autorisierung.

Kontoprovisionierung

Zwei getrennte, kontrollierte Wege binden Menschen an Keycloak-Konten — beide über denselben schmalen, fail-closed Provisionierungsport, nie über E-Mail-Gleichheit:

• Institutionskontakte: aus der institutionsübergreifenden Kontaktsuche ausgelöst, korreliert über sub; ein vorhandenes Konto erhält eine erneute Einladung statt eines Dublettenkontos, Mehrdeutigkeit scheitert geschlossen (ExternalAccountProvisioningErrorCodes).
• Mitarbeitendenkonten: ausschließlich über /administration/mitarbeitendenkonten, mit Name, E-Mail und genau einer Produktrolle; Rollenwechsel sowie Aktivieren/Sperren/Entsperren sind optimistisch concurrency-geschützte, auditierte lokale Writes (StaffAccountErrorCodes). Die ABP-Benutzerseite ist kein unterstützter GZ-Kontenpfad.

Details zu Dokument- und Portalzugriffswegen (intern, Kontobindung als Zielzustand, Gastlink als auslaufender Übergangspfad, Direkt-Share) stehen in Laufzeitsicht; Multi-Tenancy ist deaktiviert, Keycloak-Gruppen ersetzen keine GZ-Rollen oder ABP-Permissions.

2. Persistenz und EF Core

• SQL Server ist der einzige relationale Provider; es gibt genau einen HearingPortalDbContext und einen Migration Host im Projekt HearingPortal (Host).
• Jedes Modul definiert seine Entities und eine eigene Configure{Feature}()-ModelBuilder- Erweiterung in seiner Runtime; der Host ruft diese Erweiterungen nur auf und besitzt keine fachliche Konfiguration.
• Migrationen werden ausschließlich im Host erzeugt und ausgeführt (HearingPortal/Migrations), gegen eine echte, disposable SQL-Server-Datenbank getestet und mit dotnet ef migrations has-pending-model-changes als Pending-Model-frei nachgewiesen.
• Beziehungen innerhalb eines Moduls verwenden echte Foreign Keys und Indizes. Über Modulgrenzen werden ausschließlich IDs gespeichert (InstitutionId, DocumentId) — keine Cross-Module- Navigation, kein Cross-Module-Foreign-Key.
• Mutable Aggregate tragen optimistische Concurrency (ConcurrencyStamp); stale Schreibzugriffe scheitern deterministisch statt still zu überschreiben. Zeitpunkte sind UTC über ABPs IClock.
• Fachliche/auditrelevante Daten werden nicht hart gelöscht: Institutionen erst nach Nutzungsprüfung, der Hearing-Prozess über benannte Zustände (Abbruch, Widerruf, Zurückziehen).

Data-preserving Renames

Die laufende RALQM-Umbenennung zeigt das verbindliche Muster für Identifier-Änderungen: Die Migration RenamePersistedIdentifiersToRALQM (HearingPortal/Host/Migrations/20260825174437_RenamePersistedIdentifiersToRALQM.cs) benennt Tabellen (z. B. QualityMarksHearings → RALQMHearings, QualityMarksInstitutions → RALQMInstitutions, CafDocumentShareGrants → CAFDocumentShareGrants) und Indizes per RenameTable/RenameIndex um, statt Daten zu löschen und neu anzulegen. Bereits ausgerollte Migrationen behalten dabei ihre historischen Bezeichner (z. B. Constraint-Namen wie FK_GzHearings_… bleiben in älteren Migrationsschritten unverändert); nur der aktuelle Modellstand und neue Migrationen verwenden das neue Präfix. Diese Regel gilt für jede künftige Umbenennung persistierter Kennungen.

3. Persistierte Kennungen

Zwei getrennte Präfixräume, konsequent nach Ownership:

Technische Slugs (URLs, Docker-/Config-Bezeichner) bleiben bewusst kleingeschrieben, zum Beispiel ral-qualitymarks, und folgen nicht dem Groß-Präfix der persistierten Kennungen. Projekt- und Namespace-Namen (CAF.Applications.RAL.QualityMarks.HearingPortal.*) sind von dieser Konvention unabhängig und ändern sich durch die Umbenennung nicht.

Diese Trennung ist mehr als Namenskosmetik: Sie macht Ownership beim Lesen einer Tabelle, eines Fehlercodes oder einer Permission sofort erkennbar, ohne den Quellcode zu öffnen, und verhindert, dass ein wiederverwendbares CAF-Modul unbemerkt anwendungsspezifisches Wissen aufnimmt (siehe Bausteinsicht zur Modulgrenze CAF.* → HearingPortal.* verboten).

4. Lokalisierung

• UI-Texte sind Deutsch (de-DE als führende Kultur), Code-Identifier und Kommentare Englisch, Logs strukturiert/Englisch.
• Jedes Feature-Contracts-Projekt besitzt seine eigene Lokalisierungsressource und DE/EN-JSON, zum Beispiel HearingPortal.Authorization.Contracts/Localization/Authorization/{de-DE,en}.json. DE- und EN-Schlüssel müssen in beide Richtungen übereinstimmen; hart codierte UI- oder Business-Exception-Texte sind verboten.
• Fehlercode-Namespaces folgen demselben RALQM.<Feature>:-Schema wie die Fehlercodes selbst und werden per AbpExceptionLocalizationOptions.MapCodeNamespace an die Ressource des jeweiligen Feature-Contracts-Projekts gebunden (siehe HearingPortalAuthorizationContractsModule.ConfigureServices: MapCodeNamespace("RALQM.Authorization", typeof(HearingPortalAuthorizationResource))). Ein Fehlercode wie RALQM.Authorization:StaffAccounts:ConcurrencyConflict löst damit automatisch den passenden lokalisierten Text auf.
• ABP Language Management liefert den datenbankgestützten Sprach-/Textprovider im Betrieb; GDPR ergänzt den Cookie-Consent-Pfad.

5. UI- und Cohesion-Grenzen

• Eigene CAF-/GZ-Oberflächen rendern ausschließlich Cohesion (Syncfusion); MudBlazor, Syncfusion-Rohkomponenten oder Blazorise dürfen von Fachcode nicht direkt verwendet werden. Ausgenommen sind die unverändert übernommenen ABP-Administrations-, Account- und LeptonX-Seiten.
• CAF.Modules.UI.Blazor registriert Cohesion, Lizenzprüfung, Assets/Bundles und die Interactive-Server-Policy zentral; es besitzt selbst keine Produktroute.
• Feature-Komponenten setzen kein @rendermode und bleiben render-mode-neutral; der Host wählt Interactive Server. JavaScript-Interop läuft prerender-sicher erst nach interaktivem Rendern.
• Jede datengebundene Oberfläche behandelt, soweit fachlich relevant: Loading, Empty, Error/Retry, Forbidden, Validation, Saving und Stale Concurrency mit Neu-Laden-Option.
• WCAG 2.1 AA ist Mindestziel: semantisches HTML, sichtbarer Tastaturfokus, zugeordnete Labels und nicht ausschließlich farbliche Statusanzeige.

6. Fehlerbehandlung

• User-facing Fehler verwenden stabile, im owning Feature definierte Error Codes nach dem Schema RALQM.<Feature>:<Bereich>:<Grund> (z. B. RALQM.Authorization:Provisioning:AmbiguousEmail, RALQM.Authorization:StaffAccounts:InvalidRole) statt Klartext oder generischer Exceptions.
• Jeder Fehlercode ist über den Code-Namespace des Feature-Contracts-Projekts lokalisiert (siehe Abschnitt 4) — ein neuer Fehlercode ohne DE/EN-Paritätstext gilt als unvollständig.
• Geschützte Application Services unterscheiden deterministisch zwischen Validation, Not Found, Forbidden und Concurrency, soweit diese Unterscheidung keine Information an anonyme Nutzer leakt. Bei Ablehnung bleibt die Persistenz unverändert.
• Für Gastzugriffe (Portal, Dokument-Downloads, Direkt-Share) gilt bewusst das Gegenteil: unterschiedliche interne Ablehnungsgründe werden auf dieselbe äußere Antwort abgebildet (nicht enumerierbare Fehlerform, no-store, nosniff), damit IDs oder Tokens nicht erraten werden können.
• Externe Calls (Keycloak-Admin-Port, IEmailSender) klassifizieren Fehler als Validation, Not Found, Authorization, Conflict oder Unavailable und verwenden Idempotency Keys statt stiller Wiederholung mit Nebenwirkung.

7. Teststrategie

Die Lösung trennt Nachweise nach Risiko statt einer einzigen Testebene zu vertrauen:

Der zentrale Einstieg ist tools/scripts/Invoke-QualityGate.ps1: Preflight, Restore, Build ohne Warnings/Errors, alle Solutiontests und dotnet ef migrations has-pending-model-changes. Übersprungene Pflichttests gelten als Fehlschlag; vor Übergabe oder Merge ist der vollständige Lauf inklusive -IncludeBrowserGate verbindlich. Versionierte Git-Hooks (tools/git-hooks) führen das Gate zusätzlich automatisch bei jedem Commit aus (ohne BrowserGate) und heften die Schrittzusammenfassung als Git-Note refs/notes/quality-gate an den Commit.

Die konkrete Nachweismatrix je Änderungsart (Contract/Permission, Domainregel, geschützter Read/Write, Concurrency, EF-Migration, Dokument-/Portalpfad, Blazor-Komponente, Skript, Dokumentation) steht im Entwicklungsleitfaden §15.

Weiterführend

• Bausteinsicht — Modulgrenzen und Abhängigkeitsrichtung
• Laufzeitsicht — Requestablauf, Dokumentzugriffswege, Hearing-Lebenszyklus
• Architekturentscheidungen — begründete Grundsatzentscheidungen
• ../DEVELOPMENT-GUIDE.md — normative Regeln je Änderungsart
• ../GETTING-STARTED.md — lokaler Stack und Betriebseinstieg
• ../../conventions/ — themenspezifische Coding-Konventionen

09. Architekturentscheidungen

Dieses Kapitel hält die wesentlichen, dauerhaft wirksamen Architekturentscheidungen in ADR-Kurzform fest: Titel, Kontext, Entscheidung, Konsequenz. Details zu Bausteinen stehen in der Bausteinsicht, zu Qualitätsanforderungen in der Qualitätsanforderungen bzw. dem Qualitätsbaum. Die vollständige, laufend gepflegte Konventions-Bewertung inkl. Vor-/Nachteilsabwägung steht in docs/conventions-decisions.md.

ADR-01 · No-Layer-ABP statt klassischer 8-Projekt-Schichtung

• Kontext: ABP-Projekte werden üblicherweise in Domain, Application, EntityFrameworkCore, HttpApi, Blazor usw. je Modul zerlegt. Für einen modularen Monolithen mit überschaubarer Modulzahl erzeugt das viel Projekt-/Verkabelungs-Overhead ohne echten Nutzen.
• Entscheidung: Jedes Fachmodul besteht im Normalfall aus höchstens drei Assemblies: *.Contracts (DTOs, Interfaces, Permissions, Localization, öffentliche IDs), einer Runtime (Domain, Application, EF-Mapping in einer Assembly) und optional *.Blazor (Feature-UI). Domain, Application und Persistence bleiben logische, aber nicht separat materialisierte Schichten. Eine weitere Assembly entsteht erst, wenn sie unabhängig konsumiert, paketiert, ersetzt oder betrieben werden muss.
• Konsequenz: Weniger Projekte/Referenzen, schnellere Builds, geringere Einstiegshürde. Die Abhängigkeitsrichtung (Contracts ↔ Runtime ↔ Blazor, keine Rückkanten) bleibt trotzdem eine Compile-Time-Eigenschaft, durchgesetzt durch Architekturtests statt durch Projektgrenzen allein (siehe ADR-05). Konvention ABP-11 in conventions-decisions.md markiert die klassische 8-Schichtung entsprechend als N/A für dieses Repository.

ADR-02 · Monorepo mit Host + wiederverwendbaren CAF-Modulen + einer RAL-Anwendung

• Kontext: CAF.Modules.* (Authentication, Documents[.Contracts], UI.Blazor) sind anwendungsneutrale Bausteine; HearingPortal ist die einzige heute existierende Anwendung, die sie konsumiert. Getrennte Repositories hätten Versions-Ping-Pong zwischen Framework und Anwendung erzwungen, obwohl beide im selben Entwicklungstakt reifen.
• Entscheidung: Ein Repository (CAF.slnx) bündelt src/Modules/ (CAF-Bausteine) und src/Applications/RAL/QualityMarks/HearingPortal/ (Host, Shell, Contracts, Features). Die Solution gliedert dies in der IDE als vier Gruppen (Anwendung, CAF-Bausteine, Fachmodule, Tests).
• Konsequenz: Ein Commit kann Framework und Anwendung atomar ändern; Refactorings über die Grenze sind ohne Cross-Repo-Release möglich. Im Gegenzug muss die Modulgrenze CAF.Modules.* → Applications.* verboten bleiben, sonst verwischt das Monorepo den eigentlichen Zweck der Module (wiederverwendbar, anwendungsneutral) — durchgesetzt in ADR-05. Die vier CAF-Bausteine bleiben dabei bewusst Quellcode-Bausteine und werden nicht paketiert (ADR-03); der Host konsumiert sie ausschließlich per ProjectReference.

ADR-03 · CAF-Bausteine als Quellcode-Bausteine mit Vertragsdatei (VERTRAG.md)

• Kontext: CAF.Modules.Authentication, CAF.Modules.UI.Blazor, CAF.Modules.Documents und CAF.Modules.Documents.Contracts sollen wiederverwendbar bleiben, ohne dass Konsumenten sich auf undokumentierte interne Details verlassen. Eine frühere Fassung dieser Entscheidung sah echte NuGet-Pakete vor (IsPackable=true, eigene PackageId/Version, Pack-Skript). Das wurde zurückgenommen: es gab keinen Konsumenten außerhalb dieses Repositorys, also war es Paketinfrastruktur ohne Abnehmer — mit Versionspflege, Feed-Frage und NU5104-Rauschen als laufenden Kosten.
• Entscheidung: Die Bausteine sind Quellcode-Bausteine, keine NuGet-Pakete. Jedes der vier csproj setzt IsPackable=false und trägt keine PackageId, keine Version und kein PackageReadmeFile; der Host konsumiert sie ausschließlich per ProjectReference. Die verbindliche Vertragsgrenze bleibt die deutschsprachige VERTRAG.md im Wurzelverzeichnis des jeweiligen Projekts — als Quelltext-Vertrag: zugesicherte öffentliche Fläche, ausdrückliche Nicht-Zusicherungen, Versionierungsregel für den Fall einer späteren Paketierung. Ein Pack-Skript existiert nicht.
• Konsequenz: Kein Versions-Ping-Pong und kein Feed-Zwang für die tägliche Entwicklung; die Wiederverwendbarkeit ist eine Eigenschaft des Abhängigkeitsgraphen (ADR-06), nicht einer Paketgrenze. Der Vertrag ist trotzdem geschrieben und maschinell verankert: FrameworkPackagingTests pinnt genau vier CAF.Modules-Projekte, deren Nicht-Packbarkeit samt fehlender Paketidentität, und dass jede VERTRAG.md existiert, nicht leer ist und beide Pflichtabschnitte trägt. Ein versehentliches IsPackable=true oder eine gelöschte Vertragsdatei bricht den Build. Preis: Ein Konsument außerhalb dieses Repositorys ist heute nicht bedienbar — er bräuchte zuerst eine erneute Paket- und Feed-Entscheidung. Ein zweites Produkt im Repository funktioniert ohne Änderung.

ADR-04 · RALQM als data-preserving Umbenennung persistierter Kennungen

• Kontext: Das Produkt hieß im Code zunächst Guetezeichen, dann QualityMarks; die verbindliche Kurzform für persistierte, anwendungsspezifische Kennungen ist inzwischen RALQM (Tabellen RALQMHearings/RALQMInstitutions, Fehlercode-Präfix RALQM.<Feature>:, Permission-Gruppe RALQM, Rollen RALQMAdministrator/RALQMCaseOfficer/RALQMManagement). Technische Slugs (z. B. Docker-/Keycloak-Client-IDs wie ral-qualitymarks) bleiben bewusst lowercase und wurden nicht mitgezogen.
• Entscheidung: Jede Umbenennung persistierter Bezeichner erfolgt ausschließlich über eine data-preserving EF-Migration (RenamePersistedIdentifiersToRALQM, siehe src/Applications/RAL/QualityMarks/HearingPortal/Host/Migrations/) mit korrekt gespiegeltem Down(); historische Migrationen behalten ihre alten, zum jeweiligen Zeitpunkt gültigen Bezeichner (z. B. AddCafDocumentShareGrants) und werden nicht nachträglich editiert (Konvention EF-03). Bestehende Dev-Datenbanken werden über ein eigenständiges, nicht-destruktives Skript migriert (tools/scripts/Migrate-DevDatabaseToRalqm.ps1: klont das Docker-Volume, benennt DB/Login auf der Kopie um, Quelle bleibt Rollback-fähig).
• Konsequenz: Rename-Operationen sind reversibel und laufen ohne Datenverlust, auch auf Anwendungsdatenbanken mit Bestand (verifiziert per Round-Trip apply→revert→re-apply sowie gegen echte Dev-Daten: Tabellen-/User-/Grant-Zahlen vor/nach Migration identisch). Der Preis ist zusätzliche Migrations- und Skript-Pflege statt einer einfachen Such-Ersetzen-Operation im Quellcode.

ADR-05 · Cohesion als verbindliche UI-Bibliothek für Fachcode

• Kontext: ABP liefert LeptonX/MudBlazor für Account-, Administrations- und Themenseiten mit. Für die eigene Gütezeichen-Fachoberfläche soll es eine einheitliche, kapselnde Komponentenbasis geben statt direkter Vendor-Kopplung in jeder Feature-Komponente.
• Entscheidung: Eigene CAF-/RALQM-Seiten verwenden ausschließlich Cohesion, zentral über CAF.Modules.UI.Blazor registriert (Lizenzprüfung, Assets/Bundles; Paket aus dem GitLab-Gruppen-Feed, zentrale Floating-Version 3.*-*). MudBlazor, Syncfusion oder Blazorise dürfen von Fachcode nicht direkt gerendert werden; ABP-gelieferte Account-/Administrations-/LeptonX-Seiten sind davon ausgenommen und behalten ihren eigenen UI-Stack. Nur Interactive Server wird unterstützt, kein WebAssembly; Feature-Komponenten bleiben render-mode-neutral (kein @rendermode im Feature-UI).
• Konsequenz: Vendor-Details sind in Wrappern gekapselt, ein späterer UI-Bibliothekswechsel bliebe lokal begrenzt. Fehlende generische UI-Primitives gehören in die separat versionierte Cohesion-Bibliothek, nicht in Fachcode-Workarounds. Die Regel ist kein Stilhinweis, sondern arch-test-erzwungen (BL-01/BL-02 in conventions-decisions.md).

ADR-06 · Strikte Modulgrenzen durch Architekturtests statt Konvention allein

• Kontext: Ordnerstruktur und Namensschema allein verhindern in der Praxis keine Querabhängigkeiten — insbesondere unter Zeitdruck oder bei automatisiertem/agentischem Edit. Der No-Layer-Ansatz (ADR-01) und das Monorepo (ADR-02) erhöhen dieses Risiko zusätzlich, weil alle Module im selben Prozess und Repository liegen.
• Entscheidung: Die Abhängigkeitsrichtung ist explizit tabelliert (siehe Bausteinsicht) und über Architekturtests erzwungen, u. a.: CAF.Modules.* → Applications.* verboten, Contracts referenzieren nie Runtime/EF/Host, Feature-Blazor referenziert nie die eigene oder eine fremde Runtime, GZ-Runtime referenziert nie fremde Runtime/Entities/Repositories/DbSets/Tabellen, kein Modul referenziert den ausführbaren Host, keine neue Fachlogik/Fachentity im Host. Über Modulgrenzen werden nur IDs gespeichert, nie Cross-Module-Foreign-Keys oder -Navigation (z. B. InstitutionId/DocumentId statt Entity-Referenz).
• Konsequenz: Grenzverletzungen sind Build-Fehler, nicht Review-Findings. Renames und Restrukturierungen (siehe AGENT_CHANGELOG, z. B. die Gruppierung der Feature-Slices unter src/Applications/RAL/QualityMarks/HearingPortal/Features/<Feature>/ oder die RALQM-Umbenennung) dürfen laut Projektregel die Grenzregeln selbst nie lockern, sondern ausschließlich Pfad-Literale in den Tests nachziehen. Das hält die Compile-Time-Eigenschaft auch über viele aufeinanderfolgende Strukturänderungen hinweg stabil.

Referenzen

• Laufendes ADR-Register mit Vor-/Nachteil je einzelner Konvention: docs/conventions-decisions.md
• Gesamtarchitektur inkl. Modulverzeichnis und Abhängigkeitstabelle: Bausteinsicht; Qualitätsnetz: Querschnittliche Konzepte §7
• Nachvollziehbarkeit der Entscheidungsumsetzung je Arbeitsschritt: AGENT_CHANGELOG.md
• Vertiefung Bausteine/Schnitt: Bausteinsicht; Vorgaben für neue Features: Entwicklungsleitfaden, conventions/

10. Qualitätsanforderungen

Dieses Kapitel benennt, welche Qualitätsmerkmale für das RAL Gütezeichen Anhörungsportal verbindlich sind, und macht sie an konkreten, prüfbaren Szenarien fest. Architekturentscheidungen in Bausteinsicht und Querschnittliche Konzepte werden gegen genau diese Anforderungen getroffen; Risiken und technische Schulden benennt, wo sie aktuell nur teilweise erfüllt sind.

10.1 Qualitätsbaum

Der ausschlaggebende Werttreiber ist ein rechtssicherer, nachvollziehbarer Anhörungsprozess auf einer Plattform, die als modularer Monolith langfristig ohne Umbau der Kernarchitektur weiterentwickelbar bleibt (vgl. Einführung und Ziele). Daraus leiten sich fünf gleichrangige Qualitätsäste ab, die im Projekt jeweils durch Architektur und durchsetzende Tests abgesichert sind statt nur dokumentiert zu werden (CLAUDE.md):

Qualität RAL-Gütezeichen-Anhörungsportal
├─ Wartbarkeit
│  ├─ No-Layer-Modulgrenzen (Contracts vs. Runtime vs. Blazor)
│  ├─ Compile-Time durchgesetzte Abhängigkeitsrichtung
│  └─ Proportionalität (keine vorsorglichen Abstraktionen ohne Consumer)
├─ Sicherheit
│  ├─ OIDC-Authentifizierung über Keycloak, lokale ABP-Autorisierung
│  ├─ Objektberechtigung je Zugriffsweg (intern, Gast, Konto, Direktfreigabe)
│  └─ Least-Privilege-Infrastruktur (DB-Principal, Keycloak-Provisioning-Client)
├─ Barrierefreiheit
│  ├─ WCAG 2.1 AA als Mindestziel
│  ├─ Cohesion als einzige Fach-UI-Bibliothek
│  └─ automatisierte axe-Prüfung im BrowserGate
├─ Testbarkeit und Verlässlichkeit
│  ├─ Nachweismatrix je Änderungsart (Unit/Integration/SQL/Browser)
│  ├─ Quality Gate je Commit (Git-Hooks)
│  └─ zuverlässige Nebenwirkungen (Outbox, Idempotenz, Retry)
└─ Datenerhalt
   ├─ Data-preserving Migrationen bei Renames
   ├─ optimistische Concurrency auf mutablen Aggregaten
   └─ kein Hard Delete fachlicher Prozessdaten

10.2 Qualitätsszenarien

Jedes Szenario folgt dem Muster Stimulus → Reaktion → Nachweis. Die ID-Präfixe entsprechen den Ästen aus 10.1.

Wartbarkeit (WB)

Sicherheit (SI)

Barrierefreiheit (BF)

Testbarkeit und Verlässlichkeit (TV)

Datenerhalt (DE)

10.3 Nicht angestrebte Qualitätsmerkmale

Entsprechend den bewusst nicht vorhandenen Nachbarn in Kontextabgrenzung §3.4 werden horizontale Skalierung über Microservices, eine zweite Datenbank, generische Workflow-/DMS-Fähigkeiten und Multi-Tenancy bewusst nicht als Qualitätsziele verfolgt. Das schont Komplexitätsbudget zugunsten der oben genannten fünf Äste; ein neuer Bedarf verlangt zuerst einen konkreten, getesteten Anwendungsfall, keine vorsorgliche Infrastruktur.

Siehe auch

• Bausteinsicht – wo die Modulgrenzen aus 10.1 technisch verankert sind
• Querschnittliche Konzepte – Sicherheits- und UI-Mechanismen im Detail
• Risiken und technische Schulden – aktuell noch offene Nachweise (z. B. integrierter BrowserGate-Lauf)
• DEVELOPMENT-GUIDE.md §15 – vollständige Nachweismatrix und Gate-Mechanik
• GETTING-STARTED.md – lokale Ausführung von Gate und BrowserGate
• conventions/security.md, conventions/testing.md – repo-weite Konventionsbaseline
• Risiken und technische Schulden – Status und Nachweistiefe je offener Fachfunktion

11. Risiken und technische Schulden

Dieses Kapitel listet bekannte Risiken und technische Schulden des aktuellen Standes. Es ersetzt keine laufende Nachverfolgung; verbindliche Quelle für den jeweils aktuellen Stand bleibt AGENT_CHANGELOG.md. Die noch offenen Restschritte des Monorepo-Umbaus — insbesondere alles, was vor dem ersten Push erledigt sein muss — führt docs/VOR-ERSTEM-PUSH.md.

Übergreifender Kontext: Monorepo-Umbau lokal vollzogen, Remote-Anbindung offen

Der Umbau zum eigenständigen Repository caf ist lokal durchgeführt: Dieses Repository liegt unter D:\source\repos\caf, trägt eine neue Historie ohne den alten Verlauf (ein Initialcommit chore: initialize CAF monorepo) und besitzt die Branches main und development.

Noch offen ist die Remote-Anbindung: Es ist kein Git-Remote konfiguriert, das GitLab-Projekt ist damit nicht angelegt und der Schutz von main (kein Direct-/Force-Push, Änderungen nur per Merge Request) ist organisatorisch noch nicht wirksam — obwohl die Randbedingungen ihn als gesetzt beschreiben. Bis dahin ist der lokale Arbeitsbaum die einzige Kopie des Stands; ein Verlust ist nicht durch ein Remote abgedeckt.

Mehrere der unten aufgeführten Risiken sind Folgen dieses Umbaus (RALQM-Umbenennung, offene Nachweise). Den verifizierten Erledigt-/Offen-Stand führt docs/VOR-ERSTEM-PUSH.md; das ursprüngliche Übergabeprotokoll des Quellrepositorys liegt deprecated unter docs/history/.

Risiko- und Schuldenübersicht

Bewusst nicht als Schulden geführt

Die folgenden Punkte sind laut Qualitätsanforderungen §10.3 und Kontextabgrenzung §3.4 bewusste Auslassungen, keine offenen Risiken: kein lokaler OpenIddict-Server, keine Microservices, keine zweite GZ-Datenbank, kein PostgreSQL/Redis/RabbitMQ/Kafka/Elsa/GraphQL/Kubernetes, kein externes DMS, keine Dokumentbearbeitung/OCR/Volltextsuche/Legal-Archiv/generische Dateibrowser-UI. Ein neuer Bedarf in diese Richtung erfordert zuerst einen konkreten, getesteten Anwendungsfall, keine vorsorgliche Abstraktion.

Verwandte Kapitel

• Qualitätsanforderungen — Testarten und Gate-Aufbau, gegen die die hier gelisteten Lücken laufen.
• Bausteinsicht — Modulgrenzen und Paketierung, insbesondere zum Cohesion-Pin.
• Entwurfsentscheidungen — Begründung der RALQM-/CAF-Präfixregel und der datenbewahrenden Migrationsstrategie.
• Entwicklungsleitfaden und Getting Started — operative Schritte für lokale Infrastruktur und Quality Gate.

12. Glossar

Dieses Kapitel bündelt die verbindlichen Begriffe der Lösung. Fachbegriffe stammen aus dem RAL-Gütezeichen-Anhörungsprozess, technische Begriffe aus der No-Layer-/ABP-Architektur des Monorepos. Details zu den referenzierten Bausteinen stehen in der Bausteinsicht, Randbedingungen und Namenskonventionen in den Randbedingungen; das normative Regelwerk bleibt DEVELOPMENT-GUIDE.md und conventions/.

Fachliche Begriffe

Technische Begriffe