Gérer le client, sa commande logistique, ses règlements et les documents opérateur associés : facture PDF par commande, facture récapitulative et étiquette QR. Toutes ces opérations sont accessibles aux deux rôles internes.
| Acteur | Droits |
|---|---|
| Opérateur / administrateur actif | Lire, créer, modifier et supprimer clients/commandes; ajouter des règlements; générer les factures PDF et l’étiquette QR. |
| Visiteur | Aucun accès aux fiches ; seulement inscription et suivi public, documentés séparément. |
GET, POST /api/customers,GET, PUT, DELETE /api/customers/[id]GET, POST /api/orders,GET, PUT, DELETE, PATCH /api/orders/[id]GET, POST /api/customers/[id]/paymentsetPOST /api/customers/[id]/invoices
- L'équipe crée ou retrouve un client. Depuis Suivi, le bouton « + » ouvre la création de commande : l'opérateur recherche un client existant par nom, e-mail ou téléphone et le choisit parmi les suggestions, ou crée sa fiche dans le même formulaire. Nom, téléphone, adresse, ville, code postal et pays sont requis; l'e-mail est facultatif et normalisé.
- À la création manuelle d'une commande, les coordonnées expéditeur et destinataire, le service, l'origine et la destination sont requis. Pour le fret maritime, l’opérateur peut sélectionner un conteneur existant ou laisser la commande non associée ; s’il n’existe aucun conteneur, il doit en créer un avant de pouvoir l’associer. Le serveur génère un numéro unique, avec jusqu'à cinq tentatives en cas de collision.
- Une commande sans
customer_idcherche d'abord le client par e-mail, puis crée une fiche active si nécessaire. - La commande commence à
pending. Elle peut être affectée à un conteneur et recevoir des événements de suivi. - Chaque règlement est enregistré depuis la commande concernée. La fiche calcule le solde de chaque commande à partir de ses propres règlements, sans imputation par ancienneté.
- L’action Facture PDF de la fiche client crée une facture brouillon si la commande n’en possède pas encore, puis génère le PDF. À chaque règlement, la facture associée évolue automatiquement : elle passe à
paidlorsqu’elle est soldée et retrouvesentsi elle ne l’est plus. Si la facture existe déjà, le PDF est régénéré avec le même numéro. - L’action Générer la facture de la fiche crée un PDF récapitulatif de toutes les commandes du client. Chaque commande devient une ligne avec ses propres montants réglé et solde ; ce document récapitulatif n’insère pas de nouvelle facture en base.
- L’action Étiquette QR ouvre le format d’impression PDF de production : logo Danemo, nom et prénom du destinataire, téléphone, destination, expéditeur, QR destiné au scanner opérateur et référence de commande.
- La fiche permet la suppression définitive d'un client sans commande uniquement. L'opérateur saisit exactement son nom pour confirmer ; l'API vérifie elle aussi cette confirmation avant de supprimer et d'auditer l'action.
- Le menu « Plus d’actions » de chaque commande permet également sa suppression après confirmation explicite, puis la fiche est rechargée.
Ce parcours décrit la procédure métier cible communiquée par l’équipe Bruxelles. Les champs et l’assistant dédiés restent à implémenter ; les éléments déjà disponibles sont la création client/commande, le QR, l’étiquette et le suivi.
| Étape | Action équipe | Résultat à conserver dans l’application |
|---|---|---|
| 1. Accueil | Accueillir le client, proposer une bouteille d’eau, comprendre sa demande et aider au déchargement. | Heure d’arrivée, opérateur et éventuel besoin d’assistance. |
| 2. Formulaire | Remettre ou renseigner le formulaire des informations client. | Identité, téléphone, e-mail si disponible et adresse vérifiés. |
| 3. Conditionnement | Filmer/protéger le colis, répondre aux questions et expliquer les mesures de sécurité. | Nombre de colis, poids/dimensions constatés, conditionnement, photos et anomalies éventuelles. |
| 4. Informations d’envoi | Confirmer expéditeur, destinataire, contenu, trajet et destination. | Coordonnées expéditeur/destinataire, contenu, quantité, origine et destination. |
| 5. Prix | Calculer le prix ; si nécessaire, négocier puis faire valider le montant final. | Tarif initial, remise/motif éventuel, prix final, opérateur et statut du règlement. |
| 6. Enregistrement | Créer/reprendre le client et la commande ; imprimer puis apposer l’étiquette. | Référence, QR, statut initial, étiquette imprimée et lien éventuel au conteneur. |
| 7. Tracking | Transmettre le numéro de colis et expliquer les statuts ainsi que l’accès au suivi. | Canal utilisé, langue, date de notification et résultat d’envoi. |
| 8. Clôture | Remercier le client et confirmer le prochain point de contact. | Réception clôturée ou signalement d’un problème. |
En cas de problème, l’opérateur consigne le motif, les informations nécessaires et l’action prise, puis le signale au responsable. Le responsable accuse réception, consigne sa décision et clôture ou relance l’incident. La création de commande ne doit pas être bloquée par une notification en échec, mais le client doit pouvoir être recontacté par un canal alternatif.
Lorsqu’une commande est confirmée après la réception, l’e-mail client doit indiquer la prise en charge, le numéro de colis, la destination, un lien de suivi prérempli et le moyen de contact. Le modèle actuellement envoyé pour le statut confirmed est aligné sur cette formulation ; l’adresse de destination provient de la commande.
sequenceDiagram
participant E as Équipe interne
participant F as Fiche client
participant API as API métier
participant DB as Supabase
participant PDF as Générateur PDF
E->>F: rechercher ou créer un client
F->>API: créer ou modifier la commande
API->>DB: enregistrer client et commande
DB-->>API: numéro de commande et QR
API-->>F: commande créée
E->>F: ajouter un règlement
F->>API: enregistrer le règlement
API->>DB: créer payment et calculer la progression
E->>F: demander une facture
F->>API: créer ou retrouver la facture
API->>DB: vérifier la facture existante
API->>PDF: générer le document demandé
PDF-->>E: télécharger le PDF
flowchart TD
A[Équipe interne] --> B{Client existant ?}
B -- Non --> C[Créer la fiche client]
B -- Oui --> D[Ouvrir la fiche]
C --> D
D --> E[Créer ou modifier la commande]
E --> F[Commande, numéro et QR attribués]
F --> G[Ajouter règlement à la commande]
G --> H[Calculer le solde]
D --> I{Document demandé ?}
I -- Facture commande --> J{Facture déjà présente ?}
J -- Non --> K[Créer la facture et générer le PDF]
J -- Oui --> L[Régénérer le PDF existant]
I -- Récapitulatif --> M[Exporter la facture récapitulative]
classDef actor fill:#dbeafe,stroke:#2563eb,color:#111827;
classDef control fill:#ffedd5,stroke:#ea580c,color:#111827;
classDef action fill:#dcfce7,stroke:#16a34a,color:#111827;
classDef result fill:#f3e8ff,stroke:#9333ea,color:#111827;
class A actor;
class B,I,J control;
class C,D,E,F,G action;
class H,K,L,M result;
- Statuts client :
active,inactive,archived; statuts commande :pending,confirmed,in_progress,completed,cancelled. Les transitions de commande sont uniquement :pending→confirmedoucancelled,confirmed→in_progressoucancelled, puisin_progress→completed. Les statutscompletedetcancelledsont définitifs. - Services autorisés à la création manuelle : fret maritime/aérien, déménagement, dédouanement, négoce, colis.
- Une association de conteneur est admise uniquement pour
fret_maritime. L’API vérifie que l’identifiant sélectionné existe et la base maintient elle-mêmecontainer_codedepuiscontainer_id. - Le règlement est strictement positif, associé à une commande du client, en EUR, daté au format
YYYY-MM-DD, avec l'un des modesbank_transfer,cash,card,mobile,other. - La route de création de facture vérifie l'appartenance de la commande au client, refuse une valeur négative/non numérique et empêche le doublon par commande. L’interface contourne ce cas en utilisant la facture existante pour produire le PDF.
- Les PDF de facture utilisent le générateur commun
generateInvoice, avec les adresses de facturation/livraison, les lignes de commande, TVA, total, paiements et solde. - Les créations, modifications et suppressions de client/commande, ainsi que les paiements, alimentent
business_audit_loglorsqu'il est disponible. - La suppression d'un client exige une session interne, une confirmation exacte de son nom et l'absence de commande associée ; l'API retourne
400pour une confirmation invalide et409si des commandes existent.
- Les triggers SQL génèrent un QR de commande, maintiennent le code conteneur et enregistrent les changements de commande dans
order_history. - Une mise à jour de statut de commande via
ordersApi.updatepeut déclencher une notification e-mail; l'échec ne doit pas annuler la mise à jour. - Le calcul de TVA et le numéro de facture sont des triggers SQL. Un trigger synchronise également le statut et la date de règlement d’une facture liée à la commande lors de chaque création, modification ou suppression de règlement. La facture récapitulative est un export PDF opérateur et ne crée pas de ligne
invoicessupplémentaire.
- Email client dupliqué : la contrainte DB peut refuser la création; l'inscription publique retourne explicitement 409.
- Un règlement n'est ni modifiable ni supprimable par route dédiée dans le dépôt : une erreur de saisie exige aujourd'hui une correction administrée en dehors de ce flux. À confirmer.
- Un appel direct répété à
POST /api/customers/[id]/invoicesreste refusé avec HTTP 409 ; la réutilisation du PDF est un comportement de la fiche client, pas une modification de ce contrat API. - La suppression est physique et reste disponible aux opérateurs et administrateurs actifs. Les commandes liées empêchent cette action afin de préserver leur rattachement ; les règlements et factures associés au client sont ensuite soumis à leurs clés étrangères en cascade.
- Créer client puis commande, contrôler le statut
pending, le numéro unique et la présence d'un QR. Pour une commande de fret maritime, sélectionner un conteneur existant et vérifier l’association et le code conteneur retournés. - Créer une commande sans
customer_idpour un e-mail connu puis inconnu : contrôler réutilisation puis création de fiche. - Ajouter un règlement valide à une commande du client, puis essayer une commande d’un autre client, un montant nul, une date invalide et un mode inconnu : contrôler 201 puis 404/400.
- Depuis la fiche client, générer une Facture PDF deux fois pour la même commande : contrôler que le second clic régénère le PDF avec la même référence, sans erreur visible.
- Appeler directement l’API de création de facture deux fois : contrôler 201 puis 409.
- Générer la facture récapitulative : contrôler une ligne par commande et des montants réglé/solde cohérents avec la progression affichée sur la fiche.
- Générer l’étiquette QR et vérifier que le scan préremplit le code dans le scanner opérateur.
- Vérifier dans
business_audit_logles événements créés en environnement de test. - Depuis la fiche d'un client sans commande, saisir un nom erroné puis son nom exact : contrôler le refus puis la suppression et le retour à la liste. Avec une commande associée, contrôler que le bouton et l'API refusent la suppression.
- Depuis le menu « Plus d’actions » d'une commande, choisir sa suppression puis annuler : contrôler que la commande reste présente. Refaire l'action et confirmer : contrôler sa disparition de la fiche.
- Depuis Suivi, vérifier que la liste affiche sans tableau dense la référence, le client, le trajet et le statut, puis ouvrir le suivi avec son action principale. Créer une commande avec un client existant, puis avec un nouveau client, et contrôler leurs rattachements.
app/api/customers/route.ts,app/api/customers/[id]/route.ts,app/api/customers/[id]/payments/route.ts,app/api/customers/[id]/invoices/route.tsapp/api/orders/route.ts,app/api/orders/[id]/route.ts,app/admin/clients/[id]/page.tsx,lib/customer-payment-progress.ts,lib/invoice-utils.ts,lib/client-documents.ts,lib/database.ts,lib/business-audit.tssupabase/migrations/0001_initial_schema.sql,supabase/migrations/20260902090000_add_customer_payments.sql,supabase/migrations/20260921000100_assign_payments_to_orders.sql