chore: update Doc
This commit is contained in:
@@ -0,0 +1,5 @@
|
||||
frontend-prep/node_modules
|
||||
.git
|
||||
.gitignore
|
||||
Dockerfile
|
||||
frontend-prep/dist
|
||||
@@ -3,3 +3,8 @@
|
||||
test_address.sh
|
||||
easpip
|
||||
ansible/
|
||||
dist/
|
||||
frontend-prep2/
|
||||
scripts/data.txt
|
||||
scripts/data2.txt
|
||||
scripts/data3.txt
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# 📚 Documentation API - Plateforme de Gestion de Commandes
|
||||
|
||||
**Version:** 5.0.0
|
||||
**Date:** 2026-04-21
|
||||
**Base URL prod:** `https://votre-domaine.com` (HTTPS via WAF nginx + ModSecurity)
|
||||
**Version:** 5.2.0
|
||||
**Date:** 2026-05-01
|
||||
**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
|
||||
|
||||
@@ -240,15 +240,14 @@ graph TD
|
||||
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"]
|
||||
P6["POST /api/v1/webhooks/nowpayments"]
|
||||
P7["POST /webhook/telegram"]
|
||||
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)"]
|
||||
AP1["POST /api/v1/auth/login"]
|
||||
AP2["POST /api/v1/auth/logout"]
|
||||
AP3["PUT /api/v1/auth/change-password (JWT)"]
|
||||
end
|
||||
|
||||
subgraph CLIENT_AUTH["🔐 Client (JWT Required)"]
|
||||
@@ -273,26 +272,40 @@ graph TD
|
||||
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"]
|
||||
C22["GET /api/v1/profile"]
|
||||
C23["PUT /api/v1/profile/update"]
|
||||
C24["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
|
||||
|
||||
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["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"]
|
||||
A1["GET /api/v2/admin/protected/orders"]
|
||||
A2["GET /api/v2/admin/protected/orders/:id"]
|
||||
A3["PUT /api/v2/admin/protected/orders/:id/status"]
|
||||
A4["PUT /api/v2/admin/protected/orders/:id/address"]
|
||||
A5["POST /api/v2/admin/protected/orders/:id/notify-client"]
|
||||
A6["POST /api/v2/admin/protected/orders/:id/auto-assign"]
|
||||
A7["POST /api/v2/admin/protected/orders/auto-assign-all"]
|
||||
A8["POST /api/v2/admin/protected/orders/:id/force-validate"]
|
||||
A9["POST /api/v2/admin/protected/orders/:id/confirm-reception"]
|
||||
A10["GET /api/v2/admin/protected/delivery-persons"]
|
||||
A11["GET /api/v2/admin/protected/delivery-persons/:username"]
|
||||
A12["GET /api/v2/admin/protected/delivery-persons/:username/location"]
|
||||
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
|
||||
|
||||
subgraph LIVREUR_AUTH["🚚 Livreur (JWT Required)"]
|
||||
@@ -300,25 +313,35 @@ graph TD
|
||||
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"]
|
||||
L5["GET /api/v1/livreur/deliveries/:id/nav-link"]
|
||||
L6["POST /api/v1/livreur/location/update"]
|
||||
L7["GET /api/v1/livreur/location"]
|
||||
L8["POST /api/v1/livreur/update/status"]
|
||||
L9["GET /api/v1/livreur/status"]
|
||||
L10["GET /api/v1/livreur/queue"]
|
||||
L11["POST /api/v1/livreur/alert"]
|
||||
L12["DELETE /api/v1/livreur/alert/:id"]
|
||||
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
|
||||
|
||||
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"]
|
||||
K2["PUT /api/v1/cabine/commands/:id/status"]
|
||||
K3["PUT /api/v1/cabine/items/:item_id/status"]
|
||||
K4["POST /api/v1/cabine/commands/:id/confirm-reception"]
|
||||
K5["POST /api/v1/cabine/commands/:id/assign"]
|
||||
K6["POST /api/v1/cabine/commands/:id/notify-client"]
|
||||
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
|
||||
|
||||
GW[API Gateway :8080]
|
||||
@@ -685,38 +708,20 @@ NOWPAYMENTS_IPN_SECRET= # Secret IPN NowPayments
|
||||
|
||||
### 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
|
||||
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]" }
|
||||
```
|
||||
**Types de notifications envoyées :**
|
||||
- `assigned` — Commande assignée à un livreur
|
||||
- `en_route` — Livreur en route (avec ETA)
|
||||
- `arrived` — Livreur arrivé (bouton "Le livreur est là")
|
||||
- `livre` — Commande livrée
|
||||
- `ready_pickup` — Notification cabine "descendez chercher"
|
||||
- `address_proposal` — Proposition de changement d'adresse
|
||||
|
||||
### Notifications Telegram
|
||||
|
||||
@@ -1216,14 +1221,16 @@ Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**Statuts possibles:**
|
||||
- `pending` - En attente d'assignation
|
||||
- `assigned` - Assignée à un livreur
|
||||
- `en_route` - Livreur en chemin
|
||||
- `arrived` - Livreur arrivé
|
||||
- `livre` - Livrée (en attente d'approbation)
|
||||
- `approved` - Approuvée par le client
|
||||
- `cancelled` - Annulée
|
||||
- `disabled` - Désactivée
|
||||
|
||||
| Statut | Description | Qui peut le définir |
|
||||
|--------|-------------|---------------------|
|
||||
| `pending` | En attente d'assignation | Système (checkout) |
|
||||
| `assigned` | Assignée à un livreur | Système (auto-assign), Admin |
|
||||
| `en_route` | Livreur en chemin | Livreur, Admin |
|
||||
| `arrived` | Livreur arrivé à destination | Livreur, Admin, Cabine (bouton "Le livreur est là") |
|
||||
| `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
|
||||
|
||||
```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
|
||||
|
||||
```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)
|
||||
|
||||
**Toutes les routes livreur nécessitent le header:**
|
||||
@@ -1846,12 +1993,13 @@ Content-Type: application/json
|
||||
}
|
||||
```
|
||||
|
||||
**Statuts valides pour livreur:**
|
||||
- `assigned` - Assigné
|
||||
- `en_route` - En route vers le client
|
||||
- `arrived` - Arrivé à destination
|
||||
- `livre` - Livré
|
||||
- `cancelled` - Annulée
|
||||
**Statuts valides pour livreur (via cet endpoint) :**
|
||||
- `en_route` — En route vers le client (déclenche calcul ETA + notification Telegram avec ETA)
|
||||
- `arrived` — Arrivé à destination (notifie le client de descendre)
|
||||
- `livre` — Livré (via validation GPS uniquement, voir endpoint `force-validate`)
|
||||
- `cancelled` — Annulation par le livreur
|
||||
|
||||
> **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
|
||||
stateDiagram-v2
|
||||
[*] --> pending: Commande creee
|
||||
pending --> assigned: Auto-assignation GPS
|
||||
pending --> pending: Geocodage en cours
|
||||
|
||||
assigned --> en_route: Livreur demarre
|
||||
[*] --> pending: Commande creee (checkout)
|
||||
pending --> assigned: Auto-assignation GPS / Admin
|
||||
pending --> cancelled: Annulation client ou admin
|
||||
|
||||
assigned --> en_route: Livreur demarre (start)
|
||||
assigned --> cancelled: Annulation
|
||||
|
||||
en_route --> arrived: Position = Destination
|
||||
en_route --> en_route: Mise a jour position
|
||||
|
||||
arrived --> livre: Remise au client
|
||||
en_route --> arrived: Livreur arrive (GPS ou Admin/Cabine)
|
||||
en_route --> en_route: Mise a jour position GPS
|
||||
en_route --> livre: Validation GPS livreur / Admin
|
||||
|
||||
livre --> approved: Client confirme
|
||||
arrived --> livre: Remise au client (validation GPS livreur)
|
||||
arrived --> approved: Admin/Cabine force approbation
|
||||
|
||||
livre --> approved: Client confirme / Admin / Cabine
|
||||
|
||||
approved --> [*]
|
||||
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
|
||||
Position GPS mise a jour
|
||||
toutes les 30 secondes
|
||||
ETA recalcule en temps reel
|
||||
ETA calcule et stocke dans Redis
|
||||
(command:eta:{id})
|
||||
Utilise pour les notifications Telegram
|
||||
end note
|
||||
```
|
||||
|
||||
@@ -2675,7 +2832,7 @@ Le systeme bascule automatiquement sur le calcul local:
|
||||
## 📝 Notes Importantes
|
||||
|
||||
### 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
|
||||
- **Filtrage des données** : Les livreurs n'ont pas accès aux téléphones clients
|
||||
- **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
|
||||
**Version API :** 5.0.0
|
||||
**Documentation mise à jour le :** 2026-05-01
|
||||
**Version API :** 5.2.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
|
||||
**Déploiement :** Docker Compose · Nginx + ModSecurity OWASP CRS · TLS 1.2/1.3
|
||||
**Base URL prod :** `https://mln-uber.club`
|
||||
|
||||
Reference in New Issue
Block a user