# PROCUREX – Planungsentscheidungen für Confluence & Jira **Zweck dieser Datei:** Diese Datei enthält fertig ausformulierte Inhalte, um die noch offenen (Status `PROVISIONAL` / `DRAFT`) Confluence-Seiten im Space `PRX` auf `aydinsude.atlassian.net/wiki` zu finalisieren, sowie Hinweise zu betroffenen Jira-Tickets im Projekt `PRX` auf `aydinsude.atlassian.net`. **Anleitung für die Umsetzung (z.B. durch ChatGPT mit Schreibrechten):** 1. Für jede Seite unten: die genannte Confluence-Seite über die Page-ID öffnen, den Status-Absatz von `PROVISIONAL`/`DRAFT / PROVISIONAL` auf `CONFIRMED` ändern, und den bestehenden Inhalt durch den unten stehenden Text ersetzen bzw. ergänzen. 2. Diese Entscheidungen sind fachlich/technisch konsistent hergeleitet aus: den bereits vorhandenen Confluence-Seiten 05, 06, 08–13 (Domänenmodell, Jira-Regeln, Architektur, DevOps), den Jira-Tickets PRX-1 bis PRX-25, und der **real existierenden** lokalen Infrastruktur unter `C:\Entwicklung\lernen\enterprise-workspace\shared\enterprise-infrastructure\docker-compose.yml` sowie dem Referenzprojekt `library-enterprise-platform`. 3. Nach dem Übernehmen in Confluence: die zugehörigen Jira-Tasks (siehe Tabelle am Ende) von "Zu erledigen" auf "Review" oder "Done" verschieben, je nach Team-Konvention aus Confluence-Seite 06. 4. Wo unten **[ANNAHME]** steht, ist das eine sinnvolle, aber nicht aus vorhandenen Quellen zwingend abgeleitete Entscheidung – bei Bedarf vor dem Übernehmen kurz gegenprüfen. --- ## Seite 08 – Technologie und Frameworks **URL:** https://aydinsude.atlassian.net/wiki/spaces/PRX/pages/2260993 **Neuer Status:** CONFIRMED Bestätigte Technologieentscheidung für PROCUREX, abgestimmt auf die bestehende `enterprise-infrastructure`-Plattform: | Baustein | Version | Begründung | |---|---|---| | Sprache | Java 17 LTS | Bewusst bei 17 belassen (nicht 21 wie im Nachbarprojekt), Team-Entscheidung | | Framework | Spring Boot 3.3.4 | Java-17-kompatibel, identisch zur Version in `library-enterprise-platform` | | Build | Maven Multi-Module, Java-17-Toolchain | siehe Seite 11 | | Persistenz | PostgreSQL 16-alpine | exakte Version aus `enterprise-infrastructure` | | Migrationen | Flyway (Version aus Spring-Boot-3.3.4-Dependency-Management) | | | Messaging | Kafka-Client kompatibel zu Confluent Platform 7.7.1 (Broker in `enterprise-infrastructure`, KRaft-Modus) | Topic-Präfix `procurex.` | | Security/IdP | Keycloak 26.7.0, eigener Realm `procurex` | exakte Version aus `enterprise-infrastructure` | | Frontend | Angular ^22 | konsistent mit `FE-DONE-ANGULAR-Enterprise-Academy`-Referenz | | Container-Netzwerk | externes Docker-Netzwerk `proxy`, Hostname-Präfix `procurex`, Traefik-Label-Routing | Pflichtkonvention aus Seite 12 | | Observability | Prometheus v2.55.0, Grafana 11.2.0 (zentral in `enterprise-infrastructure`) | | | CI/CD | zentraler Jenkins aus `enterprise-infrastructure`, eigener PROCUREX-Pipeline-Job | | | Lizenzen/Support | Alle genannten Komponenten sind Open Source (Apache 2.0 / MIT-artig) bzw. Keycloak (Apache 2.0); für ein Lernprojekt ohne kommerzielle Supportanforderung ausreichend | [ANNAHME] | --- ## Seite 09 – Zielarchitektur und Modulstruktur **URL:** https://aydinsude.atlassian.net/wiki/spaces/PRX/pages/2293761 **Neuer Status:** CONFIRMED **Architekturstil:** Modularer Monolith (ein deploybares Spring-Boot-Artefakt), mit klaren Modulgrenzen, die eine spätere Auftrennung in eigenständige Services ermöglichen. **Maven-Modulstruktur:** ``` procurex-platform (Parent-POM, Dependency Management) ├── procurex-common (Shared Kernel: Exceptions, Value Objects, Problem-Details, Correlation-ID) ├── procurex-supplier (Bounded Context: Lieferantenverwaltung – PRX-3) ├── procurex-catalog (Bounded Context: Produktkatalog – PRX-4) ├── procurex-requisition (Bounded Context: Warenkorb – Teil von PRX-2) ├── procurex-ordering (Bounded Context: Bestellung – PRX-2, PRX-12) ├── procurex-approval (Bounded Context: Genehmigung – PRX-5, PRX-8) ├── procurex-receiving (Bounded Context: Wareneingang – PRX-10) ├── procurex-invoicing (Bounded Context: Rechnungsprüfung – PRX-11, PRX-9) ├── procurex-notification (Bounded Context: Benachrichtigungen) └── procurex-app (Spring-Boot-Bootstrap-Modul, bindet alle Module zum deploybaren Artefakt) ``` **Modul-interne Struktur (Hexagonal/Ports & Adapters), pro Bounded-Context-Modul:** - `domain` – Entitäten, Value Objects, Domain Services, Geschäftsregeln (keine Framework-Abhängigkeit) - `application` – Use Cases / Application Services, Transaktionsgrenzen - `adapter.in` – REST-Controller, Event-Consumer - `adapter.out` – JPA-Repositories, Event-Producer, Aufrufe anderer Module **Regeln:** - Datenhoheit bleibt je Modul: jedes Modul besitzt sein eigenes PostgreSQL-Schema (siehe Seite 10). Kein Modul greift direkt auf das Schema eines anderen Moduls zu. - Modul-zu-Modul-Kommunikation: synchron nur über öffentliche Application-Service-Interfaces innerhalb desselben Deployments; asynchron/entkoppelt über Kafka-Events (Outbox-Pattern), insbesondere zwischen Ordering → Approval → Receiving → Invoicing. - Architekturartefakte (Systemkontext, Containerdiagramm, Bounded Context Map, Deploymentdiagramm) werden als PlantUML/Mermaid-Quelltext im Repository unter `/docs/architecture/` gepflegt statt als Bilddatei, damit sie versionierbar bleiben. [ANNAHME] - Architekturrelevante Entscheidungen werden als ADRs (MADR-Format) unter `/docs/adr/` dokumentiert und im Entscheidungslog (Confluence-Seite 07) verlinkt. --- ## Seite 10 – APIs, Events, Daten und Security **URL:** https://aydinsude.atlassian.net/wiki/spaces/PRX/pages/2195465 **Neuer Status:** CONFIRMED **REST:** - Basis-Pfad `/api/v1/...`, eine Ressource pro Bounded Context (`/api/v1/suppliers`, `/api/v1/catalog-items`, `/api/v1/orders`, `/api/v1/approvals`, `/api/v1/goods-receipts`, `/api/v1/invoices`) - OpenAPI 3.1 über springdoc-openapi, automatisch generiert und im Build validiert - Fehler als RFC 7807 Problem Details (`application/problem+json`) - Bean Validation (Jakarta Validation) auf allen Request-DTOs - Pagination über `page`/`size`-Query-Parameter, Antwort inkl. `totalElements`/`totalPages` - Jeder Request trägt einen `X-Correlation-Id`-Header (generiert falls nicht vorhanden), der durchgereicht und geloggt wird **Events (Kafka):** - Topic-Namensschema: `procurex...v1`, z.B. `procurex.ordering.order-submitted.v1`, `procurex.approval.order-approved.v1`, `procurex.approval.order-rejected.v1`, `procurex.receiving.goods-received.v1`, `procurex.invoicing.invoice-matched.v1`, `procurex.invoicing.invoice-discrepancy-flagged.v1` - Transactional Outbox Pattern pro Modul (Outbox-Tabelle im jeweiligen Schema + Relay-Prozess), um DB-Commit und Event-Publish atomar zu halten - Idempotente Consumer: Dedupe über Event-ID (UUID) in einer Consumer-seitigen "processed events"-Tabelle - Schema-Versionierung über das `.v1`-Suffix im Topic-Namen; bei inkompatibler Änderung neues `.v2`-Topic - Dead-Letter-Queue je Topic: `.dlq` - Ein Consumer-Group-Name pro konsumierendem Modul (`procurex--consumer`) **Daten:** - Eine PostgreSQL-Datenbank `procurex` (eigene DB + eigener User in der geteilten `enterprise-infrastructure`-Postgres-Instanz, siehe `init-project-databases.sh`-Mechanismus) - Innerhalb dieser DB: ein eigenes Schema pro Bounded-Context-Modul (`supplier`, `catalog`, `requisition`, `ordering`, `approval`, `receiving`, `invoicing`), Flyway-Migrationspfad `db/migration/` pro Modul - Backup/Restore: obliegt der geteilten Postgres-Instanz in `enterprise-infrastructure`; projektbezogen zusätzlich `pg_dump` vor größeren Migrationen [ANNAHME] - Datenschutz: keine echten Personendaten (fiktives Lernprojekt), dennoch Lösch-/Anonymisierungskonzept für `Supplier`-Kontaktdaten und `ApprovalRequest`-Begründungen nach fiktiver Aufbewahrungsfrist von 24 Monaten [ANNAHME] **Security:** - Keycloak-Realm `procurex`, zwei Clients: `procurex-frontend` (public, Authorization Code + PKCE) und `procurex-backend` (Resource Server, Bearer-only) - Rollen: `ROLE_BUYER`, `ROLE_APPROVER`, `ROLE_SUPPLIER_ADMIN`, `ROLE_FINANCE`, `ROLE_RECEIVING`, `ROLE_ADMIN` - Spring Security OAuth2 Resource Server, JWT-Validierung gegen `issuer-uri = http://keycloak.localhost/realms/procurex` - Least Privilege: jeder REST-Endpunkt fordert die minimal nötige Rolle (z.B. nur `ROLE_APPROVER` darf `POST /api/v1/approvals/{id}/decision`) - Secrets (Client-Secrets, DB-Passwörter) ausschließlich über Umgebungsvariablen/`.env` (nicht versioniert), niemals im Repository --- ## Seite 11 – Buildsystem und Entwicklungsstandard **URL:** https://aydinsude.atlassian.net/wiki/spaces/PRX/pages/2097155 **Neuer Status:** CONFIRMED - Maven-Parent-POM importiert `spring-boot-dependencies:3.3.4` im `dependencyManagement`; Java-17-Toolchain über `maven.compiler.release=17` - Formatter: Spotless-Maven-Plugin mit Standard-Java-Formatierung, build-brechend bei Verstoß - Checkstyle (Google-Style) und SpotBugs als Quality Gates, build-brechend ab Schweregrad "error" - JaCoCo: Mindestlinien-Coverage 80% für `domain`- und `application`-Pakete, 60% Gesamtprojekt [ANNAHME – siehe auch Seite 13] - OWASP Dependency-Check-Maven-Plugin gegen bekannte CVEs, CycloneDX-Maven-Plugin für SBOM-Erzeugung - Branching: Trunk-based, kurzlebige Feature-Branches `feature/PRX--kurzbeschreibung` - Commit-Konvention: Conventional Commits mit Jira-Key-Präfix, z.B. `feat(PRX-2): Warenkorb zu Bestellung` - Pull Request: mindestens ein Review (simuliertes Vier-Augen-Prinzip für das fiktive Lernprojekt) plus grüne Pipeline vor Merge - ADR-Pflicht für architekturrelevante Entscheidungen (MADR-Format unter `/docs/adr/`) - Lokale Entwicklungsumgebung – Voraussetzungen: JDK 17, Maven 3.9+, Node.js LTS (für Angular), Docker Desktop - Start-Reihenfolge lokal: zuerst `enterprise-infrastructure` zentral starten (`docker compose up -d`, danach `--profile postgres --profile keycloak --profile kafka up -d` für die benötigten optionalen Dienste), erst danach PROCUREX-eigene Container/Anwendung starten - Testdaten: Flyway-`Testdata`-Migrationen nur im lokalen/Test-Profil, niemals in Produktionsmigrationen - Reset-Strategie: `flyway:clean` + `flyway:migrate` ausschließlich gegen die lokale Projekt-Datenbank, niemals gegen die geteilte `enterprise-infrastructure`-Instanz als Ganzes (Risiko: Daten anderer Lernprojekte) --- ## Seite 12 – DevOps, Infrastruktur und Deployment **URL:** https://aydinsude.atlassian.net/wiki/spaces/PRX/pages/2293771 **Neuer Status:** CONFIRMED Der bisherige Inhalt dieser Seite ist bereits inhaltlich vollständig und konsistent mit der tatsächlichen `enterprise-infrastructure`-Konfiguration verifiziert (Traefik/`proxy`-Netzwerk, zentraler Jenkins, optionale Profile für Postgres/Keycloak/Kafka/RabbitMQ/Observability). Ergänzend zu bestätigen: - Projekt-Datenbank: `procurex` (siehe Seite 10) - Keycloak-Realm: `procurex` - Kafka-Topic-Präfix: `procurex.` - Traefik-Hostnamen: `procurex.localhost` (Frontend), `procurex-api.localhost` (Backend-API) [ANNAHME] - Referenzversionen (siehe Seite 08): Traefik v3.7.10, PostgreSQL 16-alpine, Keycloak 26.7.0, Kafka/Confluent 7.7.1, Prometheus v2.55.0, Grafana 11.2.0 - Status kann direkt von `DRAFT / PROVISIONAL` auf `CONFIRMED` gesetzt werden, keine inhaltlichen Änderungen nötig außer den obigen Ergänzungen --- ## Seite 13 – Teststrategie und Qualität **URL:** https://aydinsude.atlassian.net/wiki/spaces/PRX/pages/2064392 **Neuer Status:** CONFIRMED - **Unit-Tests:** JUnit 5 + Mockito, Fokus auf Domänenregeln (z.B. gültige Bestellstatus-Übergänge, einmalige Genehmigungsentscheidung) - **Integrationstests:** Testcontainers für PostgreSQL und Kafka, ein Testcontainer-Setup pro Modul - **Contract-Tests:** Spring Cloud Contract für REST-Verträge zwischen Frontend und Backend [ANNAHME] - **E2E-Tests:** Playwright für den kompletten Procure-to-Pay-Fluss (Katalogsuche → Warenkorb → Bestellung → Genehmigung → Wareneingang → Rechnungsprüfung) [ANNAHME] - **Lasttests:** k6 für Katalogsuche, Bestellabsendung und Genehmigungsentscheidung (die drei in den Tickets explizit genannten Lastszenarien) - **Coverage-Ziel:** 80% Linien-Coverage in `domain`/`application`, 60% Gesamtprojekt (konsistent mit Seite 11), Gate in der Jenkins-Pipeline - **Security-Tests:** OWASP Dependency-Check (siehe Seite 11) als Pflicht-Gate; ergänzend ZAP-Baseline-Scan gegen die laufende Anwendung als optionaler Pipeline-Schritt [ANNAHME] - **Flaky-Test-Regel:** Ein Test, der 2x hintereinander in der Pipeline ohne Codeänderung unterschiedlich ausfällt, wird als Bug-Ticket erfasst und bis zur Behebung `@Disabled` markiert, nicht stillschweigend ignoriert - **Kein Release ohne grüne Pflicht-Gates:** Unit-, Integrations- und Contract-Tests sowie Checkstyle/SpotBugs/OWASP-Check sind Pflicht-Gates; E2E- und Lasttests sind Pflicht vor einem "Sprint-Review"-Release, nicht vor jedem einzelnen Merge [ANNAHME] --- ## Seite 14 – Observability, Betrieb und Dokumentation **URL:** https://aydinsude.atlassian.net/wiki/spaces/PRX/pages/1933360 **Neuer Status:** CONFIRMED **Hinweis:** Diese Seite wurde nicht im Volltext gelesen (nur das zugehörige Jira-Ticket PRX-25). Vorschlag basierend auf PRX-25-Akzeptanzkriterien und den vorhandenen enterprise-infrastructure-Prometheus/Grafana-Vorgaben – vor Übernahme kurz mit dem tatsächlichen Seiteninhalt abgleichen. - Jeder Service exponiert `/actuator/prometheus`, tritt dem `proxy`-Netzwerk bei, wird als eigener Scrape-Job in `shared/enterprise-infrastructure/prometheus/prometheus.yml` ergänzt (Job-Name `procurex`) - Zentrales strukturiertes Logging (JSON, mit `X-Correlation-Id` als Feld) auf stdout, Aggregation obliegt der enterprise-infrastructure-Plattform - Grafana-Dashboards projektbezogen mit Tag `procurex` gekennzeichnet, in der zentralen Grafana-Instanz - Alerts [ANNAHME]: Fehlerrate `>5%` über 5 Minuten, `p95`-Latenz `>1s` auf `/api/v1/orders`, Kafka-Consumer-Lag `>1000` Nachrichten - Aufbewahrung: Metriken 30 Tage, Logs 14 Tage (Lernprojekt-Annahme, keine echten Compliance-Vorgaben) [ANNAHME] - Runbooks als Markdown unter `/docs/runbooks/` je kritischem Fehlerbild (z.B. "Kafka-Consumer-Lag steigt", "Keycloak nicht erreichbar") --- ## Betroffene Jira-Tickets (PRX, `aydinsude.atlassian.net`) Nach Übernahme der obigen Inhalte in Confluence sollten folgende Tickets aktualisiert werden: | Ticket | Aktuelle Zusammenfassung | Vorschlag | |---|---|---| | PRX-13 | Technologieversionen und Lizenzen verbindlich bestätigen | Status → Done, Beschreibung um finale Versionstabelle (Seite 08) ergänzen | | PRX-14 | Zielarchitektur und Bounded Context Map dokumentieren | Status → Done, Verweis auf Modulliste (Seite 09) | | PRX-15 | Maven-Multi-Modul-Struktur und Dependency Management definieren | Status → Done, Verweis auf Modulbaum (Seite 09) und Buildsystem (Seite 11) | | PRX-16 | REST-API-Konventionen und OpenAPI-Regeln dokumentieren | Status → Done, Verweis auf Seite 10 | | PRX-17 | Kafka-Event-Schemas, Outbox und DLQ festlegen | Status → Done, Verweis auf Event-Namensschema (Seite 10) | | PRX-18 | PostgreSQL-Datenmodell und Flyway-Konventionen definieren | Status → Done, Verweis auf Schema-pro-Modul-Konzept (Seite 10) | | PRX-19 | Keycloak-OIDC-JWT- und Rollenmodell dokumentieren | Status → Done, Verweis auf Realm/Rollen (Seite 10) | | PRX-23 | Jenkins-CI/CD-Pipeline und Quality Gates definieren | Status → Done, Verweis auf Gates (Seite 11/13) | | PRX-24 | Teststrategie für Unit/Integration/Contract/E2E/Lasttests festlegen | Status → Done, Verweis auf Seite 13 | | PRX-25 | Prometheus-, Grafana- und Logging-Konzept dokumentieren | Status → Review (Seite 14 nicht im Volltext geprüft), Verweis auf Seite 14 | | PRX-20, PRX-21, PRX-22 | Angular-Frontend, Docker-Compose, Kubernetes/Helm | Implementierungsartefakte vorhanden und Jira erledigt; Live-Deployment sowie erneuter Build-/Testnachweis separat verifizieren | Nach diesem Update sind die Planungsblocker für die Code-Tickets PRX-2 bis PRX-5, PRX-8 bis PRX-12 (Sprint 1–4) aufgelöst. Die Implementierung hat begonnen; spätere Nachweise und offene Grenzen stehen in den Sprintabschluss- und Betriebsdokumenten.