Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,52 @@
# 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** (`/api/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.
## 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 (`/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/v1/openapi` · Swagger] | Auto-generierte OpenAPI-3.1-Doku + interaktiver Try-it-out (entwickler-gerichtet, evtl. eingebettete Drittanbieter-UI) | A6/extern |
*(Die eigentlichen REST-Endpoints `/api/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/v1/openapi.json`) + Swagger-UI
- [ ] 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: