Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/VD-P22.md
T

60 lines
5.1 KiB
Markdown
Raw 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.
# VD-P22 · Screens P22 — Public-API-Keys-UI & Webhooks
| | |
|---|---|
| **Typ** | Screen (Design) |
| **Owner** | David |
| **Phase** | P22 — Public-API & Webhooks (v2-P1) · bedient `VR-P22a`/`VR-P22b` |
| **Cycle/Fenster** | v2-W1 — Public-API/Postfach/Abo/KI-Start · 2026-07-13 → fällig 2026-07-17 |
| **Status** | geplant (NEU — Phasen-Ticket) |
> ♻️ **Löst Sammel-Ticket auf:** Dieses Phasen-Ticket ersetzt — zusammen mit `VD-P28` und `VD-P32` — das alte Sammel-Ticket **`VD-5`** („Public-API-Keys + Admin-Tiefe + KWP-Setup"). VD-P22 = der Public-API-Keys-/Webhooks-Anteil.
## Abhängigkeiten & Parallelität
- **Blocked by:** D0-Baseline (`D-D0a` App-Shell, `D-D0b` Archetypen A2–A6) — die API-Key-Verwaltung ist eine **Erweiterung** der vorhandenen v1-`ApiKey`-Fläche (M027), kein Neubau; komponiert aus den D0-Archetypen
- **Bedient (Dev):** `VR-P22a` (OpenAPI + Read-Endpoints, M161), `VR-P22b` (API-Key-Auth/Scopes/Rate-Limit) — beide v2-W1 (13.–17.07.)
- **Läuft parallel zu:** `VD-P23` (Postfach), `VD-P24` (Abo/Wizard) — gleiche v2-W1
- **Subframe:** Pflicht je Route (A2 Liste, A3 Detail, A5 Modal, A6 Settings; Swagger-UI = extern/eingebettet)
## Was wir bauen
Die **Verwaltungs-Oberfläche der Public-API**: Tenant-API-Keys (Scopes, Rate-Limit, Tarif-Gate), eingehende Lead-Webhooks (Payload-Mapping + Auto-Match), ausgehende signierte WebhookSubscriptions (Delivery-Log, Replay), API-Request-/Usage-Logs sowie die auto-generierte OpenAPI/Swagger-Doku. Secrets folgen dem **Copy-once-Muster** (einmalig sichtbar). Read-only-REST + Webhooks — bewusst kein Voll-CRUD/GraphQL/OAuth.
**Host-Contract:** Public API läuft nur auf `api.hivegrid.de` (staging: `staging-api.hivegrid.de`) mit `/v1/...`.
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 auf `api.hivegrid.de/v1/webhooks/...`, Auth-Modus (API-Key/HMAC/URL-Token), Payload-Mapping, Auto-Match-Regeln; Ingestion-Log (Eingang/Match/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 REST-Endpoints `api.hivegrid.de/v1/contacts|companies|deals|projects|tasks|leads` sind serverseitig — kein eigener Screen außer Swagger-UI.)*
## Features (muss abgedeckt sein)
- [ ] API-Key-Verwaltung als Erweiterung der v1-`ApiKey`-Fläche (Scope-Auswahl, Secret Copy-once, Rotieren/Widerrufen)
- [ ] Read-Endpoint-Doku (contacts/companies/deals/projects/tasks/leads, cursor-paginiert, Filter/Sort/Sparse/Embed)
- [ ] `read_only`-Scope blendet sensible Felder aus (Feld weglassen, nicht 403) — in der UI transparent
- [ ] Rate-Limit-/Quota-Anzeige (1k/h pro Key, 10k/h pro Tenant) + Klartext-429-Hinweis
- [ ] Incoming-Lead-Webhooks (Auth-Modus + Payload-Mapping + Auto-Match) inkl. Ingestion-Log
- [ ] Outgoing-WebhookSubscriptions: HMAC-SHA256-Signatur, Idempotenz, Retry/Backoff, Auto-Disable nach 10 Fehlern, Replay/Test
- [ ] OpenAPI-3.1 + Swagger-UI eingebunden
- [ ] Tarif-Gate (M027): API-Keys/Webhooks nur im passenden Abo → Upgrade-Prompt
## 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); 429-/Fehler-Hinweis-Banner; Empty-/Loading-/Permission-Denied-States (Klartext).
## Quellen (granular)
- `designer-briefs/P22-public-api-webhooks.md` (vollständiger Brief — diese Doc ist sein Ticket-Destillat)
- `ENTITY-MODEL.md` → **Domäne 4 (Apps-Engine)** + `ApiKey` (v2, „wandert mit Public-API"), `WebhookSubscription`
- Plane-Snapshot: ersetzt Teil von `VD-5`; bedient `VR-P22a`/`VR-P22b` (v2-W1, 13.–17.07.)
## Davids Delta (David füllt aus)
- [ ] Überschriebene/geänderte Spec-Punkte:
- [ ] Neue UI/UX-Entscheidungen:
- [ ] Subframe-Screen-Link(s):
- [ ] Offene Fragen an Dev: