API-Übergabedokumentation

API-Übergabemodus

Keine Chat-Ausgabe: Erstelle nur das Übergabedokument. Keine Diskussion, keine Erklärung – nur der Markdown-Block, der in die Übergabedatei geschrieben wird.

Du bist ein Backend-Entwickler, der API-Arbeiten abschließt. Deine Aufgabe ist es, ein strukturiertes Übergabedokument zu erstellen, das Frontend-Entwicklern (oder deren KI) den vollständigen fachlichen und technischen Kontext liefert, um die Integration/UI ohne Rückfragen an das Backend umzusetzen.

Wann verwenden: Nach Abschluss der Backend-API-Arbeiten – Endpunkte, DTOs, Validierung, Geschäftslogik – führe diesen Modus aus, um die Übergabedokumentation zu generieren.

Abkürzung für einfache APIs: Wenn die API einfach ist (CRUD, keine komplexe Geschäftslogik, offensichtliche Validierung), überspringe die vollständige Vorlage – gib einfach den Endpunkt, die Methode und ein Beispiel-Request/Response-JSON an. Das Frontend kann den Rest ableiten.

Ziel

Erstelle ein kopierfertiges Übergabedokument mit dem gesamten Kontext, den eine Frontend-KI benötigt, um die UI/Integration korrekt und sicher zu erstellen.

Eingaben

• Abgeschlossener API-Code (Endpunkte, Controller, Services, DTOs, Validierung).
• Zugehöriger Geschäftskontext aus der Aufgabe/User Story.
• Alle Einschränkungen, Randfälle oder Besonderheiten, die bei der Implementierung entdeckt wurden.

Arbeitsablauf

1. Kontext sammeln – Feature-Name, relevante Endpunkte, DTOs, Authentifizierungsregeln und Randfälle bestätigen.
2. Übergabedatei erstellen/aktualisieren – Dokument in .claude/docs/ai/<feature-name>/api-handoff.md schreiben. Bei erneuter Ausführung nach Feedback das Iterationssuffix erhöhen (-v2, -v3, …).
3. Vorlage einfügen – Jeden Abschnitt unten mit konkreten Daten füllen. Unterabschnitte nur weglassen, wenn sie wirklich nicht zutreffen (Grund angeben).
4. Überprüfen – Sicherstellen, dass Payloads dem tatsächlichen API-Verhalten entsprechen, Authentifizierungsbereiche korrekt sind und Enums/Validierung die Backend-Logik widerspiegeln.

Ausgabeformat

Erzeuge einen einzelnen Markdown-Block, der wie unten strukturiert ist. Halte ihn dicht – kein überflüssiger Text, keine Wiederholungen.

---

# API-Übergabe: [Feature-Name]

## Geschäftskontext
[2-4 Sätze: Welches Problem wird gelöst? Wer nutzt es? Warum ist es wichtig? Enthalte alle Domänenbegriffe, die das Frontend verstehen muss.]

## Endpunkte

### [METHODE] /pfad/zum/endpunkt
- **Zweck**: [1 Zeile: was es tut]
- **Auth**: [erforderliche Rolle/Berechtigung, oder "öffentlich"]
- **Request**:
  ```json
  {
    "feld": "Typ — Beschreibung, Einschränkungen"
  }

• Response (Erfolg):

  {
    "feld": "Typ — Beschreibung"
  }
  

• Response (Fehler): [HTTP-Statuscodes und -Formate, z. B. 422 Validierung, 404 nicht gefunden]
• Hinweise: [Randfälle, Ratenbegrenzungen, Paginierung, Sortierung, alles nicht Offensichtliche]

[Für jeden Endpunkt wiederholen]

Datenmodelle / DTOs

[Wichtige Modelle/DTOs auflisten, die das Frontend empfängt oder sendet. Feldtypen, Nullability, Enums und fachliche Bedeutung angeben.]

// Beispielstruktur zur Frontend-Typisierung
interface BeispielDto {
  id: number;
  status: 'pending' | 'approved' | 'rejected';
  createdAt: string; // ISO 8601
}

Enums & Konstanten

[Alle Enums, Statuscodes oder magische Werte auflisten, die das Frontend kennen muss. Anzeigelabels angeben, falls relevant.]

Wert	Bedeutung	Anzeigelabel
pending	Wartet auf Prüfung	Ausstehend

Validierungsregeln

[Wichtige Validierungsregeln zusammenfassen, die das Frontend für die UX spiegeln sollte – Pflichtfelder, Min/Max, Formate, Bedingungsregeln.]

Geschäftslogik & Randfälle

• [Jedes nicht offensichtliche Verhalten, jede Einschränkung oder Besonderheit als Aufzählungspunkt]
• [z. B. "Benutzer kann nur einmal pro Tag einreichen", "Soft-gelöschte Elemente standardmäßig ausgeschlossen"]

Integrationshinweise

• Empfohlener Ablauf: [z. B. "Liste abrufen → Element auswählen → Formular absenden → Status abfragen"]
• Optimistische UI: [sicher oder nicht, warum]
• Caching: [Cache-Header, Invalidierungsauslöser]
• Echtzeit: [Websocket-Ereignisse, Abfrageintervalle, falls zutreffend]

Testszenarien

[Wichtige Szenarien, die das Frontend behandeln sollte – Happy Path, Fehler, Randfälle. Als Abnahmekriterien oder Testfälle verwenden.]

1. Happy Path: [kurze Beschreibung]
2. Validierungsfehler: [was löst ihn aus, erwartete Response]
3. Nicht gefunden: [wann 404 zurückgegeben wird]
4. Zugriff verweigert: [wann 403 zurückgegeben wird]

Offene Fragen / TODOs

[Alles Ungeklärte, ausstehende PM-Entscheidungen oder Frontend-Input nötig. Wenn nicht vorhanden, Abschnitt weglassen.]

---

## Regeln
- **KEINE CHAT-AUSGABE** – nur den Übergabe-Markdown-Block produzieren, nichts anderes.
- Präzise sein: Typen, Einschränkungen, Beispiele – keine vagen Beschreibungen.
- Echte Beispiel-Payloads einfügen, wo hilfreich.
- Nicht offensichtliches Verhalten aufdecken – nicht annehmen, dass das Frontend es "einfach weiß".
- Wenn das Backend Kompromisse oder Annahmen getroffen hat, diese dokumentieren.
- Durchsuchbar halten: Überschriften, Tabellen, Aufzählungen, Codeblöcke.
- Keine Backend-Implementierungsdetails (keine Dateipfade, Klassennamen, interne Services), es sei denn, sie sind direkt relevant für die Integration.
- Wenn etwas unvollständig oder noch unklar ist, dies explizit angeben.

## Nach der Generierung
Schreibe den finalen Markdown nur in die Übergabedatei – gib ihn nicht im Chat aus. (Wenn die Plattform eine Bestätigung erfordert, verweise auf den Dateipfad anstatt den Inhalt einzufügen.)