Kernarchitektur und ihre Umsetzung

Wie die Anwendung technisch aufgebaut wird: eine Hülle aus der eCore-Vorlage, ein Vorgangskern als gemeinsame Datenbasis, sechs Fachmodule, die nur mit dem Kern sprechen, und geteilte Dienst-Container ohne eigenen Zustand. Betrieben wird sie als mandantenfähiger SaaS-Dienst von calhelp im begleiteten Abo. Diese Seite ist die Bauanleitung für Etappe 1 und der Rahmen für alle folgenden.

Grundsätze

• Eine Vorgangsakte. Alles hängt am Vorgang mit seinem Aktenzeichen. Fachmodule fügen Phasen, Felder, Akteneinträge und Dokumente hinzu, sie führen keine eigene Akte.
• Fachmodule kennen den Kern, nie einander. Beschaffung weiß nicht, dass es Signatur gibt; sie meldet „Freigabe erteilt“. So lässt sich jedes Modul einzeln einführen, und eine Vorgangsart ohne Vergabe startet direkt bei Dokumente.
• Konfiguration statt Code. Vorgangsarten, Vergaberegeln, Zeichnungsregeln, Postfächer, Anmeldung und Vorlagen werden in der Verwaltung gepflegt. Was sich je Kunde unterscheidet, steht nicht im Quelltext.
• Ein Produkt, viele Mandanten. Das Dezernat ist der erste Mandant, nicht der einzige. Nichts Kundenspezifisches steht im Code: Postfächer, Briefkopf, Vorgangsarten, Regeln und Anmeldung sind Einstellungen des Mandanten, und jede Tabelle, jede Datei und jeder Schlüssel gehört genau einem Mandanten.
• eCore-Regeln gelten unverändert. Jeder Endpunkt hinter capability:<modul>, fail-closed; Personenbezogenes durch EnvelopeCrypto; kein IP- oder User-Agent-Log an Fachdaten; keine Inhalte in Logs; KI schlägt vor, entscheidet nicht.
• Arbeitsplatz am Desktop, App am Telefon. Dieselben Seiten zeigen am breiten Bildschirm eine Arbeitsfläche mit Navigation, Liste und Akte nebeneinander und am Telefon die dichte App-Form von eCore. Ein Quelltext, kein zweites Frontend.
• Generisches nach unten. Was jede Hülle brauchen kann (Dokumentablage, Teams, SSO, Fristen-Engine, Desktop-Modus), geht als Minor in eCore, mit dieser App als erstem Abnehmer. Fachliches bleibt in der Hülle.

Modulkarte

Aufbau des Repositorys

Die Hülle entsteht mit dem Werkzeug der eCore-Vorlage. Der App-Schlüssel ist evorgang; daraus werden Composer-Paket, Capability des Kerns, Tabellenpräfix, Mandant, Layer und Image-Namen abgeleitet.

node scripts/neue-app.mjs evorgang Evorgang --ziel=../eVorgang

eVorgang/
├── backend/                 Laravel-Anwendung, bindet calhelp/ecore per VCS
├── frontend/                Nuxt, extends ecore-ui, ecore-admin-ui und die Modul-Layer
├── packages/
│   ├── evorgang/            Vorgangskern       Calhelp\Evorgang\      capability:evorgang
│   ├── evorgang-ui/         Akte, Vorgangsliste, Zeitleiste
│   ├── evorgang-admin-ui/   Vorgangsarten, Organisation, Feldkatalog
│   ├── posteingang/         Calhelp\Posteingang\   capability:posteingang
│   ├── beschaffung/         Calhelp\Beschaffung\   capability:beschaffung
│   ├── dokumente/           Calhelp\Dokumente\     capability:dokumente
│   ├── signatur/            Calhelp\Signatur\      capability:signatur
│   ├── vertrag/             Calhelp\Vertrag\       capability:vertrag
│   └── partner/             Calhelp\Partner\       capability:partner
│       (jedes Fachmodul mit eigenem -ui und -admin-ui Layer)
├── docker/                  Dockerfiles, Caddyfile, Compose-Erweiterung für die Dienste
├── scripts/                 Hüllen-Werkzeuge aus der Vorlage
├── docs/                    diese Projektplanung (GitHub Pages)
├── ecore.pin.json           Fassung von eCore, die diese App nutzt
└── docker-compose.yml

Das generierte Modul wird der Vorgangskern. Die Fachmodule entstehen als weitere Pakete nach demselben Muster: je ein ModuleManifest, eigene Routen hinter capability:<modul>, eigener Limiter, eigene Migrationen mit Modulpräfix. Ein Modul wird freigeschaltet, indem seine Capability im App-Manifest steht; fehlt sie, antworten seine Routen 403 und seine Oberfläche bleibt ausgeblendet. Damit ist jede Etappe eine Freischaltung, kein Umbau.

Abhängigkeitsregel

Die Regel wird in der CI geprüft: der Regelwächter der Vorlage (regeln.config.json) bekommt je Fachmodul eine Importliste, ein Verstoß bricht den Build.

Datenmodell des Kerns

Alle Tabellen tragen organization_id und laufen durch den Mandanten-Scope von eCore. Fachmodule verweisen höchstens auf users, organizations, ecore_media_files und die Tabellen des Kerns.

Verträge des Kerns

Fachmodule schreiben nie direkt in Kern-Tabellen. Sie benutzen diese Schnittstellen aus Calhelp\Evorgang\Contracts, die der Kern im Service-Container bindet:

Phasen und Workflow

Jede Vorgangsart beschreibt ihre Phasen und Übergänge. Daraus baut der Kern zur Laufzeit einen Zustandsautomaten mit symfony/workflow. Fachmodule hängen Prüfungen als Guard-Listener an Übergänge, etwa „Zuschlag nur mit der Mindestzahl an Vergleichsangeboten“ (Beschaffung) oder „interne Zeichnung abgeschlossen“ (Signatur). Ein BPMN-System wie Camunda wäre mächtiger, brächte aber einen zweiten Laufzeitdienst und ein Modellierwerkzeug, das im Dezernat niemand pflegen wird.

Rückgabe zur Überarbeitung und Nachforderung von Unterlagen sind gewöhnliche Übergänge zurück in eine frühere Phase, mit Pflichtbegründung und Frist. Nicht jeder Vorgang durchläuft alle Phasen: eine Reisekostenfrage endet nach der Bearbeitung, eine Vertraulichkeitsvereinbarung beginnt bei der Dokumenterstellung.

Ereignisse

Der Kern veröffentlicht bei jedem Phasenwechsel PhaseGewechselt, dazu fachliche Ereignisse, die Module auslösen. Ereignisse sind Laravel-Events, werden erst nach dem Commit zugestellt und von Listenern in der Queue verarbeitet, damit ein fehlschlagender Listener keinen Phasenwechsel zurückrollt. Die Klassen liegen in Calhelp\Evorgang\Events; wo der Code-Name vom Planungsnamen abweicht, steht dieser in Klammern. Die Ereignisse der Zeichnung tragen nur Kennungen und Hashes, nie Inhalte.

Die Fachmodule

Wie sich ein Fachmodul anhängt

Neben den Ereignissen kennt der Kern die Fachmodule nur über Container-Tags und gebundene Verträge. Ohne die Capability eines Moduls beim Mandanten hält sein Wächter nichts an, und sein Abschnitt im Aktenexport sagt, dass es abgeschaltet ist.

Posteingang: zwei Adapter, eine Schnittstelle

MailboxAdapter mit abrufen(), markieren(), senden() und verbindungTesten(). GraphAdapter spricht Microsoft Graph für Exchange Online (App-Registrierung, Client-Credentials), ImapAdapter deckt Exchange lokal und andere Server ab. Welcher gilt, steht je Postfach in der Verwaltung, die Zugangsdaten liegen verschlüsselt. Der Abruf läuft als Job im Scheduler je Postfach mit eigenem Intervall und merkt sich den Stand, damit kein Mail doppelt zum Vorgang wird. Für Exchange Online registriert calhelp eine mandantenfähige App in Entra ID, der jeder Kunde per Administratorzustimmung den Zugriff auf seine Funktionspostfächer gibt; ein lokales Exchange muss aus dem Internet per IMAP über TLS erreichbar sein oder wird über ein Gateway angebunden.

Signatur: einfache Signatur als Standardweg

Interne Zeichnung durch angemeldete Personen, externe ab Etappe 5 über einen Einmal-Link mit Token im URL-Fragment und optionalem Bestätigungscode per Mail. Die Zeichnung startet im Signaturmodul: beim Start wird der SHA-256 der Fassung eingefroren, jede Entscheidung prüft ihn erneut. Nach der letzten Zeichnung rendert der PdfRenderer von eCore (Gotenberg) das Zeichnungsprotokoll, qpdf hängt es an die unveränderten Bytes der gezeichneten Fassung, auf Wunsch mit dem Stempel „Auftrag erteilt“; das Ergebnis liegt als Ausfertigung in der Akte. Das ist eine einfache elektronische Signatur nach Art. 3 Nr. 10 eIDAS; Siegel und qualifizierte Signatur über einen Vertrauensdiensteanbieter (CSC API v2) kommen in Etappe 7.

Betrieb als SaaS

calhelp betreibt eVorgang als Plattform in einem Rechenzentrum in Deutschland, im begleiteten Abo: calhelp richtet den Mandanten ein, pflegt Vorgangsarten und Regeln mit dem Kunden, spielt Updates ein und betreibt Sicherung und Überwachung. Der Kunde stellt keinen Server. Alles läuft in Docker-Containern; dieselben Images laufen in Entwicklung, Abnahme und Produktion. Für Kunden, die eine eigene Instanz verlangen, lassen sich dieselben Images als dedizierte Instanz betreiben, ohne zweiten Codestand.

Mandantentrennung

Plattform-Verwaltung

Neben der Verwaltung des Mandanten gibt es eine Verwaltung für calhelp: Mandanten anlegen und stilllegen, Abo und freigeschaltete Module (Capabilities) zuweisen, Kontingente, Update-Stand, Überwachung von Abrufjobs, Fristenjob und Protokollprüfung je Mandant. Aus der Abo-Schicht von eCore kommen Pläne und Freischaltung; welche Module ein Abo enthält, bestimmt die Capability je Mandant.

Container

Die Dienst-Container sind nur im internen Netz erreichbar und verlangen eine Anmeldung (Bearer-Token, beim PDF-Wandler Basic-Auth). Ein gezeichnetes Dokument wird nie neu gerendert: ein Chromium-Update änderte die Bytes, es gelten nur die abgelegten. Dateien der Ablage gehören in die Sicherung; ob die eCore-Sicherung sie je Mandant erfasst und einzeln wiederherstellt, wird in Etappe 1 geprüft und sonst ergänzt. Erreichbar von außen sind nur caddy und, je nach Kunde, der Abruf der Postfächer nach außen.

Oberfläche: Desktop-Modus

eCore kennt bisher nur die App-Form: eine Spalte von höchstens 480 px (--e-measure), dicht und für den Daumen gemacht. Die Verwaltung ist breiter (1040 px mit Seitenleiste), aber nicht für Massenarbeit gebaut. Wer im Dezernat den ganzen Tag Vorgänge bearbeitet, sitzt am großen Bildschirm und braucht Liste, Akte und Dokument gleichzeitig im Blick. Deshalb bekommt eCore einen Desktop-Modus als Minor; eVorgang ist sein erster Abnehmer.

Wie er sich verhält

• Breite entscheidet, nicht ein Schalter. Ab 64rem (1024 px) zeigt das Gerüst die Arbeitsfläche, darunter die App-Form. Eine Hülle schaltet den Modus beim Anmelden ihres Gerüsts ein (registerAppShell(layout, { desktop: true })); ohne die Angabe bleibt alles wie heute. Damit ist die Erweiterung additiv.
• Ein Quelltext. Seiten setzen sich aus denselben Bausteinen zusammen; die Bausteine ordnen sich je nach verfügbarer Breite an (Container Queries statt nur Media Queries), damit ein Bereich in der Mitte eines dreigeteilten Bildschirms so reagiert wie ein Telefon.
• Dichte nach Zeigegerät. Mit Maus (pointer: fine) und ab 64rem werden Zeilen und Abstände enger; am Touchscreen bleiben 44 px Trefferfläche. Jede Person kann zusätzlich „kompakt“ oder „normal“ wählen, gespeichert in ihren Einstellungen.
• Blätter werden Seitenbereiche. Was am Telefon als Blatt von unten kommt (ESheet), öffnet am Desktop als Bereich rechts neben dem Inhalt; der nächste Schritt (EActionBar) steht im Kopf des Detailbereichs statt unten klebend.
• Tastatur. Kürzel für die häufigsten Wege (nächster Vorgang, zuweisen, kommentieren, Phase wechseln, Suche), mit Übersicht auf ?. Jede Handlung bleibt auch per Maus und Vorlesehilfe erreichbar.

Neue Bausteine in eCore

Was eVorgang daraus macht

Das Fixture beispiel der eCore-Vorlage bekommt die Desktop-Naht zuerst, damit der Vertrag belegt ist, bevor eine Hülle ihn nutzt. Browser-Tests prüfen jede Seite in drei Breiten (Telefon, 1280 px, 1920 px).

Anmeldung und Rechte

• Anmeldung: SSO über SAML oder OIDC und eigene Konten nebeneinander, je Mandant in der Verwaltung mit Verbindungstest. Ein lokales AD wird über ADFS oder Entra ID per SAML/OIDC angebunden; LDAP direkt aus der Cloud gibt es nur mit gesicherter Verbindung zum Kunden. Externe Unterzeichnende brauchen kein Konto.
• Rollen: eCore-Rollen bleiben die Grobstufe (Mitglied, Redaktion, Verwaltung).
• Teams: je Funktionspostfach eins, dazu fachliche Teams. Ein Vorgang ist sichtbar für sein Team, seine Beteiligten und die antragstellende Organisationseinheit.
• Zeichnungsbefugnisse: Regeln nach Betrag und Vertragsart im Signaturmodul; die Werte kommen aus dem Anforderungsworkshop.

Querschnitt

Qualitätssicherung

• Tests je Endpunkt mit den eCore-Pflichtfällen: Auth-Pflicht, Happy Path, Capability-Gate, Mandanten-Isolation.
• Kern-Tests für Automat, Feldkatalog, Fristen und Protokollkette; Vertragstests, die jedes Fachmodul gegen die Kern-Schnittstellen fährt.
• CI aus der Vorlage: Pint, PHPStan, PHPUnit gegen PostgreSQL, ESLint, Typecheck, Vitest, Regelwächter, docker compose config.
• Je Mail-Adapter ein Testpostfach in der Entwicklung; Graph und IMAP verhalten sich bei Ordnern, Lesestatus und Anhängen unterschiedlich.
• Wiederherstellung von Datenbank und Ablage wird vor dem Produktivstart in Etappe 2 geprobt, für die ganze Plattform und für einen einzelnen Mandanten.
• Mandanten-Isolation zusätzlich als eigene Testreihe: zwei Mandanten mit gleichen Aktenzeichen, Postfächern und Vorlagen dürfen einander in keiner Liste, Suche, Datei oder Ereignis sehen.
• Weil Coding-Agenten den Code schreiben, trägt die Automatik die Grundprüfung: Abnahmekriterien als Tests vor dem Code, Vertragstests gegen den Kern, Regelwächter für die Abhängigkeitsregel, Browser-Tests in drei Breiten. Der Mensch prüft im Review Fachlichkeit, Sicherheit und Architektur.
• Repository-Regeln (CLAUDE.md, Abhängigkeitsregel, Pflichtfälle) stehen im Repository, damit jeder Agent sie mit dem Code liest.