# Novaris Versicherung AG — Systemlandschaft Dieses Dokument gibt den Gesamtueberblick ueber das Lernprojekt: welche fiktive Systemlandschaft wir nachbauen, warum sie so aussieht, wie sie aussieht, und in welchen Phasen sie entsteht. Es ist der Einstiegspunkt fuer die gesamte Dokumentation. ## Die fiktive Ausgangslage **Novaris Versicherung AG** ist ein mittelgrosser Versicherer, dessen IT-Landschaft ueber gut 20 Jahre gewachsen ist: - In den 1990er/2000er-Jahren liefen die Kernbestandssysteme auf einem Mainframe mit DB2 - Vertraege wurden in COBOL-Batch-Programmen verwaltet (Tabelle `CTR_MASTER`, siehe `LegacyContractRecord`). - Anfang der 2010er wurde ein Teil der Fachlogik nach Java EE / WebSphere migriert - neue Vertraege laufen seither ueber ein Oracle-gefuehrtes Policensystem (`Policy`-Entity), das eng mit dem noch nicht vollstaendig abgeloesten DB2-Bestand zusammenspielt. - Partnersysteme (Abrechnung/Billing, teils externe Dienstleister) werden klassisch per SOAP angebunden. - Asynchrone Prozesse (Schadensmeldungen, Benachrichtigungen) laufen ueber IBM MQ/JMS. - Die gesamte Landschaft laeuft auf WebSphere (traditional bzw. Liberty). Diese Gemengelage - zwei Datenbanken fuer denselben fachlichen Bestand, SOAP-Partner, asynchrones Messaging, EJB als tragende Businesslogik-Technologie - ist bewusst keine Kunstwelt: Sie ist ein sehr typisches Bild fuer Versicherer, die Java-EE-Technologie frueh uebernommen, aber nie vollstaendig konsolidiert haben. Genau dieses Bild soll man am Ende dieses Projekts aus eigener Erfahrung verstanden haben - inklusive der Stellen, an denen es unschoen ist, und warum es trotzdem so aussieht. ## Modulkarte (Ist-Stand + Ausbaustufen) ``` +-----------------------------------+ | novaris-policy-web-legacy-jsf | (JSF-"Kundenportal") | Legacy-Auth: JAAS (LTPA: nur Doku) | +------------------+------------------+ | Local-EJB (selbes EAR: | novaris-policy-ear) v +------------------+ +-----+----------+ JDBC +----------------+ | novaris-billing- |<-------------------->| novaris-policy- |<-------->| Oracle | | soap (SOAP-Service)| SOAP/@WebServiceRef | core (EJB-Kern) | | (Policenbestand)| +------------------+ +-----+----------+ +----------------+ | JDBC (Legacy-DAO) v +----------------+ | DB2 | | (CTR_MASTER) | +----------------+ ^ | JMS/MQ (Queue, Request/Reply) +------+---------+ | novaris-claims- | | mq | +-----------------+ novaris-policy-core --(Topic, Pub/Sub)--> jms/novaris/policyEventsTopic | +------------------------+------------------------+ v v +--------------------------+ +--------------------------+ | novaris-notification-jms | | novaris-notification-jms | | PolicyDocumentGeneration | | CustomerNotification | | MDB (Selektor: POLICY_ | | MDB (Selektor: POLICY_ | | ISSUED) | | ISSUED or CLAIM_REG.) | +--------------------------+ +--------------------------+ ``` ## Liefer-Phasen | Phase | Inhalt | Status | |---|---|---| | 0 | Reactor-Skeleton, Doku-Grundgeruest | erledigt | | 1 | `novaris-common-legacy` + `novaris-policy-core`: der EJB-Kern (Stateless/Stateful/MDB/Timer/Interceptor, duale Persistenz Oracle+DB2) | erledigt | | 2 | `novaris-billing-soap`: SOAP-Service + SOAP-Client-Integration in policy-core | erledigt | | 3 | `novaris-claims-mq` (Queue, Request/Reply) + `novaris-notification-jms` (Topic, Pub/Sub) | erledigt | | 4 | `novaris-policy-web-legacy-jsf` (JSF-"Kundenportal") + `novaris-policy-ear`, WebSphere-Konfigurationsdoku, Legacy-Auth | erledigt | | 5 | `novaris-integration-tests`: echtes Oracle + echtes IBM MQ (Docker-CLI-orchestriert), Open-Liberty-Serverstart verifiziert; DB2 und automatisiertes EAR-Deployment bewusst nur dokumentiert | erledigt | | 6+ | Migration/Refactoring (bewusst separat, nicht Teil dieses Aufbaus) | spaeter, auf Wunsch des Nutzers | ### Phase 2 im Detail: SOAP-Anbindung an das Billing-System - **Contract-first**, mit einer wichtigen Einschraenkung: die WSDL (`novaris-billing-soap/src/main/resources/wsdl/BillingService.wsdl`) ist die dokumentierte Quelle der Wahrheit, wird aber **nicht per `wsimport` generiert** - die dafuer verfuegbare Maven-Plugin-Toolchain erwies sich auf dem aktuellen JDK als nicht mehr lauffaehig. SEI und Fault-Klassen liegen deshalb handgeschrieben, aber vertragsgetreu, in `novaris-common-legacy`. Details und Begruendung: `novaris-billing-soap/README.md` und `docs/20-soap/01-contract-first-und-wsdl.md`. - **Serverseite:** `BillingServiceEndpoint` in `novaris-billing-soap`, mit In-Memory- Registrierung (kein eigener DB-Ausbau fuer dieses Partnersystem in dieser Phase) und einem echten SOAP Fault (`BillingRegistrationFault`) fuer fachliche Ablehnungen. - **Clientseite:** `BillingIntegrationBean` in `novaris-policy-core`, per `@WebServiceRef` angebunden, mit Timeout-Konfiguration, Retry bei technischen Fehlern und Fault-spezifischer Behandlung (idempotent bei `ALREADY_REGISTERED`). - **Bewusst offen gelassenes Risiko:** `PolicyManagementBean.activatePolicy(...)` ruft das Billing-System synchron **innerhalb** der eigenen CMT-Transaktion auf - ein SOAP- Aufruf ist nicht XA-transaktional, es entsteht ein "Dual-Write"-Inkonsistenzrisiko. Das wird nicht geloest, sondern bewusst dokumentiert (siehe Javadoc von `BillingIntegrationBean.registerPolicyForBilling`) - es ist der eigentliche fachliche Grund fuer Phase 3 (asynchrone JMS/MQ-Entkopplung). ### Phase 3 im Detail: JMS/MQ-Systemlandschaft - **`novaris-claims-mq`** (Schaden-Teilsystem): `ClaimSubmissionClient` sendet Schadensmeldungen synchron per klassischem Request/Reply-Muster (`JMSReplyTo` + `JMSCorrelationID` auf einer festen Antwort-Queue) an `ClaimIntakeMDB` in novaris-policy-core, die jetzt auch eine Antwort zurueckschickt. Siehe `docs/30-jms-mq/02-request-reply.md`. - **`novaris-notification-jms`** (Benachrichtigung): zwei unabhaengige, durable Topic- Abonnenten (`PolicyDocumentGenerationMDB`, `CustomerNotificationMDB`) mit unterschiedlichen Message-Selektoren auf demselben Policy-Events-Topic - publiziert von der neuen `PolicyEventPublisherBean` in novaris-policy-core. Siehe `docs/30-jms-mq/03-topics-und-selektoren.md`. - **Test-Ersatz fuer IBM MQ:** genau wie bei der SOAP-Anbindung (siehe Phase 2, wsimport- Ersatz) wird fuer schnelle, Docker-freie Tests ein eingebetteter Apache-ActiveMQ-Broker statt echtem IBM MQ verwendet - der Anwendungscode kennt ausschliesslich die Standard-`javax.jms`-API und ist gegenueber dem tatsaechlichen Provider dahinter unveraendert. Echtes IBM MQ wird in Phase 5 per Testcontainers angebunden. ### Phase 4 im Detail: Web-Frontend, EAR-Packaging und Legacy-Auth - **Frontend-Technologie:** bewusst **JSF (Facelets/`.xhtml`)**, nicht eine moderne SPA - das ist die authentische WebSphere-Ära-Technologie fuer serverseitig gerenderte Oberflaechen. Managed Beans (`javax.faces.bean.ManagedBean`, bewusst die JSF-2.x-Form vor CDI `@Named`, siehe `PolicyOverviewBean`-Javadoc) injizieren EJB-Interfaces direkt per `@EJB` - moeglich, weil Web- und EJB-Modul im selben EAR liegen (`docs/50-websphere-config/02-ear-packaging-und-deployment.md`). - **Zwei Seiten, zwei Scopes:** `PolicyOverviewBean` (`@RequestScoped`, Policenuebersicht) und `PolicyApplicationBean` (`@SessionScoped`, mehrseitiger Antragsprozess). Letztere demonstriert konkret, warum Stateful Session Beans (`PolicyApplicationWizardBean`, Phase 1) und session-gebundene Web-Beans natuerlich zusammenpassen: dieselbe Bean-Instanz - und damit dieselbe EJB-Referenz - bleibt ueber alle Formular-Postbacks eines Antrags hinweg erhalten. Schadenserfassung findet bewusst NICHT im Portal statt - Schadensmeldungen kommen bereits ueber `novaris-claims-mq` per JMS herein (Phase 3), ein zusaetzlicher manueller Erfassungsweg waere ein redundanter zweiter Eingangskanal. - **Bezeichnung als "Portal":** Das Web-Modul wird als **Novaris-Kundenportal** gerahmt - passend zum Sprachgebrauch, den Versicherer fuer ihre Kunden-/Maklerzugaenge historisch verwenden. - **Legacy-Auth:** `NovarisLegacyLoginModule` (echtes, getestetes JAAS Custom Login Module, `web.xml` FORM-Auth mit `j_security_check`) gegen einen simulierten Altbestand (`LegacyUserDirectory`). **LTPA** (WebSphere-proprietaeres SSO-Token) ist bewusst nur dokumentiert, nicht nachgebaut - siehe `docs/50-websphere-config/01-legacy-auth-jaas-ltpa.md` fuer die Begruendung dieser Grenze. - **EAR-Packaging:** `novaris-policy-ear` buendelt EJB- und Web-Modul mit handgeschriebener `application.xml` zu einer echten, `mvn package`-bauenden EAR-Datei. - **Migrationsziel:** Das klar getrennte Modul **`novaris-policy-web-modern-spa`** ist in M7 umgesetzt und wird als eigenes statisches Container-Deployment auf OpenShift vorbereitet. Die Namensgebung `novaris-policy-web-legacy-jsf` fuer das jetzige Modul haelt beide jederzeit eindeutig auseinander. ### Phase 5 im Detail: echte Infrastruktur statt Ersatz-Implementierungen - **`novaris-integration-tests`** (neues Modul): loest die in Phasen 1-4 bewusst getroffenen Ersatz-Entscheidungen fuer die zwei wichtigsten Faelle konkret ein - `OraclePersistenceIT` (echtes Oracle statt gemockter JPA-Zugriff) und `IbmMqRequestReplyIT` (echtes IBM MQ statt eingebettetem ActiveMQ). Beide gruen, reproduzierbar. Siehe `docs/40-persistence-oracle-db2/03-jpa-gegen-echtes-oracle-verifiziert.md` und `docs/30-jms-mq/04-ibm-mq-vs-activemq-ersatz.md`. - **Docker-CLI statt Testcontainers-Bibliothek:** die Testcontainers-Java-Bibliothek konnte in der Umgebung, in der dieses Projekt entstanden ist, nicht direkt mit der Docker Engine API sprechen (vermutlich eine Docker-Desktop-interne Proxy-/Sicherheitsschicht dieser Installation) - die normale `docker`-Kommandozeile funktionierte einwandfrei. Die Integrationstests orchestrieren Container deshalb ueber einen schlanken `ProcessBuilder`-Wrapper (`DockerCli`). Siehe `novaris-integration-tests/README.md`. - **DB2: bewusst nur dokumentiert.** Explizit mit dem Nutzer abgestimmt - das offizielle DB2-Community-Image ist deutlich schwerer (mehrere GB, `--privileged`, oft 10+ Minuten Start) als Oracle/IBM MQ. Referenzkonfiguration: `docs/40-persistence-oracle-db2/02-db2-nur-dokumentiert.md`. - **Open Liberty: Serverstart verifiziert, automatisches EAR-Deployment offen.** Der Liberty-Kernel startet nachweislich zuverlaessig mit dem vollen Feature-Set dieses Projekts; vier echte Konfigurationsfehler wurden dabei gefunden und behoben. Das vollautomatisierte Deployment der EAR gegen die laufende Instanz hat noch ein offenes, genau eingegrenztes Problem (Modul-Pfadaufloesung des `liberty-maven-plugin` in diesem Multi-Modul-Reactor) - bewusst als offener Punkt dokumentiert statt erzwungen, siehe `docs/50-websphere-config/03-liberty-serverstart-verifiziert.md`. ## Wichtige Cross-Cutting-Themen (in mehreren Phasen relevant) - **Money-as-cents & duale Persistenz:** siehe `Policy`/`LegacyContractRecord`-Javadoc. - **Serialisiertes Java-Objekt als JMS-Payload:** siehe `ClaimNotificationMessage`-Javadoc - bewusster Trade-off, der in einer spaeteren Migration (Textformat, Schema) aufgeloest werden muesste. - **EJB-Konzepte im Detail:** siehe `docs/10-ejb-konzepte/`. ## Nicht Teil dieses Projekts (aktuell) Migration und Refactoring der hier aufgebauten Legacy-Landschaft sind ausdruecklich fuer einen spaeteren, eigenen Arbeitsschritt vorgesehen - dieses Projekt baut zunaechst bewusst den "Vorher"-Zustand vollstaendig und verstehbar auf.