121 lines
5.7 KiB
Markdown
121 lines
5.7 KiB
Markdown
<!-- status: build -->
|
|
<!-- started: 2026-04-26 -->
|
|
<!-- component: gateway, frontend-nyla -->
|
|
|
|
# Infomaniak Connector (kDrive + Mail) + UDB-Integration
|
|
|
|
## Beschreibung und Kontext
|
|
|
|
PowerOn besitzt das Provider-Connector-Pattern fuer externe Datenanbindungen
|
|
(Microsoft, Google, ClickUp). Infomaniak war bisher nicht angebunden. Ziel: ein
|
|
neuer `InfomaniakConnector`, der OAuth gegen `login.infomaniak.com` durchfuehrt
|
|
und Daten aus zwei Services bereitstellt:
|
|
|
|
- **kDrive** (Pendant zu OneDrive / Google Drive)
|
|
- **Mail** (Pendant zu Outlook / Gmail)
|
|
|
|
Die Verbindung ist eine reine **Daten-Connection** (`TokenPurpose.DATA_CONNECTION`).
|
|
Infomaniak ist explizit **kein** Login-Provider fuer PowerOn -- entsprechend gibt
|
|
es nur `_FLOW_CONNECT`, kein `_FLOW_LOGIN`.
|
|
|
|
Zusatzlich wurden zwei kleine Inkonsistenzen in der ClickUp-UDB-Anzeige
|
|
behoben (`_SERVICE_ICONS` + `_SERVICE_TO_SOURCE_TYPE`).
|
|
|
|
## Fokus und kritische Details
|
|
|
|
- **Refresh-Token-Persistenz**: Infomaniak rotiert Refresh-Tokens nicht in jedem
|
|
Token-Response; falls `refresh_token` im Callback fehlt, wird aus dem letzten
|
|
gespeicherten Token rekonstruiert (analog Google).
|
|
- **API-Pfad-Konvention**: Drei-Ebenen-Hierarchie kDrive (`/{driveId}/{fileId}`)
|
|
und vier-Ebenen Mail (`/{mailboxId}/{folderId}/{uid}`); `ServiceAdapter.browse`
|
|
unterscheidet die Tiefe via Segment-Count.
|
|
- **Antwort-Wrapping**: Erfolgreiche Responses sind als
|
|
`{result: 'success', data: ...}` gewrappt -- `_unwrapData()` normalisiert.
|
|
- **Authority-Filter** in `tokenRefreshService` muss `INFOMANIAK` enthalten,
|
|
sonst werden Token nie proaktiv refreshed.
|
|
|
|
## Ziel und Nicht-Ziele
|
|
|
|
- Ziel: Infomaniak-Daten (kDrive + Mail) wie MSFT/Google im UDB browsbar.
|
|
- Ziel: ConnectionsPage hat Button "Infomaniak" (analog ClickUp).
|
|
- Ziel: Refresh-Token-Lifecycle vollautomatisch (kein User-Reconnect noetig).
|
|
- Ziel: ClickUp-UDB-Inkonsistenz beheben (Service-Icon + Source-Type-Mapping).
|
|
- NICHT: Infomaniak als PowerOn-Login (`User`-Erstellung via Infomaniak-OAuth).
|
|
- NICHT: Upload-Implementierung in kDrive/Mail (gibt nur Browse + Download).
|
|
|
|
## Betroffene Module
|
|
|
|
- Gateway:
|
|
- `modules/datamodels/datamodelUam.py` (Enum)
|
|
- `modules/auth/oauthProviderConfig.py` (Scopes)
|
|
- `modules/auth/tokenManager.py` (Refresh)
|
|
- `modules/auth/tokenRefreshService.py` (Background-Refresh)
|
|
- `modules/connectors/providerInfomaniak/connectorInfomaniak.py` (neu)
|
|
- `modules/connectors/connectorResolver.py` (Registry)
|
|
- `modules/routes/routeSecurityInfomaniak.py` (neu)
|
|
- `modules/routes/routeDataConnections.py` (Dispatch)
|
|
- `app.py` (Router-Mount)
|
|
- Frontend:
|
|
- `src/api/connectionApi.ts` (Authority-Typ)
|
|
- `src/hooks/useConnections.ts` (Popup-Handler)
|
|
- `src/pages/basedata/ConnectionsPage.tsx` (Button)
|
|
- `src/components/UnifiedDataBar/SourcesTab.tsx` (Icons + Colors + Mapping, ClickUp-Fix)
|
|
- DB-Migration: nein (nur Enum-Wert, alle Tabellen abwaertskompatibel).
|
|
- Andere: keine.
|
|
|
|
## Entscheidungen
|
|
|
|
| Datum | Entscheidung | Begruendung |
|
|
|------------|--------------|-------------|
|
|
| 2026-04-26 | Self-contained Connector (httpx im Modul, kein eigener Service) | Folgt Google/MSFT-Pattern, nicht ClickUp-Pattern (das delegiert an `ClickupService`) |
|
|
| 2026-04-26 | Nur DATA_CONNECTION, kein Login | User explicitly: "wir benoetigen nur den userconnection auth" |
|
|
| 2026-04-26 | `kdrive` + `mail` als Service-Namen | Kurz, konsistent mit Infomaniak-Branding (kDrive heisst offiziell so) |
|
|
|
|
## Umsetzungs-Checkliste
|
|
|
|
- [x] AuthAuthority-Enum erweitert
|
|
- [x] Scopes definiert (`user_info kdrive mail`)
|
|
- [x] InfomaniakConnector + KdriveAdapter + MailAdapter
|
|
- [x] ConnectorResolver-Registry
|
|
- [x] OAuth-Route `/api/infomaniak/auth/connect[/callback]`
|
|
- [x] Token-Refresh (`refreshInfomaniakToken` + Background-Service)
|
|
- [x] DataConnections-Dispatch (`authority_map`, Labels, `connect_service`)
|
|
- [x] App-Router-Mount
|
|
- [x] Frontend-Typen
|
|
- [x] Hook `createInfomaniakConnectionAndAuth` + Event-Listener
|
|
- [x] ConnectionsPage-Button
|
|
- [x] UDB-Integration (Authority-Icon, Service-Icons, Source-Colors, Mapping)
|
|
- [x] ClickUp-UDB-Fix
|
|
- [x] Setup-Guide `wiki/d-guides/infomaniak-oauth-setup.md`
|
|
- [ ] Manueller End-to-End-Test (ClientID/Secret im Manager registrieren, Verbinden, kDrive browsen, Mail browsen, Datei downloaden)
|
|
- [ ] `wiki/b-reference/connectors.md` (falls vorhanden) ergaenzen
|
|
|
|
## Akzeptanzkriterien
|
|
|
|
| # | Kriterium (Given-When-Then) | Prio |
|
|
|---|-----------------------------|------|
|
|
| 1 | Given Infomaniak-Credentials in `APP_CONFIG`, When Nutzer "Infomaniak" auf ConnectionsPage klickt, Then oeffnet sich der OAuth-Popup auf `login.infomaniak.com/authorize` | must |
|
|
| 2 | Given erfolgreicher OAuth-Callback, Then ist die UserConnection `ACTIVE`, Token gespeichert (`tokenAccess`+`tokenRefresh`), `externalId/Email` gesetzt | must |
|
|
| 3 | Given aktive Connection, When im UDB die Authority expandiert wird, Then werden Services `kdrive` und `mail` mit Icons angezeigt | must |
|
|
| 4 | Given Token vor Ablauf < 5 min, When Background-Refresh laeuft, Then wird `_refresh_infomaniak_token` aufgerufen und Token erneuert | must |
|
|
| 5 | Given ClickUp-Service-Node im UDB, Then ist das Service-Icon das Klemmbrett (Fix) | should |
|
|
|
|
## Testplan
|
|
|
|
| ID | AC | Art | Automatisiert | Repo-Pfad | Status |
|
|
|----|----|-----|---------------|-----------|--------|
|
|
| T1 | 1-2 | manual | nein | UI: ConnectionsPage | pending |
|
|
| T2 | 3 | manual | nein | UI: UDB SourcesTab | pending |
|
|
| T3 | 4 | unit | spaeter | gateway/tests/auth/test_tokenManager.py | pending |
|
|
| T4 | 5 | manual | nein | UI: UDB SourcesTab | pending |
|
|
|
|
## Links
|
|
|
|
- PR: tbd
|
|
- Setup-Guide: `wiki/d-guides/infomaniak-oauth-setup.md`
|
|
|
|
## Abschluss
|
|
|
|
- [ ] `b-reference/` aktualisiert
|
|
- [ ] `TOPICS.md` aktualisiert
|
|
- [ ] Dokument nach `z-archive/` verschoben
|