Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
1 parent
5e99e14772
commit
7f88026f79
5955 files changed
+1177325
-188362
No files matched your search
@@ -8,7 +8,7 @@
|
||||
| **Owner** | Raffael |
|
||||
| **Phase** | P5 — Apps-Engine & Integrations-Framework |
|
||||
| **Cycle/Fenster** | W2 — Plattform & CRM (Demo 1) · fällig 2026-06-21 · Gate W2 (Noah-Demo #1) |
|
||||
| **Status** | **done (2026-07-07)** — 10/10 DoD = 100 %; Backend seit 2026-06-28, Interim-UI (AD-28) + Run-Detail + Katalog-Seed via PR #50, Sidebar-Reachability-Fix via PR #51; Plane auf Done, Label `design-nachzug` gesetzt |
|
||||
| **Status** | **done (2026-07-07, Regressions-Fix 2026-07-17)** — 10/10 DoD = 100 %; Backend seit 2026-06-28, Interim-UI (AD-28) + Run-Detail + Katalog-Seed via PR #50, Sidebar-Reachability-Fix via PR #51; Plane auf Done, Label `design-nachzug` gesetzt. RLS-Cutover-Regression im Worker-notify (DoD #4) am 2026-07-17 per Audit gefunden und gefixt (s. Umsetzungs-Notiz) |
|
||||
|
||||
**🎨 design-nachzug: offen** (seit 2026-07-07) — Interim-UI aus `~/ui` steht; finale Subframe-Optik aus `D-P5` ausstehend.
|
||||
|
||||
@@ -21,13 +21,13 @@
|
||||
## Was wir bauen
|
||||
Das **eine, typsichere Integrations-Framework**, über das später Gmail, Outlook, AirCall, Signatur-Adapter (SES-Default/PandaDoc-BYOK), Legacy-Provider und KWP laufen. Ein Admin stellt eine `DataConnection` über **OAuth2-Connect** oder **API-Key-Connect** in der Settings-UI her; die **type-safe Adapter-Registry** erlaubt neue Connection-Typen ohne Kern-Änderung (Build-Time-Scan, Drift-Check); `AppSyncRun`/`AppSyncItem`/`AppSyncRunLog` protokollieren Sync-Läufe in Klartext; **Connection-Health-Monitoring** zeigt active/degraded/broken/revoked/pending mit Klartext + Lösungs-Hinweisen; **OAuth-Tokens per-Tenant-DEK-verschlüsselt** (AD-8). Mehrere Connections pro App pro Tenant (z.B. drei Gmail-Mailboxen).
|
||||
|
||||
> ⚙️ **Recut (KWP → v2):** KWP = `DataConnection type='rest-api'` (API-Key-Connect) — **kein `kwpsync.exe`-Windows-Client-Flow** (Scope-Schnitt #12). `windows_client` bleibt im Datenmodell, hat in v1 keinen UI-Flow. Apps selbst werden erst in ihren Modul-Phasen (P14/P15/P16/P20) angedockt — P5 liefert nur das Framework + die generische Katalog-/Wizard-UI.
|
||||
> ⚙️ **Recut (KWP → v2, aktualisiert 2026-07-12):** KWP = `DataConnection type='oauth2'` (Authorization Code + PKCE, Kundenkürzel + dynamische Relay-Auflösung) — **kein `kwpsync.exe`-Windows-Client-Flow und kein KWP-API-Key-Setup**. `windows_client` bleibt im Datenmodell, hat in v1 keinen UI-Flow. Apps selbst werden erst in ihren Modul-Phasen angedockt; P5 liefert das Framework + die generische Katalog-/Wizard-UI.
|
||||
|
||||
## Benötigte Screens (Backend bedient — Design liefert `D-P5` aus `D-D0a`/`D-D0b`)
|
||||
| Screen [Route] | Kern-Inhalt | Liefert (Design) |
|
||||
|---|---|---|
|
||||
| Integrations-Katalog [`/admin/integrations`] | App-Karten nach Kategorie (ERP/Kommunikation/Kalender/Signatur/Payment/KI), Status-Ampel, Anzahl Connections, Suche/Filter | `D-P5` (A6) |
|
||||
| App-Detail / Connection-Verwaltung [`/admin/integrations/:app`] | Pro DataConnection: Status-Indikator, Klartext-Hinweis, letzter Sync, Re-Sync/Reconnect/Disconnect, Sync-History; mehrere Connections pro App | `D-P5` (A6+A2) |
|
||||
| Integrations-Katalog [`/settings/integrations`] | App-Karten nach Kategorie (ERP/Kommunikation/Kalender/Signatur/Payment/KI), Status-Ampel, Anzahl Connections, Suche/Filter | `D-P5` (A6) |
|
||||
| App-Detail / Connection-Verwaltung [`/settings/integrations/:app`] | Pro DataConnection: Status-Indikator, Klartext-Hinweis, letzter Sync, Re-Sync/Reconnect/Disconnect, Sync-History; mehrere Connections pro App | `D-P5` (A6+A2) |
|
||||
| Connection-Setup-Wizard [Modal/Flow] | Voraussetzungen → auto-generiertes Credential-Formular (aus `connection_schema`) → Validation/Health-Check → Initial-Sync; OAuth2-Redirect + API-Key-Reveal | `D-P5` (A5+A6) |
|
||||
| Sync-History / Run-Detail [`…/syncs`, `…/syncs/:id`] | AppSyncRun-Liste (Datum/kind/Status/items-Zähler/Summary) + Filter; Run-Detail mit AppSyncItem-Liste + Log | `D-P5` (A2/A3) |
|
||||
|
||||
@@ -37,13 +37,13 @@ Das **eine, typsichere Integrations-Framework**, über das später Gmail, Outloo
|
||||
- [x] **DataConnection** per OAuth2-Connect oder API-Key-Connect — *Backend (createConnection: Adapter-Validierung + Envelope-Crypto) + funktionale Route-Action fertig; finale Wizard-Optik = Davids D-P5.*
|
||||
- [x] **Type-safe Adapter-Registry** (Drift-Check → Klartext-Warnung) — neue Typen ohne Kern-Änderung
|
||||
- [x] **AppSyncRun/AppSyncItem/AppSyncRunLog** mit Klartext-Summary
|
||||
- [x] **Connection-Health-Monitoring** + Token-Refresh-Worker + degraded/broken → `notify()` — *Health-Probe + notify + Worker-Crons (token-refresh 5m, health-sweep 15m) über geteiltes @hivegrid/integrations-Paket.*
|
||||
- [x] **Connection-Health-Monitoring** + Token-Refresh-Worker + degraded/broken → `notify()` — *Health-Probe + notify + Worker-Crons (token-refresh 1m, health-sweep 15m) über geteiltes @hivegrid/integrations-Paket. Worker-notify seit 2026-07-17 RLS-gebunden über M011-`notify()` mit tx-Client (Cutover-Regression, s. Umsetzungs-Notiz).*
|
||||
- [x] **OAuth-Tokens per-Tenant-DEK-verschlüsselt** (AD-8)
|
||||
- [x] Lifecycle: Connect / Reconnect (gleiche ID, kein History-Verlust) / Disconnect (Status revoked statt Hard-Delete) — *Backend + Route-Actions; finale Wizard-Optik = D-P5.*
|
||||
- [x] Mehrere DataConnections pro App pro Tenant (mit User-Label)
|
||||
- [x] Manueller Re-Sync + Schema-Drift-Sentinel + Webhook-Storm-Schutz (`triggerWebhookSync` via `withIdempotency`)
|
||||
- [x] Permissions: `integrations.read/.connect/.disconnect/.manual_sync/.view_logs/.admin`
|
||||
- [x] *(→ v2)* `kwpsync.exe`-Windows-Client-Flow ausgeschlossen (KWP = rest-api)
|
||||
- [x] *(→ v2)* `kwpsync.exe`-Windows-Client-Flow ausgeschlossen (KWP = OAuth2/PKCE-Adapter)
|
||||
|
||||
## Technische Bausteine
|
||||
- **Entities** (eigene `prisma/schema/apps.prisma`): `App` (key, category, connection_type oauth2/api_key, connection_schema, phase — **global, kein RLS**), `DataConnection` (tenant_id, app_id, credentials **verschlüsselt**, connection_status, last_health_check), `AppSyncRun`, `AppSyncRunLog`, `AppSyncItem` (entity_type/id ↔ external_id, polymorph). `core.prisma` nur für Tenant-Relationen berühren (AD-21).
|
||||
@@ -56,13 +56,67 @@ Das **eine, typsichere Integrations-Framework**, über das später Gmail, Outloo
|
||||
## Quellen (granular)
|
||||
- `ENTITY-MODEL.md` → **Domäne 4: Apps-Engine** (App/DataConnection/AppSyncRun/AppSyncRunLog/AppSyncItem) + Cross-Cutting (DataConnection)
|
||||
- `REQUIREMENTS.md` → `REQ-apps-engine-datenmodell`, `REQ-apps-engine-lifecycle`
|
||||
- `ROADMAP.md` → Phase 5 · `PHASE-SOURCES.md` → Phase 5 (M008/M009/M010)
|
||||
- `ROADMAP.md` → Phase 5 · Milestones: (M008/M009/M010)
|
||||
- `designer-briefs/P05-apps-engine-integrations-framework.md`
|
||||
- `_bmad-output/specs/M33a-apps-engine.md` (⚠ alte Drei-Komponenten-KWP-Architektur **nicht** bauen — Recut)
|
||||
- `docs/ARCHITECTURE-DECISIONS.md` → AD-8 (per-Tenant-DEK)
|
||||
|
||||
## Umsetzungs-Notiz
|
||||
|
||||
**2026-07-22 (Raffael) — Dependency-Impact des laufenden KWP-Haltbarkeits-Nachzugs; DoD unverändert.**
|
||||
|
||||
Auf Staging lief Revision `d4daa0421`. Der KWP-Pfad erneuerte das Token um **03:04:47 CEST** erfolgreich;
|
||||
der nächste Lauf um **03:09:53 CEST** endete jedoch mit `broken` / `integrations.health.refreshFailed`, ohne
|
||||
dass die konkrete Provider-/Transportklassifikation in den verfügbaren Runtime-Diagnosen erhalten blieb.
|
||||
Das ist ein offener KWP-Dauerbetriebsnachweis in `VR-P32a`/`VEXT-1`, keine Rücknahme des vorhandenen
|
||||
Apps-Engine-Frameworks.
|
||||
|
||||
Der lokal abgeschlossene, noch nicht deployte Nachzug bleibt auf den KWP-spezifischen
|
||||
Refresh-/Health-Pfad begrenzt: Handler-Logger an den strukturierten Runtime-Sink binden, replay-sichere und
|
||||
mehrdeutige Token-POST-Ausgänge eindeutig trennen, einen unklar verbrauchten Einmal-Refresh-Token niemals beim
|
||||
Provider wiederholen, ausschließlich lokale Persistenz-Retries zulassen und den KWP-Refresh-/Health-Gate
|
||||
früher ausführen. Der vollständige Root-Testlauf ist mit **7.115 bestandenen / 55 übersprungenen Tests** grün;
|
||||
ebenso Root-Typecheck/-Lint, Worker-Build und die relevanten Deploy-/Runtime-Gates. Ein Deploy-/Live-Proof wird
|
||||
noch nicht beansprucht; die generischen Adapter- und Lifecycle-Verträge aus R-P5 bleiben unverändert.
|
||||
**R-P5: 10/10 DoD = 100 %; Ticket bleibt Done · Design-Nachzug weiterhin offen.**
|
||||
|
||||
**2026-07-22 (Raffael) — KWP-Dauer-Proof abgeschlossen; DoD unverändert.** PR `#210` lief als Revision
|
||||
`2938f29da` über Deploy-Run `10995` grün auf Staging. Nach dem normalen OAuth-Reconnect blieben Connection
|
||||
und geschützter Health-Probe `active`; neun aufeinanderfolgende automatische Refresh-Rotationen endeten mit
|
||||
`failed=0` und ohne Provider-/Persistenzfehler. Ein anschließender geschützter Health-Probe blieb ebenfalls
|
||||
gesund. Damit ist der in `VR-P32a`/`VEXT-1` offene
|
||||
KWP-Dauerbetriebsnachweis geschlossen. Die generischen Adapter- und Lifecycle-Verträge aus R-P5 bleiben
|
||||
unverändert. **R-P5: 10/10 DoD = 100 %; Ticket bleibt Done · Design-Nachzug weiterhin offen.**
|
||||
|
||||
**2026-07-17 (Akeshan) — Stand-Audit + RLS-Regressions-Fix im Worker-notify (DoD #4), Branch `fix/r-p5-integrations-notify-rls`.**
|
||||
|
||||
Voll-Audit (Code vs. Plane vs. Doc) nach dem RLS-Cutover vom 14.07.: 9 von 10 DoD-Punkten unverändert erfüllt
|
||||
(Proof-Pfade gegengelesen: Service/Registry/Schema/Crypto/Permissions/Routen/Sidebar/Seed/Smoke/Hot-Swap/i18n).
|
||||
**Befund:** `notifyOwner` in `packages/integrations/src/worker-tasks.server.ts` rief `createNotificationDelivery`
|
||||
ohne Client auf → Default-Root-Client **außerhalb** der `withTenantRLS`-Transaktion der Crons (der Worker-Helfer
|
||||
setzt nur die GUC im tx, keinen Async-Kontext). Unter FORCE RLS wurde der Insert per Policy abgelehnt und vom
|
||||
`.catch(() => undefined)` still geschluckt — degraded/broken-Benachrichtigungen gingen auf Staging/Prod verloren.
|
||||
Gleiche Regressions-Klasse wie R-P1b (PR #146); der dortige Fix deckte diesen Pfad nicht ab, weil er nicht über
|
||||
`notify()` lief.
|
||||
|
||||
**Fix (Commit `8b72f3326`):** `notifyOwner` nutzt jetzt das M011-`notify()`-Contract auf dem **gebundenen
|
||||
tx-Client** (erfüllt zugleich den DoD-#4-Wortlaut inkl. Präferenz-Logik) mit `sourceKey`
|
||||
`integrations:connection-unhealthy:<connectionId>` — wiederholte 5m/15m-Sweeps upserten eine Delivery statt zu
|
||||
spammen. Regressionstests bilden die Policy nach (Delivery landet nur über den übergebenen Client im Store; alter
|
||||
Code = 0 Deliveries): `packages/integrations/src/worker-tasks.test.ts` 6/6 grün.
|
||||
|
||||
**Verifiziert:** typecheck `@hivegrid/integrations` + `@hivegrid/worker` je 0 Fehler · `worker-tasks.test.ts` 6/6 ·
|
||||
`apps/worker/src/notify-rls.test.ts` 4/4 · `apps/worker/src/handlers.test.ts` 110/110 · `verify:i18n` Exit 0 ·
|
||||
lefthook grün. Kein Schema-Delta, keine Migration, keine neuen i18n-Keys (Key existierte de+en).
|
||||
|
||||
**Stand: R-P5 wieder 10/10 DoD = 100 %** (zwischenzeitlich 9/10 durch die Cutover-Regression). Ticket bleibt Done.
|
||||
|
||||
**2026-07-12 (Raffael) — Settings-Routing konsolidiert, DoD unverändert 10/10 = 100 %.**
|
||||
Die Apps-Engine-UI ist jetzt kanonisch vollständig unter `/settings/integrations/**` verschachtelt, damit die
|
||||
Settings-Innensidebar bei Katalog, Connection-Verwaltung und Sync-History erhalten bleibt. Bestehende
|
||||
`/integrations/**`-UI-Links werden kompatibel weitergeleitet; die extern registrierten OAuth-Callbacks unter
|
||||
`/integrations/<provider>/oauth/callback` bleiben unverändert. Die abhängigen Connector-Tickets AK-P14a,
|
||||
AK-P15a und AK-P16a verwenden bereits `/settings/integrations/<modul>` und benötigen keinen Nachzug.
|
||||
|
||||
> **✅ Stand 2026-06-28 — auf `main` gemergt.** R-P5 lief über den gemeinsamen Branch `feat/AK-P17a` und ging mit **PR #5** (squash, Merge-Commit `b0fae1af8`, Base `main`, 2026-06-28 17:50) auf `main`. Nachzug-Fix `packages/integrations/package.json` im Docker-deps-Target via **PR #8** (`0b9d2e46`, 18:05). Alle R-P5-Artefakte (`appsEngineService`, `@hivegrid/integrations`, `crypto.prisma`/`appsEngine.prisma`, Worker-Crons, Admin-Routen-Hülle) liegen im `main`-Tree. *Die älteren „Branch lokal, nicht gepusht"-Notizen unten sind damit überholt.* **Backend 9/9 DoD grün.** Extern offen bleibt nur: Davids `D-P5`-Optik, RLS-Live/Visual-Regression gegen Staging-DB, ~~App-Tabellen-Katalog-Seed (deferred)~~ *(Seed am 2026-07-07 nachgezogen, s.u.)*, Plane-Ticket auf Done.
|
||||
|
||||
**2026-06-27 (Akeshan) — Backend-Kern + Crypto-Fundament, Branch `feat/R-P5` (lokal, nicht gepusht).**
|
||||
@@ -127,5 +181,5 @@ R-P2a/AK-P3/AK-P4b (keine Snapshot-Harness — Interim-Baseline wird beim David-
|
||||
Refactor-Nachzug offen: finale Subframe-Optik aus `D-P5` (Plane-Label `design-nachzug`).
|
||||
|
||||
- [ ] Katalog/Wizard/Connection-Card an Davids UI angepasst
|
||||
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
|
||||
- [ ] REQUIREMENTS/ROADMAP nachgezogen
|
||||
- [ ] Plane-Ticket `R-P5` aktualisiert
|
||||
Reference in new issue
Block a user