123 lines
10 KiB
Markdown
123 lines
10 KiB
Markdown
# 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.
|