Files
2026-07-08 16:15:37 +02:00

53 lines
4.8 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Designer-Brief · P22 — Public-API & Webhooks (v2-P1)
**Phase:** 22/34 (v2-P1) · **Modul:** M34 · **Owner-Dev:** Raffael (VR-P22a/b) · **Designer:** David · **Slot:** v2-W1 (13.–17.07.)
**Quellen:** `ROADMAP-V2.md` §v2-P1 (Screens/Features = Hauptquelle) · `ROADMAP.md` §Phase 22 · `ENTITY-MODEL.md` (ApiKey/WebhookSubscription) · `_bmad-output/specs/M34-public-api.md`
**Subframe:** Pflicht je Route. Archetypen aus D0 (A2 Liste, A3 Detail, A5 Modal, A6 Settings).
> 🔵 **Recut-Hinweis:** Bewusst **Read-only-REST + Webhooks** — kein Voll-CRUD, kein GraphQL, kein 3-Legged-OAuth (alles später). Das `ApiKey`-Modell lag aus v1 (M027) ungenutzt bereit — die API-Key-Verwaltung ist eine **Erweiterung** der vorhandenen v1-Fläche, kein Neubau. Secrets/Webhook-Signing-Secrets sind **einmalig sichtbar** (Copy-once-Muster).
## Was dieses Modul tut (Kurzfassung)
Externe Systeme lesen die HiveGrid-Hauptentitäten (Kontakte, Firmen, Deals, Projekte, Tasks, Leads) über eine **versionierte REST-API** auf `api.hivegrid.de/v1/...` (staging: `staging-api.hivegrid.de/v1/...`, cursor-paginiert) und tauschen Events über **signierte Webhooks** aus — eingehend (Lead-Ingestion mit Auto-Match) wie ausgehend (HMAC-SHA256, Idempotenz, Retry/Backoff, Auto-Disable). Auth läuft über Tenant-API-Keys mit Scopes und Rate-Limit; die ausgehende Webhook-Action dockt an die v1-Automation (`external_event`-Trigger) an. Keine Public-API-Routen unter `app.hivegrid.de/api`.
## Benötigte Screens
| Screen [Route] | Kern-Inhalt | Archetyp |
|---|---|---|
| API-Key-Verwaltung [`/admin/api-keys`] | Key-Liste (Name, Scopes, letzte Nutzung, Status, Tarif-Gate) · Key erstellen (Scope-Auswahl, Secret einmal sichtbar) · Rotieren/Widerrufen | A2 + A5 (Erweiterung v1) |
| Incoming-Webhook-Verwaltung [`/admin/api-keys/incoming-webhooks`] | Slug-Endpoints (`api.hivegrid.de/v1/webhooks/incoming/{tenant}/{slug}`), Auth-Modus (API-Key/HMAC/URL-Token), Payload-Mapping, Auto-Match-Regeln · Ingestion-Log (Eingang, Match-Ergebnis, Fehler) | A2 + A3 |
| Outgoing-Subscription-Liste [`/admin/webhooks`] | Ziel-URL, abonnierte Event-Typen, Status (aktiv/auto-disabled), letzte Zustellung, Fehlerzähler | A2 |
| Outgoing-Subscription-Detail [`/admin/webhooks/:id`] | Secret (einmal sichtbar), Delivery-Stats, Delivery-Log mit Retry-Status, Replay/Test-senden, Aktivieren/Pausieren | A3 |
| API-Request-Logs + Usage [`/admin/api-keys/usage`] | Request-Log (Endpoint, Key, Status, Latenz, Rate-Limit-Treffer) · Usage-Aggregat (Calls/h pro Key + Tenant, Quota-Auslastung) | A2 |
| OpenAPI/Swagger-UI [`api.hivegrid.de/v1/openapi.json` · Swagger auf API-Host] | Auto-generierte OpenAPI-3.1-Doku + interaktiver Try-it-out (entwickler-gerichtet, evtl. eingebettete Drittanbieter-UI) | A6/extern |
*(Die eigentlichen REST-Endpoints `api.hivegrid.de/v1/contacts|companies|deals|projects|tasks|leads` sind serverseitig — kein eigener Screen außer Swagger-UI.)*
## Geplante Features (muss abgedeckt sein)
- [ ] Read-Endpoints für contacts/companies/deals/projects/tasks/leads — cursor-paginiert, Filter/Sort/Sparse-Fieldsets/Embed (Tiefe 1)
- [ ] `read_only`-Scope blendet sensible Felder aus (Feld weglassen, nicht 403)
- [ ] API-Key-Auth mit Scopes + Rate-Limit (1k/h pro Key, 10k/h pro Tenant), `X-RateLimit-*`-Header + Klartext-429
- [ ] Eingehende Lead-Webhooks legen Leads an (API-Key/HMAC/URL-Token + Payload-Mapping + Auto-Match)
- [ ] Ausgehende WebhookSubscriptions: HMAC-SHA256-Signatur, Idempotenz-ID, Retry mit exp. Backoff (max 5), Auto-Disable nach 10 Fehlern
- [ ] OpenAPI-3.1 auto-generiert (`api.hivegrid.de/v1/openapi.json`) + Swagger-UI auf API-Host
- [ ] Tarif-Gates (M027): API-Keys/Webhooks nur in passendem Abo verfügbar
- [ ] Writes durch v1-Frozen/past_due-Middleware geblockt (402); RLS via `app.tenant_id`
## Benötigte UI-Elemente (Liste, KEIN Layout — Anordnung = Davids freie Hand)
Daten-Tabelle (sortierbar, paginiert) für Keys/Webhooks/Logs, „Secret/Token einmal sichtbar"-Reveal mit Copy-Button + Warnhinweis, Scope-Multi-Select (Checkbox-Gruppe), Status-Badges (aktiv/pausiert/auto-disabled), Tarif-Gate-Hinweis/Upgrade-Prompt, Payload-Mapping-Editor (Feld-zu-Feld-Zuordnung), Auth-Modus-Auswahl (API-Key/HMAC/URL-Token), Delivery-Log-Timeline mit Retry-Status-Marker, Replay-/Test-senden-Button, Rate-Limit-/Quota-Auslastungs-Anzeige (Balken/Zahl), Code-Snippet-Block (HMAC-Verifizierungs-Beispiel), Empty-/Loading-/Permission-Denied-States (Klartext), 429-/Fehler-Hinweis-Banner.
## Davids Delta (David füllt aus)
- [ ] Überschriebene/geänderte Spec-Punkte:
- [ ] Neue UI/UX-Entscheidungen:
- [ ] Subframe-Screen-Link(s):
- [ ] Offene Fragen an Dev:
## Dev-Nachzug (wir nach Davids Delta)
- [ ] Spec/ENTITY-MODEL an Davids Entscheidungen angepasst:
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen:
- [ ] Plane-Ticket (VR-P22a/b) aktualisiert: