feat(billing): implement REST API, database config, and tests for billing service

- **REST API:** Added `BillingController` with endpoints for managing participant accounts and transactions, including history retrieval. - **Database Configuration:** Introduced `BillingDatabaseConfiguration` to initialize database schema using Exposed. - **Testing:** Added integration tests for `TeilnehmerKontoService` using H2 in-memory database.
2026-04-10 12:26:57 +02:00
parent 21f3a57e6e
commit eef17b3067
8 changed files with 476 additions and 20 deletions
@@ -0,0 +1,210 @@
+openapi: 3.0.3
+info:
+  title: Billing SCS API
+  description: >
+    API für den Billing-Bounded-Context (Kassa, Abrechnung, Teilnehmerkonten)
+  version: 1.0.0
+servers:
+  - url: http://localhost:8089
+    description: Lokaler Entwicklungs-Server
+paths:
+  /api/billing/konten:
+    get:
+      summary: Teilnehmerkonto suchen
+      description: Sucht ein Konto basierend auf Veranstaltungs-ID und Personen-ID. Erstellt das Konto, falls es nicht existiert.
+      parameters:
+        - name: veranstaltungId
+          in: query
+          required: true
+          schema:
+            type: string
+            format: uuid
+        - name: personId
+          in: query
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '200':
+          description: Teilnehmerkonto
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/KontoDto'
+        '400':
+          description: Ungültige UUID-Formate
+    post:
+      summary: Teilnehmerkonto erstellen oder abrufen
+      description: Erstellt ein neues Teilnehmerkonto für eine Veranstaltung und eine Person.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateKontoRequest'
+      responses:
+        '200':
+          description: Teilnehmerkonto (neu erstellt oder bestehend)
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/KontoDto'
+        '400':
+          description: Validierungsfehler
+  /api/billing/konten/{kontoId}:
+    get:
+      summary: Teilnehmerkonto nach ID abrufen
+      parameters:
+        - name: kontoId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '200':
+          description: Details zum Teilnehmerkonto
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/KontoDto'
+        '404':
+          description: Konto nicht gefunden
+        '400':
+          description: Ungültige Konto-ID
+  /api/billing/konten/{kontoId}/buchungen:
+    get:
+      summary: Buchungshistorie abrufen
+      description: Liefert alle Buchungen für ein bestimmtes Teilnehmerkonto.
+      parameters:
+        - name: kontoId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '200':
+          description: Liste von Buchungen
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/BuchungDto'
+        '400':
+          description: Ungültige Konto-ID
+    post:
+      summary: Buchung hinzufügen
+      description: Führt eine neue Buchung auf dem Teilnehmerkonto durch und aktualisiert den Saldo.
+      parameters:
+        - name: kontoId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/BuchungRequest'
+      responses:
+        '200':
+          description: Aktualisiertes Teilnehmerkonto nach der Buchung
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/KontoDto'
+        '400':
+          description: Validierungsfehler oder ungültige Konto-ID
+components:
+  schemas:
+    KontoDto:
+      type: object
+      properties:
+        kontoId:
+          type: string
+          format: uuid
+        veranstaltungId:
+          type: string
+          format: uuid
+        personId:
+          type: string
+          format: uuid
+        personName:
+          type: string
+        saldoCent:
+          type: integer
+          format: int64
+          description: Aktueller Saldo in Cent
+        bemerkungen:
+          type: string
+          nullable: true
+        updatedAt:
+          type: string
+          format: date-time
+          description: Zeitpunkt der letzten Aktualisierung
+    BuchungDto:
+      type: object
+      properties:
+        buchungId:
+          type: string
+          format: uuid
+        kontoId:
+          type: string
+          format: uuid
+        betragCent:
+          type: integer
+          format: int64
+          description: Betrag in Cent (positiv für Gutschriften, negativ für Belastungen)
+        typ:
+          $ref: '#/components/schemas/BuchungsTyp'
+        verwendungszweck:
+          type: string
+        gebuchtAm:
+          type: string
+          format: date-time
+    CreateKontoRequest:
+      type: object
+      required:
+        - veranstaltungId
+        - personId
+        - personName
+      properties:
+        veranstaltungId:
+          type: string
+          format: uuid
+        personId:
+          type: string
+          format: uuid
+        personName:
+          type: string
+          minLength: 1
+    BuchungRequest:
+      type: object
+      required:
+        - betragCent
+        - typ
+        - verwendungszweck
+      properties:
+        betragCent:
+          type: integer
+          format: int64
+        typ:
+          $ref: '#/components/schemas/BuchungsTyp'
+        verwendungszweck:
+          type: string
+          minLength: 1
+    BuchungsTyp:
+      type: string
+      enum:
+        - NENNGEBUEHR
+        - KOPPELGEBUEHR
+        - NACHNENNGEBUEHR
+        - STARTGEBUEHR
+        - EINZAHLUNG
+        - AUSZAHLUNG
+        - SONSTIGES