docs: massive restructuring of documentation, development guides and agent playbooks

2026-06-15 12:54:38 +02:00
parent e4988b4397
commit ce63303b2c
686 changed files with 45423 additions and 319 deletions
@@ -0,0 +1,63 @@
+---
+type: Reference
+status: ACTIVE
+owner: Backend Developer
+last_update: 2026-04-03
+---
+
+# API-Übersicht Stammdaten
+
+Abdeckung: Backend Sprint B‑1 (abgeschlossen). Konsolidierte Endpunkte für Reiter, Pferde, Vereine und Funktionäre. Implementiert mit Ktor; DTOs und Validierung in den jeweiligen Services.
+
+Hinweis Tenant/Headers: Stammdaten sind global bzw. nicht tenant‑spezifisch. Für domain‑spezifische Vorgänge (Entries, Kassa) gilt ADR‑0021/`X-Event-Id`.
+
+## Reiter (`/reiter`)
+
+- GET `/reiter` — Liste (optional Filter: `lizenzKlasse`, `vereinId`; Pagination: `limit`, `offset`)
+- GET `/reiter/search?q=...` — Suche nach Name oder Satznummer
+- GET `/reiter/{id}` — Einzelabruf
+- GET `/reiter/satznummer/{nr}` — Lookup per Satznummer
+- POST `/reiter` — Anlegen
+- PUT `/reiter/{id}` — Aktualisieren (partiell)
+- DELETE `/reiter/{id}` — Löschen
+
+Quelle: `backend/services/masterdata/masterdata-api/.../ReiterController.kt`
+
+## Pferde (`/horse`)
+
+- GET `/horse` — Liste (optional Filter: `jahrgang`, `besitzerId`; Pagination: `limit`, `offset`)
+- GET `/horse/search?q=...` — Suche nach Name/Nummern
+- GET `/horse/{id}` — Einzelabruf
+- POST `/horse` — Anlegen
+- PUT `/horse/{id}` — Aktualisieren (partiell)
+- DELETE `/horse/{id}` — Löschen
+
+Quelle: `backend/services/masterdata/masterdata-api/.../HorseController.kt`
+
+## Vereine (`/verein`)
+
+- GET `/verein` — Liste (optional Filter: `verband`/Bundesland; Pagination: `limit`, `offset`)
+- GET `/verein/search?q=...` — Suche nach Name/Kurzname
+- GET `/verein/{id}` — Einzelabruf
+- POST `/verein` — Anlegen
+- PUT `/verein/{id}` — Aktualisieren (partiell)
+- DELETE `/verein/{id}` — Löschen
+
+Quelle: `backend/services/masterdata/masterdata-api/.../VereinController.kt`
+
+## Funktionäre (`/funktionaer`)
+
+- GET `/funktionaer` — Liste (optional Filter: `rolle`; Pagination: `limit`, `offset`)
+- GET `/funktionaer/search?q=...` — Suche nach Name
+- GET `/funktionaer/{id}` — Einzelabruf
+- POST `/funktionaer` — Anlegen
+- PUT `/funktionaer/{id}` — Aktualisieren (partiell)
+- DELETE `/funktionaer/{id}` — Löschen
+
+Quelle: `backend/services/masterdata/masterdata-api/.../FunktionaerController.kt`
+
+## Standards
+
+- Auth: Standard-Bearer optional je nach Deploymentprofil (siehe Service-Konfig)
+- Content-Type: `application/json; charset=utf-8`
+- Fehlerfälle: 400 (Validierung), 404 (nicht gefunden)
@@ -0,0 +1,37 @@
+---
+type: Reference
+status: DRAFT
+owner: Backend Developer
+last_update: 2026-04-03
+---
+
+# Kassa-API (Entwurf)
+
+Abhängigkeit: Backend Sprint B‑2 (Kassa-Service) — laut Curator‑Roadmap noch offen. Dieses Dokument reserviert die Endpunkte und beschreibt die Erwartungen. Die Implementierungsdetails werden ergänzt, sobald der Service fertiggestellt ist.
+
+Mandantenkontext: Erfordert `X-Event-Id` (ADR‑0021). Alle Kassa‑Operationen sind tenant‑lokal.
+
+## Endpunkte (geplant)
+
+- GET `/kassa/saldo` — Liefert den aktuellen Saldo der Veranstaltung und optional pro Turnier.
+  - Query: `turnierId` (optional, UUID)
+  - Response: `{ saldoCents: long, currency: "EUR", scope: "veranstaltung"|"turnier", turnierId?: UUID }`
+
+- GET `/zahlvorgaenge` — Listet Kassa‑Buchungen/Zahlvorgänge (paginiert, filterbar).
+  - Query: `turnierId?`, `teilnehmerId?`, `typ?` (EINZAHLUNG|AUSZAHLUNG|KORREKTUR), `limit`, `offset`
+  - Response: Liste von Transaktionen mit Betrag, Zeit, Verweis (Teilnehmer/Turnier), Notiz
+
+- POST `/zahlvorgaenge` — Erstellt einen neuen Zahlungsvorgang (Ein-/Auszahlung/Korrektur).
+  - Body: `{ typ, betragCents, currency, referenz: { teilnehmerId?|turnierId? }, notiz? }`
+  - Wirkung: Aktualisiert `teilnehmer_konten` bzw. `turnier_kassa` atomar.
+
+## Validierung & Regeln (voraussichtlich)
+
+- Atomare Konsistenz: Transaktion + Saldo‑Update innerhalb einer DB‑Transaktion.
+- Negativsaldo optional durch Feature‑Flag blockierbar.
+- Audit‑Trail pro Vorgang (who/when), Idempotenz‑Key optional.
+
+## Implementierungsstand
+
+- Datenstrukturen `teilnehmer_konten` und `turnier_kassa` sind per Flyway angelegt (siehe [Datenbankschema](../Schema/Database_Schema_V1-V009.md)).
+- Endpunkte folgen nach Abschluss Backend B‑2. Dieses Dokument wird dann auf `status: ACTIVE` gesetzt.