From b217a57a154afbc93ae3ff41ef8ee349d28ef54c Mon Sep 17 00:00:00 2001 From: Xor290 Date: Fri, 1 May 2026 20:53:48 +0200 Subject: [PATCH] chore: update Doc --- .dockerignore | 5 + .gitignore | 5 + README.md | 362 ++++++++++++++++++++++++++++++++++++-------------- 3 files changed, 270 insertions(+), 102 deletions(-) create mode 100644 .dockerignore diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 00000000..0d2a13c9 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,5 @@ +frontend-prep/node_modules +.git +.gitignore +Dockerfile +frontend-prep/dist diff --git a/.gitignore b/.gitignore index 9db1edfb..65fffc95 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,8 @@ test_address.sh easpip ansible/ +dist/ +frontend-prep2/ +scripts/data.txt +scripts/data2.txt +scripts/data3.txt diff --git a/README.md b/README.md index d8be1bc0..5e1ede5c 100644 --- a/README.md +++ b/README.md @@ -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 -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]" } -``` +**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 ``` **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 --- +#### Modifier le statut d'une commande + +```bash +PUT /api/v2/admin/protected/orders/:id/status +Authorization: Bearer +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 +``` + +**RĂ©ponse (200 OK):** +```json +{ + "success": true, + "message": "Client notifiĂ©", + "client_username": "jean_dupont" +} +``` + +--- + #### Assignation automatique GPS ```bash @@ -1730,6 +1789,51 @@ Authorization: Bearer --- +#### Modifier le statut d'une commande + +```bash +PUT /api/v1/cabine/commands/:id/status +Authorization: Bearer +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 +``` + +**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 +``` + +**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 +Content-Type: application/json +``` + +**RequĂȘte:** +```json +{ "username": "john_deliveryman" } +``` + +--- + +#### Livreurs disponibles + +```bash +GET /api/v1/cabine/all/deliveryman +Authorization: Bearer +``` + +--- + ## 🚚 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`