Architecture et contrats

ComposantsCopier le lien du titre

• FastAPI et PostgreSQL : comptes, sources, tâches et plans appartenant à une entreprise.
• Worker de la même image : exécution des calculs et récupération des tâches.
• Valhalla : matrices dirigées et géométrie des routes sur un graphe OSM.
• VROOM : optimisation utilisant les matrices fournies.
• React et MapLibre : espace de planification de l’application.

La validation indépendante contrôle notamment couverture, horaires, charges, équipements, limites, géométrie et coûts modélisés. Une proposition du solveur n’est pas une preuve de validité. La marge de sécurité de l’entreprise ne réduit que les créneaux transmis au solveur ; la validation contrôle les vrais créneaux.

Parcours d’un calculCopier le lien du titre

1. Le navigateur transmet les enregistrements sélectionnés et les paramètres à FastAPI.
2. L’API vérifie la session, l’entreprise et la demande, puis enregistre une tâche dans PostgreSQL.
3. Le worker récupère la tâche et demande à Valhalla les temps et distances de trajet dirigés.
4. VROOM propose une affectation aux véhicules et un ordre d’arrêts. Le worker obtient les trajets détaillés auprès de Valhalla.
5. La validation indépendante compare le résultat aux données copiées. Le worker enregistre le résultat ou l’échec ; l’interface lit l’état de la tâche.
6. Un résultat réussi reste un brouillon. L’utilisateur le vérifie avant approbation, export CSV et feuilles de route.

L’API et le worker utilisent la même image applicative, mais s’exécutent séparément. PostgreSQL conserve les données ; les tuiles cartographiques servent uniquement de fond visuel.

Retrouver un résultat dans l’interfaceCopier le lien du titre

Chaque plan indique comment il a été calculé : objectif, préférence routière, marge de sécurité, version du plan et données routières, et précise que les péages et le coût total complet ne sont pas calculés. Calculs récents liste chaque tentative de la journée par son heure et son état ; le pointeur posé sur l’une d’elles affiche son identifiant de tâche complet, que les journaux du worker enregistrent sous la forme job_id=.

1. 0:00Détails du calculL’objectif, la préférence routière, la version du plan et les données routières utilisées.
2. 0:02Calculs récentsChaque tentative avec son état et son identifiant, à rapprocher des journaux du serveur.

ContratsCopier le lien du titre

Les formulaires présentent des unités lisibles ; les API utilisent les unités indiquées dans les schémas générés. Gardez modèles, migrations, contrats, exemples et tests cohérents. Les champs non pris en charge doivent être rejetés ou implémentés explicitement. scripts/export_contracts.py génère le contrat OpenAPI, les schémas JSON, les limites de formulaire appliquées par l’interface, les colonnes d’import CSV affichées par l’écran d’import et son modèle (web/src/csv-columns.json) et la liste des messages serveur à traduire en français ; son mode --check échoue en cas d’écart.

Les plans sont des brouillons modifiables avec protection par numéro de version. Les routes manuelles recalculent les trajets demandés sans relancer l’optimisation de toutes les affectations.

Couverture des essaisCopier le lien du titre

Les benchmarks routiers couvrent des cas fictifs Paris/Île-de-France, dont 250 livraisons. Cela ne prouve ni l’optimalité, ni l’acceptation longue distance, ni une capacité multi-entreprises. Les scénarios et commandes reproductibles sont fournis dans les guides techniques du kit.

L’intégration continue (.github/workflows/ci.yml) s’exécute à chaque modification : analyse du code Python, tests du backend et des lanceurs avec des bases PostgreSQL isolées, contrôle d’écart des contrats, mise en forme, analyse, tests, types d’API générés et construction de l’interface, contrôles de supervision des processus Linux sur les images construites, surcouche HTTPS (TLS, cookies, CSRF, en-têtes, masquage des journaux), et droits des rôles avec sauvegarde et restauration isolée sur une base Compose jetable. Un flux distinct (engines.yml), lancé à la demande et chaque semaine, télécharge l’extrait Île-de-France courant, construit les graphes et exécute les suites du moteur réel et du worker.