Xor290/projet_gestion_commande
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update README.md

Browse Source
This commit is contained in:
Xor290
2026-04-21 09:11:23 +02:00
parent 2e9827af98
commit 38518f013e
1 changed files with 342 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+342 -68
View File
@@ -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 <client_token>
Content-Type: application/json
```
```json
{ "push_token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]" }
```
#### Désinscrire le push token (Client)
```bash
DELETE /api/v1/push-token
Authorization: Bearer <client_token>
```
#### Enregistrer le push token (Livreur)
```bash
POST /api/v1/livreur/push-token
Authorization: Bearer <livreur_token>
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 <admin_token>
```
**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 <livreur_token>
```
#### Statut Telegram (Livreur)
```bash
GET /api/v1/livreur/telegram/status
Authorization: Bearer <livreur_token>
```
#### Délier Telegram
```bash
DELETE /api/v1/livreur/telegram/unlink
Authorization: Bearer <livreur_token>
```
---
## 💸 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: <hmac_sha512_signature>
```
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 <client_token>
```
**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 <token>
- `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