Plan- und Lizenzmatrix

Stand: 2026-03-22

Dieses Dokument friert die Begriffe und Schlüssel für persönliche Pläne, Vereinslizenzen und Provider-Integrationen ein.

Grundsatz

• Öffentliche Produktbegriffe sind nicht automatisch identisch mit internen Entitlement- oder Provider-Keys.
• Persönliche Zugriffe und Vereinslizenzen sind zwei getrennte Ebenen.
• Club-Funktionen werden nicht aus dem persönlichen Plan allein abgeleitet, sondern aus dem Club-Lizenzzustand.

Kanonische Matrix

Ebene	Kanonischer Schlüssel	Öffentlicher Begriff	Erlaubte Legacy-Aliase	Quelle der Wahrheit	Verwendet für
Persönlicher Plan	free	Free	basic -> free	UserSetting.data.subscriptionPlan, JWT plan	persönlicher Basiszugriff
Persönlicher Plan	pro	Pro	keine	UserSetting.data.subscriptionPlan, JWT plan	persönliche Premium-Funktionen
Persönlicher Zugriffsstatus	club	Club Plus	plus -> club, club_plus -> club nur an Boundarys	normalisierte Access-Sicht in Web/Mobile/Backend	bezahlter Zugriff aus Vereinskontext
Vereinslizenz / Provider	club_plus	Club Plus	keine	ClubLicense.plan, Stripe-/Keygen-Metadaten	Vereinslizenz und Provider-Vertrag

Verantwortung pro Ebene

• subscriptionPlan
• ist der einzige kanonische persönliche Planwert im User-Settings-Dokument.
• darf intern auf free | pro | club normalisiert werden.
• club_plus
• ist ausschließlich der Provider- und Vereinslizenzschlüssel.
• darf nicht als persönlicher Plan gespeichert werden.
• Club-Funktions-Gating
• läuft über /api/club/license/access.
• maßgeblich sind accessState, isValid und canUseClubFeatures.
• Persönliches Paid-Gating
• läuft über gemeinsame Plan-Helper.
• pro und club gelten beide als bezahlter Zugriff.

Access-State-Vertrag für Club Plus

Zugelassene Club-Zugriffsstatus:

• trial
• active
• cancel_scheduled

Nicht zugelassen:

• inactive
• pending
• expired
• past_due
• cancelled

Shared-Code-Grenzen

• backend
• normalisiert Claims, User-Settings und bezahlte Feature-Gates.
• hält club_plus für Stripe, Keygen und ClubLicense.
• frontend/packages/core
• ist die gemeinsame Frontend-Quelle für Plan-Normalisierung und Access-Flags.
• frontend/apps/web
• darf lokale Storage-Details kennen, aber nicht eigene Plan-Aliaslogik erfinden.
• frontend/mobile
• darf keine rohen Claim-Strings wie plus oder club_plus direkt interpretieren.
• nutzt denselben normalisierten Access-Vertrag wie Web.

Migrationsregeln

• basic wird weiterhin zu free normalisiert.
• plus wird weiterhin zu club normalisiert.
• club_plus wird nur beim Übergang aus Provider-/Lizenzdaten in die Access-Sicht zu club normalisiert.
• Neue Daten sollen nur noch die kanonischen Felder schreiben:
• persönlicher Plan: subscriptionPlan
• Vereinslizenz: ClubLicense.plan = club_plus

Testerwartung

• Plan-Normalisierung auf Web und Mobile akzeptiert die dokumentierten Legacy-Aliase und liefert denselben kanonischen Access-Key.
• Club-Lizenz-Gating verwendet dieselben erlaubten Access-States wie das Backend.
• Reporting-, Export- und andere Paid-Gates vergleichen keine rohen Strings wie nur pro, sondern nutzen gemeinsame Helper.