# API Centralisee Althea

## Description
Backend centralise (bus d'evenements + SSO) pour l'ecosysteme Althea.
Permet aux applications (Ecole Althea, QALIOPI, Tableau Joyeux) de communiquer entre elles via des evenements et de partager une authentification unifiee.

## Stack
- PHP 8+ (custom, pas de framework, pas de Composer)
- MySQL 8+ (BDD : `cbernardalth_api`)
- Hebergement : O2switch (mutualise)
- Pas de Redis, pas de Docker

## Structure
```
backend/
├── api/
│   ├── index.php           # Router (match PHP 8)
│   ├── config/             # app.php (.env loader), database.php (PDO)
│   ├── controllers/        # Controllers (methodes statiques)
│   ├── middleware/          # Cors, RateLimit, AppAuth (HMAC), UserAuth (JWT)
│   ├── services/           # HMACService, JWTService, AlertService, EventBus
│   └── utils/              # Response, Logger
├── database/
│   ├── schema.sql          # Schema complet
│   ├── seed.sql            # Donnees initiales (apps, event_types, subscriptions)
│   ├── migrations/         # Fichiers NNN_description.sql
│   └── migrate.php         # Runner de migrations
├── cron/
│   ├── deliver.php         # Livraison des evenements (toutes les min)
│   └── monitor.php         # Monitoring + alertes (toutes les 5 min)
├── public/.htaccess        # URL rewriting
├── logs/                   # Fichiers de log (YYYY-MM-DD.log)
├── .env                    # Config (jamais en git)
└── .env.example            # Template de config
```

## Dev local
```bash
# Copier la config
cp .env.example .env
# Editer .env (DB credentials)

# Creer la BDD et importer le schema
mysql -u root < database/schema.sql
mysql -u root cbernardalth_api < database/seed.sql

# Lancer le serveur
cd public
php -S localhost:8082 ../api/index.php

# Tester
curl http://localhost:8082/api/v1/health
```

## Conventions
- Controllers : methodes statiques, nommage `VerbNoun`
- Auth apps : headers X-App-Key + X-Signature (HMAC-SHA256) + X-Timestamp
- Auth users : header Authorization: Bearer JWT
- Reponses : `{"success": true, "data": ...}` ou `{"success": false, "error": "..."}`
- PDO : prepared statements toujours, FETCH_ASSOC
- Logs : Logger::info/warning/error/critical
- Alertes : Logger::critical → alerte email automatique

## Projets lies
- `../Ecole Althea/` — Source de verite principale (React + PHP + MySQL)
- `../QALIOPI ALTHEA/` — Dashboard suivi Qualiopi (React + PHP + MySQL)
- `../projet-tableau-joyeux/` — Gestion de projet interne (React + PHP + MySQL)
- Documentation complete dans `../docs/` (9 fichiers)

## Ports dev
- Ecole Althea : 8000
- QALIOPI : 8081
- API Centralisee : 8082

## Crons production (O2switch)
```
* * * * *   php /home/cbernardalth/api.altheaprovence.com/cron/deliver.php
*/5 * * * * php /home/cbernardalth/api.altheaprovence.com/cron/monitor.php
```

## Flux d'evenements actifs

### inscription.created (Ecole → QALIOPI)

| | Detail |
|---|---|
| **Emetteur** | Ecole Althea (`backend/src/CentralApiService.php`) |
| **Declencheur** | `InscriptionService::createInscription()` apres commit |
| **Recepteur** | QALIOPI (`backend/api/controllers/CentralWebhookController.php`) |
| **Callback URL** | `https://gestionqaliopi.altheaprovence.com/api/webhook/central` |
| **Action** | Upsert client + creer commande + initialiser 4 tables de suivi |

### Payload type

```json
{
    "inscription_id": 123,
    "email": "eleve@example.com",
    "first_name": "Jean",
    "last_name": "Dupont",
    "formation_name": "Herboristerie Familiale",
    "formation_id": 5,
    "date_inscription": "2026-03-09 10:30:00",
    "montant_ttc": 590.00,
    "montant_ht": 590.00,
    "modalite_paiement": "En 1 fois",
    "methode_paiement": "Carte bancaire",
    "total_echeances": null
}
```

## Architecture du bus

```
Ecole Althea                 API Centrale               QALIOPI
     |                            |                        |
     |  POST /api/v1/events       |                        |
     |  [HMAC X-App-Key]          |                        |
     |--------------------------->|                        |
     |                            |  POST /webhook/central |
     |                            |  [HMAC X-Signature]    |
     |                            |----------------------->|
     |                            |       200 OK           |
     |                            |<-----------------------|
     |       200 OK               |                        |
     |<---------------------------|                        |
```

- L'emission est **non-bloquante** cote Ecole (publishEventSafe)
- La livraison est **immediate** puis **retry cron** si echec (max 5 tentatives, backoff exponentiel)
- Le webhook QALIOPI repond 200 = succes, 4xx/5xx = retry

## Ajouter un nouveau flux d'evenements

1. **schema.sql / seed.sql** : ajouter le `event_type` + la `subscription`
2. **Emetteur** : appeler `CentralApiService::publishEventSafe('mon.event', $payload)` apres commit
3. **Recepteur** : ajouter un case dans le `match` du `CentralWebhookController` de l'app cible
4. **Tester** : `POST /api/v1/events` avec les headers HMAC, verifier que la delivery arrive