geo/api/docs/TECHBOOK.md

# Documentation Technique API GeoSector

## 🏗️ Infrastructure

**Stack** : PHP 8.3 | NGINX | MariaDB 10.11 | Alpine Linux (Incus)

| Environnement | Container | DB (IP) | URL | Serveur |
|---------------|-----------|---------|-----|---------|
| **DEV** | dva-geo | maria3 (13.23.33.4) | https://dapp.geosector.fr | IN3 (195.154.80.116) |
| **REC** | rca-geo | maria3 (13.23.33.4) | https://rapp.geosector.fr | IN3 (195.154.80.116) |
| **PROD** | pra-geo | maria4 (13.23.33.4) | https://app3.geosector.fr | IN4 (51.159.7.190) |

**Architecture** : MVC sans framework | Point d'entrée : `index.php` | Config : `AppConfig.php` singleton

## 🗄️ Base de données

### Modèle d'isolation par opération (CRITIQUE)

**Principe** : Chaque opération est un **univers fermé** isolé de la table centrale `users`.

```
users (table centrale, conservée après suppression opération)
  └── ope_users (id, fk_user, fk_operation) ← PIVOT par opération
        ├── ope_users_sectors (fk_user → ope_users.id)
        └── ope_pass (fk_user → ope_users.id)
```

**⚠️ IMPORTANT pour Flutter** :
- **`users.id`** = Identifiant global (gestion membres, login)
- **`ope_users.id`** = Identifiant opération (passages, secteurs)
- **Flutter doit gérer les 2 IDs** lors du login et des CRUD

**Réponse login :**
```json
{
  "users_sectors": [
    {
      "id": 123,           // users.id (gestion membres)
      "ope_user_id": 50,   // ope_users.id (passages/secteurs)
      "name": "John Doe",
      "fk_sector": 456
    }
  ]
}
```

**Requêtes API depuis Flutter :**
```json
// ✅ Création secteur : envoyer ope_users.id
POST /api/sectors { "users": [50, 51] }  // ope_users.id

// ✅ Création passage : fk_user = ope_users.id
POST /api/passages { "fk_user": 50 }  // ope_users.id

// ✅ Modification membre : utiliser users.id
PUT /api/users/123  // users.id
```

### Tables principales

- **`entites`** : Amicales (chiffrement AES-256-CBC sur nom, email, IBAN)
- **`users`** : Table centrale utilisateurs (conservée même si opération supprimée)
- **`operations`** : Campagnes liées à une entité
- **`ope_users`** : **PIVOT** users ↔ opérations (ON DELETE CASCADE depuis operations)
- **`ope_sectors`** : Secteurs géographiques (polygones)
- **`ope_users_sectors`** : Affectation users ↔ secteurs (FK → `ope_users.id`)
- **`ope_pass`** : Passages (FK → `ope_users.id`, ON DELETE CASCADE)
- **`medias`** : Fichiers (logos, exports, reçus) - Stockage : `/uploads/`

## 🔒 Sécurité

- **Auth** : Sessions PHP (httpOnly, secure, SameSite=Strict)
- **Mots de passe** : NIST SP 800-63B, bcrypt, HIBP check (k-anonymity)
- **Chiffrement** : AES-256-CBC (noms, emails, téléphones, IBAN)
- **Protection** : Brute force (8 tentatives/5min), IP blocking, PDO prepared statements
- **Monitoring** : `SecurityMonitor`, `AlertService`, `IPBlocker`

## 💳 Stripe Connect

- **DEV** : Clés TEST Pierre
- **REC** : Clés TEST client + webhook `webhook-rca`
- **PROD** : Clés LIVE client + webhook `webhook-pra`
- **API** : `2025-08-27.basil`
- **Tap to Pay** : iOS 16.4+ (iPhone XS+) | Android 11+ (95+ devices certifiés)
- **Flow** : Passage créé → PaymentIntent → Tap to Pay → Mise à jour `stripe_payment_id`

## 📦 Fonctionnalités

1. **Reçus fiscaux** : PDF auto (<5KB) pour dons, envoi email queue
2. **Logos entités** : Upload PNG/JPG, redimensionnement 250x250px, base64
3. **Migration** : Endpoints REST par entité (9 phases)
4. **CRONs** : Email queue (*/5), cleanup sécurité (2h), Stripe devices (dim 3h)

## 🚀 Déploiement

```bash
./deploy-api.sh      # Local → dva-geo (DEV)
./deploy-api.sh rca  # dva-geo → rca-geo (REC)
./deploy-api.sh pra  # rca-geo → pra-geo (PROD)
```

- Backup auto (10 versions)
- Préservation `/logs/` et `/uploads/`
- Permissions : `nginx:nginx` (code), `nginx:nginx` (logs/uploads)
- Composer install avec `--optimize-autoloader`

## ⚠️ Points d'attention API ↔ Flutter

### 1. Isolation opérations (depuis Oct 2025)

**Avant** : `ope_pass.fk_user` → `users.id` (table centrale)
**Après** : `ope_pass.fk_user` → `ope_users.id` (pivot opération)

**Impact Flutter** :
- Login retourne **2 IDs** : `id` (users.id) + `ope_user_id` (ope_users.id)
- Création secteur/passage : envoyer `ope_user_id`
- Affichage passages : mapper avec `ope_user_id`

### 2. Endpoints critiques modifiés

| Endpoint | Body envoyé | Mapping |
|----------|-------------|---------|
| `POST /api/sectors` | `users: [50, 51]` | ope_users.id |
| `PUT /api/sectors/{id}` | `users: [50, 51]` | ope_users.id |
| `POST /api/passages` | `fk_user: 50` | ope_users.id |
| `PUT /api/passages/{id}` | `fk_user: 50` | ope_users.id |
| `POST /api/users` | - | Retourne `ope_user_id` |

### 3. Requête SQL typique

```sql
-- ❌ AVANT (CASSÉ)
SELECT op.*, u.encrypted_name
FROM ope_pass op
JOIN users u ON op.fk_user = u.id

-- ✅ APRÈS (CORRECT)
SELECT op.*, u.encrypted_name
FROM ope_pass op
JOIN ope_users ou ON op.fk_user = ou.id
JOIN users u ON ou.fk_user = u.id
```

### 4. Suppression en cascade

```sql
DELETE FROM operations WHERE id = 850;
-- Supprime automatiquement (CASCADE) :
-- - ope_users
-- - ope_users_sectors
-- - ope_pass
-- - ope_sectors
-- ✅ users conservé (table centrale)
```

## 📝 Changelog critique

**Version 3.3.7 (26 Oct 2025)** :
- 🔧 Correction bug `SectorController::update()` : Recherche users par `ope_users.id` au lieu de `users.id`
- 🔧 Permissions logs corrigées : `nginx:nginx` + `750/640`
- 🔧 PHP `display_errors = Off` (warnings loggés dans `/var/log/php83/error.log`)

**Version 3.3.6 (21 Oct 2025)** :
- Validation inscription : Code postal + ville (doublon)

**Version 3.2.7 (16 Oct 2025)** :
- Migration RCA-GEO vers maria3 complétée
- URL PROD : `app3.geosector.fr`

**Version 3.2.4-3.2.6 (Sep 2025)** :
- Stripe Connect complet (Tap to Pay, webhooks multi-env)

---

**Mis à jour : 26 Octobre 2025**