# Système de Gestion des Abonnements

## Vue d'ensemble

Le système de gestion des abonnements permet aux parents d'accéder aux fonctionnalités premium de l'application de gestion scolaire. Il gère les abonnements, les paiements, les promotions et les notifications.

## Modèles de données

### 1. Abonnement
Gère les abonnements des parents avec les champs suivants :
- `codeAbonnement` : Identifiant unique de l'abonnement
- `codeParent` : Code du parent abonné
- `codeEcole` : Code de l'école
- `typeAbonnement` : Type (gratuit, mensuel, trimestriel, semestriel, annuel, essai)
- `statut` : Statut actuel (actif, expire, suspendu, annule, en_attente_paiement, essai)
- `dateDebut` / `dateFin` : Période de validité
- `montant` / `montantFinal` : Montants avec et sans réduction
- `methodePaiement` : Méthode de paiement utilisée
- `renouvellementAuto` : Renouvellement automatique activé

### 2. OffreAbonnement
Définit les offres disponibles :
- `codeOffre` : Identifiant unique de l'offre
- `nom` / `description` : Informations de l'offre
- `typeAbonnement` : Type d'abonnement
- `dureeJours` : Durée en jours
- `montant` / `devise` : Prix et devise
- `fonctionnalites` : Liste des fonctionnalités incluses
- `codeEcole` : École spécifique (null = toutes les écoles)
- `actif` : Offre active ou non
- `dateDebutValidite` / `dateFinValidite` : Période de validité de l'offre

### 3. TransactionAbonnement
Historique des transactions de paiement :
- `codeTransaction` : Identifiant unique de la transaction
- `codeAbonnement` : Abonnement concerné
- `typeTransaction` : Type (paiement, remboursement, annulation, etc.)
- `statut` : Statut de la transaction
- `montant` / `montantNet` : Montants avec et sans frais
- `methodePaiement` : Méthode utilisée
- `operateur` / `numeroTelephone` : Informations de paiement mobile

### 4. PromotionAbonnement
Gère les codes promotionnels :
- `codePromotion` : Code unique de la promotion
- `typeReduction` : Type (pourcentage, montant_fixe, gratuit)
- `valeurReduction` : Valeur de la réduction
- `dateDebut` / `dateFin` : Période de validité
- `nombreUtilisationsMax` : Nombre maximum d'utilisations
- `nombreUtilisationsParParent` : Utilisations par parent
- `montantMinimum` / `montantMaximum` : Plage de montants applicables

### 5. NotificationAbonnement
Notifications liées aux abonnements :
- `codeNotification` : Identifiant unique
- `typeNotification` : Type (expiration, paiement_reussi, etc.)
- `titre` / `message` : Contenu de la notification
- `statut` : Statut d'envoi
- `canauxEnvoi` : Canaux utilisés (push, email, sms)
- `priorite` : Niveau de priorité

## API Endpoints

### Abonnements

#### Créer un abonnement
```
POST /api/abonnement/create
```
**Paramètres :**
- `codeParent` (string, requis) : Code du parent
- `codeEcole` (string, requis) : Code de l'école
- `codeOffre` (string, requis) : Code de l'offre
- `codePromotion` (string, optionnel) : Code promotionnel
- `methodePaiement` (string, optionnel) : Méthode de paiement
- `renouvellementAuto` (boolean, optionnel) : Renouvellement automatique

#### Rechercher les abonnements
```
GET /api/abonnement/find
```
**Paramètres de filtrage :**
- `codeParent` : Filtrer par parent
- `codeEcole` : Filtrer par école
- `statut` : Filtrer par statut
- `typeAbonnement` : Filtrer par type
- `dateDebut` / `dateFin` : Période de création

#### Mettre à jour un abonnement
```
PUT /api/abonnement/update
```
**Paramètres :**
- `codeAbonnement` (string, requis) : Code de l'abonnement
- `statut` (string, optionnel) : Nouveau statut
- `dateFin` (string, optionnel) : Nouvelle date de fin
- `renouvellementAuto` (boolean, optionnel) : Renouvellement automatique

#### Traiter un paiement
```
POST /api/abonnement/process-payment
```
**Paramètres :**
- `codeAbonnement` (string, requis) : Code de l'abonnement
- `methodePaiement` (string, requis) : Méthode de paiement
- `montant` (number, requis) : Montant payé
- `devise` (string, requis) : Devise
- `referencePaiement` (string, optionnel) : Référence externe
- `operateur` (string, optionnel) : Opérateur mobile money

#### Vérifier le statut
```
GET /api/abonnement/check-status
```
**Paramètres :**
- `codeAbonnement` (string, requis) : Code de l'abonnement

#### Tester les notifications
```
POST /api/abonnement/test-notification
```
**Paramètres :**
- `codeAbonnement` (string, requis) : Code de l'abonnement
- `typeNotification` (string, requis) : Type de notification à tester
- `canaux` (array, optionnel) : Canaux d'envoi à tester

### Offres d'abonnement

#### Créer une offre
```
POST /api/offre-abonnement/create
```
**Paramètres :**
- `nom` (string, requis) : Nom de l'offre
- `description` (string, optionnel) : Description
- `typeAbonnement` (string, requis) : Type d'abonnement
- `dureeJours` (number, requis) : Durée en jours
- `montant` (number, requis) : Montant
- `devise` (string, requis) : Devise
- `fonctionnalites` (array, optionnel) : Fonctionnalités incluses
- `codeEcole` (string, optionnel) : École spécifique

#### Rechercher les offres
```
GET /api/offre-abonnement/find
```
**Paramètres de filtrage :**
- `codeEcole` : Filtrer par école
- `typeAbonnement` : Filtrer par type
- `actif` : Filtrer par statut actif
- `montantMin` / `montantMax` : Plage de montants

### Promotions

#### Valider un code promotionnel
```
POST /api/promotion-abonnement/validate
```
**Paramètres :**
- `codePromotion` (string, requis) : Code à valider
- `codeParent` (string, requis) : Code du parent
- `codeOffre` (string, requis) : Code de l'offre
- `montantOriginal` (number, requis) : Montant original

## Flux d'utilisation typique

### 1. Création d'un abonnement
1. Le parent choisit une offre via l'API `offre-abonnement/find`
2. Optionnellement, il valide un code promotionnel via `promotion-abonnement/validate`
3. Il crée l'abonnement via `abonnement/create`
4. Si l'abonnement nécessite un paiement, il traite le paiement via `abonnement/process-payment`

### 2. Suivi d'un abonnement
1. Le parent vérifie le statut via `abonnement/check-status`
2. Il peut consulter l'historique via `abonnement/find`
3. Il reçoit des notifications automatiques pour les événements importants

### 3. Gestion administrative
1. L'administrateur crée des offres via `offre-abonnement/create`
2. Il gère les promotions et codes de réduction
3. Il surveille les abonnements et transactions
4. Il peut mettre à jour les statuts via `abonnement/update`

## Gestion des statuts

### Transitions autorisées :
- `en_attente_paiement` → `actif`, `annule`
- `essai` → `actif`, `expire`, `annule`
- `actif` → `suspendu`, `expire`, `annule`
- `suspendu` → `actif`, `expire`, `annule`
- `expire` → `actif`, `annule`
- `annule` → (aucune transition possible)

### Vérifications automatiques :
- Expiration des abonnements actifs
- Expiration des périodes d'essai
- Notifications d'expiration proche (7 jours avant)
- Mise à jour automatique des statuts

## Notifications

### Types de notifications :
- `expiration_proche` : 7 jours avant expiration
- `expiration` : Abonnement expiré
- `paiement_reussi` : Paiement traité avec succès
- `paiement_echoue` : Échec de paiement
- `essai_commence` : Début de période d'essai
- `essai_fin` : Fin de période d'essai
- `suspension` : Abonnement suspendu
- `reactivation` : Abonnement réactivé
- `abonnement_active` : Abonnement activé

### Canaux d'envoi :
- **Email** : Templates HTML personnalisés avec design moderne
- **WhatsApp** : Messages formatés avec emojis et mise en forme
- **SMS** : Messages courts et concis

### Logique d'envoi :
1. **Priorité Email** : Si l'utilisateur a un email, envoi par email
2. **Priorité WhatsApp** : Si l'utilisateur a un numéro de téléphone, envoi par WhatsApp
3. **Fallback SMS** : Si WhatsApp échoue, envoi par SMS

### Templates disponibles :
- **Abonnement activé** : Notification de bienvenue avec détails
- **Paiement réussi** : Confirmation avec détails de transaction
- **Expiration proche** : Rappel 7 jours avant expiration
- **Expiration** : Notification d'expiration avec appel à l'action
- **Essai commencé** : Début de période d'essai avec fonctionnalités

### Envoi automatique :
- **Envoi instantané** : Notifications envoyées immédiatement lors des événements
- **Tâche cron** : Traitement des notifications en attente toutes les 15 minutes
- **Vérification quotidienne** : Contrôle des abonnements expirés à 8h00

## Sécurité et validation

### Validations automatiques :
- Vérification de l'existence des entités (parent, école, offre)
- Validation des montants et devises
- Contrôle des dates de validité
- Vérification des limites d'utilisation des promotions
- Validation des transitions de statut

### Gestion des erreurs :
- Codes d'erreur standardisés
- Messages d'erreur explicites
- Logs détaillés pour le débogage
- Rollback automatique en cas d'échec

## Intégration avec l'application mobile

### Points d'intégration :
1. **Écran des offres** : Utilise `offre-abonnement/find`
2. **Validation des promotions** : Utilise `promotion-abonnement/validate`
3. **Création d'abonnement** : Utilise `abonnement/create`
4. **Paiement** : Utilise `abonnement/process-payment`
5. **Statut de l'abonnement** : Utilise `abonnement/check-status`
6. **Historique** : Utilise `abonnement/find`

### Synchronisation :
- Vérification automatique du statut à chaque connexion
- Notifications push pour les événements importants
- Mise à jour en temps réel des informations d'abonnement

## Maintenance et monitoring

### Tâches automatiques recommandées :
1. **Vérification quotidienne des expirations** : Mettre à jour les statuts expirés
2. **Nettoyage des notifications** : Archiver les anciennes notifications
3. **Rapports de statistiques** : Générer des rapports d'utilisation
4. **Sauvegarde des données** : Sauvegarde régulière des transactions

### Métriques à surveiller :
- Nombre d'abonnements actifs
- Taux de conversion (essai → payant)
- Taux de renouvellement
- Revenus générés
- Utilisation des promotions
- Performance des paiements 