---
kind: wireframe-package
project: HiveGrid Screen Project
ticket: D-P5
package: WF-P5 Integrationen
typ: Flow
status: Validiert
subframe: ""
canvas: "WF-P5 Integrationen.canvas"
---

# WF-P5 Integrationen

Status: Validiert (Screen-Liste)  
Subframe-Link: -  
Canvas: [Canvas](<WF-P5 Integrationen.canvas>)  
Stand: 2026-07-08

---

## 1. Kurzfassung

Der „App-Store" von HiveGrid: Katalog externer Dienste, Verbindungs-Verwaltung je App (mehrere Verbindungen möglich), Einrichtungs-Assistent (OAuth **und** API-Schlüssel) und Sync-Verlauf mit Klartext. **Das wiederverwendbare Verbindungs-Gerüst** — E-Mail (P14), Telefonie (P15), Kalender/Signatur (P16) nutzen später genau diese Bausteine.

---

## 2. Intent Check

| Frage | Antwort |
|---|---|
| Welches Ticket/Modul ist betroffen? | D-P5, Dev-Pendant R-P5 (Apps-Engine/Adapter-Layer) |
| Was soll der Nutzer am Ende schaffen? | Externen Dienst anschließen, Zustand verstehen (Ampel + Klartext), Probleme selbst lösen (neu verbinden), nachvollziehen, was übertragen wurde |
| Flow, Screen, Zustand oder Doku? | Screens + Wizard-Modals |
| Welche Planning-Quellen wurden geprüft? | `ticket-docs/D-P5.md`, SCREEN-MAP §2, HiveGrid Map |
| Was ist sicher im Scope? | Katalog, App-Seite, Assistent (2 Varianten), Trennen-Dialog, Sync-Verlauf + Lauf-Detail |
| Was ist sicher nicht im Scope? | App-spezifische Einrichtungs-Details (→ P14/P15/P16), KWP-Sonder-UI (v2), Windows-Client-Flow (kein UI) |
| Admin/Normalrolle-Unterschiede? | Rechte `integrations.read/.connect/.disconnect/.manual_sync/.view_logs/.admin` |
| Unsichere Annahmen? | Ob der Katalog auch nicht verfügbare/kommende Apps zeigt (Teaser) — offene Frage |

---

## 3. Scope

| Punkt | Inhalt |
|---|---|
| Ticket/Modul | D-P5 · Integrationen |
| Nutzerrolle | Admin (Maximalansicht) |
| Startpunkt | Sidebar »Integrationen« (`/admin/integrations`) |
| Ziel | Verbindung läuft grün; Läufe nachvollziehbar |
| Haupt-Archetyp | A6 Settings/Connection-Card · A5 Wizard · A2 Liste |
| Bespoke-Anteil | Keiner |
| Out of scope | App-spezifische Setups, KWP-UI (v2) |

---

## 4. Entscheidungen (validiert 2026-07-08)

| Entscheidung | Status | Notiz |
|---|---|---|
| Ein Paket für das ganze Framework | genommen | Katalog + App-Seite + Assistent + Verlauf |
| **Sync-Verlauf als eigene Seiten** (Liste + Lauf-Detail) | genommen | Davids Entscheidung — KEIN Drawer-Muster wie beim Audit; App-Seite zeigt nur die letzten Läufe + »alle anzeigen« |
| Assistent: beide Zugangsdaten-Varianten als eigene Frames | genommen | M01 OAuth-Weg · M02 API-Schlüssel-Weg (Formular auto-generiert aus App-Schema) |
| Trennen mehrstufig bestätigt, kein Hard-Delete | genommen | Status wird »getrennt«, Jobs stoppen, Klartext-Warnung |
| Mehrere Verbindungen je App mit Namens-Label | genommen | z. B. drei Postfächer »Büro«/»Max«/»Info« |
| KI-Kategorie bleibt im Katalog | genommen | Andockpunkt für MCP (Pivot AD-26), passt zum Sidebar-Punkt »MCP« |

### Happy Path

1. Sidebar »Integrationen« → Katalog mit App-Karten nach Kategorie, Ampel je App.
2. App öffnen → Verbindungs-Karten; »Verbinden« startet den Assistenten.
3. Assistent: Voraussetzungen → Zugangsdaten (OAuth-Knopf ODER Schlüssel einfügen) → Verbindungs-Test ✓ → optional erster Abgleich.
4. Später: Ampel gelb/rot → Klartext-Banner mit Lösungs-Knopf (»neu verbinden«); Sync-Verlauf zeigt jeden Lauf in Klartext, Lauf-Detail jeden Datensatz.

### Meldungs-/Error-States (validiert)

| Ereignis | UI-Form | Blockiert? | Bauen? | Copy/Notiz |
|---|---|---|---|---|
| Verbindung hakt / kaputt / Schema geändert | Klartext-Banner + Lösungs-Knopf | nein | Nur dokumentieren | auf App-Seite + Katalog-Ampel |
| Verbindungs-Test im Assistent fehlgeschlagen | Schritt-Fehler mit Klartext + zurück | ja (Schritt) | Nur dokumentieren | im Wizard |
| Lauf fehlgeschlagen | rote Zeile + Fehl-Detail je Datensatz | nein | Nur dokumentieren | in S03/S04 |
| Kein Zugriff | A7 »kein Zugriff« | ja | Wiederverwenden | `integrations.read` |
| Katalog-Filter ohne Treffer | Leer-Zustand | nein | Nur dokumentieren | Filter zurücksetzen |

---

## 7. Validierte Screen-Liste

| ID | Screen/Zustand | Typ | Umsetzung | Ort | Status |
|---|---|---|---|---|---|
| S01 | App-Katalog | Screen | Bauen | `/admin/integrations` | Validiert |
| S02 | App-Seite (Verbindungs-Verwaltung) | Screen | Bauen | `/admin/integrations/:app` | Validiert |
| S03 | Sync-Verlauf (eigene Seite) | Screen | Bauen | `…/syncs` | Validiert |
| S04 | Lauf-Detail (eigene Seite) | Screen | Bauen | `…/syncs/:id` | Validiert |
| M01 | Assistent — OAuth-Weg | Modal/Wizard | Bauen | aus S02 | Validiert |
| M02 | Assistent — API-Schlüssel-Weg | Modal/Wizard | Bauen | aus S02 | Validiert |
| M03 | Trennen-Bestätigung | Modal (mehrstufig) | Bauen | aus S02 | Validiert |
| D01–D05 | Banner/Fehler-Zustände (s. Tabelle) | Inline/Banner | Nur dokumentieren | — | Validiert |

---

## 8. Grid

```text
Sidebar -> S01 -> S02 -> S03 -> S04
S02 -> M01 (OAuth) / M02 (API-Schluessel) / M03 (Trennen)
Connection-Card + Assistent = wiederverwendbar fuer P14/P15/P16
```

---

## 9. Screen-Pakete

- [[S01 App-Katalog]]
- [[S02 App-Seite]]
- [[S03 Sync-Verlauf]]
- [[S04 Lauf-Detail]]
- [[M01 Assistent OAuth]]
- [[M02 Assistent API-Schluessel]]
- [[M03 Trennen-Bestaetigung]]

---

## 10. Offene Fragen

- Zeigt der Katalog auch noch nicht verfügbare/kommende Apps als Teaser (mit Schloss, analog Abo-Gating)? → David/Dev
- Genaue App-Liste v1 (welche Karten sind zum Start drin) → Dev

## Handoff-Check

- [x] Jeder Screen ist mit Umsetzung markiert.
- [x] Meldungs-/Error-State-Matrix ist ausgefüllt.
- [ ] Subframe-Link ist eingetragen. *(Subframe erst nach explizitem OK)*