From 38518f013e52ea22880c24cd55249539b55e1b85 Mon Sep 17 00:00:00 2001 From: Xor290 Date: Tue, 21 Apr 2026 09:11:23 +0200 Subject: [PATCH] update README.md --- README.md | 410 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 342 insertions(+), 68 deletions(-) diff --git a/README.md b/README.md index 00a96192..d8be1bc0 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,26 @@ # 📚 Documentation API - Plateforme de Gestion de Commandes -**Version:** 4.0.0 -**Date:** 2025-01-18 -**Base URL:** `http://localhost:8080` -**Technologies:** Go, Gin, PostgreSQL, Redis, TomTom API +**Version:** 5.0.0 +**Date:** 2026-04-21 +**Base URL prod:** `https://votre-domaine.com` (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 --- ## 📋 Table des MatiĂšres 1. [Vue d'ensemble](#vue-densemble) -2. [Authentication](#authentication) -3. [API Client (v1)](#api-client-v1) -4. [API Admin (v2)](#api-admin-v2) -5. [API Cabine (v1)](#api-cabine-v1) -6. [API Livreur (v1)](#api-livreur-v1) -7. [Systeme GPS Integre](#-systeme-gps-integre) -8. [Codes d'Erreur](#codes-derreur) +2. [DĂ©ploiement Production](#-dĂ©ploiement-production) +3. [Authentication](#authentication) +4. [API Client (v1)](#api-client-v1) +5. [API Admin (v2)](#api-admin-v2) +6. [API Cabine (v1)](#api-cabine-v1) +7. [API Livreur (v1)](#api-livreur-v1) +8. [Notifications Push & Telegram](#-notifications-push--telegram) +9. [Paiements Crypto](#-paiements-crypto) +10. [Systeme GPS Integre](#-systeme-gps-integre) +11. [Codes d'Erreur](#codes-derreur) --- @@ -26,12 +30,36 @@ Cette API REST complĂšte gĂšre une plateforme de livraison avec assignation auto ### ✹ FonctionnalitĂ©s Principales -- **🔐 Authentication JWT** multi-rĂŽles (Client, Admin, Livreur, Cabine) -- **🚗 Auto-assignation GPS** des livreurs les plus proches +- **🔐 Authentication JWT** multi-rĂŽles (Client, Admin, Livreur, Cabine) avec rĂ©vocation de token +- **🚗 Auto-assignation GPS** des livreurs les plus proches (worker toutes les 1 minute) - **📍 Suivi temps rĂ©el** avec ETA et gĂ©olocalisation -- **🔄 SystĂšme de queues** optimisĂ© pour les livraisons +- **🔄 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 +- **🔔 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) + +### đŸ—ïž Stack Technique + +| Composant | Technologie | +|-----------|-------------| +| **Backend** | Go 1.24 + Gin · port 8080 | +| **Base de donnĂ©es** | PostgreSQL 16 | +| **Cache / Sessions / Queues** | Redis 7 | +| **Frontend web** | React 19 + TypeScript + Vite (`frontend-prep/`) | +| **App mobile client** | Expo 54 + React Native (`mobile/`) | +| **App mobile admin/livreur** | Expo 54 + React Native (`frontend-admin/`) | +| **WAF / Reverse proxy** | Nginx + ModSecurity OWASP CRS | +| **GĂ©ocodage** | Nominatim (OpenStreetMap) | +| **Routing / ETA** | TomTom Routing API | +| **Push notifications** | Expo Push Notifications | +| **Paiements** | NowPayments (crypto) | +| **Messagerie** | Telegram Bot API | + +--- ### đŸ—ïž Architecture Globale du Systeme @@ -154,31 +182,38 @@ graph TB flowchart LR subgraph Client["đŸ‘€ Client"] C1[Consulter Produits] - C2[Gerer Panier] + C2[Gerer Panier + Stock auto] C3[Passer Commande] - C4[Suivre Livraison] + C4[Suivre Livraison + ETA] C5[Approuver/Annuler] + C6[Notifications Push] + C7[Solde Parrainage] end subgraph Admin["đŸ‘šâ€đŸ’Œ Admin"] - A1[Gerer Produits] - A2[Voir Commandes] - A3[Assigner Livreurs] + A1[Gerer Produits/Clients] + A2[Voir/Modifier Commandes] + A3[Assigner Livreurs GPS] A4[Gerer Penalites] - A5[Surveiller GPS] + A5[Surveiller GPS + Queues] + A6[Parametres Globaux] end subgraph Livreur["🚚 Livreur"] L1[Voir Mes Livraisons] - L2[Mettre a Jour Position] + L2[Mettre a Jour Position GPS] L3[Changer Statut] L4[Voir Ma Queue] + L5[Alertes Police] + L6[Notifications Push] end subgraph Cabine["🏭 Cabine/Cuisine"] - K1[Voir Articles] - K2[Preparer Commande] - K3[Marquer Pret] + K1[Voir Articles Commande] + K2[Preparer/Marquer Pret] + K3[Assigner Livreur] + K4[Gerer Penalites Client] + K5[Voir Alertes] end subgraph Backend["⚙ Backend"] @@ -187,10 +222,10 @@ flowchart LR QUEUE[Gestion Queue] end - C1 & C2 & C3 & C4 & C5 --> API - A1 & A2 & A3 & A4 & A5 --> API - L1 & L2 & L3 & L4 --> API - K1 & K2 & K3 --> API + C1 & C2 & C3 & C4 & C5 & C6 & C7 --> API + A1 & A2 & A3 & A4 & A5 & A6 --> API + L1 & L2 & L3 & L4 & L5 & L6 --> API + K1 & K2 & K3 & K4 & K5 --> API API --> GPS API --> QUEUE ``` @@ -199,56 +234,96 @@ flowchart LR ```mermaid graph TD - subgraph PUBLIC["🔓 Endpoints Publics"] + subgraph PUBLIC["🔓 Endpoints Publics (sans auth)"] P1["GET /api/v1/products"] P2["GET /api/v1/products/:id"] - P3["POST /api/v1/auth/register"] - P4["POST /api/v1/auth/login"] - P5["POST /api/v1/geocode"] + P3["GET /api/v1/products/category/:category"] + P4["GET /api/v1/categories"] + P5["GET /api/v1/app-settings"] + P6["POST /api/v1/geocode"] + P7["POST /api/v1/validate-address"] + end + + subgraph AUTH_PUBLIC["🔑 Auth Publique (rate-limited)"] + AP1["POST /api/v1/auth/register"] + AP2["POST /api/v1/auth/login"] + AP3["POST /api/v1/auth/logout"] + AP4["PUT /api/v1/auth/change-password (JWT)"] end subgraph CLIENT_AUTH["🔐 Client (JWT Required)"] C1["POST /api/v1/panier/add"] C2["GET /api/v1/panier/:username"] C3["DELETE /api/v1/panier/remove"] - C4["POST /api/v1/checkout"] - C5["GET /api/v1/my-commands"] - C6["GET /api/v1/commands/:id/status"] - C7["GET /api/v1/commands/:id/tracking"] - C8["GET /api/v1/commands/:id/eta"] - C9["POST /api/v1/commands/:id/approve"] - C10["POST /api/v1/commands/:id/cancel"] + C4["DELETE /api/v1/panier/clear"] + C5["POST /api/v1/checkout"] + C6["GET /api/v1/my-commands"] + C7["GET /api/v1/my-commands/history"] + C8["GET /api/v1/my-commands/history/detailed"] + C9["GET /api/v1/commands/:id"] + C10["GET /api/v1/commands/:id/status"] + C11["GET /api/v1/commands/:id/tracking"] + C12["GET /api/v1/commands/:id/eta"] + C13["GET /api/v1/commands/:id/items"] + C14["GET /api/v1/commands/:id/history"] + C15["POST /api/v1/commands/:id/approve"] + C16["POST /api/v1/commands/:id/cancel"] + C17["POST /api/v1/commands/:id/address/respond"] + C18["GET /api/v1/my-cancellation-history"] + C19["GET /api/v1/penalties"] + C20["GET /api/v1/notifications"] + C21["POST /api/v1/notifications/read"] + C22["POST /api/v1/push-token"] + C23["DELETE /api/v1/push-token"] + C24["PUT /api/v1/profile/update"] + C25["GET /api/v1/referral/balance"] end - subgraph ADMIN_AUTH["đŸ‘šâ€đŸ’Œ Admin (JWT Required)"] - A1["GET /api/v2/admin/protected/orders"] + subgraph ADMIN_AUTH["đŸ‘šâ€đŸ’Œ Admin v2 (JWT Required)"] + A1["GET/PUT /api/v2/admin/protected/orders"] A2["POST /api/v2/admin/protected/orders/:id/auto-assign"] A3["POST /api/v2/admin/protected/orders/auto-assign-all"] - A4["GET /api/v2/admin/protected/delivery-persons"] - A5["GET /api/v2/admin/protected/delivery-persons/:username/location"] - A6["GET /api/v2/admin/protected/delivery/queues"] - A7["POST /api/v2/admin/protected/delivery/distances"] - A8["GET /api/v2/admin/protected/commands/:id/navigation-links"] + A4["POST /api/v2/admin/protected/orders/:id/force-validate"] + A5["GET /api/v2/admin/protected/delivery-persons"] + A6["GET /api/v2/admin/protected/delivery-persons/:username/location"] + A7["GET /api/v2/admin/protected/delivery/queues"] + A8["POST /api/v2/admin/protected/delivery/distances"] A9["POST /api/v2/admin/protected/products"] A10["POST /api/v2/admin/protected/penalty"] + A11["GET/POST /api/v2/admin/protected/clients/:id"] + A12["GET /api/v2/admin/protected/alerts"] + A13["GET /api/v2/admin/protected/settings"] end subgraph LIVREUR_AUTH["🚚 Livreur (JWT Required)"] L1["GET /api/v1/livreur/deliveries"] - L2["PUT /api/v1/livreur/deliveries/:id/status"] - L3["POST /api/v1/livreur/location/update"] - L4["GET /api/v1/livreur/location"] - L5["POST /api/v1/livreur/update/status"] - L6["GET /api/v1/livreur/queue"] + L2["GET /api/v1/livreur/deliveries/:id"] + L3["POST /api/v1/livreur/deliveries/:id/start"] + L4["PUT /api/v1/livreur/deliveries/:id/status"] + L5["POST /api/v1/livreur/location/update"] + L6["GET /api/v1/livreur/location"] + L7["POST /api/v1/livreur/update/status"] + L8["GET /api/v1/livreur/status"] + L9["GET /api/v1/livreur/queue"] + L10["POST /api/v1/livreur/alert"] + L11["GET /api/v1/livreur/alerts"] + L12["GET /api/v1/livreur/notifications"] + L13["POST /api/v1/livreur/push-token"] end subgraph CABINE_AUTH["🏭 Cabine (JWT Required)"] K1["GET /api/v1/cabine/commands/:id/items"] K2["PUT /api/v1/cabine/items/:item_id/status"] + K3["POST /api/v1/cabine/commands/:id/confirm-reception"] + K4["POST /api/v1/cabine/commands/:id/assign"] + K5["GET /api/v1/cabine/all/deliveryman"] + K6["GET /api/v1/cabine/alerts"] + K7["GET /api/v1/cabine/penalties/all"] end GW[API Gateway :8080] GW --> PUBLIC + GW --> AUTH_PUBLIC GW --> CLIENT_AUTH GW --> ADMIN_AUTH GW --> LIVREUR_AUTH @@ -315,8 +390,21 @@ sequenceDiagram participant DB as PostgreSQL participant R as Redis + rect rgb(220, 240, 220) + Note over C,R: 1. Ajout au panier + C->>F: Ajouter produit + F->>API: POST /panier/add {product_id, quantity} + API->>DB: Verifier stock (GetProductStockByID) + DB-->>API: Stock OK + API->>DB: Decrementer stock (DecrementProductStockByID) + API->>DB: Ajouter ligne panier + API-->>F: 201 Created + F-->>C: Panier mis a jour + Note over C,R: Si suppression panier → stock restitue automatiquement + end + rect rgb(230, 245, 230) - Note over C,R: 1. Creation Commande + Note over C,R: 2. Checkout C->>F: Valider panier F->>API: POST /checkout {address} API->>GPS: Geocoder adresse @@ -338,21 +426,23 @@ sequenceDiagram end rect rgb(230, 230, 245) - Note over C,R: 2. Livraison + Note over C,R: 3. Livraison L->>API: GET /livreur/deliveries API-->>L: Liste commandes + L->>API: POST /deliveries/:id/start L->>API: POST /location/update {lat, lng} API->>R: Update position API->>R: Publish update R-->>F: Notification position F-->>C: Carte mise a jour L->>API: PUT /deliveries/:id/status {en_route} + Note over L,API: ETA calcule et stocke dans Redis L->>API: PUT /deliveries/:id/status {arrived} L->>API: PUT /deliveries/:id/status {livre} end rect rgb(245, 230, 230) - Note over C,R: 3. Finalisation + Note over C,R: 4. Finalisation C->>F: Approuver livraison F->>API: POST /commands/:id/approve {rating} API->>DB: Update statut approved @@ -519,6 +609,193 @@ graph LR --- +## 🚀 DĂ©ploiement Production + +### PrĂ©requis + +- Docker + Docker Compose +- Certificats SSL : `fullchain.pem` + `privkey.pem` (Let's Encrypt recommandĂ©) +- Fichier `.env` complĂ©tĂ© (voir `.env.example`) + +### Structure des fichiers + +``` +docker/ +├── backend/ +│ ├── Dockerfile # Stage builder (Go), runtime, waf (nginx+ModSec) +│ ├── nginx.conf # Config nginx hardened (TLS 1.2/1.3, HSTS, CSP) +│ ├── custom-rules.conf # RĂšgles ModSecurity personnalisĂ©es +│ └── entrypoint.sh # Entrypoint backend Go +├── frontend/ +│ ├── Dockerfile # Build React/Vite + nginx interne +│ └── nginx.conf # Nginx interne (HTTP, sans TLS) +├── certs/ # Certificats SSL (non versionnĂ©s) +│ ├── fullchain.pem +│ └── privkey.pem +└── docker-compose-prod.yml +``` + +### DĂ©ploiement + +```bash +# 1. Copier les certificats +mkdir -p docker/certs +cp /etc/letsencrypt/live/votre-domaine/fullchain.pem docker/certs/ +cp /etc/letsencrypt/live/votre-domaine/privkey.pem docker/certs/ +chmod 644 docker/certs/privkey.pem + +# 2. Configurer les variables d'environnement +cp docker/.env.example docker/.env +# Éditer docker/.env avec vos valeurs + +# 3. Lancer la stack +docker compose -f docker/docker-compose-prod.yml up -d --build + +# 4. VĂ©rifier les logs +docker compose -f docker/docker-compose-prod.yml logs -f waf +``` + +### Services Docker + +| Service | Image | RĂŽle | +|---------|-------|------| +| `waf` | owasp/modsecurity-crs:nginx-alpine | Point d'entrĂ©e HTTPS (ports 80/443) | +| `backend` | Go 1.24 alpine | API REST (port 8080 interne) | +| `frontend` | nginx:alpine | SPA React (port 80 interne) | +| `postgres` | postgres:16-alpine | Base de donnĂ©es | +| `redis` | redis:7-alpine | Cache + sessions + queues | + +### Variables d'environnement requises + +```bash +DB_PASSWORD= # Mot de passe PostgreSQL +USER_JWT_SECRET= # Secret JWT clients (min 32 chars) +ADMIN_JWT_SECRET= # Secret JWT admin/livreur/cabine (min 32 chars) +REDIS_PASSWORD= # Mot de passe Redis +TOMTOM_API_KEY= # ClĂ© API TomTom +SESSION_SECRET= # Secret sessions +TELEGRAM_WEBHOOK_URL= # URL webhook Telegram +TELEGRAM_WEBHOOK_SECRET= # Secret webhook Telegram +NOWPAYMENTS_IPN_SECRET= # Secret IPN NowPayments +``` + +--- + +## 🔔 Notifications Push & Telegram + +### Push Notifications (Expo) + +Le systĂšme utilise Expo Push Notifications pour envoyer des notifications aux applications mobiles. + +#### Enregistrer le push token (Client) + +```bash +POST /api/v1/push-token +Authorization: Bearer +Content-Type: application/json +``` + +```json +{ "push_token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]" } +``` + +#### DĂ©sinscrire le push token (Client) + +```bash +DELETE /api/v1/push-token +Authorization: Bearer +``` + +#### Enregistrer le push token (Livreur) + +```bash +POST /api/v1/livreur/push-token +Authorization: Bearer +Content-Type: application/json +``` + +```json +{ "push_token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]" } +``` + +### Notifications Telegram + +Les admins et livreurs peuvent lier leur compte Telegram pour recevoir des alertes. + +#### GĂ©nĂ©rer un token de liaison (Admin) + +```bash +POST /api/v2/admin/protected/telegram/link-token +Authorization: Bearer +``` + +**RĂ©ponse:** +```json +{ + "link_token": "abc123xyz", + "expires_in": 300, + "bot_url": "https://t.me/votre_bot?start=abc123xyz" +} +``` + +#### GĂ©nĂ©rer un token de liaison (Livreur) + +```bash +POST /api/v1/livreur/telegram/link-token +Authorization: Bearer +``` + +#### Statut Telegram (Livreur) + +```bash +GET /api/v1/livreur/telegram/status +Authorization: Bearer +``` + +#### DĂ©lier Telegram + +```bash +DELETE /api/v1/livreur/telegram/unlink +Authorization: Bearer +``` + +--- + +## 💾 Paiements Crypto + +Le systĂšme intĂšgre NowPayments pour les paiements en cryptomonnaie. + +### Webhook IPN (Instant Payment Notification) + +Endpoint public sĂ©curisĂ© par signature HMAC-SHA512. + +```bash +POST /api/v1/webhooks/nowpayments +Content-Type: application/json +x-nowpayments-sig: +``` + +Le webhook met automatiquement Ă  jour le statut de paiement de la commande correspondante. + +#### VĂ©rifier le statut de paiement d'une commande + +```bash +GET /api/v1/commands/:id/payment-status +Authorization: Bearer +``` + +**RĂ©ponse:** +```json +{ + "command_id": 1234, + "payment_status": "confirmed", + "amount_paid": 25.00, + "currency": "USDT" +} +``` + +--- + ## 🔐 Authentication ### Register Client @@ -706,6 +983,8 @@ GET /api/v1/products/:id ### Gestion du Panier +> **Note stock :** Le stock est dĂ©crĂ©mentĂ© dĂšs l'ajout au panier et restituĂ© automatiquement lors de la suppression d'un article ou du vidage du panier. + #### Ajouter au panier ```bash @@ -944,7 +1223,6 @@ Authorization: Bearer - `livre` - LivrĂ©e (en attente d'approbation) - `approved` - ApprouvĂ©e par le client - `cancelled` - AnnulĂ©e -- `failed` - Échec de livraison - `disabled` - DĂ©sactivĂ©e --- @@ -1573,7 +1851,6 @@ Content-Type: application/json - `en_route` - En route vers le client - `arrived` - ArrivĂ© Ă  destination - `livre` - LivrĂ© -- `failed` - Échec de livraison - `cancelled` - AnnulĂ©e --- @@ -2201,7 +2478,7 @@ Un worker CRON s'execute automatiquement pour assigner les commandes en attente. #### Configuration -- **Frequence:** Toutes les 5 minutes +- **Frequence:** Toutes les 1 minute - **Fichier:** `backend/gestion/workers/cron_auto_assign.go` #### Processus du Worker @@ -2258,14 +2535,11 @@ stateDiagram-v2 en_route --> en_route: Mise a jour position arrived --> livre: Remise au client - arrived --> failed: Client absent - + livre --> approved: Client confirme - livre --> failed: Probleme signale - + approved --> [*] cancelled --> [*] - failed --> [*] note right of en_route Position GPS mise a jour @@ -2413,8 +2687,8 @@ Le systeme bascule automatiquement sur le calcul local: - **TĂ©lĂ©phones** : Format international (`+33612345678`) ### Workers Automatiques -- **Auto-Assignment Cron** : Toutes les 5 minutes -- **Queue Cleanup** : Toutes les 5 minutes +- **Auto-Assignment Cron** : Toutes les 1 minute (`workers/cron_auto_assign.go`) +- **Queue Cleanup** : Toutes les 5 minutes - **ETA Updates** : Toutes les 30 secondes - **Stock Cleanup** : Toutes les 5 minutes @@ -2427,7 +2701,7 @@ Le systeme bascule automatiquement sur le calcul local: --- -**Documentation gĂ©nĂ©rĂ©e le :** 2025-01-18 -**Version API :** 4.0.0 -**Technologies :** Go, Gin, PostgreSQL, Redis, TomTom API -**Support :** DĂ©veloppĂ© avec ❀ en Go +**Documentation mise Ă  jour le :** 2026-04-21 +**Version API :** 5.0.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