HiveGrid-Wireframes/Tickets/Interim-Handover/P05-Integrations.md

# P05 · Integrations / Apps-Engine (R-P5 → D-P5)

> Interim-UI-Referenz (AD-28). Lauffähige `~/ui`-Vorschau-Screens (VM als Prop) im gebundelten
> `03 Quellen und Referenzen/hivegrid-cloud/`-Checkout. **Layout = Davids freie Hand.**

### IntegrationsCatalogPage · D-P5 „Integrations-Katalog" (Archetyp A6)
- **Interim-Screen:** `apps/web/app/components/screens/integrations/IntegrationsCatalogPage.tsx`
- **Route(n):** `/:tenant/integrations` (`routes/app.$tenant/integrations._index.tsx`)
- **Daten (VM):** `IntegrationCatalogVM` — `packages/view-models/src/apps-engine/integration-catalog.vm.ts`
- **Benötigte UI-Elemente (KEIN Layout):** Card, BadgeFeedback (Verbindungs-Zähler / Status-Licht), SearchInput (client-seitiger Filter), EmptyState (inkl. `variant="no-results"`), Link · Icons: keine
- **Interaktionen (Actions):** keine Mutationen (reines Navigations-Screen); nur client-State `query` (Suchfilter) + `Link` auf `row.detailHref`. Karten nach Kategorie gruppiert (Reihenfolge = erstes Auftreten).
- **States:** Empty (`emptyHeadlineKey`/`emptyBodyKey` bei 0 Apps) · No-results (Filter ohne Treffer) · Loading (VM `status !== "ready"` → leerer Container) · Permission-Denied: Route wirft 404 (`integrations.read` fehlt), Modul aus → locked empty
- **Davids Delta (offen):**
  - [ ] Überschriebene/geänderte Spec-Punkte:
  - [ ] Neue UI/UX-Entscheidungen:
  - [ ] Subframe-Screen-Link(s):
  - [ ] Offene Fragen an Dev:

### ConnectionDetailPage · D-P5 „App-Detail / Connection-Verwaltung" (Archetyp A6+A2)
- **Interim-Screen:** `apps/web/app/components/screens/integrations/ConnectionDetailPage.tsx`
- **Route(n):** `/:tenant/integrations/:app` (`routes/app.$tenant/integrations.$app._index.tsx`)
- **Daten (VM):** `ConnectionDetailVM` (+ `ConnectionRow`) — `packages/view-models/src/apps-engine/connection-detail.vm.ts`; zusätzlich `AppCredentialField[]` aus `@hivegrid/integrations` als Prop
- **Benötigte UI-Elemente (KEIN Layout):** Alert (Screen-Banner bei degraded/broken), Button, Dialog (Disconnect-Confirm, XS 420), EmptyState, LinkButton (Breadcrumb zurück), plus Sub-Komponenten `ConnectionCard` (Liste, 2-spaltiges Grid) und `ConnectWizardDialog` · Icons: FeatherPlus
- **Interaktionen (Actions `ConnectionDetailActions`):** `onConnect(input: ConnectWizardSubmit)` · `onReconnect(connectionId, input: ConnectWizardSubmit)` · `onDisconnect(connectionId)` · `onManualSync(connectionId)`; lokaler Dialog-State (`wizard`, `disconnectRow`), `closeSignal` schließt Dialoge nach Erfolg
- **States:** Empty (`emptyHeadlineKey`/`emptyBodyKey` + Connect-CTA) · Loading (leerer Container) · Banner-State (mind. 1 degraded/broken → `error`/`warning` + Reconnect-Button) · Permission-Denied: Route 404 (`notFoundResponse` mehrfach)
- **Davids Delta (offen):**
  - [ ] Überschriebene/geänderte Spec-Punkte:
  - [ ] Neue UI/UX-Entscheidungen:
  - [ ] Subframe-Screen-Link(s):
  - [ ] Offene Fragen an Dev:

### ConnectionCard · D-P5 App-Card mit Status-Ampel (Sub-Komponente, kein eigener Archetyp)
- **Interim-Screen:** `apps/web/app/components/screens/integrations/ConnectionCard.tsx`
- **Route(n):** n/a — Sub-Komponente von `ConnectionDetailPage` (wird von P14/P15/P16/P20-App-Connections wiederverwendet)
- **Daten (VM):** `ConnectionRow` — `packages/view-models/src/apps-engine/connection-detail.vm.ts`
- **Benötigte UI-Elemente (KEIN Layout):** Card, BadgeFeedback (Status-Ampel via `connectionStatusBadge`), Button (secondary/destructive), LinkButton, Link (→ `row.syncsHref`) · Icons: keine. Zeigt Label, Klartext-`healthMessageKey`, letzter Health-Check (Intl-DateTime)
- **Interaktionen (Actions):** `onManualSync(connectionId)` · `onReconnect(row)` · `onDisconnect(row)`; Buttons gated über `canManualSync`/`canReconnect`/`canDisconnect` + Status (`revoked`/`degraded`/`broken`)
- **States:** kein eigenes Empty/Loading (Parent steuert); Button-`submitting`-Loading; `data-status` steuert Sichtbarkeit der Lifecycle-Buttons
- **Davids Delta (offen):**
  - [ ] Überschriebene/geänderte Spec-Punkte:
  - [ ] Neue UI/UX-Entscheidungen:
  - [ ] Subframe-Screen-Link(s):
  - [ ] Offene Fragen an Dev:

### ConnectWizardDialog · D-P5 „Connection-Setup-Wizard" (Archetyp A5+A6, Größe M 720)
- **Interim-Screen:** `apps/web/app/components/screens/integrations/ConnectWizardDialog.tsx`
- **Route(n):** n/a — Sub-Komponente von `ConnectionDetailPage`
- **Daten (VM):** kein `@hivegrid/view-models`-Typ; Props aus `AppCredentialField[]` (`@hivegrid/integrations`) + lokale Typen `ConnectWizardMode`, `ConnectWizardSubmit`
- **Benötigte UI-Elemente (KEIN Layout):** Dialog (720px), StepperHorizontal (+ `.Step`: prerequisites → credentials → confirm), TextInput (+ `.Input`, Label + Secret-Felder), IconButton (Reveal-Toggle), Alert (Error / OAuth-Hinweis / no-fields), Button (Cancel/Back/Next/Connect) · Icons: FeatherEye, FeatherEyeOff
- **Interaktionen (Actions):** `onSubmit(input: {label, credentials})` (postet connect/reconnect-Route-Action) · `onClose()`; lokal: Schritt-Navigation, `toggleReveal(name)`, Validierung (`labelMissing`/`requiredMissing`), OAuth2-ohne-Felder-Sonderfall
- **States:** Error (`errorMessage` → Alert) · OAuth2-ohne-Formular (Info-Alert, geführter Redirect erst P14/P16) · Submitting (Connect-Button-Loading) · Disabled-Next bei unvollständigen Credentials
- **Davids Delta (offen):**
  - [ ] Überschriebene/geänderte Spec-Punkte:
  - [ ] Neue UI/UX-Entscheidungen:
  - [ ] Subframe-Screen-Link(s):
  - [ ] Offene Fragen an Dev:

### SyncHistoryPage · D-P5 „Sync-History" (Archetyp A2)
- **Interim-Screen:** `apps/web/app/components/screens/integrations/SyncHistoryPage.tsx`
- **Route(n):** `/:tenant/integrations/:app/:connectionId/syncs` (`routes/app.$tenant/integrations.$app.$connectionId.syncs._index.tsx`)
- **Daten (VM):** `SyncHistoryVM` (+ `SyncKind`, `SyncStatus`) — `packages/view-models/src/apps-engine/sync-history.vm.ts`
- **Benötigte UI-Elemente (KEIN Layout):** Table (+ `.HeaderRow`/`.HeaderCell`/`.Row`/`.Cell`), Select (Status- + Kind-Filter, client-seitig), BadgeFeedback (`syncStatusBadge`), Button (Re-Sync), EmptyState (+ `no-results`), LinkButton, Link (→ Run-Detail `${runHrefBase}/${row.id}`) · Icons: keine. Spalten: started/kind/status/items (succeeded/total, failed ✗)/summary
- **Interaktionen (Actions `SyncHistoryActions`):** `onManualSync(connectionId)` (gated `canManualSync`); lokaler Filter-State `status`/`kind`
- **States:** Empty (`emptyHeadlineKey`/`emptyBodyKey`) · No-results (Filter leer) · Loading (leerer Container) · Permission-Denied: Route 404
- **Davids Delta (offen):**
  - [ ] Überschriebene/geänderte Spec-Punkte:
  - [ ] Neue UI/UX-Entscheidungen:
  - [ ] Subframe-Screen-Link(s):
  - [ ] Offene Fragen an Dev:

### SyncRunDetailPage · D-P5 „Sync-Run-Detail" (Archetyp A3)
- **Interim-Screen:** `apps/web/app/components/screens/integrations/SyncRunDetailPage.tsx`
- **Route(n):** `/:tenant/integrations/:app/:connectionId/syncs/:runId` (`routes/app.$tenant/integrations.$app.$connectionId.syncs.$runId.tsx`)
- **Daten (VM):** `SyncRunDetailVM` — `packages/view-models/src/apps-engine/sync-run-detail.vm.ts`
- **Benötigte UI-Elemente (KEIN Layout):** Card (Counter total/succeeded/failed + Klartext-Summary), Alert (Error bei `status==="failed"`), Table (AppSyncItem: entity/externalId/operation/status/error), BadgeFeedback (`syncStatusBadge`/`syncItemStatusBadge`/`syncLogSeverityBadge`), EmptyState (leere Items), LinkButton, Link (Breadcrumb); Log-Zeilen mit Severity-Badge + Timestamp · Icons: keine
- **Interaktionen (Actions):** keine (reines Read-Only-Detail); nur `Link` zurück (`backHref`)
- **States:** Empty-Items (`emptyItemsHeadlineKey`/`emptyItemsBodyKey`) · Failed-Run (Error-Alert) · Loading (leerer Container) · Permission-Denied: Route 404
- **Davids Delta (offen):**
  - [ ] Überschriebene/geänderte Spec-Punkte:
  - [ ] Neue UI/UX-Entscheidungen:
  - [ ] Subframe-Screen-Link(s):
  - [ ] Offene Fragen an Dev: