meldestelle/docs/04_Agents/Roadmaps/Backend_Roadmap.md

👷 [Backend Developer] — Schritt-für-Schritt Roadmap

Stand: 3. April 2026 Rolle: Spring Boot / Ktor, Kotlin, SQL, API-Design, Datenbankschema, Services

---

🔴 Sprint A — Sofort (diese Woche)

✅ ADR-0021 (Tenant-Strategie) liegt vor (2026-04-02) — A-1 gestartet

• A-1 | Tenant-Isolation im Datenzugriffs-Layer implementieren

  • ADR-0021 (Architect) lesen und Strategie übernehmen
  • Tenant-Resolution-Mechanismus implementieren (wie erkennt das Backend die Ziel-Datenbank?)
    • Entries Service: TenantWebFilter liest X-Event-Id/Subdomain; TenantRegistry (In-Memory, konfigurierbar)
  • Alle Datenzugriffe mit Tenant-Kontext absichern
    • Entries Service (Exposed): tenantTransaction {} setzt SET search_path TO <schema> pro Request
  • Sicherstellen: Kein Cross-Tenant-Datenzugriff möglich
    • Verhindert durch verpflichtenden Tenant-Kontext + search_path; Fehlerfälle: 400/404/423
  • Nächste Schritte (A-1 Ausbau):
    • JdbcTenantRegistry gegen control.tenants implementieren (inkl. Migrationen)
      • Flyway-SQL: db/control/V1__init_control_and_tenants.sql
      • Spring-JDBC JdbcTenantRegistry + Konfiguration (multitenancy.registry.type=jdbc)
    • Flyway pro Tenant-Schema (Rollout aktivierter Tenants)
      • db/tenant/V1__entries_schema.sql (Tabellen nennungen, nennungs_transfers)
      • TenantMigrationsRunner migriert aktive Schemas beim Start (liest control.tenants oder multitenancy.defaultSchemas)
    • Rollout der Absicherung auf weitere Services (Repos/DAOs)
      • Folge-PRs für weitere Services (aktuell: Entries Service migriert)
    • Observability: tenant_id in Logs/Metrics/Traces`
      • TenantWebFilter setzt MDC["tenant_id"]
    • Tests: Unit (Resolver/Registry) + E2E (Isolation A/B)
      • Unit: JdbcTenantRegistryTest (H2)
      • E2E: Isolation A/B mit Testcontainers Postgres
        • Aktueller Status: Integrationstest temporär via @Disabled deaktiviert, um den Build zu entblocken; Re-Enable nach Stabilisierung der Jackson/Spring-Web-Konverter-Autokonfiguration

• A-2 | Datenbankschema: Domänen-Hierarchie umsetzen

  • Tabelle veranstaltungen anlegen (interne ID, Tenant-Grenze)
  • Tabelle turniere anlegen (FK → veranstaltung_id, OEPS-Turniernummer als eigenes Feld)
  • Tabelle bewerbe anlegen (FK → turnier_id, Klasse, Höhe, Bezeichnung)
  • Tabelle abteilungen anlegen (FK → bewerb_id, nr, bezeichnung, typ: SEPARATE_SIEGEREHRUNG | ORGANISATORISCH)
  • Tabelle teilnehmer_konten anlegen (FK → veranstaltung_id, aggregiert Salden über Turniere)
  • Tabelle turnier_kassa anlegen (FK → turnier_id, separate Kassa pro Turnier)
  • Migrations-Skript schreiben und testen (db/tenant/V2__domain_hierarchy.sql, Test: DomainHierarchyMigrationTest)
  • Ergänzung V3 (Turnier-Status): Migration db/tenant/V3__turniere_status.sql
    • ALTER TABLE turniere ADD COLUMN status VARCHAR(16) NOT NULL DEFAULT 'DRAFT' + CHECK(status IN ('DRAFT','PUBLISHED'))
    • ALTER TABLE turniere ADD COLUMN published_at TIMESTAMP WITH TIME ZONE NULL
    • Backfill: Alle bestehenden Zeilen auf DRAFT setzen; Default danach wieder entfernen oder beibehalten (Entscheidung: beibehalten für Insert-Sicherheit)
    • Indexe: CREATE INDEX IF NOT EXISTS idx_turniere_status ON turniere(status)
    • Folgetasks: Domänenservice-Validierung für Statuswechsel (siehe B-1 Turniere/PATCH)

• A-3 | Validierungs-Grundlage: Turnierkategorie-Limits

  • Grundlage implementiert: Entkoppelte Policy-Schnittstelle + Bewerb-Descriptor
    • Events-Domain: DomTurnier.validateKategorieLimits(bewerbe, policy) delegiert an TurnierkategoriePolicy
    • Neu: TurnierBewerbDescriptor, TurnierkategoriePolicy, NoopTurnierkategoriePolicy
    • Test: DomTurnierKategorieValidationTest mit Fake-Policy (Verkabelung + Beispielverletzungen)
  • Konkrete Regeln/Limits gemäß ÖTO umsetzen (eigene Policy-Implementierung)
    • OeToTurnierkategoriePolicy: Harte Max-Limits umgesetzt (CSN: Höhe in cm; CDN: Klassen-Level). Sonderregeln (Pflichtbewerbe, Tageslimits, Genehmigungen) offen.
    • Tests: OeToTurnierkategoriePolicyTest (CSN/C und C-NEU; B vs. 140 cm; CDN/C und C-NEU; B vs. S)
  • Voraussetzung: Spezifikation von 📜 Rulebook Expert (A-5) abwarten (zur Ergänzung der Sonderregeln)

---

🟠 Sprint B — Kurzfristig (nächste Woche)

• B-1 | CRUD-Endpunkte für alle Stammdaten-Entitäten (überarbeitet)

  • Multitenancy: Alle Endpunkte laufen im Tenant-Schema (Erkennung via X-Event-Id oder Subdomain; siehe A-1). IDs sind UUIDs. Fehlercodes: 400 (Bad Request), 404 (Not Found), 409 (Conflict), 422 (Validation), 423 (Locked – Tenant/Status).

  • Konventionen:

    • POST → 201 + Location-Header; GET (Liste) ist paginiert (page, size) + einfache Filter (q, spezifische Felder).
    • PUT = Voll-Update; PATCH = Teil-Update für Status/kleine Änderungen, wo sinnvoll.
    • Lösch-Strategie: Hard-Delete nur für Stammdaten ohne Referenzen; sonst 409 bei FK-Verletzung.
    • Standard-HTTP-Codes: GET 200, POST 201, PUT 200, PATCH 200, DELETE 204; Fehler gemäß obiger Liste.

  • Veranstaltung (Singleton pro Tenant)

    • GET /veranstaltung — aktuelle Veranstaltung lesen
    • PUT /veranstaltung — Veranstaltung aktualisieren
    • Hinweis: Erstellen/Löschen einer Veranstaltung erfolgt im Control-Plane (außerhalb des Tenant-Services); daher kein POST/DELETE hier.

  • Turniere

    • POST /turniere — Turnier anlegen (Felder: veranstaltungId implizit aus Tenant, oepsTurniernummer, optional bezeichnung, datumVon/Bis, optional status—Default DRAFT)
    • GET /turniere — Liste (Filter: oepsTurniernummer, Zeitraum, status; Paging)
    • GET /turniere/{id} — Detail
    • PUT /turniere/{id} — Voll-Update (ohne Status-Übergang)
      • Regeln: Bei PUBLISHED nur Metadaten änderbar, keine strukturellen Felder (z. B. oepsTurniernummer) → sonst 423 Locked.
    • DELETE /turniere/{id} — löschen (409, falls abhängige Bewerbe existieren; bei PUBLISHED grundsätzlich gesperrt → 423 Locked)
    • Status-Management (neues Feld, Migration V3__turniere_status.sql): DRAFT | PUBLISHED
      • PATCH /turniere/{id}/status — Statuswechsel mit Validierung
        • Erlaubt: DRAFT → PUBLISHED (setzt publishedAt-Timestamp serverseitig)
        • PUBLISHED → DRAFT nur erlaubt, wenn keine Nennungen/Zahlungen verbucht sind (sonst 409 Conflict)
        • Unerlaubte Übergänge → 422 Validation (inkl. Begründung im problem+json-Body)

  • Bewerbe (FK → Turnier)

    • POST /turniere/{turnierId}/bewerbe — anlegen
    • GET /turniere/{turnierId}/bewerbe — Liste im Turnier
    • GET /bewerbe/{id} — Detail
    • PUT /bewerbe/{id} — aktualisieren
    • DELETE /bewerbe/{id} — löschen (409 bei existierenden Abteilungen/Nennungen; gesperrt falls zu PUBLISHED Turnier → 423 Locked)

  • Abteilungen (FK → Bewerb)

    • POST /bewerbe/{bewerbId}/abteilungen — anlegen (Felder: nr, bezeichnung, typ: SEPARATE_SIEGEREHRUNG | ORGANISATORISCH)
    • GET /bewerbe/{bewerbId}/abteilungen — Liste
    • GET /abteilungen/{id} — Detail
    • PUT /abteilungen/{id} — aktualisieren
    • DELETE /abteilungen/{id} — löschen (gesperrt falls zu PUBLISHED Turnier → 423 Locked)

  • Hinweis: Filter q (LIKE/ILIKE) bei Bewerbe-Liste ist vorerst ausgelassen und kann nachgezogen werden.

  • Reiter (Athleten-Stammdaten)

    • POST/GET/GET{id}/PUT/DELETE /reiter — Suche über q (Name, Lizenznr.), Filter: lizenzKlasse, vereinId

  • Pferde (Pferde-Stammdaten)

    • POST/GET/GET{id}/PUT/DELETE /pferde — Suche q (Name, Lebensnr.), Filter: jahrgang, besitzerId

  • Vereine

    • POST/GET/GET{id}/PUT/DELETE /vereine — Suche q (Name, Kürzel), Filter: verband

  • Funktionäre

    • POST/GET/GET{id}/PUT/DELETE /funktionaere — Suche q (Name, Lizenznr.), Filter: rolle

  • Technische Notizen

    • API-Doku per OpenAPI (Springdoc) veröffentlichen; Beispiel-Payloads für POST/PUT/PATCH (Statuswechsel)
    • Konsistentes Error-Format (problem+json)
    • E2E-Tests: CRUD-Flows für Turnier → Bewerb → Abteilung inkl. FK-Constraints
    • Migration V3__turniere_status.sql in Flyway integrieren und gegen H2/Postgres testen (Back/Forward kompatibel)
    • Guardrails: Service-Ebene erzwingt Locks für PUBLISHED (PUT/DELETE) und valide Status-Transitions (PATCH)
    • Problem+JSON-Details: type, title, status, detail, instance befüllen; bei 422 Begründung/Violations je Feld mitschicken.

• B-2 | Kassa-Service implementieren

  • TeilnehmerKonto-Service: Saldo aus mehreren Turnieren aggregieren
  • Zahlvorgang-Service: Eine Zahlung auf Veranstaltungs-Ebene buchen
  • Rechnungs-Generierung: Separate Rechnung je Turnier aus einem Zahlvorgang
  • Endpunkte: GET /veranstaltungen/{id}/kassa/saldo, POST /veranstaltungen/{id}/zahlvorgaenge

• B-3 | ÖTO-Validierung serverseitig absichern

  • Spezifikation von 📜 Rulebook Expert (Sprint A-5) umsetzen
  • OEPS-Nummern-Format validieren
  • FEI-ID-Format validieren
  • Lizenzklassen-Validierung (R1–R4, LZF)
  • Altersklassen-Kompatibilität Pferd × Bewerb validieren
  • Abteilungs-Zwangsteilung im CSN-C-NEU durchsetzen (Bewerb ≤95cm: ohne/mit Lizenz; ≥100cm: R1/R2+)

• B-4 | Nennungs-Service (Grundstruktur)

  • Tabelle nennungen anlegen (FK → abteilung_id, Status: NEU | GEPRÜFT | BESTÄTIGT | ABGELEHNT)
  • POST /turniere/{id}/nennungen — Nennungs-Eingang vom Web-Formular
  • GET /turniere/{id}/nennungen — Postfach für Desktop-App (Meldestelle)
  • PATCH /nennungen/{id}/status — Bestätigen / Ablehnen

---

🟡 Sprint C — Mittelfristig (in 2 Wochen)

• C-1 | Testdaten-Seeder implementieren

  • Reproduzierbare Veranstaltung mit 2 Turnieren (Neumarkt-Szenario)
  • Bewerbe mit korrekten Abteilungen (inkl. CSN-C-NEU Pflicht-Teilung)
  • Reiter, Pferde, Vereine als Stammdaten
  • Nennungen in verschiedenen Status-Stufen
  • Seeder via Gradle-Task ausführbar

• C-2 | Statistik-Endpunkte

  • GET /turniere/{id}/statistiken — Statistiken pro Turnier
  • GET /veranstaltungen/{id}/statistiken — Aggregierte Statistiken über alle Turniere

---

📌 Abhängigkeiten

Warte auf	Von wem
ADR-0021 (Tenant-Strategie)	🏗️ Architect
Validierungs-Spezifikation (OEPS, FEI, Lizenz)	📜 Rulebook Expert
Domänen-Modell final	🏗️ Architect

Meine Aufgabe	Ermöglicht wem
CRUD-Endpunkte (B-1)	🎨 Frontend: Backend-Anbindung
Kassa-Service (B-2)	🎨 Frontend: Kassa-Screen
Nennungs-Service (B-4)	🎨 Frontend: Nennungs-Postfach