Club Identity Contract

Diese Seite beschreibt den kanonischen Multi-Club-Identity-Vertrag fuer Punkt 41, Phase 1. Sie ist die Referenz fuer Keycloak-Attribute, JWT-Claims und die serverseitige Spiegelung in UserSetting.data.

Status

• Phase 1 ist abgeschlossen.
• Der Keycloak-Bestand wurde auf den kanonischen Club-Attributvertrag bereinigt.
• Aktive JWT-/Keycloak-Pfade fuer Club-Claims lesen nur noch clubid.* und clubname.*.
• Writer schreiben nur noch die kanonischen Club-Attribute und loeschen bekannte Legacy-Keys aktiv bei Updates.
• Verbleibende lokale Club-Scope-Storage-Bruecken und numerische vereinsId-Scopes sind ein separater Sunset-/Polish-Folgepunkt und gehoeren nicht mehr zum Abschluss von Punkt 41.

Zielbild

• Club-Identitaet wird kanonisch ueber clubid.* und clubname.* transportiert.
• sportpassId bleibt der kanonische Mitglieds-/Schuetzen-Identifikator.
• User.id bleibt der technische Keycloak-sub, aber die relationale Personen-Zuordnung wird serverseitig zusaetzlich ueber eindeutiges User.sportpassId gespiegelt.
• Alte oder zusaetzliche sub-Werte duerfen ueber eine Alias-Zuordnung auf denselben kanonischen User zeigen.
• Web und Backend folgen fuer Club-Claims jetzt demselben Prioritaetsvertrag: kanonische Claims only.

Kanonische Claims

• clubid.primary: string
• clubname.primary: string
• clubid.secondary: string[] optional
• clubname.secondary: string[] optional
• sportpassId: string
• realm_access.roles: string[]

Legacy-Kompatibilitaet

Legacy-Keycloak-Claimnamen fuer Club-Identitaet gehoeren nicht mehr zum aktiven Runtime-Vertrag:

• primary.clubid
• secondary.clubid
• club_ids
• clubIds
• club_id
• club
• clubName
• club_name

Diese Felder werden in den aktiven Auth-/JWT-Pfaden nicht mehr als Quelle fuer kanonische clubIds oder clubname* akzeptiert.

Bewusste Rest-Kompatibilitaet ausserhalb von Punkt 41:

• preferred_username bleibt als separater Subject-/Sportpass-Fallback fuer Legacy-Loginfaelle bestehen.
• lokale Web-Storage-Bruecken wie targetshot:club_id, targetshot:club_name, targetshot:club und targetshot:vereinsId bleiben bis zu einem spaeteren Shell-/Club-Scope-Sunset getrennt dokumentiert.

Keycloak Writer

Neue oder aktualisierte Keycloak-Attribute werden in Phase 1 nur noch in dieser Form geschrieben:

• clubid.primary
• clubid.secondary
• clubname.primary
• clubname.secondary
• sportpassId

Nicht mehr neu schreiben:

• club_id
• club_name
• sonstige alte Club-Varianten

Serverseitige Spiegelung

UserSetting.data bleibt in Phase 1 die serverseitige Hilfsspiegelung fuer Web- und Backend-Pfade. Neue Token-/Keycloak-Synchronisationen schreiben dort nur noch die kanonische Form:

• clubIds
• clubPrimaryId
• clubSecondaryIds
• clubnamePrimary
• clubnameSecondary
• sportpassId
• clubIdsSource

Das alte Spiegel-Feld club_name wird nicht mehr neu beschrieben.

Parallel dazu gilt serverseitig:

• User.sportpassId ist die relationale Unique-Spiegelung des kanonischen Personen-Identifiers.
• UserSubjectAlias.subject haelt alte oder sekundare sub-Werte fest, damit Legacy-Logins auf den kanonischen User gemappt werden koennen, ohne sportpassId als Wahrheitsquelle wieder zu verwischen.

Audit- und Backfill-Plan

Phase 1 macht keine grosse Prisma-Migration und keinen grossen Datenumbau. Der Abschlussstand ist:

1. Keycloak-Audit:
2. der externe Keycloak-Bestand wurde auf den kanonischen Club-Attributvertrag bereinigt.
3. Settings-Audit:
4. serverseitige Spiegelung schreibt nur noch clubIds, clubPrimaryId, clubSecondaryIds, clubnamePrimary, clubnameSecondary und sportpassId.
5. Web-Storage-Audit:
6. verbliebene lokale Shell-/Club-Scope-Bruecken bleiben sichtbar dokumentiert und sind ein separater Sunset-Folgepunkt, nicht mehr Teil von Punkt 41.
7. Migrationsreihenfolge:
8. Writer haerten
9. Reader auf kanonische Felder priorisieren
10. Legacy-Keycloak-Clubclaims aus aktiven Auth-/JWT-Pfaden entfernen
11. lokale Storage-Bruecken spaeter separat kontrolliert abbauen