Files
2026-07-08 16:15:37 +02:00

123 lines
10 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.