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:

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.<bounded-context>.<event-name>.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: <topic-name>.dlq
• Ein Consumer-Group-Name pro konsumierendem Modul (procurex-<modul>-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/<schema> 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-<Ticketnummer>-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:

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.