Référence d’application. Il s’agit d’une architecture illustrative et d’une liste de contrôle du périmètre, et non d’un projet client vérifié ni d’un déploiement mesuré. Les technologies, le périmètre d’intégration et les éléments livrés sont convenus selon le brief réel.
Scénario et contraintes
Un opérateur logistique remplace la répartition des livraisons sur feuilles de calcul et la facturation manuelle. Deux contraintes orientent la conception : les chauffeurs travaillent dans des zones dépourvues d’un signal fiable, et chaque ligne de facture doit pouvoir être justifiée lorsqu’un client la conteste. Le système s’appuie donc sur un journal d’événements en ajout uniquement comme source de vérité, plutôt que sur une colonne d’état que n’importe qui pourrait écraser.
Architecture
Couches et responsabilités
| Couche | Technologie | Responsabilité |
|---|---|---|
| Application web des opérations | Vue 3 + Element Plus | Saisie des commandes, tableau de répartition, gestion des exceptions, contrôle de la facturation. |
| Application chauffeur | Android (Kotlin), utilisable hors ligne | Liste des tâches, scan, photo, signature et capture de l’état. Tout est d’abord écrit localement, puis envoyé lorsqu’une connexion est disponible. |
| Portail client | Mini-programme WeChat | Suivi en libre-service ; mesurer toute évolution du volume de demandes plutôt que de supposer une réduction. |
| API | Go + Gin | Validation, règles de répartition, ingestion des événements, calcul des frais. |
| Stockage | MySQL | Envois, événements, règlement. La table des événements est en ajout uniquement et constitue le système de référence. |
| Cache / file d’attente | Redis | Mise en cache du tableau de répartition, déduplication des envois, tâches en arrière-plan pour la facturation et les notifications. |
| Fichiers | Stockage d’objets | Photos et signatures de preuve de livraison, référencées par une clé plutôt que stockées dans la base de données. |
Modèle de données
Les tables ci-dessous portent les règles dont dépend tout le reste. Les définir incorrectement transforme une démonstration fonctionnelle en un système impossible à étendre.
Entités principales
| Entité | Champs clés, relations et règles |
|---|---|
| consignment | Enregistrement de l’envoi : parties, adresses, type de service, créneaux horaires, poids et volume déclarés, ainsi que la base tarifaire convenue lors de la saisie. |
| shipment_event | En ajout uniquement, horodaté, avec opérateur, emplacement, type d’événement et contenu utile. L’état actuel est déduit du dernier événement et non stocké séparément : c’est ce qui rend la chronologie défendable en cas de litige. |
| task / assignment | Attribution du chauffeur et du véhicule avec ordre des arrêts, ainsi qu’historique des réattributions lorsqu’une tâche est transférée. |
| pod_asset | Preuve de livraison : clés des photos et signatures, horodatage de la capture et emplacement de l’appareil, conservés comme éléments justificatifs de la facturation. |
| charge / invoice | Lignes de frais générées à partir de règles appliquées aux événements enregistrés, chacune contenant l’identifiant de l’événement qui la justifie. Par conception, toute ligne de facture dépourvue d’un événement traçable est rejetée. |
| rate_card | Règles tarifaires propres au client selon le poids, le volume, la distance, le temps d’attente et les majorations, versionnées afin que les factures historiques reproduisent toujours leurs montants d’origine. |
Interfaces clés
Points de terminaison qui portent les règles métier
| Point de terminaison | Objectif et remarques sur la concurrence |
|---|---|
| POST /api/v1/consignments | Saisie de la commande avec géocodage de l’adresse et résolution de la grille tarifaire au moment de la création, afin que la base tarifaire soit fixée avant l’exécution de la tâche. |
| POST /api/v1/events/batch | Envoi groupé d’événements depuis l’application chauffeur après une interruption de connectivité. Déduplication à partir d’un UUID d’événement client, avec stockage séparé de l’heure de capture et de l’heure de réception afin de préserver l’exactitude de la chronologie. |
| POST /api/v1/tasks/{id}/pod | Envoie la signature et les photos avec l’horodatage de capture, puis renvoie les clés de stockage associées à l’envoi. |
| POST /api/v1/billing/run | Génère les lignes de frais à partir des événements d’une période. Idempotent par (client, période), afin qu’une nouvelle exécution corrige les données au lieu de créer des doublons. |
| GET /api/v1/track/{no} | Suivi public mis en cache, exposant uniquement le sous-ensemble d’événements visible par le client. |
Décisions techniques
- Les événements comme source de vérité, l’état comme valeur dérivée. Une colonne d’état modifiable perd l’historique dont dépend la gestion des litiges. Déduire l’état coûte une jointure, mais fournit une piste d’audit complète et défendable.
- Stockage séparé de l’heure de capture et de l’heure de réception. Le scan effectué par un chauffeur à 14:02 et envoyé à 17:30 doit apparaître à 14:02, avec un délai d’envoi connu ; sinon chaque zone hors ligne produit une chronologie erronée.
- UUID d’événements générés par le client. Les nouvelles tentatives d’envoi sont normales sur les connexions médiocres ; la déduplication doit donc s’appuyer sur un identifiant détenu par le client.
- Grilles tarifaires versionnées plutôt que modifiées. Une modification de prix ne doit pas réécrire silencieusement les factures du mois dernier ; les anciennes versions sont donc conservées et les frais historiques continuent de les référencer.
- Facturation générée mais non émise automatiquement. Les règles couvrent les cas calculables ; tout ce qui nécessite un jugement humain est placé dans une file de contrôle plutôt que forcé dans l’automatisation.
Objectifs de conception hypothétiques
Les chiffres ci-dessous sont des exemples hypothétiques de planification de capacité, et non des résultats client mesurés, une recommandation de dimensionnement validée ou un SLA. Définissez les objectifs d’acceptation propres au projet après avoir précisé la charge de travail, les appareils, les données, le matériel et les dépendances tierces ; vérifiez-les au moyen d’un pilote et de tests de charge avant de vous engager sur un objectif de production.
Objectifs de capacité et de performance
| Objectif | Valeur et hypothèse |
|---|---|
| Ingestion des événements | Lots d’au plus quelques centaines d’événements par envoi, dédupliqués, dimensionnés pour un chauffeur revenant après plusieurs heures hors ligne. |
| Tableau de répartition | Affiche l’ensemble de travail actif en moins de 1 seconde, avec filtrage et pagination côté serveur plutôt que le chargement de toutes les données dans le navigateur. |
| Exécution de la facturation | Un mois d’événements pour un client est traité comme une tâche en arrière-plan avec indication de la progression ; la durée varie selon le volume d’événements et est mesurée sur vos données réelles pendant la recette. |
| Envoi des photos | Compresser et mettre en file localement avant l’envoi, effectuer une nouvelle tentative en cas d’échec, puis vérifier la conservation, l’accusé de réception et la récupération sur les appareils réels. |
Ce que comprend la livraison
- Code source de l’application web des opérations, du backend Go, de l’application chauffeur Android et du mini-programme
- Schéma de base de données documentant les tables d’événements et de règlement, ainsi que l’historique des migrations
- Documentation de l’API, y compris le contrat d’envoi hors ligne et de déduplication
- Notes de déploiement, configuration du stockage d’objets, procédure de sauvegarde et de restauration
- Plan de migration des données depuis les feuilles de calcul existantes, avec rapport de rapprochement après importation
Planifier ce projet pour votre entreprise
Les modules ci-dessus constituent un point de départ et non un package fixe. Nous limitons généralement la première version à un flux métier principal et un flux d’administration, puis nous l’étendons lorsque l’utilisation réelle montre où se situent effectivement la charge et les cas limites. Envoyez un brief précisant le périmètre et nous le comparerons à cette architecture afin de vous indiquer les éléments dont vous n’avez pas encore besoin.
