docs: comprehensive v9c architecture plan - Subscription & Coupon System
Added detailed documentation for v9c features: - Complete database schema (8 new tables) - Backend architecture (6 new routers, middleware, cron jobs) - Frontend extensions (pages, components, admin panels) - Zugriffs-Hierarchie und Stacking-Logik - Tier-System mit Admin-editierbaren Limits - Coupon-System (Single-Use + Multi-Use Period) - User Activity Tracking - E-Mail Templates - Migration roadmap (25 steps in 5 phases) Spätere Features dokumentiert (v9d/v9e): - Bonus-System & Gamification - Stripe-Integration - Partner-Verwaltung - Admin-Benachrichtigungen Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
parent
b4a1856f79
commit
95c57de8d0
314
CLAUDE.md
314
CLAUDE.md
|
|
@ -96,19 +96,321 @@ mitai-jinkendo/
|
|||
- ✅ Automatische SQLite→PostgreSQL Migration bei Container-Start
|
||||
- ✅ **Modulare Backend-Architektur**: 14 Router-Module, main.py von 1878→75 Zeilen (-96%)
|
||||
|
||||
### Was in v9c kommt:
|
||||
- 🔲 Selbst-Registrierung mit E-Mail-Bestätigung
|
||||
- 🔲 Freemium Tier-System (free/basic/premium/selfhosted)
|
||||
- 🔲 14-Tage Trial automatisch
|
||||
- 🔲 Einladungslinks für Beta-Nutzer
|
||||
- 🔲 Admin kann Tiers manuell setzen
|
||||
### Was in v9c kommt: Subscription & Coupon Management System
|
||||
**Core Features:**
|
||||
- 🔲 Selbst-Registrierung mit E-Mail-Verifizierung (Pflicht)
|
||||
- 🔲 Flexibles Tier-System (free/basic/premium/selfhosted) - Admin-editierbar
|
||||
- 🔲 Trial-System (Dauer konfigurierbar, auto-start nach E-Mail-Verifikation)
|
||||
- 🔲 **Coupon-System** (2 Typen):
|
||||
- Single-Use Coupons (Geschenke, zeitlich begrenzt)
|
||||
- Multi-Use Period Coupons (z.B. Wellpass, monatlich erneuerbar)
|
||||
- 🔲 Coupon-Stacking-Logik (Pause + Resume bei Wellpass-Override)
|
||||
- 🔲 Access-Grant-System (zeitlich begrenzte Zugriffe mit Quelle-Tracking)
|
||||
- 🔲 User-Activity-Log (Login, Password-Änderungen, Coupon-Einlösungen, etc.)
|
||||
- 🔲 User-Stats (Login-Streaks, Nutzungsstatistiken)
|
||||
- 🔲 Individuelle User-Restrictions (Admin kann Limits pro User setzen)
|
||||
- 🔲 App-Settings (globale Konfiguration durch Admin)
|
||||
- 🔲 Erweiterte Admin-User-Verwaltung (Activity-Log, Stats, Access-Historie)
|
||||
|
||||
**E-Mail Templates (v9c):**
|
||||
- 🔲 Registrierung + E-Mail-Verifizierung
|
||||
- 🔲 Einladungslink
|
||||
- 🔲 Passwort-Reset (bereits vorhanden)
|
||||
|
||||
**Spätere Features (v9d/v9e):**
|
||||
- 🔲 Bonus-System (Login-Streaks → Punkte → Geschenk-Coupons)
|
||||
- 🔲 Trial-Reminder-E-Mails (3 Tage vor Ablauf)
|
||||
- 🔲 Monatliches Nutzungs-Summary per E-Mail
|
||||
- 🔲 Self-Service Upgrade (Stripe-Integration)
|
||||
- 🔲 Partner-Verwaltung (Wellpass, Hansefit, etc.)
|
||||
- 🔲 Admin-Benachrichtigungen (neue Registrierungen, etc.)
|
||||
|
||||
### Was in v9d kommt:
|
||||
- 🔲 Bonus-System & Gamification (Streaks, Achievements)
|
||||
- 🔲 Stripe-Integration (Self-Service Upgrade, Subscriptions)
|
||||
- 🔲 OAuth2-Grundgerüst für Fitness-Connectoren
|
||||
- 🔲 Strava Connector
|
||||
- 🔲 Withings Connector (Waage)
|
||||
- 🔲 Garmin Connector
|
||||
|
||||
---
|
||||
|
||||
## v9c Architektur-Details: Subscription & Coupon System
|
||||
|
||||
### Datenbank-Schema (Neue Tabellen)
|
||||
|
||||
#### **app_settings** - Globale Konfiguration
|
||||
```sql
|
||||
key, value, value_type, description, updated_at, updated_by
|
||||
|
||||
Beispiele:
|
||||
- trial_days: 14
|
||||
- trial_behavior: 'downgrade' | 'lock'
|
||||
- allow_registration: true/false
|
||||
- default_tier_trial: 'premium'
|
||||
- gift_coupons_per_month: 3
|
||||
```
|
||||
|
||||
#### **tiers** - Tier-Konfiguration (Admin-editierbar)
|
||||
```sql
|
||||
id, slug, name, description, sort_order
|
||||
max_weight_entries, max_ai_calls_month, max_photos (NULL = unbegrenzt)
|
||||
allow_export, allow_activity_import, allow_nutrition_import
|
||||
allow_fitness_connectors, allow_gift_coupons
|
||||
|
||||
Initial Tiers:
|
||||
- free: 30 Einträge, 0 KI, 5 Fotos, kein Export/Import
|
||||
- basic: unbegrenzt, 10 KI/Monat, 50 Fotos, Export/Import
|
||||
- premium: unbegrenzt, unbegrenzt KI, unbegrenzt Fotos, alle Features
|
||||
- selfhosted: unbegrenzt alles (für Lars)
|
||||
```
|
||||
|
||||
#### **coupons** - Coupon-Verwaltung
|
||||
```sql
|
||||
code, type ('single_use' | 'multi_use_period' | 'gift')
|
||||
valid_from, valid_until, grants_tier, duration_days
|
||||
max_redemptions, current_redemptions
|
||||
created_by, created_for, notes, active
|
||||
|
||||
Beispiel Single-Use:
|
||||
Code: FRIEND-GIFT-XYZ, 30 Tage Premium, max 1x
|
||||
|
||||
Beispiel Multi-Use Period:
|
||||
Code: WELLPASS-2026-03, gültig 01.03-31.03, unbegrenzte Einlösungen
|
||||
```
|
||||
|
||||
#### **coupon_redemptions** - Einlösungs-Historie
|
||||
```sql
|
||||
coupon_id, profile_id, redeemed_at, access_grant_id
|
||||
UNIQUE(coupon_id, profile_id) - User kann denselben Coupon nur 1x einlösen
|
||||
```
|
||||
|
||||
#### **access_grants** - Zeitlich begrenzte Zugriffe
|
||||
```sql
|
||||
profile_id, granted_tier, valid_from, valid_until
|
||||
source ('coupon' | 'admin_grant' | 'trial')
|
||||
active (false wenn pausiert durch Wellpass-Override)
|
||||
paused_at, paused_by (access_grant_id das pausiert hat)
|
||||
|
||||
Stacking-Logik:
|
||||
- Multi-Use Period Coupon (Wellpass): pausiert andere grants
|
||||
- Single-Use Coupon: stackt zeitlich (Resume nach Ablauf)
|
||||
```
|
||||
|
||||
#### **user_activity_log** - Aktivitäts-Tracking
|
||||
```sql
|
||||
profile_id, activity_type, details (JSONB), ip_address, user_agent, created
|
||||
|
||||
Activity Types:
|
||||
- login, password_change, email_change, coupon_redeemed
|
||||
- tier_change, export, ai_analysis, registration
|
||||
```
|
||||
|
||||
#### **user_stats** - Aggregierte Statistiken
|
||||
```sql
|
||||
profile_id, first_login, last_login, total_logins
|
||||
current_streak_days, longest_streak_days, last_streak_date
|
||||
total_weight_entries, total_ai_analyses, total_exports
|
||||
bonus_points (später), gift_coupons_available (später)
|
||||
```
|
||||
|
||||
#### **user_restrictions** - Individuelle Einschränkungen
|
||||
```sql
|
||||
profile_id, max_ai_calls_month, max_weight_entries, max_photos
|
||||
block_export, block_ai, block_import
|
||||
reason, set_by (admin_id)
|
||||
|
||||
Überschreibt Tier-Limits für spezifische User
|
||||
```
|
||||
|
||||
#### **profiles** - Erweiterte Spalten
|
||||
```sql
|
||||
tier, tier_locked (Admin kann Tier festnageln)
|
||||
trial_ends_at, email_verified, email_verify_token
|
||||
invited_by, contract_type, contract_valid_until
|
||||
stripe_customer_id (vorbereitet für v9d)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Backend-Erweiterungen
|
||||
|
||||
#### Neue Router (v9c):
|
||||
```
|
||||
routers/tiers.py - Tier-Verwaltung (List, Edit, Create)
|
||||
routers/coupons.py - Coupon-System (Redeem, Admin CRUD)
|
||||
routers/access_grants.py - Zugriffs-Verwaltung (Current, Grant, Revoke)
|
||||
routers/user_admin.py - Erweiterte User-Verwaltung (Activity, Stats, Restrictions)
|
||||
routers/settings.py - App-Einstellungen (Admin)
|
||||
routers/registration.py - Registrierung + E-Mail-Verifizierung
|
||||
```
|
||||
|
||||
#### Neue Middleware:
|
||||
```python
|
||||
require_tier(min_tier) - Feature-Gate basierend auf Tier
|
||||
check_feature_limit(feature, action) - Limit-Prüfung (z.B. max_weight_entries)
|
||||
log_activity(type, details) - Activity-Logging
|
||||
```
|
||||
|
||||
#### Hintergrund-Tasks (Cron):
|
||||
```python
|
||||
check_expired_access() # Täglich 00:00 - Trial/Coupon-Ablauf prüfen
|
||||
reset_monthly_limits() # 1. jeden Monats - AI-Calls zurücksetzen
|
||||
update_user_streaks() # Täglich 23:59 - Login-Streaks aktualisieren
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Zugriffs-Hierarchie
|
||||
|
||||
```
|
||||
Effektiver Tier wird ermittelt durch (Priorität absteigend):
|
||||
1. Admin-Override (tier_locked=true) → nutzt profiles.tier
|
||||
2. Aktiver access_grant (nicht pausiert, valid_until > now)
|
||||
3. Trial (trial_ends_at > now)
|
||||
4. Base tier (profiles.tier)
|
||||
|
||||
Wellpass-Override-Logik:
|
||||
- User hat Single-Use Coupon (20 Tage verbleibend)
|
||||
- User löst Wellpass-Coupon ein (gültig bis 31.03)
|
||||
- Single-Use access_grant wird pausiert (active=false, paused_by=wellpass_grant_id)
|
||||
- Nach Wellpass-Ablauf: Single-Use wird reaktiviert (noch 20 Tage)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Tier-Limits & Feature-Gates
|
||||
|
||||
**Daten-Sichtbarkeit bei Downgrade:**
|
||||
- Frontend: Buttons/Features ausblenden (Export, KI, Import)
|
||||
- Backend: API limitiert Rückgabe (z.B. nur letzte 30 Gewichtseinträge bei free)
|
||||
- Daten bleiben erhalten, werden nur versteckt
|
||||
- Bei Upgrade wieder sichtbar
|
||||
|
||||
**Feature-Checks:**
|
||||
```python
|
||||
# Beispiel: Gewicht-Eintrag erstellen
|
||||
@check_feature_limit('weight', 'create')
|
||||
def create_weight_entry():
|
||||
# Prüft: Hat User max_weight_entries erreicht?
|
||||
# Falls ja: HTTPException 403 "Limit erreicht - Upgrade erforderlich"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Frontend-Erweiterungen
|
||||
|
||||
#### Neue Seiten:
|
||||
```
|
||||
RegisterPage.jsx - Registrierung (Name, E-Mail, Passwort)
|
||||
VerifyEmailPage.jsx - E-Mail-Verifizierung (Token aus URL)
|
||||
RedeemCouponPage.jsx - Coupon-Eingabe (oder Modal)
|
||||
AdminCouponsPage.jsx - Coupon-Verwaltung (Admin)
|
||||
AdminTiersPage.jsx - Tier-Konfiguration (Admin)
|
||||
AdminSettingsPage.jsx - App-Einstellungen (Admin)
|
||||
```
|
||||
|
||||
#### Neue Komponenten:
|
||||
```jsx
|
||||
<TierBadge tier="premium" /> // Tier-Anzeige mit Icon
|
||||
<FeatureGate tier="basic">...</> // Feature nur für Basic+ zeigen
|
||||
<AccessStatus /> // "Trial endet in 5 Tagen" Banner
|
||||
<CouponInput onRedeem={...} /> // Coupon-Eingabefeld
|
||||
<ActivityTimeline activities={...} /> // User-Activity-Log
|
||||
<StreakCounter days={7} /> // Login-Streak Anzeige (später)
|
||||
```
|
||||
|
||||
#### Erweiterte Admin-Seiten:
|
||||
```
|
||||
AdminUsersPage.jsx erweitert um:
|
||||
- Activity-Log Button → zeigt user_activity_log
|
||||
- Stats Button → zeigt user_stats
|
||||
- Access-Grants Button → zeigt aktive/abgelaufene Zugriffe
|
||||
- Restrictions Button → individuelle Limits setzen
|
||||
- Grant Access Button → manuell Tier-Zugriff gewähren
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### E-Mail Templates (v9c)
|
||||
|
||||
**1. Registrierung + E-Mail-Verifizierung:**
|
||||
```
|
||||
Betreff: Willkommen bei Mitai Jinkendo - E-Mail bestätigen
|
||||
|
||||
Hallo {name},
|
||||
|
||||
vielen Dank für deine Registrierung bei Mitai Jinkendo!
|
||||
|
||||
Bitte bestätige deine E-Mail-Adresse:
|
||||
{app_url}/verify-email?token={token}
|
||||
|
||||
Nach der Bestätigung startet dein 14-Tage Premium Trial automatisch.
|
||||
|
||||
Viel Erfolg bei deinem Training!
|
||||
Dein Mitai Jinkendo Team
|
||||
```
|
||||
|
||||
**2. Einladungslink (Admin):**
|
||||
```
|
||||
Betreff: Du wurdest zu Mitai Jinkendo eingeladen
|
||||
|
||||
Hallo,
|
||||
|
||||
{admin_name} hat dich zu Mitai Jinkendo eingeladen!
|
||||
|
||||
Registriere dich jetzt:
|
||||
{app_url}/register?invite={token}
|
||||
|
||||
Du erhältst {tier} Zugriff.
|
||||
|
||||
Dein Mitai Jinkendo Team
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Migrations-Reihenfolge (v9c)
|
||||
|
||||
```
|
||||
Phase 1 - DB Schema:
|
||||
1. app_settings Tabelle + Initialdaten
|
||||
2. tiers Tabelle + 4 Standard-Tiers
|
||||
3. coupons Tabelle
|
||||
4. coupon_redemptions Tabelle
|
||||
5. access_grants Tabelle
|
||||
6. user_activity_log Tabelle
|
||||
7. user_stats Tabelle
|
||||
8. user_restrictions Tabelle
|
||||
9. profiles Spalten erweitern
|
||||
10. Bestehende Profile migrieren (Lars → tier='selfhosted', email_verified=true)
|
||||
|
||||
Phase 2 - Backend:
|
||||
11. Tier-System Router + Middleware
|
||||
12. Registrierungs-Flow
|
||||
13. Coupon-System
|
||||
14. Access-Grant-Logik
|
||||
15. Activity-Logging
|
||||
16. Erweiterte Admin-Endpoints
|
||||
|
||||
Phase 3 - Frontend:
|
||||
17. Registrierungs-Seiten
|
||||
18. Tier-System UI-Komponenten
|
||||
19. Coupon-Eingabe
|
||||
20. Erweiterte Admin-Panels
|
||||
21. Feature-Gates in bestehende Seiten einbauen
|
||||
|
||||
Phase 4 - Cron-Jobs:
|
||||
22. Expired-Access-Checker
|
||||
23. Monthly-Reset
|
||||
24. Streak-Updater
|
||||
|
||||
Phase 5 - Testing & Deployment:
|
||||
25. Dev-Testing
|
||||
26. Prod-Deployment
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deployment
|
||||
|
||||
### Infrastruktur
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user