update README

2026-05-15 22:28:21 +02:00
parent afbe310dd7
commit 0350074242
1 changed files with 83 additions and 7 deletions
@@ -1,7 +1,7 @@
 # 📚 Documentation API - Plateforme de Gestion de Commandes

-**Version:** 5.2.0  
-**Date:** 2026-05-01  
+**Version:** 5.3.0  
+**Date:** 2026-05-15  
 **Base URL prod:** `https://mln-uber.club` (HTTPS via WAF nginx + ModSecurity)  
 **Base URL dev:** `http://localhost:8080`  
 **Technologies:** Go 1.24, Gin, PostgreSQL 16, Redis 7, React 19 + Vite, Expo 54 (React Native), TomTom API
@@ -35,12 +35,15 @@ Cette API REST complète gère une plateforme de livraison avec assignation auto
 - **📍 Suivi temps réel** avec ETA et géolocalisation
 - **🔄 Système de queues** Redis optimisé pour les livraisons
 - **⚡ Workers automatiques** (nettoyage, assignation, notifications)
- **🎯 Système de pénalités** pour la gestion des comportements
+- **🎯 Système de pénalités** pour la gestion des comportements (client & livreur)
 - **🔔 Notifications push** Expo (iOS/Android) pour clients et livreurs
 - **🤖 Intégration Telegram** pour alertes et notifications admin/livreur
 - **💸 Paiements crypto** via NowPayments (webhook HMAC)
 - **🛡️ WAF nginx + ModSecurity** (OWASP CRS) en production
 - **📱 Applications mobiles** Expo 54 (client + admin/livreur)
+- **🏷️ Prix par quantité activables/désactivables** — visibilité client filtrée automatiquement
+- **⏱️ Bouton "Client absent"** — timer 5 min au statut `arrived`, amende automatique au livreur si annulation
+- **📲 OTA updates** canaux nommés par rôle (`pre-prod-client`, `production-client`, `pre-prod-admin`, etc.)

 ### 🏗️ Stack Technique

@@ -554,6 +557,7 @@ erDiagram
        int product_id FK
        int quantity
        float price
+        boolean active_price
    }

    PRODUCT_MEDIA {
@@ -1046,6 +1050,8 @@ Authorization: Bearer <client_token>

 ### Produits (Public - Pas d'auth requis)

+> **Filtrage des prix inactifs :** Chaque prix d'un produit porte un flag `active_price` (booléen). Les endpoints publics et client **n'exposent que les prix actifs** (`active_price = true`). Les rôles `admin` et `cabine` reçoivent tous les prix (actifs et inactifs) pour permettre la gestion complète. Côté frontend (web + mobile), les prix sont également filtrés au chargement (`filter(p => p.active_price !== false)`).
+
 #### Liste des produits

 ```bash
@@ -1069,7 +1075,8 @@ GET /api/v1/products
          "id": 1,
          "product_id": 1,
          "quantity": 1,
-          "price": 12.50
+          "price": 12.50,
+          "active_price": true
        }
      ],
      "media": [
@@ -1851,7 +1858,30 @@ Content-Type: application/json

 ### Système de Pénalités

-#### Appliquer une pénalité
+Les amendes sont stockées dans `clients.amende` (PostgreSQL). Tant que `amende > 0`, le middleware `BlockClientIfPenalty` bloque toute tentative de checkout.
+
+**Échelle progressive (annulations) :**
+| Nbre d'annulations | Amende |
+|---|---|
+| 1ère | 20 € |
+| 2ème | 50 € |
+| 3ème | 100 € |
+| 4ème et + | 150 € |
+
+**Sources d'amende :**
+- Client annule sa propre commande → `ApplyCancellationPenalty` (incrémente `cancellations_count`)
+- Livreur annule depuis le statut `arrived` (client absent) → même fonction appelée automatiquement
+
+**Message d'erreur au checkout bloqué :**
+```json
+{
+  "error": "Commande bloquée : vous avez une amende de 20€ en attente de paiement. Prenez attache avec Milieu Nantais sur signal pour régulariser votre situation..",
+  "amende": 20.0,
+  "blocked": true
+}
+```
+
+#### Appliquer une pénalité (Admin)

 ```bash
 POST /api/v2/admin/protected/penalty
@@ -2133,6 +2163,22 @@ Content-Type: application/json

 > **Note :** Le passage à `livre` via ce endpoint requiert des coordonnées GPS valides pour la validation de proximité.

+> **Amende automatique :** si le livreur annule une commande dont le statut courant est `arrived`, une amende progressive est automatiquement appliquée au client (`ApplyCancellationPenalty`) — échelle : 1ère=20€, 2ème=50€, 3ème=100€, 4ème+=150€. Le livreur peut déclencher cette annulation via le bouton **"Client absent"** (cf. section ci-dessous).
+
+---
+
+### Bouton "Client absent" (DashboardScreen)
+
+Lorsque le statut d'une livraison passe à `arrived`, un timer de **5 minutes** démarre automatiquement dans l'app livreur (`frontend-admin`). Pendant ce délai, un compte à rebours est affiché sur la carte de livraison. Une fois les 5 minutes écoulées, le bouton **"Client absent"** apparaît.
+
+**Comportement :**
+- Appui sur "Client absent" → annulation de la commande avec la raison `client_absent`
+- L'API reçoit `status: cancelled` + `issue_type: client_absent`
+- Le backend applique automatiquement `ApplyCancellationPenalty(clientUsername)` (amende progressive)
+- Le timer est stocké dans un `useRef` (pas de re-render) et comparé à `Date.now()` toutes les secondes
+
+**Implémentation :** `frontend-admin/src/screens/delivery/DashboardScreen.tsx` — constante `ABSENT_TIMEOUT_SECS = 300`, ref `arrivedAtRef`, état `elapsedSeconds`.
+
 ---

 ### Position GPS
@@ -2828,6 +2874,8 @@ stateDiagram-v2
        - Livreur PUT status=arrived
        - Admin/Cabine bouton "Le livreur est la"
        Notifie le client (Telegram + push)
+        Timer 5min → bouton "Client absent"
+        Annulation depuis arrived → amende client
    end note

    note right of en_route
@@ -2924,6 +2972,15 @@ Le systeme bascule automatiquement sur le calcul local:
 }
 ```

+#### 403 - Checkout bloqué (amende en attente)
+```json
+{
+  "error": "Commande bloquée : vous avez une amende de 20€ en attente de paiement. Prenez attache avec Milieu Nantais sur signal pour régulariser votre situation..",
+  "amende": 20.0,
+  "blocked": true
+}
+```
+
 #### 404 - Not Found
 ```json
 {
@@ -2990,8 +3047,27 @@ Le systeme bascule automatiquement sur le calcul local:

 ---

-**Documentation mise à jour le :** 2026-05-01  
-**Version API :** 5.2.0  
+## 📋 Changelog
+
+### v5.3.0 — 2026-05-15
+
+- **Prix inactifs filtrés côté client** : le flag `active_price` sur `PRODUCT_PRICES` permet de désactiver un tarif sans le supprimer. Les endpoints publics/client et les frontends web+mobile masquent automatiquement les prix inactifs. Admin et cabine voient tous les prix.
+- **Désactivation au lieu de suppression** : dans la modal d'édition produit (admin), retirer un prix existant le désactive (`active_price = false`) plutôt que de le supprimer de la base.
+- **Amende automatique — livreur annule depuis `arrived`** : quand le livreur passe une commande en `cancelled` alors qu'elle était à `arrived`, `ApplyCancellationPenalty` est appelé automatiquement (amende progressive : 20→50→100→150€).
+- **Bouton "Client absent"** : après 5 minutes au statut `arrived`, l'app livreur affiche un bouton "Client absent" qui déclenche l'annulation avec amende.
+- **Message d'erreur checkout avec contact** : le message de blocage inclut désormais "Prenez attache avec Milieu Nantais sur signal pour régulariser votre situation."
+- **OTA channels par rôle** : les canaux Expo OTA sont désormais nommés `pre-prod-client` / `production-client` / `pre-prod-admin` / `production-admin` pour éviter les mises à jour croisées entre builds.
+
+### v5.2.0 — 2026-05-01
+
+- Activation/désactivation des prix par quantité (admin)
+- Gestion de stock améliorée
+- Refactoring handlers produits
+
+---
+
+**Documentation mise à jour le :** 2026-05-15  
+**Version API :** 5.3.0  
 **Technologies :** Go 1.24, Gin, PostgreSQL 16, Redis 7, React 19, Expo 54, TomTom API, ModSecurity WAF  
 **Déploiement :** Docker Compose · Nginx + ModSecurity OWASP CRS · TLS 1.2/1.3  
 **Base URL prod :** `https://mln-uber.club`