# GOBOT Customer Control API

Doc complète de l'API GOBOT pour la gestion des clients et assurances. L'API gère les souscriptions d'assurance (auto/voyage), les récompenses (rewards) multi-services et la blacklist.

## 🚀 Installation & Setup

### Prérequis
- PHP 8.1+
- Laravel 12
- MySQL
- Composer

### Installation
```bash
git clone [repo-url]
cd gobot-customer-control
composer install
cp .env.example .env
# Configure ta DB dans .env
php artisan key:generate
php artisan migrate
php artisan db:seed
php artisan serve
```

### Tests
```bash
php artisan test
# Ou pour les tests API spécifiques
php artisan test --filter Api
```

## 🏗️ Architecture

Le projet utilise une architecture modulaire Laravel standard :
- **Controllers** : Gestion des requêtes HTTP
- **Models** : Eloquent avec relations et scopes
- **Services** : Logique métier (BlacklistService, RewardService)
- **Requests** : Validation des données entrantes
- **Observers** : Traçabilité automatique des changements
- **Jobs/Commands** : Notifications automatiques (rappels expiration)

### Base de Données

Tables principales :
- `customers` : Infos clients (nom, téléphone, email)
- `subscriptions` : Souscriptions d'assurance (auto/voyage)
- `subscription_histories` : Traçabilité des modifications
- `services` : Services externes (MTN, SBEE, SUNU)
- `blacklists` : Blacklist multi-services
- `reward_types` & `rewards` : Système de récompenses

## 📡 API Endpoints

Tous les endpoints sont préfixés par `/api/v1/`. Utilise `Content-Type: application/json` pour les POST/PUT.

### 🔍 Health Check

#### GET `/api/v1/ping`
Vérifie que l'API fonctionne.
- **Réponse** : `{"status": "ok", "timestamp": "2026-03-19T10:00:00Z"}`

---

### 🏢 Gestion des Services

#### GET `/api/v1/services`
Liste tous les services.
- **Query param optionnel** : `actif=true`
- **Réponse 200** : Array des services

#### GET `/api/v1/services/{id}`
Détails d'un service spécifique.
- **Réponse 200** : Détails complets du service

#### POST `/api/v1/services`
Crée un nouveau service.
```json
{
  "name": "sbee",
  "label": "SBEE",
  "description": "Société Béninoise d'Énergie Électrique",
  "is_active": true
}
```
- **Réponse 201** : Service créé

#### PUT `/api/v1/services/{id}`
Met à jour un service.
- **Réponse 200** : Service mis à jour

#### DELETE `/api/v1/services/{id}`
Supprime un service (si pas utilisé).
- **Réponse 200** : Supprimé
- **Erreur 422** : Service utilisé (blacklists/rewards existants)

---

### 📝 Gestion des Souscriptions

#### POST `/api/v1/subscriptions`
Crée une nouvelle souscription (auto ou voyage).
```json
{
  "type": "auto",
  "chatbot": "MTN",
  "phone": "22901000000",
  "name": "John Doe",
  "email": "john@example.com",
  "birth_date": "1990-01-01",
  "start_date": "2026-03-19",
  "end_date": "2027-03-19",
  "amount": 50000,
  "codeproduit": "AUTO001",
  "codeformule": "FORM001",
  "codeduree": "12M",
  "numeropolice": "POL123",
  "msisdn_payment": "22901000000",
  "payment_method": "MTN_MOMO",
  "metadata": {
    "immatriculation": "AA-123-BB",
    "marque": "Toyota",
    "modele": "Corolla",
    "chassis": "CH123",
    "genre": "VP",
    "usage": "Particulier",
    "energie": "essence",
    "puissance": 100,
    "nbplace": 5,
    "datemiseencirculation": "2020-01-01"
  }
}
```
Pour le type `voyage`, remplacer `metadata` par :
```json
{
  "codedesti": "SN",
  "codepays": "SN",
  "duree": "15",
  "nomvoyageur": "Marie",
  "prenomvoyageur": "Dupont",
  "datenaissancevoyageur": "1985-05-15",
  "age": 35,
  "telephonevoyageur": "22901000000",
  "emailvoyageur": "marie@example.com",
  "numpiece": "B123456789"
}
```
- **Réponse 201** : Détails complets de la souscription créée
- **Erreur 422** : Validation échouée

#### GET `/api/v1/subscriptions/{chatbot}`
Récupère une souscription par ID de session chatbot.
- **Réponse 200** : Détails complets + client + metadata
- **Erreur 404** : Session non trouvée

#### PUT `/api/v1/subscriptions/{chatbot}`
Met à jour une souscription (traçabilité automatique).
- **Réponse 200** : Souscription mise à jour
- **Erreur 404** : Session non trouvée

#### GET `/api/v1/subscriptions/{chatbot}/history`
Historique des modifications d'une souscription.
- **Réponse 200** : Array de changements (field, old_value, new_value, changed_at)
- **Erreur 404** : Session non trouvée

---

### 👥 Gestion des Clients

#### POST `/api/v1/customers/contrats`
Recherche les 3 derniers contrats distincts d'un client (par téléphone ou police).
- Dédupliqués par plaque (auto) ou numéro de police (voyage)
- Triés actifs en premier, expirés ensuite
```json
{
  "phone": "22901000000",
  "numeropolice": "POL123"
}
```
- **Réponse 200** : Array de max 3 contrats
- **Erreur 404** : Aucun contrat trouvé
- **Erreur 422** : Paramètres manquants

#### GET `/api/v1/customers/{customer}/subscriptions`
Liste toutes les souscriptions d'un client.
- **Réponse 200** : Array des souscriptions avec résumé complet

---

### 🤖 Chatbot (point d'entrée WhatsApp / Infobip)

Accepte **GET** et **POST** sur le même endpoint.

#### POST `/api/v1/chatbot/customers/contracts`
```json
{
  "type": "auto",
  "phone": "22901000000",
  "session_id": "MTN"
}
```

#### GET `/api/v1/chatbot/customers/contracts`
```
?type=auto&phone=22901000000&session_id=MTN
```

**Réponses possibles :**

`BLACKLISTED` (403) — numéro bloqué :
```json
{ "success": false, "code": "BLACKLISTED", "message": "Accès refusé pour ce numéro." }
```

`SESSION_EXISTS` (200) — session déjà initialisée :
```json
{
  "success": true,
  "code": "SESSION_EXISTS",
  "customer_id": 1,
  "subscription": { ...détails complets... }
}
```

`READY` (200) — nouvelle session :
```json
{
  "success": true,
  "code": "READY",
  "customer_id": 1,
  "customer_lastname": "DOSSOU",
  "customer_firstname": "Marlène",
  "type": "auto",
  "session_id": "MTN",
  "contrats_actifs": [ ...détails complets... ],
  "derniers_contrats": [ ...détails complets... ]
}
```

> `contrats_actifs` : contrats non expirés (pour détecter un renouvellement).  
> `derniers_contrats` : 3 derniers distincts (pour pré-remplir les données du flow).

---

### 🚫 Gestion Blacklist

#### GET `/api/v1/blacklist`
Liste les entrées blacklist.
- **Query params** : `target_type`, `service_id`, `actif`
- **Réponse 200** : Data + meta pagination

#### POST `/api/v1/blacklist`
Ajoute une entrée.
```json
{
  "target_type": "phone",
  "target_value": "22901000000",
  "service_id": 1,
  "reason": "Fraude détectée",
  "start_date": "2026-03-19",
  "end_date": "2026-06-19"
}
```
- **Réponse 201** : Entrée créée

#### GET `/api/v1/blacklist/check`
Vérifie si une valeur est blacklistée.
- **Query params** : `target_type` (requis), `target_value` (requis), `service_id` (optionnel)
- **Réponse 200** : `{"blocked": true/false}`

#### DELETE `/api/v1/blacklist/{id}`
Supprime une entrée.
- **Réponse 200** : Supprimé

---

### 🎁 Système de Récompenses

#### GET `/api/v1/rewards`
Historique des récompenses d'un client.
- **Query param** : `customer_id` (requis)
- **Réponse 200** : Data paginée + meta

#### POST `/api/v1/rewards`
Attribue une récompense après achat.
```json
{
  "customer_id": 1,
  "service_id": 1,
  "amount": 25000
}
```
- **Réponse 201** : Récompense attribuée
- **Réponse 200** : `NO_REWARD` si conditions non remplies

#### GET `/api/v1/rewards/solde`
Solde total des récompenses d'un client.
- **Query param** : `customer_id` (requis)
- **Réponse 200** : `{"solde_fcfa": 15000}`

---

## 🔧 Notes Techniques

### Validation
- Tous les requests utilisent des classes de validation dédiées (`FormRequest`)
- Erreurs retournées en JSON avec codes HTTP appropriés

### Sécurité
- Blacklist vérifiée automatiquement sur `/api/v1/chatbot/customers/contracts`
- Authentification possible via Sanctum (non activée par défaut)

### Notifications
- Commande `contrats:notifier-expirations` programmée quotidiennement
- Envoi d'emails 7j et 1j avant expiration

### Évolutivité
- Services configurables via table `services`
- Metadata JSON pour extensions faciles (nouveaux champs auto/voyage)

---

Mis à jour le 23/03/26