# 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.