feat: Version 3.3.4 - Nouvelle architecture pages, optimisations widgets Flutter et API

- Mise à jour VERSION vers 3.3.4 - Optimisations et révisions architecture API (deploy-api.sh, scripts de migration) - Ajout documentation Stripe Tap to Pay complète - Migration vers polices Inter Variable pour Flutter - Optimisations build Android et nettoyage fichiers temporaires - Amélioration système de déploiement avec gestion backups - Ajout scripts CRON et migrations base de données 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-05 20:11:15 +02:00
parent 242a90720e
commit b6584c83fa
1625 changed files with 145669 additions and 51249 deletions
--- a/api/docs/TECHBOOK.md
+++ b/api/docs/TECHBOOK.md
@@ -10,7 +10,8 @@
 6. [Sécurité](#sécurité)
 7. [Gestion des mots de passe (NIST SP 800-63B)](#gestion-des-mots-de-passe-nist-sp-800-63b)
 8. [Endpoints API](#endpoints-api)
-9. [Changements récents](#changements-récents)
+9. [Paiements Stripe Connect](#paiements-stripe-connect)
+10. [Changements récents](#changements-récents)

 ## Structure du projet

@@ -130,6 +131,27 @@ Exemple détaillé du parcours d'une requête POST /api/users :

 ## Base de données

+### Architecture des containers MariaDB
+
+Depuis janvier 2025, les bases de données sont hébergées dans des containers MariaDB dédiés :
+
+| Environnement | Container API | Container DB | Serveur | IP DB | Nom BDD | Utilisateur | Source des données |
+|---------------|--------------|--------------|---------|-------|---------|-------------|-------------------|
+| **DEV** | dva-geo | maria3 | IN3 | 13.23.33.4 | dva_geo | dva_geo_user | Migré depuis dva-geo/geo_app |
+| **RECETTE** | rca-geo | maria3 | IN3 | 13.23.33.4 | rca_geo | rca_geo_user | Migré depuis rca-geo/geo_app |
+| **PRODUCTION** | pra-geo | maria4 | IN4 | 13.23.33.4 | pra_geo | pra_geo_user | **Dupliqué depuis maria3/rca_geo** |
+
+**Note importante :** La base de production `pra_geo` est créée en dupliquant `rca_geo` depuis IN3/maria3 vers IN4/maria4.
+
+**Avantages de cette architecture :**
+- Isolation des données par environnement
+- Performances optimisées (containers dédiés)
+- Sauvegardes indépendantes
+- Maintenance simplifiée
+- Séparation physique Production/Recette (serveurs différents)
+
+**Migration :** Utiliser le script `scripts/migrate_to_maria_containers.sh` pour migrer les données.
+
 ### Structure des tables principales

 #### Table `users`
@@ -735,6 +757,300 @@ Lors du login, les paramètres de l'entité sont retournés dans le groupe `amic

 Ces paramètres permettent à l'application Flutter d'adapter dynamiquement le formulaire de création de membre.

+## Paiements Stripe Connect
+
+### Vue d'ensemble
+
+L'API intègre un système complet de paiements via Stripe Connect, permettant aux amicales de recevoir des paiements pour leurs calendriers via deux méthodes :
+- **Paiements Web** : Interface de paiement dans un navigateur
+- **Tap to Pay** : Paiements NFC via l'application mobile Flutter
+
+### Architecture Stripe Connect
+
+#### Tables de base de données
+
+**Table `stripe_accounts` :**
+```sql
+CREATE TABLE `stripe_accounts` (
+  `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
+  `fk_entite` int(10) unsigned NOT NULL,
+  `stripe_account_id` varchar(50) NOT NULL,
+  `account_type` enum('express','standard','custom') DEFAULT 'express',
+  `charges_enabled` tinyint(1) DEFAULT 0,
+  `payouts_enabled` tinyint(1) DEFAULT 0,
+  `details_submitted` tinyint(1) DEFAULT 0,
+  `country` varchar(2) DEFAULT 'FR',
+  `default_currency` varchar(3) DEFAULT 'eur',
+  `business_name` varchar(255) DEFAULT NULL,
+  `support_email` varchar(255) DEFAULT NULL,
+  `onboarding_completed_at` timestamp NULL DEFAULT NULL,
+  `created_at` timestamp NOT NULL DEFAULT current_timestamp(),
+  `updated_at` timestamp NULL DEFAULT NULL ON UPDATE current_timestamp(),
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `stripe_account_id` (`stripe_account_id`),
+  KEY `fk_entite` (`fk_entite`),
+  CONSTRAINT `stripe_accounts_ibfk_1` FOREIGN KEY (`fk_entite`) REFERENCES `entites` (`id`)
+);
+```
+
+**Ajout du champ `stripe_payment_id` dans `ope_pass` :**
+```sql
+ALTER TABLE `ope_pass` ADD COLUMN `stripe_payment_id` VARCHAR(50) DEFAULT NULL COMMENT 'ID du PaymentIntent Stripe (pi_xxx)';
+ALTER TABLE `ope_pass` ADD INDEX `idx_stripe_payment` (`stripe_payment_id`);
+```
+
+#### Services principaux
+
+**StripeService** (`src/Services/StripeService.php`) :
+- Gestion des PaymentIntents
+- Communication avec l'API Stripe
+- Gestion des comptes Stripe Connect
+
+**StripeController** (`src/Controllers/StripeController.php`) :
+- Endpoints pour la création de PaymentIntents
+- Gestion des webhooks Stripe
+- API pour les comptes Connect
+
+### Flow de paiement
+
+#### 1. Création du compte Stripe Connect (Onboarding)
+
+```http
+POST /api/stripe/accounts/create
+Authorization: Bearer {session_id}
+Content-Type: application/json
+
+{
+  "amicale_id": 45,
+  "type": "express",
+  "country": "FR",
+  "email": "contact@amicale-pompiers.fr",
+  "business_profile": {
+    "name": "Amicale des Pompiers",
+    "product_description": "Vente de calendriers des pompiers",
+    "mcc": "8398"
+  }
+}
+```
+
+**Réponse :**
+```json
+{
+  "success": true,
+  "stripe_account_id": "acct_1O3ABC456DEF789",
+  "onboarding_url": "https://connect.stripe.com/express/oauth/authorize?...",
+  "status": "pending"
+}
+```
+
+#### 2. Création d'un PaymentIntent (Tap to Pay)
+
+**Flow actuel (v2) :**
+1. L'application crée/modifie d'abord le passage pour obtenir un ID réel
+2. Puis crée le PaymentIntent avec cet ID
+
+```http
+POST /api/stripe/payments/create-intent
+Authorization: Bearer {session_id}
+Content-Type: application/json
+
+{
+  "amount": 2500,  // 25€ en centimes
+  "passage_id": 456,  // ID RÉEL du passage (jamais 0)
+  "payment_method_types": ["card_present"],  // Tap to Pay
+  "location_id": "tml_xxx",
+  "amicale_id": 45,
+  "member_id": 67,
+  "stripe_account": "acct_1234"
+}
+```
+
+**Réponse :**
+```json
+{
+  "success": true,
+  "client_secret": "pi_3QaXYZ_secret_xyz",
+  "payment_intent_id": "pi_3QaXYZ123ABC456",
+  "amount": 2500,
+  "currency": "eur",
+  "passage_id": 456,
+  "type": "tap_to_pay"
+}
+```
+
+#### 3. Traitement du paiement
+
+**Côté application Flutter :**
+- Utilisation du SDK Stripe Terminal
+- Collecte NFC avec le `client_secret`
+- Traitement automatique du paiement
+
+**Mise à jour automatique :**
+- Le `stripe_payment_id` est automatiquement ajouté au passage lors de la création du PaymentIntent
+- Lien bidirectionnel entre le passage et le paiement Stripe
+
+### Endpoints Stripe
+
+#### Gestion des comptes
+
+- `POST /api/stripe/accounts/create` : Création d'un compte Connect
+- `GET /api/stripe/accounts/{id}` : Statut d'un compte
+- `PUT /api/stripe/accounts/{id}` : Mise à jour d'un compte
+
+#### Gestion des paiements
+
+- `POST /api/stripe/payments/create-intent` : Création d'un PaymentIntent
+- `GET /api/stripe/payments/{id}` : Statut d'un paiement
+- `POST /api/stripe/payments/confirm` : Confirmation d'un paiement
+
+#### Gestion des devices Tap to Pay
+
+- `GET /api/stripe/devices/certified-android` : Liste des appareils Android certifiés
+- `POST /api/stripe/devices/check-tap-to-pay` : Vérification de compatibilité d'un appareil
+- `GET /api/stripe/config` : Configuration publique Stripe
+- `GET /api/stripe/stats` : Statistiques de paiement
+
+#### Webhooks
+
+- `POST /api/stripe/webhooks` : Réception des événements Stripe
+  - `account.updated` : Mise à jour du statut d'un compte
+  - `payment_intent.succeeded` : Confirmation d'un paiement réussi
+  - `payment_intent.payment_failed` : Échec d'un paiement
+
+### Sécurité et validation
+
+#### Prérequis pour les paiements :
+- ✅ Compte Stripe Connect activé (`charges_enabled = 1`)
+- ✅ Virements activés (`payouts_enabled = 1`)
+- ✅ Onboarding terminé (`details_submitted = 1`)
+- ✅ Passage existant avec montant correspondant
+- ✅ Utilisateur authentifié et autorisé
+
+#### Validation des montants :
+- Minimum : 1€ (100 centimes)
+- Maximum : 999€ (99 900 centimes)
+- Vérification de correspondance avec le passage
+
+#### Sécurité des transactions :
+- Headers CORS configurés
+- Validation côté serveur obligatoire
+- Logs de toutes les transactions
+- Gestion des erreurs robuste
+
+### États et statuts
+
+#### États des comptes Stripe :
+- `pending` : Onboarding en cours
+- `restricted` : Informations manquantes
+- `active` : Opérationnel pour les paiements
+- `rejected` : Refusé par Stripe
+
+#### États des paiements :
+- `requires_payment_method` : En attente de paiement
+- `processing` : Traitement en cours
+- `succeeded` : Paiement réussi
+- `canceled` : Paiement annulé
+- `requires_action` : Action utilisateur requise
+
+### Intégration avec l'application
+
+#### Flutter (Tap to Pay) :
+- SDK Stripe Terminal pour iOS/Android
+- Interface NFC native
+- Gestion des états du terminal
+- Validation en temps réel
+
+#### Web (Paiements navigateur) :
+- Stripe.js pour l'interface
+- Formulaire de carte sécurisé
+- Confirmation 3D Secure automatique
+
+### Monitoring et logs
+
+#### Logs importants :
+- Création/mise à jour des comptes Connect
+- Succès/échecs des paiements
+- Erreurs webhook Stripe
+- Tentatives de paiement frauduleuses
+
+#### Métriques de suivi :
+- Taux de succès des paiements par amicale
+- Montants moyens des transactions
+- Temps de traitement des paiements
+- Erreurs par type d'appareil
+
+### Configuration environnement
+
+#### Variables Stripe par environnement :
+
+| Environnement | Clés | Webhooks |
+|---------------|------|----------|
+| **DEV** | Test keys (pk_test_, sk_test_) | URL dev webhook |
+| **RECETTE** | Test keys (pk_test_, sk_test_) | URL recette webhook |
+| **PRODUCTION** | Live keys (pk_live_, sk_live_) | URL prod webhook |
+
+#### Comptes Connect :
+- Type : Express (simplifié pour les associations)
+- Pays : France (FR)
+- Devise : Euro (EUR)
+- Frais : Standard Stripe Connect
+
+### Gestion des appareils certifiés Tap to Pay
+
+#### Table `stripe_android_certified_devices`
+
+Stocke la liste des appareils Android certifiés pour Tap to Pay en France :
+- **95+ appareils** pré-chargés lors de l'installation
+- **Mise à jour automatique** hebdomadaire via CRON
+- **Vérification de compatibilité** via endpoints dédiés
+
+#### Endpoint de vérification de compatibilité
+
+```http
+POST /api/stripe/devices/check-tap-to-pay
+Content-Type: application/json
+
+{
+  "platform": "ios" | "android",
+  "manufacturer": "Samsung",  // Requis pour Android
+  "model": "SM-S921B"         // Requis pour Android
+}
+```
+
+**Réponse Android compatible :**
+```json
+{
+  "status": "success",
+  "tap_to_pay_supported": true,
+  "message": "Tap to Pay disponible sur cet appareil",
+  "min_android_version": 14
+}
+```
+
+**Réponse iOS :**
+```json
+{
+  "status": "success",
+  "message": "Vérification iOS à faire côté client",
+  "requirements": "iPhone XS ou plus récent avec iOS 16.4+",
+  "details": "iOS 16.4 minimum requis pour le support PIN complet"
+}
+```
+
+#### Requirements Tap to Pay
+
+| Plateforme | Appareil minimum | OS minimum | Notes |
+|------------|------------------|------------|-------|
+| **iOS** | iPhone XS (2018+) | iOS 16.4+ | Support PIN complet |
+| **Android** | Variable | Android 11+ | NFC obligatoire, non rooté |
+
+### Documentation technique complète
+
+Pour le flow détaillé complet, voir :
+- **`docs/STRIPE-TAP-TO-PAY-FLOW.md`** : Documentation technique complète du flow de paiement
+- **`docs/PLANNING-STRIPE-API.md`** : Planification et architecture Stripe
+- **`docs/STRIPE-TAP-TO-PAY-REQUIREMENTS.md`** : Requirements officiels et liste complète des devices certifiés
+
 ## Intégration Frontend

 ### Configuration des Requêtes
@@ -754,6 +1070,71 @@ fetch('/api/endpoint', {
 - Pas besoin de stocker ou gérer des tokens manuellement
 - Redirection vers /login si session expirée (401)

+## Système de tâches CRON
+
+### Vue d'ensemble
+
+L'API utilise des scripts CRON pour automatiser les tâches de maintenance et de traitement. Les scripts sont situés dans `/scripts/cron/` et s'exécutent dans les containers Incus Alpine.
+
+### Tâches CRON configurées
+
+| Script | Fréquence | Fonction | Container |
+|--------|-----------|----------|-----------|
+| `process_email_queue.php` | */5 * * * * | Traite la queue d'emails (reçus, notifications) | DVA, RCA |
+| `cleanup_security_data.php` | 0 2 * * * | Nettoie les données de sécurité obsolètes | DVA, RCA |
+| `update_stripe_devices.php` | 0 3 * * 0 | Met à jour la liste des devices certifiés Tap to Pay | DVA, RCA |
+
+### Configuration des CRONs
+
+Sur les containers Alpine (dva-geo, rca-geo, pra-geo) :
+
+```bash
+# Vérifier les crons actifs
+crontab -l
+
+# Éditer les crons
+crontab -e
+
+# Format des lignes cron
+*/5 * * * * /usr/bin/php /var/www/geosector/api/scripts/cron/process_email_queue.php >> /var/www/geosector/api/logs/email_queue.log 2>&1
+0 2 * * * /usr/bin/php /var/www/geosector/api/scripts/cron/cleanup_security_data.php >> /var/www/geosector/api/logs/cleanup_security.log 2>&1
+0 3 * * 0 /usr/bin/php /var/www/geosector/api/scripts/cron/update_stripe_devices.php >> /var/www/geosector/api/logs/stripe_devices.log 2>&1
+```
+
+### Script `process_email_queue.php`
+
+- **Fonction** : Envoie les emails en attente dans la table `email_queue`
+- **Batch** : 50 emails maximum par exécution
+- **Lock file** : `/tmp/process_email_queue.lock` (évite l'exécution simultanée)
+- **Gestion d'erreur** : 3 tentatives max par email
+
+### Script `cleanup_security_data.php`
+
+- **Fonction** : Purge les données de sécurité selon la politique de rétention
+- **Rétention** :
+  - Métriques de performance : 30 jours
+  - Tentatives de login échouées : 7 jours
+  - Alertes résolues : 90 jours
+  - IPs expirées : Déblocage immédiat
+
+### Script `update_stripe_devices.php`
+
+- **Fonction** : Maintient à jour la liste des appareils certifiés Tap to Pay
+- **Source** : Liste de 95+ devices intégrée + fichier JSON optionnel
+- **Actions** :
+  - Ajoute les nouveaux appareils certifiés
+  - Met à jour les versions Android minimales
+  - Désactive les appareils obsolètes
+  - Envoie une notification email si changements importants
+- **Personnalisation** : Possibilité d'ajouter des devices via `/data/stripe_certified_devices.json`
+
+### Monitoring des CRONs
+
+Les logs sont stockés dans `/var/www/geosector/api/logs/` :
+- `email_queue.log` : Logs du traitement des emails
+- `cleanup_security.log` : Logs du nettoyage sécurité
+- `stripe_devices.log` : Logs de mise à jour des devices
+
 ## Maintenance et Déploiement

 ### Logs
@@ -764,11 +1145,36 @@ fetch('/api/endpoint', {

 ### Déploiement

-1. Pull du repository
-2. Vérification des permissions
-3. Configuration de l'environnement
-4. Tests des endpoints
-5. Redémarrage des services
+Le script `deploy-api.sh` gère le déploiement sur les 3 environnements :
+
+```bash
+# Déploiement DEV : code local → container dva-geo sur IN3
+./deploy-api.sh
+
+# Déploiement RECETTE : container dva-geo → container rca-geo sur IN3
+./deploy-api.sh rca
+
+# Déploiement PRODUCTION : container rca-geo (IN3) → container pra-geo (IN4)
+./deploy-api.sh pra
+```
+
+Flux de déploiement :
+1. **DEV** : Archive du code local, déploiement sur container `dva-geo` sur IN3 (195.154.80.116)
+   - URL publique : https://dapp.geosector.fr/api/
+   - IP interne : http://13.23.33.43/api/
+2. **RECETTE** : Archive depuis container `dva-geo`, déploiement sur `rca-geo` sur IN3
+   - URL publique : https://rapp.geosector.fr/api/
+3. **PRODUCTION** : Archive depuis `rca-geo` (IN3), déploiement sur `pra-geo` (51.159.7.190)
+   - URL publique : https://app.geosector.fr/api/
+
+Caractéristiques :
+- Sauvegarde automatique avec rotation (garde les 10 dernières)
+- Préservation des dossiers `logs/` et `uploads/`
+- Gestion des permissions :
+  - Code API : `nginx:nginx` (755/644)
+  - Logs et uploads : `nobody:nginx` (755/644)
+- Installation des dépendances Composer (pas de mise à jour)
+- Journalisation dans `~/.geo_deploy_history`

 ### Surveillance

@@ -779,6 +1185,89 @@ fetch('/api/endpoint', {

 ## Changements récents

+### Version 3.2.5 (29 Septembre 2025)
+
+#### 1. Système de gestion automatique des devices Tap to Pay
+
+**Nouveaux endpoints ajoutés :**
+- `GET /api/stripe/devices/certified-android` : Récupération de la liste complète des appareils certifiés
+- `POST /api/stripe/devices/check-tap-to-pay` : Vérification de compatibilité d'un appareil spécifique
+- Endpoints publics (pas d'authentification requise) pour vérification côté app
+
+**Script CRON de mise à jour automatique :**
+- **Script** : `/scripts/cron/update_stripe_devices.php`
+- **Fréquence** : Hebdomadaire (dimanche 3h)
+- **Fonction** : Maintient à jour la liste de 95+ appareils Android certifiés
+- **Base de données** : Table `stripe_android_certified_devices` avec 77 appareils actifs
+
+**Corrections des requirements iOS :**
+- Mise à jour : iOS 16.4+ minimum (au lieu de 15.4/16.0)
+- Raison : Support PIN complet obligatoire pour les paiements > 50€
+
+**Documentation ajoutée :**
+- `docs/STRIPE-TAP-TO-PAY-REQUIREMENTS.md` : Requirements officiels complets
+- Liste exhaustive des appareils certifiés par fabricant
+- Configuration SDK pour toutes les plateformes
+
+#### 2. Configuration des tâches CRON sur les containers
+
+**Environnements configurés :**
+- **DVA-GEO (DEV)** : 3 CRONs actifs
+- **RCA-GEO (RECETTE)** : 3 CRONs actifs (ajoutés le 29/09)
+- **PRA-GEO (PROD)** : À configurer
+
+**Tâches automatisées :**
+1. Queue d'emails : Toutes les 5 minutes
+2. Nettoyage sécurité : Quotidien à 2h
+3. Mise à jour devices Stripe : Hebdomadaire dimanche 3h
+
+### Version 3.2.4 (Septembre 2025)
+
+#### 1. Implémentation complète de Stripe Connect V1
+
+**Paiements Stripe intégrés pour les amicales :**
+- **Stripe Connect Express** : Onboarding simplifié pour les associations
+- **Tap to Pay** : Paiements NFC via l'application mobile Flutter
+- **Paiements Web** : Interface de paiement navigateur avec Stripe.js
+- **Webhooks** : Gestion automatique des événements Stripe
+
+**Nouvelles tables de base de données :**
+- `stripe_accounts` : Gestion des comptes Connect par amicale
+- `stripe_payment_history` : Historique des transactions Stripe
+- `stripe_refunds` : Gestion des remboursements
+- Ajout de `stripe_payment_id` dans `ope_pass` pour liaison bidirectionnelle
+
+**Nouveaux services :**
+- **StripeService** : Communication avec l'API Stripe, gestion des PaymentIntents
+- **StripeController** : Endpoints API pour création de comptes, paiements et webhooks
+
+**Flow de paiement optimisé (v2) :**
+1. Passage créé/modifié EN PREMIER pour obtenir un ID réel
+2. Création PaymentIntent avec `passage_id` réel (jamais 0)
+3. Traitement Tap to Pay via SDK Stripe Terminal
+4. Mise à jour automatique du passage avec `stripe_payment_id`
+
+**Endpoints ajoutés :**
+- `POST /api/stripe/accounts/create` : Création compte Connect
+- `POST /api/stripe/payments/create-intent` : Création PaymentIntent
+- `GET /api/stripe/payments/{id}` : Statut d'un paiement
+- `POST /api/stripe/webhooks` : Réception événements Stripe
+
+**Sécurité et validation :**
+- Validation stricte des montants (1€ à 999€)
+- Vérification correspondance passage/montant
+- Gestion des permissions par amicale
+- Logs complets des transactions
+
+**Configuration multi-environnements :**
+- DEV/RECETTE : Clés de test Stripe
+- PRODUCTION : Clés live avec webhooks sécurisés
+- Migration base de données via `migrate_stripe_payment_id.sql`
+
+**Documentation technique :**
+- `docs/STRIPE-TAP-TO-PAY-FLOW.md` : Flow complet de paiement
+- `docs/PLANNING-STRIPE-API.md` : Architecture et planification
+
 ### Version 3.0.7 (Août 2025)

 #### 1. Implémentation complète de la norme NIST SP 800-63B pour les mots de passe