# Story 7.3: Implémenter le programme de parrainage

Status: review

## Story

As a utilisateur,
I want inviter des amis et gagner des récompenses,
So que je peux bénéficier d'avantages en partageant l'application.

## Acceptance Criteria

**Given** je suis connecté
**When** j'accède à la section Parrainage
**Then** je vois mon lien de parrainage unique
**And** je vois combien d'amis j'ai invités
**And** je vois mes récompenses disponibles

**Given** 3 de mes amis s'inscrivent via mon lien
**When** le 3ème ami s'inscrit
**Then** je reçois 1 mois premium GRATUIT
**And** une notification de succès est affichée
**And** mon statut premium est activé automatiquement

## Tasks / Subtasks

- [x] Créer la page de parrainage (AC: #1)
  - [x] Créer `src/app/(dashboard)/parrainage/page.tsx`
  - [x] Afficher le lien de parrainage unique
  - [x] Afficher le nombre d'amis invités
  - [x] Afficher les récompenses disponibles
  - [x] Utiliser shadcn/ui components

- [x] Créer le système de parrainage (AC: #1, #2)
  - [x] Créer la table `referrals` dans Drizzle
  - [x] Ajouter colonnes: id, referrer_id, referred_id, status, created_at
  - [x] Créer la table `rewards` dans Drizzle
  - [x] Ajouter colonnes: id, user_id, reward_type, value, used
  - [x] Générer et appliquer les migrations

- [x] Créer le lien de parrainage unique (AC: #1)
  - [x] Créer `src/services/referralService.ts`
  - [x] Générer un code de parrainage unique par utilisateur
  - [x] Créer l'URL de parrainage: `https://chartbastan.com/signup?ref=CODE`
  - [x] Stocker le code dans la base de données
  - [x] Valider que le code est unique

- [x] Implémenter le tracking des parrainages (AC: #1, #2)
  - [x] Créer l'endpoint `POST /api/v1/referrals/track`
  - [x] Tracker les inscriptions avec le code de parrainage
  - [x] Stocker la relation referrer/referred dans `referrals`
  - [x] Compter le nombre d'amis invités
  - [x] Gérer les erreurs de tracking

- [x] Créer le composant de lien de parrainage (AC: #1)
  - [x] Créer `src/components/referral/ReferralLink.tsx`
  - [x] Afficher le lien de parrainage avec bouton "Copier"
  - [x] Ajouter bouton "Partager" (Twitter, Facebook, WhatsApp)
  - [x] Afficher le nombre d'amis invités
  - [x] Utiliser shadcn/ui components

- [x] Créer le système de récompenses (AC: #2)
  - [x] Créer `src/services/rewardService.ts`
  - [x] Vérifier si l'utilisateur a invité 3 amis
  - [x] Activer 1 mois premium automatiquement
  - [x] Envoyer une notification de succès
  - [x] Créer l'endpoint `POST /api/v1/rewards/check`

- [x] Créer le composant de récompenses (AC: #1)
  - [x] Créer `src/components/referral/RewardsList.tsx`
  - [x] Afficher les récompenses disponibles
  - [x] Afficher les récompenses utilisées
  - [x] Afficher le nombre d'amis invités / 3 pour premium
  - [x] Utiliser shadcn/ui components

- [x] Tester le programme de parrainage (Tous AC)
  - [x] Tester la génération du lien de parrainage
  - [x] Tester le tracking des parrainages
  - [x] Tester l'activation de premium après 3 amis
  - [x] Tester les notifications de succès
  - [x] Vérifier la comptabilité avec les limites de prédictions

## Dev Notes

### Stack Technique
- **Database:** Drizzle + SQLite
- **State:** Zustand
- **UI:** shadcn/ui + Tailwind CSS

### File Structure
```
src/
├── app/
│   └── (dashboard)/
│       └── parrainage/page.tsx
├── components/
│   └── referral/
│       ├── ReferralLink.tsx
│       └── RewardsList.tsx
└── services/
    ├── referralService.ts
    └── rewardService.ts
```

### References
- [Source: _bmad-output/planning-artifacts/epics.md#Story-7.3]

## Dev Agent Record

### Agent Model Used
GLM-4.7

### Completion Notes List
- Programme de parrainage implémenté avec succès
- Tables Drizzle créées: referrals et rewards avec colonne referralCode dans users
- Migrations générées et appliquées (0005 et 0006)
- Service referralService.ts complet avec génération de codes uniques, tracking, statistiques
- Service rewardService.ts complet avec vérification et activation automatique de premium
- API endpoints créés: /api/v1/referrals/referral-code, /api/v1/referrals/track, /api/v1/rewards/check
- Modification de /api/auth/register pour supporter les codes de parrainage
- Composants frontend ReferralLink.tsx et RewardsList.tsx avec interface complète
- Page de parrainage /src/app/(dashboard)/parrainage/page.tsx
- Tests créés et passants pour les services et APIs
- Linting vérifié, aucune erreur
- Tous les critères d'acceptation satisfaits

### File List
- `src/db/schema.ts`
- `drizzle/migrations/0005_tough_sinister_six.sql`
- `drizzle/migrations/0006_friendly_the_spike.sql`
- `src/services/referralService.ts`
- `src/services/rewardService.ts`
- `src/app/api/auth/register/route.ts`
- `src/app/api/v1/referrals/referral-code/route.ts`
- `src/app/api/v1/referrals/track/route.ts`
- `src/app/api/v1/rewards/check/route.ts`
- `src/components/referral/referralLink.tsx`
- `src/components/referral/rewardsList.tsx`
- `src/app/(dashboard)/parrainage/page.tsx`
- `src/tests/services/referralService.test.ts`
- `src/tests/services/rewardService.test.ts`
- `src/tests/api/referralApi.test.ts`