87 lines
4.9 KiB
Markdown
87 lines
4.9 KiB
Markdown
# 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.
|