Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/VEXT-1.md
T
2026-07-08 16:15:37 +02:00

10 KiB
Raw Blame History

VEXT-1 · KWP-API-Zugang nutzen + Recut-Detailplanung gegen API-Doku

Typ Setup (Externals — typ:external)
Owner Raffael
Phase Phase 32 (v2-P5) — KWP-Integration (Vorlauf)
Cycle/Fenster v2-W2 — KWP/Portal/Mobile-Start · fällig 2026-07-20
Status in Arbeit · 🟢 Zugang aktiv seit 2026-06-25 (~3–4 Wochen früher als geplant)

🟢 Update 2026-06-25 — Zugang eingetroffen (früher als ~19./20.07.): KWP hat den OAuth2-Zugang für den Mandanten geerkens2 freigeschalten. Der block-2-Zustand der KWP-Phase ist damit faktisch aufgelöst — VR-P32a/b/c bleiben aber blocked-by R-P5 (Apps-Engine M33a). Stand der 7 Vertrags-Fragen siehe Umsetzungs-Notiz unten. KWP bleibt v2-Scope (kein v1-Vorziehen — Big-Bang-Launch v1 zuerst, AD-19); der frühe Zugang wird genutzt, um die Vertrags-Fragen vorab gegen die echte API zu klären (Spike), nicht um den v1-Sprint aufzureißen.

Was zu tun

KWP-API-Zugang aktivieren und die Recut-Detailplanung pro Milestone gegen die echte API-Doku durchführen — nicht gegen Annahmen. Konkret die 7 offenen Vertrags-Fragen aus dem bindenden Recut klären und je Milestone (M089–M095) entscheiden:

  1. Auth-Methode (API-Key / OAuth2 / mTLS?) → bestimmt DataConnection.type (rest-api/oauth2) + Credential-Handling
  2. Endpoints + Capabilities (welche Entitäten les-/schreibbar: Aufträge, Stammdaten, Belege, Plantafel, Dokumente?)
  3. Webhook-Support (KWP→HiveGrid Push?) → entscheidet M094 (Trigger-Pull vs. Cron-Pull) und M092
  4. Rate-Limits → bestimmt Replay-Rate (M091) und Pull-Intervalle
  5. Versionierung/Changelog → bestimmt Umfang M092 (eigenständig vs. in M089)
  6. Dokumenten-API (Listing + Download) → Voraussetzung M095
  7. Konflikt-Felder (version_hash/last_modified in Responses?) → Voraussetzung M093/M094

In v1 bereits erledigt (Andockpunkte): Callback-URL https://app.hivegrid.de/integrations/kwp/oauth/callback an KWP gemeldet (feste URL, Tenant im state, OAuth Auth-Code + PKCE); bnWin.net-8.1-N3-Update bei Geerkens angestoßen. Staging-Redirect-URI (staging-app.…) bei KWP mitregistrieren.

Warum / blockt

Ohne aktiven Zugang + Detailplanung gegen die echte Doku ist der KWP-Bau (VR-P32a/b/c) reine Spekulation. Liefert die konkreten Parameter (Auth-Typ, Endpoints, Webhook-Support, Rate-Limits, Konflikt-Felder), die jeden der drei Dev-Tickets steuern. kwpsync.exe NICHT bauen (Recut bindend, M089 = Connector statt Windows-Client). ⚠ Creds liegen bei API-Anbindung verschlüsselt in der Cloud (DataConnection.config, Per-Tenant-DEK) — Spec-19.1.2 gilt nicht mehr 1:1 → Vermerk an AVV/Subprozessoren (VR-P31/M166) weiterreichen.

Abhängigkeiten

  • Blocked by: — (extern: KWP-Hersteller-Zugang ~19./20.07.)
  • Blocks: VR-P32a (Connector — braucht Auth/Endpoints/Webhook-Klärung), VN-1 (KWP-Vorbereitung/Validierung)
  • Parallel: v1-Andockpunkte (Apps-Engine M33a, Extension-Points) stehen bereits — dieser Task füllt nur die Vertrags-Lücken.

Definition of Done

  • KWP-API-Zugang aktiv (Auth/Endpoints/Webhook-Support geklärt)
  • Recut-Detailplanung pro Milestone (M089–M095) gegen die echte Doku — alle 7 Vertrags-Fragen beantwortet
  • kwpsync.exe NICHT gebaut (Recut bindend bestätigt)
  • Staging-Redirect-URI bei KWP registriert; AVV/Subprozessor-Vermerk an VR-P31 weitergereicht

Quellen (granular)

  • docs/milestones/M19-KWP-API-RECUT.md (bindend) → 7 offene Vertrags-Fragen, appsEngine.prisma-Übernahme-Liste, Credential-Hinweis
  • ROADMAP-V2.md → §v2-P5 + §Offene Vorlauf-Tasks #1 (KWP-API-Vertrag ~20.07.)
  • ROADMAP.md → Phase 32 · PHASE-SOURCES.md → Phase 32 (Callback-URL gemeldet, bnWin.net-8.1-N3, Andockpunkte v1)
  • abhängig-für: ticket-docs/VR-P32a.md/VR-P32b.md/VR-P32c.md

Umsetzung (2026-06-25, Owner Raffael) — Zugang aktiv, Vertrags-Fragen teil-beantwortet

Geliefert von KWP (Mandant geerkens2): OAuth2-Zugang via Keycloak-OIDC, Realm kwp-federated (id.kwp-online.de). Confidential Client (offline_access), ClientId-Schema _extern-<tenant>, Tenant-Kürzel als URL-Param tenant=geerkens2 am Authorization-Endpoint. Secret NICHT in Repo/Doc — gehört in Coolify-Secret-Store bzw. später per-Tenant-DEK in DataConnection.config (AD-8); da es per Mail/Chat lief → bei KWP Rotation vor Prod einplanen.

OIDC-Discovery verifiziert (…/realms/kwp-federated/.well-known/openid-configuration): Auth …/protocol/openid-connect/auth · Token …/token · Userinfo · JWKS …/certs · Logout · Introspection · Revocation. grant_types: authorization_code, refresh_token, client_credentials, device_code, token-exchange u.a. code_challenge_methods: plain, S256 (PKCE ✓). Token-Auth: client_secret_basic/-post, private_key_jwt, mTLS. scopes_supported global nur openid, email → die fachlichen Scopes sind Client-zugewiesene Keycloak-Scopes (die aus der Mail sind maßgeblich für unseren Token-Request).

Resource-API gefunden (vom Partner geliefert): Swagger-UI https://kwp3.app02.kwp-online.de/relay/kwp3/pwa/swagger/index.html, OpenAPI-JSON unter …/swagger/v1/swagger.json. Title „KWP Api" v1, basePath /relay/kwp3/pwa, Security = OAuth2. Charakter: RPC-artige Action-API (nicht REST-CRUD): /api/Adresse/LoadAdressKomplett|Add|Save|Search|…, /api/Aktivitaet/AddAktivitaet|SaveInfoEintrag|…, /api/Abteilung/…. Description: „respecting permissions and user context" → User-gebunden (deshalb Auth-Code-Flow, nicht reines client_credentials).

Stand der 7 Vertrags-Fragen:

  1. Auth-Methode → ✅ geklärt: OAuth2/OIDC (Keycloak), Auth-Code + PKCE (S256), Confidential Client + offline_access/Refresh → DataConnection.type='oauth2' (NICHT rest-api). Pro HiveGrid-Tenant eigene ClientId/Secret/tenant-Kürzel in DEK-config.
  2. Endpoints/Capabilities → 🟠 teilweise: Adresse (Kontakte/Ansprechpartner/Custom-Felder/Geo/Anrufer-Info), Aktivität, Abteilung bestätigt. Vorgang (=Projekt-Kern!), Termin, Archiv noch zu erfassen — in der pwa-Spec nicht im (gekürzten) WebFetch-Ausschnitt sichtbar; evtl. eigene Relay-Module. → Spike (echter HTTP-Client, volle JSON laden).
  3. Webhook-Support → 🟠 offen: in der abgerufenen pwa-Spec keine webhooks/callbacks gesehen (Sicht war gekürzt) → Arbeitshypothese Pull-Modell; final im Spike/bei KWP bestätigen. Steuert M094 (Trigger- vs. Cron-Pull) + M092.
  4. Rate-Limits → ❓ offen (nicht in Discovery/Swagger-Übersicht) → bei KWP erfragen; steuert Replay-Rate M091.
  5. Versionierung → 🟢 teilweise: API v1, basePath /relay/kwp3/pwa. Changelog-Politik bei KWP erfragen.
  6. Dokumenten-API → 🟠 offen: Scope archiv-extern existiert, Endpoints noch zu erfassen (Spike) → M095.
  7. Konflikt-Felder → ❓ offen: Response-Schema je Entität auf version_hash/last_modified prüfen (Spike) → M093/M094.

NEU — offene Frage (Scope-Mapping): Mail-Scopes sind adresse-extern archiv-extern termin-extern vorgang-extern aktivitaet-extern offline_access; die Swagger-Security nennt interne Scope-Namen (adressverwaltung, aktivitaetenverwaltung, projektampel, wartungswesen, mobmont, …). Klären, ob die *-extern-Scopes intern gemappt werden und alle benötigten Endpoints abdecken.

Noch zu tun (Rest dieses Tickets): Spike gegen die echte API (Token holen → 1 Resource-Call → Vorgang/Termin/Archiv-Endpoints + Konflikt-Felder + Webhook/Rate-Limit erfassen); Staging-Redirect-URI bei KWP registrieren; AVV/Subprozessor-Vermerk an VR-P31/M166. Bleibt v2 — Spike erst sinnvoll nach/mit R-P5.

Rückfragen an KWP (Entwurf, 2026-06-25 — via Noah/Geerkens weiterleiten)

Betreff: Rückfragen zur KWP-API-Anbindung (Mandant geerkens2)

vielen Dank für die Freischaltung des API-Zugangs. Den OAuth2-Flow (Keycloak, Realm kwp-federated, Auth-Code + PKCE) und die OpenAPI-Doku unter …/relay/kwp3/pwa/swagger/v1/swagger.json konnten wir bereits einsehen. Für die saubere Anbindung haben wir noch einige Rückfragen:

  1. Daten-Endpunkte/Umfang: Die uns vorliegende pwa-Swagger zeigt vor allem Adresse, Aktivität und Abteilung. Über welche Endpunkte bzw. welche weiteren Relay-Module erreichen wir die Bereiche Vorgang, Termin und Archiv (unsere Scopes vorgang-/termin-/archiv-extern)? Gibt es eine vollständige/aggregierte OpenAPI-Spezifikation?
  2. Scope-Mapping: Zugewiesen sind adresse-/archiv-/termin-/vorgang-/aktivitaet-extern (+ offline_access). In der Swagger-Security stehen interne Scope-Namen (adressverwaltung, aktivitaetenverwaltung, projektampel, …). Werden die *-extern-Scopes intern darauf gemappt, und decken sie alle benötigten Endpunkte ab?
  3. Synchronisation: Gibt es Webhooks/Push bei Änderungen (KWP → uns), oder ist die Sync rein Pull? Falls Pull: gibt es Delta-/„geändert seit"-Parameter (Zeitstempel/Cursor)?
  4. Konflikt-/Versionsfelder: Liefern die Antworten je Datensatz ein Änderungsdatum bzw. eine Version (last_modified/version/ETag) für Delta-Sync und Konflikt-Erkennung?
  5. Rate-Limits: Welche Limits gelten (Requests/Minute, parallele Verbindungen)? Empfohlene Poll-Intervalle?
  6. Token-Lebensdauer: Gültigkeit Access-/Refresh-Token; rotieren die Refresh-Token bei Nutzung? (Relevant für den dauerhaften Hintergrund-Sync mit offline_access.)
  7. Schreibzugriff: Die Endpunkte enthalten Add/Save/Remove. Sind die externen Scopes lesend und schreibend nutzbar, und gibt es Einschränkungen, was ein externer Client schreiben darf?
  8. Test-/Sandbox-Mandant: Gibt es einen Test-/Sandbox-Tenant zum Entwickeln und für unsere Staging-Umgebung, statt gegen den Produktiv-Mandanten geerkens2?
  9. Versionierung: Wie wird die API versioniert (aktuell /v1) und wie werden Breaking Changes angekündigt?

Klein: Im Authorization-Beispiel stand client_id=der-oauth-client als Platzhalter — bestätigen Sie bitte, dass für uns client_id=_extern-geerkens2 zu verwenden ist.