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,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.