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

chore: update Doc

Browse Source
This commit is contained in:
Xor290
2026-05-01 20:53:48 +02:00
parent f116d24c49
commit b217a57a15
3 changed files with 270 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.dockerignore
+5
View File
@@ -0,0 +1,5 @@
frontend-prep/node_modules
.git
.gitignore
Dockerfile
frontend-prep/dist
.gitignore
+5
View File
@@ -3,3 +3,8 @@
test_address.sh test_address.sh
easpip easpip
ansible/ ansible/
dist/
frontend-prep2/
scripts/data.txt
scripts/data2.txt
scripts/data3.txt
README.md
+257 -99
View File
@@ -1,8 +1,8 @@
# 📚 Documentation API - Plateforme de Gestion de Commandes # 📚 Documentation API - Plateforme de Gestion de Commandes
**Version:** 5.0.0 **Version:** 5.2.0
**Date:** 2026-04-21 **Date:** 2026-05-01
**Base URL prod:** `https://votre-domaine.com` (HTTPS via WAF nginx + ModSecurity) **Base URL prod:** `https://mln-uber.club` (HTTPS via WAF nginx + ModSecurity)
**Base URL dev:** `http://localhost:8080` **Base URL dev:** `http://localhost:8080`
**Technologies:** Go 1.24, Gin, PostgreSQL 16, Redis 7, React 19 + Vite, Expo 54 (React Native), TomTom API **Technologies:** Go 1.24, Gin, PostgreSQL 16, Redis 7, React 19 + Vite, Expo 54 (React Native), TomTom API
@@ -240,15 +240,14 @@ graph TD
P3["GET /api/v1/products/category/:category"] P3["GET /api/v1/products/category/:category"]
P4["GET /api/v1/categories"] P4["GET /api/v1/categories"]
P5["GET /api/v1/app-settings"] P5["GET /api/v1/app-settings"]
P6["POST /api/v1/geocode"] P6["POST /api/v1/webhooks/nowpayments"]
P7["POST /api/v1/validate-address"] P7["POST /webhook/telegram"]
end end
subgraph AUTH_PUBLIC["🔑 Auth Publique (rate-limited)"] subgraph AUTH_PUBLIC["🔑 Auth Publique (rate-limited)"]
AP1["POST /api/v1/auth/register"] AP1["POST /api/v1/auth/login"]
AP2["POST /api/v1/auth/login"] AP2["POST /api/v1/auth/logout"]
AP3["POST /api/v1/auth/logout"] AP3["PUT /api/v1/auth/change-password (JWT)"]
AP4["PUT /api/v1/auth/change-password (JWT)"]
end end
subgraph CLIENT_AUTH["🔐 Client (JWT Required)"] subgraph CLIENT_AUTH["🔐 Client (JWT Required)"]
@@ -273,26 +272,40 @@ graph TD
C19["GET /api/v1/penalties"] C19["GET /api/v1/penalties"]
C20["GET /api/v1/notifications"] C20["GET /api/v1/notifications"]
C21["POST /api/v1/notifications/read"] C21["POST /api/v1/notifications/read"]
C22["POST /api/v1/push-token"] C22["GET /api/v1/profile"]
C23["DELETE /api/v1/push-token"] C23["PUT /api/v1/profile/update"]
C24["PUT /api/v1/profile/update"] C24["GET /api/v1/referral/balance"]
C25["GET /api/v1/referral/balance"] C25["GET /api/v1/parrain"]
C26["GET /api/v1/commands/:id/payment-status"]
C27["POST /api/v1/telegram/link-token"]
C28["GET /api/v1/telegram/status"]
C29["DELETE /api/v1/telegram/unlink"]
end end
subgraph ADMIN_AUTH["👨‍💼 Admin v2 (JWT Required)"] subgraph ADMIN_AUTH["👨‍💼 Admin v2 (JWT Required)"]
A1["GET/PUT /api/v2/admin/protected/orders"] A1["GET /api/v2/admin/protected/orders"]
A2["POST /api/v2/admin/protected/orders/:id/auto-assign"] A2["GET /api/v2/admin/protected/orders/:id"]
A3["POST /api/v2/admin/protected/orders/auto-assign-all"] A3["PUT /api/v2/admin/protected/orders/:id/status"]
A4["POST /api/v2/admin/protected/orders/:id/force-validate"] A4["PUT /api/v2/admin/protected/orders/:id/address"]
A5["GET /api/v2/admin/protected/delivery-persons"] A5["POST /api/v2/admin/protected/orders/:id/notify-client"]
A6["GET /api/v2/admin/protected/delivery-persons/:username/location"] A6["POST /api/v2/admin/protected/orders/:id/auto-assign"]
A7["GET /api/v2/admin/protected/delivery/queues"] A7["POST /api/v2/admin/protected/orders/auto-assign-all"]
A8["POST /api/v2/admin/protected/delivery/distances"] A8["POST /api/v2/admin/protected/orders/:id/force-validate"]
A9["POST /api/v2/admin/protected/products"] A9["POST /api/v2/admin/protected/orders/:id/confirm-reception"]
A10["POST /api/v2/admin/protected/penalty"] A10["GET /api/v2/admin/protected/delivery-persons"]
A11["GET/POST /api/v2/admin/protected/clients/:id"] A11["GET /api/v2/admin/protected/delivery-persons/:username"]
A12["GET /api/v2/admin/protected/alerts"] A12["GET /api/v2/admin/protected/delivery-persons/:username/location"]
A13["GET /api/v2/admin/protected/settings"] A13["GET /api/v2/admin/protected/delivery/queues"]
A14["POST /api/v2/admin/protected/delivery/distances"]
A15["POST/GET /api/v2/admin/protected/products/:id"]
A16["POST /api/v2/admin/protected/categories"]
A17["POST /api/v2/admin/protected/penalty"]
A18["GET /api/v2/admin/protected/all/clients"]
A19["PUT /api/v2/admin/protected/clients/:id"]
A20["GET /api/v2/admin/protected/alerts"]
A21["GET/PUT /api/v2/admin/protected/settings"]
A22["GET /api/v2/admin/protected/penalties/all"]
A23["GET /api/v2/admin/protected/addresses"]
end end
subgraph LIVREUR_AUTH["🚚 Livreur (JWT Required)"] subgraph LIVREUR_AUTH["🚚 Livreur (JWT Required)"]
@@ -300,25 +313,35 @@ graph TD
L2["GET /api/v1/livreur/deliveries/:id"] L2["GET /api/v1/livreur/deliveries/:id"]
L3["POST /api/v1/livreur/deliveries/:id/start"] L3["POST /api/v1/livreur/deliveries/:id/start"]
L4["PUT /api/v1/livreur/deliveries/:id/status"] L4["PUT /api/v1/livreur/deliveries/:id/status"]
L5["POST /api/v1/livreur/location/update"] L5["GET /api/v1/livreur/deliveries/:id/nav-link"]
L6["GET /api/v1/livreur/location"] L6["POST /api/v1/livreur/location/update"]
L7["POST /api/v1/livreur/update/status"] L7["GET /api/v1/livreur/location"]
L8["GET /api/v1/livreur/status"] L8["POST /api/v1/livreur/update/status"]
L9["GET /api/v1/livreur/queue"] L9["GET /api/v1/livreur/status"]
L10["POST /api/v1/livreur/alert"] L10["GET /api/v1/livreur/queue"]
L11["GET /api/v1/livreur/alerts"] L11["POST /api/v1/livreur/alert"]
L12["GET /api/v1/livreur/notifications"] L12["DELETE /api/v1/livreur/alert/:id"]
L13["POST /api/v1/livreur/push-token"] L13["GET /api/v1/livreur/alerts"]
L14["GET /api/v1/livreur/notifications"]
L15["POST /api/v1/livreur/notifications/read"]
L16["POST /api/v1/livreur/telegram/link-token"]
L17["GET /api/v1/livreur/telegram/status"]
L18["DELETE /api/v1/livreur/telegram/unlink"]
end end
subgraph CABINE_AUTH["🏭 Cabine (JWT Required)"] subgraph CABINE_AUTH["🏭 Cabine (JWT Required)"]
K1["GET /api/v1/cabine/commands/:id/items"] K1["GET /api/v1/cabine/commands/:id/items"]
K2["PUT /api/v1/cabine/items/:item_id/status"] K2["PUT /api/v1/cabine/commands/:id/status"]
K3["POST /api/v1/cabine/commands/:id/confirm-reception"] K3["PUT /api/v1/cabine/items/:item_id/status"]
K4["POST /api/v1/cabine/commands/:id/assign"] K4["POST /api/v1/cabine/commands/:id/confirm-reception"]
K5["GET /api/v1/cabine/all/deliveryman"] K5["POST /api/v1/cabine/commands/:id/assign"]
K6["GET /api/v1/cabine/alerts"] K6["POST /api/v1/cabine/commands/:id/notify-client"]
K7["GET /api/v1/cabine/penalties/all"] K7["GET /api/v1/cabine/all/deliveryman"]
K8["GET /api/v1/cabine/alerts"]
K9["GET /api/v1/cabine/penalties/all"]
K10["GET /api/v1/cabine/addresses"]
K11["GET /api/v1/cabine/notifications"]
K12["POST /api/v1/cabine/telegram/link-token"]
end end
GW[API Gateway :8080] GW[API Gateway :8080]
@@ -685,38 +708,20 @@ NOWPAYMENTS_IPN_SECRET= # Secret IPN NowPayments
### Push Notifications (Expo) ### Push Notifications (Expo)
Le système utilise Expo Push Notifications pour envoyer des notifications aux applications mobiles. Le système utilise Expo Push Notifications pour envoyer des notifications aux applications mobiles (client et livreur). Les tokens Expo sont envoyés directement via l'API Expo depuis le backend — il n'y a pas d'endpoint REST dédié à l'enregistrement du push token.
#### Enregistrer le push token (Client) **Flux :**
1. L'app mobile obtient un `ExponentPushToken` via `expo-notifications`
2. Le backend envoie les notifications via `sendExpoPush()` dans `db/db_notifications.go`
3. Expo relay la notification vers le device cible (iOS/Android)
```bash **Types de notifications envoyées :**
POST /api/v1/push-token - `assigned` — Commande assignée à un livreur
Authorization: Bearer <client_token> - `en_route` — Livreur en route (avec ETA)
Content-Type: application/json - `arrived` — Livreur arrivé (bouton "Le livreur est là")
``` - `livre` — Commande livrée
- `ready_pickup` — Notification cabine "descendez chercher"
```json - `address_proposal` — Proposition de changement d'adresse
{ "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 ### Notifications Telegram
@@ -1216,14 +1221,16 @@ Authorization: Bearer <token>
``` ```
**Statuts possibles:** **Statuts possibles:**
- `pending` - En attente d'assignation
- `assigned` - Assignée à un livreur | Statut | Description | Qui peut le définir |
- `en_route` - Livreur en chemin |--------|-------------|---------------------|
- `arrived` - Livreur arrivé | `pending` | En attente d'assignation | Système (checkout) |
- `livre` - Livrée (en attente d'approbation) | `assigned` | Assignée à un livreur | Système (auto-assign), Admin |
- `approved` - Approuvée par le client | `en_route` | Livreur en chemin | Livreur, Admin |
- `cancelled` - Annulée | `arrived` | Livreur arrivé à destination | Livreur, Admin, Cabine (bouton "Le livreur est là") |
- `disabled` - Désactivée | `livre` | Livrée, en attente d'approbation | Livreur (validation GPS), Admin |
| `approved` | Approuvée et finalisée | Client (approve), Admin, Cabine |
| `cancelled` | Annulée | Client, Livreur, Admin |
--- ---
@@ -1481,6 +1488,58 @@ Authorization: Bearer <admin_token>
--- ---
#### Modifier le statut d'une commande
```bash
PUT /api/v2/admin/protected/orders/:id/status
Authorization: Bearer <admin_token>
Content-Type: application/json
```
**Requête:**
```json
{ "status": "arrived" }
```
**Statuts acceptés:** `pending`, `assigned`, `en_route`, `arrived`, `livre`, `approved`, `cancelled`
**Réponse (200 OK):**
```json
{
"success": true,
"message": "Statut mis à jour",
"command_id": 1234,
"new_status": "arrived"
}
```
**Erreurs possibles:**
- `400` - Statut invalide
- `403` - Rôle insuffisant (admin ou cabine requis)
- `404` - Commande non trouvée
---
#### Notifier le client de descendre
Envoie une notification (Telegram + in-app) au client pour récupérer sa commande, puis passe le statut en `arrived`.
```bash
POST /api/v2/admin/protected/orders/:id/notify-client
Authorization: Bearer <admin_token>
```
**Réponse (200 OK):**
```json
{
"success": true,
"message": "Client notifié",
"client_username": "jean_dupont"
}
```
---
#### Assignation automatique GPS #### Assignation automatique GPS
```bash ```bash
@@ -1730,6 +1789,51 @@ Authorization: Bearer <cabine_token>
--- ---
#### Modifier le statut d'une commande
```bash
PUT /api/v1/cabine/commands/:id/status
Authorization: Bearer <cabine_token>
Content-Type: application/json
```
**Requête:**
```json
{ "status": "arrived" }
```
**Statuts acceptés:** `pending`, `assigned`, `en_route`, `arrived`, `livre`, `approved`, `cancelled`
**Réponse (200 OK):**
```json
{
"success": true,
"message": "Statut mis à jour",
"command_id": 1234,
"new_status": "arrived"
}
```
---
#### Notifier le client de descendre
```bash
POST /api/v1/cabine/commands/:id/notify-client
Authorization: Bearer <cabine_token>
```
**Réponse (200 OK):**
```json
{
"success": true,
"message": "Client notifié",
"client_username": "jean_dupont"
}
```
---
#### Modifier le statut d'un article #### Modifier le statut d'un article
```bash ```bash
@@ -1763,6 +1867,49 @@ Content-Type: application/json
--- ---
#### Confirmer réception (approbation finale)
```bash
POST /api/v1/cabine/commands/:id/confirm-reception
Authorization: Bearer <cabine_token>
```
**Réponse (200 OK):**
```json
{
"success": true,
"message": "Réception confirmée",
"command_id": 1234,
"new_status": "approved"
}
```
---
#### Assigner un livreur
```bash
POST /api/v1/cabine/commands/:id/assign
Authorization: Bearer <cabine_token>
Content-Type: application/json
```
**Requête:**
```json
{ "username": "john_deliveryman" }
```
---
#### Livreurs disponibles
```bash
GET /api/v1/cabine/all/deliveryman
Authorization: Bearer <cabine_token>
```
---
## 🚚 API Livreur (v1) ## 🚚 API Livreur (v1)
**Toutes les routes livreur nécessitent le header:** **Toutes les routes livreur nécessitent le header:**
@@ -1846,12 +1993,13 @@ Content-Type: application/json
} }
``` ```
**Statuts valides pour livreur:** **Statuts valides pour livreur (via cet endpoint) :**
- `assigned` - Assigné - `en_route` — En route vers le client (déclenche calcul ETA + notification Telegram avec ETA)
- `en_route` - En route vers le client - `arrived` — Arrivé à destination (notifie le client de descendre)
- `arrived` - Arrivé à destination - `livre` — Livré (via validation GPS uniquement, voir endpoint `force-validate`)
- `livre` - Livré - `cancelled` — Annulation par le livreur
- `cancelled` - Annulée
> **Note :** Le passage à `livre` via ce endpoint requiert des coordonnées GPS valides pour la validation de proximité.
--- ---
@@ -2524,27 +2672,36 @@ flowchart TD
```mermaid ```mermaid
stateDiagram-v2 stateDiagram-v2
[*] --> pending: Commande creee [*] --> pending: Commande creee (checkout)
pending --> assigned: Auto-assignation GPS pending --> assigned: Auto-assignation GPS / Admin
pending --> pending: Geocodage en cours pending --> cancelled: Annulation client ou admin
assigned --> en_route: Livreur demarre assigned --> en_route: Livreur demarre (start)
assigned --> cancelled: Annulation assigned --> cancelled: Annulation
en_route --> arrived: Position = Destination en_route --> arrived: Livreur arrive (GPS ou Admin/Cabine)
en_route --> en_route: Mise a jour position en_route --> en_route: Mise a jour position GPS
en_route --> livre: Validation GPS livreur / Admin
arrived --> livre: Remise au client arrived --> livre: Remise au client (validation GPS livreur)
arrived --> approved: Admin/Cabine force approbation
livre --> approved: Client confirme livre --> approved: Client confirme / Admin / Cabine
approved --> [*] approved --> [*]
cancelled --> [*] cancelled --> [*]
note right of arrived
Declenche par :
- Livreur PUT status=arrived
- Admin/Cabine bouton "Le livreur est la"
Notifie le client (Telegram + push)
end note
note right of en_route note right of en_route
Position GPS mise a jour ETA calcule et stocke dans Redis
toutes les 30 secondes (command:eta:{id})
ETA recalcule en temps reel Utilise pour les notifications Telegram
end note end note
``` ```
@@ -2675,7 +2832,7 @@ Le systeme bascule automatiquement sur le calcul local:
## 📝 Notes Importantes ## 📝 Notes Importantes
### Sécurité ### Sécurité
- **Tokens JWT** : Expiration variable selon le rôle (Client: 5h, Admin: 2h) - **Tokens JWT** : Expiration variable selon le rôle (Client: 5h · Admin/Livreur/Cabine: 10h)
- **Validation GPS** : Requis pour certaines actions de livraison - **Validation GPS** : Requis pour certaines actions de livraison
- **Filtrage des données** : Les livreurs n'ont pas accès aux téléphones clients - **Filtrage des données** : Les livreurs n'ont pas accès aux téléphones clients
- **Rate Limiting** : Protection contre les abus - **Rate Limiting** : Protection contre les abus
@@ -2701,7 +2858,8 @@ Le systeme bascule automatiquement sur le calcul local:
--- ---
**Documentation mise à jour le :** 2026-04-21 **Documentation mise à jour le :** 2026-05-01
**Version API :** 5.0.0 **Version API :** 5.2.0
**Technologies :** Go 1.24, Gin, PostgreSQL 16, Redis 7, React 19, Expo 54, TomTom API, ModSecurity WAF **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 **Déploiement :** Docker Compose · Nginx + ModSecurity OWASP CRS · TLS 1.2/1.3
**Base URL prod :** `https://mln-uber.club`