LiPo POC [project.lipo]

Ausführbarer Proof of Concept mit zwei Kotlin-/Spring-Boot-Backends, zwei React-/Ant-Design-Frontends und lokaler Infrastruktur. Die REST-Verträge liegen auf annotierten Controller-Interfaces; separate Controller-Implementierungen führen die Anwendungsfälle aus. Kubb erzeugt die TypeScript-Clients aus den OpenAPI-Spezifikationen der Backends.

Umfang [project.lipo.scope]

Das SAP-Mitarbeiter-Frontend legt Bestellungen an und bearbeitet Nachrichten, Dokumente und Workflow-Entscheidungen. Der Adapter speichert seine Daten in SQLite und veröffentlicht Mitarbeiteraktionen über eine transaktional gespeicherte Outbox an Redpanda. LiPo projiziert diese Events idempotent nach PostgreSQL. Lieferantenaktionen laufen synchron von LiPo zum internen Adapter-REST-Vertrag und werden erst nach erfolgreicher Speicherung bestätigt. Damit entsprechen die Kommunikationsrichtungen [contract.rest.lipo_to_adapter] und [contract.event.adapter_to_lipo].

Das LiPo-Frontend authentifiziert Lieferanten über Keycloak und trennt Bestellungen anhand des supplierId-Claims. Beide Frontends laden sämtliche fachlichen Daten über REST, aktualisieren eigene Aktionen unmittelbar und verwenden STOMP ausschließlich für Live-Hinweise mit anschließendem REST-Abgleich. Manuelle Aktualisierung und die vollständigen Abläufe bleiben bei unterbrochener STOMP-Verbindung verfügbar, wie in [contract.stomp.ausfallverhalten] festgelegt.

Die vollständige Spezifikation steht in lipo_poc_requirements.md. Die Implementierung umfasst Bestellungen, Nachrichten, Dokumente, Zeit- und Kostenüberschreitungen, Teil- und Endfertigstellung, Lieferanten-weite Read-/Unread-Zustände, Auditdaten, Idempotenz und die Mitarbeiter-Gegenseite.

Dokumente können immer heruntergeladen werden. PDFs sowie PNG-, JPEG-, GIF-, WebP-, AVIF- und BMP-Bilder lassen sich zusätzlich direkt in LiPo und SAP als Vorschau öffnen; weitere Dateitypen werden ausschließlich zum Download angeboten ([feature.dokument.vorschau]).

Voraussetzungen [setup.prerequisites]

• JDK 21
• Node.js ab 22.12 und npm ab 10
• Docker mit Compose sowie Python 3 für das lokale Infrastruktur-Setup
• Internetzugang beim ersten Herunterladen der Maven- und npm-Abhängigkeiten

Die STOMP-E2E-Prüfungen benötigen zusätzlich das fest versionierte Python-Paket:

python3 -m pip install -r e2e/requirements.txt

Infrastruktur [setup.infrastructure]

python3 infra/init-local-env.py
docker compose up -d
docker compose ps

Die Zugangsdaten werden ausschließlich in der ignorierten lokalen .env-Datei gespeichert. Die Infrastruktur-Dokumentation beschreibt Verbindungen, Seed-Benutzer und Datenhaltung. Alle konfigurierten Service-Ports liegen zwischen 27000 und 27999.

Compose startet PostgreSQL auf 27100, Keycloak auf 27200 und Redpanda auf 27300. Die Backends lesen .env beim Start aus dem Projekt- oder Modulverzeichnis. Der Adapter legt seine SQLite-Datei standardmäßig unter data/adapter.db an.

Backend-Start [setup.backends]

Im Projektverzeichnis:

./mvnw verify

Anschließend jeweils in einem eigenen Terminal:

./mvnw -pl lipo-backend spring-boot:run

./mvnw -pl adapter-backend spring-boot:run

Anwendung	Adresse	OpenAPI
LiPo Backend	http://localhost:27010	http://localhost:27010/v3/api-docs
Adapter Backend	http://localhost:27020	http://localhost:27020/v3/api-docs
LiPo Frontend	http://localhost:27011	—
SAP Mitarbeiter-Frontend	http://localhost:27021	—

Beide Backends stellen REST und STOMP am selben Port bereit; der WebSocket-Handshake liegt jeweils unter /ws. Das LiPo Backend validiert JWTs auch beim STOMP-CONNECT und begrenzt Lieferanten-Updates auf /topic/suppliers/{supplierId}/updates. Das Adapter Backend veröffentlicht Mitarbeiter-Updates auf /topic/employee/updates.

jOOQ-Codegenerierung [setup.backends.jooq]

Beim Maven-Lifecycle-Schritt generate-sources erzeugt lipo-backend die jOOQ-Klassen aus den Flyway-DDL-Dateien unter lipo-backend/src/main/resources/db/migration. Die Ausgabe liegt ausschließlich unter lipo-backend/target/generated-sources/jooq und wird nicht eingecheckt. Die Generierung benötigt keine laufende PostgreSQL-Instanz:

./mvnw -pl lipo-backend generate-sources

./mvnw verify führt die Generierung automatisch vor Kompilierung und Tests aus.

Für Generierung direkt aus dem echten Compose-PostgreSQL:

python3 scripts/generate-jooq.py

Das Profil jooq-postgres migriert zunächst mit Flyway und liest anschließend das reale Schema. Zugangsdaten werden aus .env in die Prozessumgebung geladen. Dieser Weg wurde gegen PostgreSQL 17.9 inklusive Kotlin-Kompilierung geprüft.

Frontend-Start und Client-Generierung [setup.frontends]

Diese Befehle jeweils in lipo-frontend und adapter-frontend ausführen:

npm ci
npm run generate
npm test
npm run build
npm run dev

npm run generate führt kubb generate aus. Die eingecheckte openapi.json ermöglicht die Generierung ohne laufendes Backend. Generierte Dateien liegen unter src/generated und werden nicht von Hand bearbeitet.

Nach Änderungen an Controller-Interfaces oder DTOs das jeweilige Backend neu starten und im zugehörigen Frontend ausführen:

npm run sync:openapi
npm run generate
npm run build

Beide Frontends verwenden den authentifizierten Kubb-Client für REST. Mutationen senden einen stabilen Idempotency-Key, der bei einem identischen Retry erhalten bleibt. Die STOMP-Clients aktualisieren nach Verbindungsaufbau, Wiederverbindung und fachlichen Events die betroffenen REST-Daten.

Tests [validation.tests]

Backend-Unit- und Integrationstests, jOOQ-Codegenerierung und die beiden Backend-Builds laufen gemeinsam mit:

./mvnw verify

Frontend-Helfer und Produktions-Builds werden je Frontend geprüft:

npm test
npm run build

Die reale Backend-E2E-Suite verwendet HTTP, Keycloak, PostgreSQL, SQLite und Redpanda ohne fachliche Mocks. Sie prüft unter anderem Lieferantentrennung, synchrone LiPo-zu-Adapter-Aufrufe, Kafka-Projektion und Deduplizierung, bytegenaue Dokumente, gemeinsamen Read-State und beide Entscheidungen aller Workflows. Details stehen in e2e/README.md.

Die E2E-Suite startet ausschließlich die isolierte Stage test mit eigener Infrastruktur auf Ports 28xxx. Die Entwicklungsumgebung auf 27xxx kann dabei weiterlaufen. Jeder Lauf setzt die Testdaten zurück und entfernt anschließend Container, Volumes und temporäre Dateien:

python3 scripts/run-e2e.py

--skip-build verwendet vorhandene Backend-JARs. Ohne diesen Schalter generiert der Runner jOOQ mit jooq-postgres direkt aus der frischen PostgreSQL-Testdatenbank. --generate-clients synchronisiert zusätzlich beide OpenAPI-Dateien, erzeugt die Kubb-Clients neu und prüft beide Frontends mit Tests und Produktions-Builds. Der Test-Runner aktiviert PostgreSQL-Integration und Broker-Ausfalltests automatisch. Direkte Tests gegen laufende Entwicklungs-Backends sind nicht vorgesehen. Die Testmatrix ordnet Use Cases, Fehlerklassen und Testebenen zu.

Die HTTP-/Persistenz-E2E-Suite und die Resilienz-Szenarien prüfen STOMP-Live-Updates und Zugriffsschutz, HTTP-Idempotenz, Dokumentgrößengrenzen, Workflow-Zuordnung, geteilten Lesestatus, den Read-Model-Wiederaufbau durch Kafka-Replay und Outbox-Wiederaufnahme nach einem Redpanda-Ausfall. Der tatsächlich gemeinsam mit Lieferant und SAP durchgespielte Browser-Ablauf einschließlich REST-Betrieb ohne STOMP ist in e2e/browser-verification.md dokumentiert; dort ist auch die Browser-Prüfgrenze bei Blob-Vorschauen vermerkt.

IntelliJ [setup.intellij]

Die Root-pom.xml als Maven-Projekt importieren und JDK 21 als Projekt-SDK auswählen. Die eingecheckten Konfigurationen in .run starten LiPo Backend, Adapter Backend, LiPo Frontend und Adapter Frontend einzeln. Für die Frontends zuerst npm ci ausführen und Node.js als Projekt-Interpreter konfigurieren; npm-Run-Konfigurationen benötigen die JavaScript-/Node.js-Unterstützung der IDE.

Die Backend-Main-Klassen sind at.lipo.backend.LipoBackendApplicationKt und at.lipo.adapter.AdapterBackendApplicationKt. Sie können auch direkt aus dem Editor gestartet werden. Vor dem Start müssen PostgreSQL, Keycloak und Redpanda verfügbar sein; der Adapter erzeugt seine SQLite-Datenbank selbst.

Konventionen [project.conventions]

Code ist englisch. Kommentare werden nur verwendet, wenn sie unbedingt erforderlich sind. Anforderungsverweise verwenden ausschließlich semantische Tags aus der Spezifikation, keine Abschnittsnummern.

Zusammenhängende, geprüfte Änderungen werden jeweils committed und zum konfigurierten Remote gepusht. Etwa 500 geänderte Zeilen oder fünf Minuten dienen als grober Richtwert; fachlich kohärente Commits haben Vorrang.