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: