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

4.9 KiB

R-BAUHOW · BauHow-Connector über die Apps-Engine

Typ Dev (Code) / Integration
Owner Raffael
Plane HIV-218
Phase ungeplant · baut auf der abgeschlossenen Apps-Engine R-P5 auf
Cycle/Fenster noch nicht terminiert
Status Blocked / On Hold · 0/8 DoD = 0 % done · wartet auf EXT-18

Abhängigkeiten & Parallelität

  • Blocked by: EXT-18 liefert Test-Workspace, Auth-Vertrag, API-Unterlagen, bestätigten Datenumfang und den unterstützten Mechanismus für den direkten Projekteinstieg.
  • Technische Grundlage vorhanden: R-P5 stellt Apps-Engine, Adapter-Registry, verschlüsselte DataConnection-Credentials, Health-Status und Sync-Protokoll bereit. Das wird genutzt und nicht neu gebaut.
  • Blocks: derzeit keine weiteren Tickets.
  • Auswirkung der Abhängigkeit: Vor Abschluss von EXT-18 beginnt kein Codebau. Der Connector darf weder OAuth/SSO noch Ressourcen, Scopes, Webhooks oder Schreibrechte annehmen, die BauHow nicht bestätigt hat.

Was wir bauen

Einen tenant-sicheren BauHow-Adapter hinter der bestehenden HiveGrid-Apps-Engine. Der Zielumfang ist bewusst klein und wird nur gegen den in EXT-18 bestätigten Vertrag umgesetzt:

  • BauHow-Verbindung über das von BauHow freigegebene Verfahren herstellen,
  • Kunden-, Projekt- und Gebäudedaten im vereinbarten Minimalumfang übertragen und externe IDs idempotent zuordnen,
  • das verknüpfte BauHow-Projekt über den bestätigten SSO-/Deep-Link-/Launch-Vertrag öffnen,
  • Status, Ergebnisse und Dokumente nur in den bestätigten Richtungen synchronisieren.

Falls BauHow OAuth unterstützt, gilt der HiveGrid-Standard mit Authorization Code, PKCE soweit unterstützt, signiertem kurzlebigem state, fester Callback-URL je Umgebung und verschlüsselter Credential-Ablage. Falls BauHow einen anderen Vertrag vorgibt, wird dieser dokumentiert umgesetzt; HiveGrid simuliert kein OAuth oder SSO über Passwortweitergabe.

Benötigte Screens

Screen / Einstieg Kern-Inhalt
Integrations-Einstellungen [/settings/integrations/bauhow] Verbinden, Verbindungsstatus, Verbindung testen, neu verbinden und trennen; Klartext zu Voraussetzungen und Fehlern
Projekt-Detail Verknüpftes BauHow-Projekt öffnen; fehlende Verbindung oder Verknüpfung mit nächster Aktion erklären

Die finale Screen-Ausprägung wird erst nach dem bestätigten Anbieter-Vertrag festgezogen. Bei Umsetzung ohne fertiges Subframe-Delta gilt AD-28 mit Interim-UI und später getracktem Design-Nachzug.

Definition of Done

  • Ergebnis aus EXT-18 ist als verbindlicher Auth-/API-/Launch-Vertrag in dieser Doc nachgezogen
  • BauHow-Adapter ist über defineAdapter() registriert und nutzt den bestehenden DataConnection-Lifecycle
  • Verbindung ist CSRF-sicher, tenant-/permission-scoped und speichert Secrets ausschließlich verschlüsselt
  • Bestätigter Minimalumfang für Kunde, Projekt und Gebäude wird idempotent übertragen und extern gemappt
  • Verknüpftes BauHow-Projekt lässt sich über den bestätigten Launch-Vertrag aus HiveGrid öffnen
  • Bestätigte Status-/Ergebnis-/Dokument-Synchronisation ist mit Retry, Idempotenz und Klartext-Status umgesetzt
  • Audit, Activity, Notifications, Fehlerkatalog, RLS und Permission-Gates verwenden die Querschnitts-Services
  • Unit-/Contract-Tests mit versionierten Fixtures, Smoke-Test, Interim-/Final-Visual und Hot-Swap sind grün; Live-Proof im BauHow-Test-Workspace ist dokumentiert

Technische Bausteine

  • Apps-Engine-Adapter in der bestehenden Integrationsstruktur; kein zweites Connector-Framework
  • DataConnection und AppSyncRun/AppSyncItem für Verbindung, Laufprotokoll und externe ID-Zuordnung
  • Provider-HTTP-Client mit Zod-validierten Payloads, expliziten Timeouts, Retry/Backoff und Rate-Limit-Behandlung
  • OAuth-Callback, falls bestätigt, unter /integrations/bauhow/oauth/callback; Tenant und initiierender User ausschließlich über verifizierten state, niemals als ungesicherte Callback-Pfadannahme
  • Fixture-first-Tests; echter Account nur für den abschließenden kontrollierten Live-Proof

Quellen

  • .planning/ticket-docs/EXT-18.md (offener BauHow-Zugangs- und API-Vertrag)
  • .planning/ticket-docs/R-P5.md (Apps-Engine, Adapter und DataConnection)
  • docs/INTEGRATION-CONTRACTS.md §3 (Integrationsrouten und OAuth-Callback)
  • AGENTS.md (Layer-Trennung, RLS, Querschnitts-Services, Tests und AD-28)

Dev-Nachzug

  • Anbieter-Antwort aus EXT-18 ohne unbestätigte Annahmen einarbeiten
  • Screens/Interim-UI-Vertrag anhand des tatsächlichen Connect- und Launch-Flows festziehen
  • Plane-Abhängigkeiten und %-Stand nach jedem DoD-Wechsel aktualisieren

Umsetzungs-Notiz

  • 2026-08-01 · 0/8 DoD = 0 % done: Ticket aus dem in der Mail an Nick beschriebenen Scope angelegt. Alle acht DoD-Punkte sind offen; der Codebau ist vollständig durch EXT-18 blockiert. Selbst machbar vor der BauHow-Antwort: 0 Punkte.