🚚 VROOM ! — Spécifications Techniques

📋 Table des matières

• 1. Architecture générale
• 2. Stack technique
• 3. Fichiers du projet
• 4. Base de données (Supabase)
• 5. FDW & Synchronisation
• 6. vr-database.js — Module DB
• 7. vr-app.js — Application principale
• 8. Zones de livraison
• 9. Gestion des tournées
• 10. Système de livraison
• 11. Gestion des camions
• 12. GPS & Carte
• 13. Commentaires & Mentions
• 14. Labels & Priorités
• 15. vr-history.js — Module historique
• 16. Authentification & Rôles
• 17. Flux de données
• 18. Constantes & Configuration
• 19. Cron Jobs
• 20. Anomalies & Maintenance
• 21. Historique des corrections
• 22. Page livraison autonome
• 23. Colis par client (livraison partielle)
• 24. Panneau clients spéciaux
• 25. Cohérence 3 tables tournées

VROOM est une application web de gestion logistique pour les livraisons de colis en Guadeloupe. Elle gère le cycle complet : réception en stock → planification des tournées → livraison → historique.

┌─────────────────┐     FDW (next_server)     ┌─────────────────────┐
│  DB Next (prod)  │◄────────────────────────►│   Supabase (Voyey)   │
│  DigitalOcean    │    next_data schema       │   PostgreSQL         │
└─────────────────┘                            │                     │
                                               │  vr_parcels_cache   │
                                               │  vr_tours / v2      │
                                               │  vr_tours_meta      │
                                               │  vr_deliveries      │
                                               │  vr_comments        │
                                               │  vr_client_labels   │
                                               │  vr_gps_corrections │
                                               │  vr_trucks          │
                                               │  vr_truck_history   │
                                               │  vr_agents          │
                                               └──────────┬──────────┘
                                                          │ Supabase JS SDK
                                               ┌──────────▼──────────┐
                                               │   Frontend (Web)     │
                                               │   index.html         │
                                               │   vr-app.js          │
                                               │   vr-database.js     │
                                               │   vr-history.html/js │
                                               └─────────────────────┘
        

Cache local des colis synchronisé depuis la DB Next via FDW. Source de vérité pour l'app VR.

4.1.1 Statuts des colis (whitelist sync)

Serveur FDW

Tables distantes (next_data.*)

logistics_parcel, logistics_shelf, logistics_zone, logistics_city, logistics_transaction, logistics_orderrequest, logistics_parcelimage, userzone_customer, userzone_customeraddress, userzone_user, payment_payment

Fonction sync_parcels_cache() RPC CRON multi-paliers

Appelée par sync_parcels_full_safe() via pg_cron job sync-parcels-full-15min (5,20,35,50 * * * *, timeout 600s). Sync incrémentale légère en complément via sync_parcels_light() (*/5). Voir §19.

Fonction sync_parcel_images() RPC

Met à jour la colonne images (JSONB) depuis next_data.logistics_parcelimage. Appel manuel.

Module IIFE VR_Database. Couche d'abstraction Supabase. Toutes les fonctions sont asynchrones sauf init(), isTruckShelf() et convertToClients().

Connexion

Colis & Clients

Tournées

Commentaires

Labels, GPS, Livraisons, Agents

Camions

Constantes exportées

ZONES_LIVRAISON = ['B/T-Z1', 'B/T-Z2', 'B/T-Z3', 'G/T-Z1', 'G/T-Z2', 'G/T-Z3']
ZONES_RETRAIT   = ['Point relais Jarry']
TRUCK_SHELF_MIN = 800
TRUCK_SHELF_MAX = 899

Module IIFE. 12 000+ lignes. Gère toutes les vues, interactions, filtres et persistance.

Fonctions utilitaires critiques

Onglets principaux (10 vues)

État interne principal

parcels[]       // Colis bruts depuis vr_parcels_cache
clients[]       // Clients groupés (output de convertToClients)
stats{}         // Statistiques agrégées du cache
tours{}         // {tourNum: [clientIds]} — assignations locales
toursMeta{}     // {tourKey: {id, status, date, agent, schedule, report, tracking}}
tourIdCache{}   // {tourNum: UUID} — mapping vers vr_tours_v2
agents[]        // Liste agents/livreurs
currentTour     // Tournée active sélectionnée
currentUser     // {id, email, name, role, sector}
map             // Instance Leaflet
markers[]       // Markers Leaflet sur la carte
clientComments{}// Cache commentaires {email: {count, maxPriority}}
clientLabels{}  // Cache labels {email: {priority}}

Cycle de vie d'une tournée

  draft ──► planned ──► in_progress ──► completed ──► archived
    │                       │
    │                       ▼
    │                    paused ──► in_progress (reprise)
    │
    └── deleted (si vide)
        

Structure d'une tournée (vr_tours_meta)

{
  tour_num: 55,                    // Numéro (55-99+)
  date: '2026-03-24',              // Date planifiée
  status: 'planned',               // Statut courant
  agent: { id, name, email },      // Agent/livreur assigné
  driver_name: 'Melinda',
  vehicle: { type, plate },        // Véhicule
  schedule: {                      // Horaires prévus
    journeyStart, journeyEnd,
    tourStart, tourEnd,
    pauseDuration
  },
  tracking: {                      // Données de suivi temps réel
    startTime, endTime,
    deliveryLogs: [{ clientId, timestamp, status, gps }],
    pauses: [{ start, end, duration }],
    totalPauseTime
  },
  report: {                        // Rapport de fin de tournée
    fuelLevel, coolantOk,
    expenses: [],
    issues, urgentReschedule,
    cancelledClients: [],
    validated: true/false
  }
}

Assignation des clients

Les clients sont assignés par zone, par ville, individuellement ou par transfert depuis une autre tournée. L'ordre peut être modifié par drag & drop. Les données sont persistées dans vr_tours_v2.clients_data (JSONB).

Numérotation

Tournées numérotées de 55 à 99+. Jusqu'à 12 tournées ont des couleurs prédéfinies (voir CSS). Au-delà, couleur calculée par hsl((num * 137) % 360, 70%, 50%).

Statuts de livraison par client

Persistance offline-first

L'état de livraison est sauvé en localStorage à chaque action. En cas de perte réseau, le livreur peut continuer. La synchronisation Supabase est throttled à 2 secondes.

Tracking temps réel

Timer de livraison avec gestion des pauses. Chaque livraison enregistre un log avec timestamp, coordonnées GPS, et durée depuis le client précédent.

Convention étagères

Structure camion

Exemple : Camion de Melinda
  shelf_start: 800, shelf_end: 809
  truck_shelf: 800 (compartiment principal)
  bags_count: 9 (bags 801-809)

  Visualisation grille 3×3 :
  ┌─────┬─────┬─────┐
  │ 801 │ 802 │ 803 │
  ├─────┼─────┼─────┤
  │ 804 │ 805 │ 806 │
  ├─────┼─────┼─────┤
  │ 807 │ 808 │ 809 │
  └─────┴─────┴─────┘
  + Compartiment principal : 800

Les colis sur étagère 800-899 sont exclus du stock actif (sauf si excludeTrucks=false) mais visibles dans l'onglet Camions.

Sources GPS (par ordre de priorité)

Configuration carte

Les clients retrait n'ont PAS de GPS (ils viennent chercher au point relais). Les markers sont colorés par tournée ou par zone selon le mode.

Système de commentaires

Chaque client peut avoir des commentaires avec 3 niveaux de priorité :

Mentions @agent

Taper @ dans un commentaire active l'autocomplétion des noms d'agents (vr_agents). Les mentions créent des notifications (vr_notifications).

Table vr_client_labels. Un label par client (UPSERT sur client_email). Affichage visuel dans la liste clients et la carte.

Page séparée (vr-history.html). Module IIFE VRHistory. Affiche les tournées terminées/archivées.

Sources de données

Filtres disponibles

Période (aujourd'hui / semaine / mois), numéro de tournée, nom d'agent.

Vue détail

Chaque tournée affiche : agent, véhicule, horaires (prévus vs réels), résultats (livrés/absents/reportés/annulés), pauses, chronologie des livraisons, dépenses, notes, export PDF.

Export PDF

Génère un document HTML imprimable (window.open + print) avec tableau complet des livraisons, statistiques et notes.

Flux de connexion

Rôles

Pipeline de chargement principal

init()
  └─► VR_Database.init()
       └─► loadData()
            ├─► getAllParcels()            // vr_parcels_cache (filtre anomalies)
            ├─► convertToClients(parcels)  // Regroupement par email
            ├─► getCacheStats()            // Agrégation zones/transactions
            ├─► applyGPSCorrections()      // vr_gps_corrections
            ├─► loadSavedTours()           // vr_tours (today)
            ├─► loadCommentsIndicators()   // vr_comments stats
            ├─► loadClientLabels()         // vr_client_labels
            └─► Render : Dashboard + Filtres + Grille tournées + Carte

Détermination type client (livraison vs retrait)

Pour chaque colis :
  1. STATUS prioritaire :
     - PRET_RETRAIT / PRET_RECUPERATION → retrait
     - PRET_LIVRAISON / PLANIFICATION_LIVRAISON / PRET_POUR_PLANIFICATION → livraison
  2. Sinon, ZONE :
     - B/T-Z* ou G/T-Z* → livraison
     - "relais" ou "jarry" ou vide → retrait
  3. Fallback : retrait

Pour le client (après regroupement) :
  - Si AU MOINS UN colis livraison → clientType = 'livraison'
  - Sinon → clientType = 'retrait'
  - Retrait : zone = 'Point relais Jarry', GPS = null, adresse = null

Types d'anomalies détectées

Filtrage dans l'app principale

Les colis anomalies (sans étagère, hors PRET_LIVRAISON/PLANIFICATION_LIVRAISON) sont automatiquement exclus de getAllParcels() et getCacheStats(). Ils restent dans vr_parcels_cache et sont accessibles via la page Anomalies.

Historique des corrections (19/03/2026)

Corrections planification tournées (26/03/2026)

Fonctions utilitaires ajoutées / modifiées (26/03/2026)

// Obtenir la date locale au format YYYY-MM-DD (timezone-safe)
getLocalDateStr(date?)
  Input: Date object, string ISO, string YYYY-MM-DD, ou vide (= maintenant)
  Output: string 'YYYY-MM-DD' en heure LOCALE (pas UTC)
  Usage: Remplace new Date().toISOString().split('T')[0] partout (~30 occurrences)

// Formater une date en français (timezone-safe)
formatDateFr(dateStr)
  Input: string date (tout format)
  Output: 'mer. 27 mars' (fr-FR, weekday short + day + month short)
  Logique: Parse YYYY-MM-DD → new Date(y, m-1, d, 12, 0, 0) en LOCAL

// Numéros de tournée disponibles pour une date (indépendants par jour)
getAvailableTourNumbersForDate(dateStr, excludeNum?)
  Propose T1-T20, exclut seulement les numéros déjà utilisés POUR CE JOUR
  Plus de blocage cross-jours (T1 du 26 n'empêche plus T1 du 27)

// Tour ID Cache — isolation par jour (fix 30/03/2026)
getTourCacheKey(tourNum, date?)
  Output: "tourNum-YYYY-MM-DD" (ex: "1-2026-03-31")

getCachedTourId(tourNum, date?)
  Lit tourIdCache[getTourCacheKey(tourNum, date)]

setCachedTourId(tourNum, date, tourId)
  Écrit tourIdCache[getTourCacheKey(tourNum, date)] = tourId

Règles de gestion des numéros de tournée

18/05/2026 — Mise à jour doc (transmission Dannick) + intégration dashboard VIE

19/03/2026 — Chantier FDW & Cache colis

26/03/2026 — Chantier Tournées (dates, numérotation, modals)

30/03/2026 — Chantier tourIdCache (doublons cross-jours)

30/03/2026 — Création et déploiement

Fichiers créés

Architecture vr-delivery.js

VR_Delivery (IIFE)
├── Auth: checkSession(), login(), logout(), _doLogin()
├── Date helpers: getLocalDateStr(), formatDateFr(), formatTime(), formatDuration()
├── Tour loading: loadMyTours() → vr_tours_meta + vr_tours_v2
├── Persistence: saveStateLocal(), loadStateLocal(), clearStateLocal()
│   └── Key: 'vr_delivery_state_v2' (date-validated, full client data)
├── Sync engine: addToSyncQueue(), processSyncQueue(), updateSyncIndicator()
│   ├── Types: delivery, tracking, meta, gps
│   ├── Queue key: 'vr_sync_queue' (localStorage)
│   ├── Retry: exponential backoff [1s, 3s, 10s, 30s, 60s], max 5
│   └── Network: online/offline listeners auto-flush
├── Delivery: selectTour(), markClientStatus(), openDeliveryModal()
├── Timer: toggleTimer(), startTimerTick(), updateTimerDisplay(), updateTimerUI()
│   └── States: not started → running → paused → running → ...
├── GPS: captureGPS() — Guadeloupe bounds, localStorage + sync queue
├── Report: openReportModal(), collectReportData(), saveReportDraft(), validateReport()
├── UI: renderTourSelector(), renderDeliveryList(), updateProgress()
└── beforeunload: force save on exit

Sync Engine — détail

Bugs corrigés pendant le déploiement

Ajouté le 31/03/2026. Permet au livreur de signaler quels colis ont été remis et lesquels ne l'ont pas été chez un même client.

Flux utilisateur

Persistance (3 niveaux)

Schema DB

ALTER TABLE vr_deliveries
  ADD COLUMN parcels_delivered JSONB DEFAULT '[]'::jsonb,
  ADD COLUMN parcels_not_delivered JSONB DEFAULT '[]'::jsonb;

-- Format: ["129280", "123735"]
-- Index pour requêtes sur colis non livrés
CREATE INDEX idx_deliveries_not_delivered
  ON vr_deliveries USING gin(parcels_not_delivered)
  WHERE parcels_not_delivered != '[]'::jsonb;

Rapport de fin de tournée

La section "Colis retour" du rapport affiche 2 catégories :

UI — Modal livraison (stickers)

Enrichissement des téléphones

Les clients_data de vr_tours_v2 ne contiennent pas le champ phone. Au chargement d'une tournée dans vr-delivery.js, les téléphones sont enrichis depuis vr_parcels_cache.client_phone par batch (requête .in('client_email', emails)).

Drag & Drop (réordonnement clients)

Les clients de la tournée peuvent être réordonnés par drag & drop (desktop + touch mobile). La technique utilisée est la même que dans vr-app.js (modale détail tournée) : déplacement DOM direct pendant le dragover/touchmove via insertBefore + getDragAfterElement(). Le nouvel ordre est sauvé en localStorage + sync vers vr_tours_v2.clients_data.

Ajouté le 31/03/2026. Panneau en haut de l'onglet Tournées affichant les clients nécessitant un traitement particulier. Tout fermé par défaut (toggle ▶/▼).

4 catégories

Hors format — logique métier

• Exclus de getStatsByCity() → pas dans les cartes villes/zones
• Alerte confirm() si on tente de les assigner à une tournée via assignToTour()
• Bon de livraison individuel (1 page A4 par client) avec infos VOYEY + client + colis + signatures

Dépendances — îles concernées

• Détection par ville OU code postal (avec variantes d'orthographe : "Grand Bourg" / "Grand-Bourg")
• Exclus de getStatsByCity() → pas dans les cartes villes/zones normales
• Groupés par île dans le panneau (La Désirade, Marie-Galante, Les Saintes)
• Même système de BAL que hors format (modal sélection + impression individuelle)

Bon de Livraison (BAL) — format

┌─────────────────────────────────────────────────┐
│  VOYEY.COM                │  DESTINATAIRE        │
│  372 impasse palétuviers  │  Nom du client       │
│  97122 Baie-Mahault       │  Adresse complète    │
│  [email protected]          │  Tél + Email         │
├─────────────────────────────────────────────────┤
│  🏋️ BON DE LIVRAISON    N° BL-HF-YYYYMMDD-XX   │
├─────────────────────────────────────────────────┤
│  Zone │ Étagères │ Poids total │ Nb colis       │
├─────────────────────────────────────────────────┤
│  # │ Sticker │ Type │ Poids │ Étagère │ Obs     │
│  1 │ 129431  │ B3   │ 45.2kg│ ETG923  │ ⚠️ HF  │
│  2 │ 127102  │ B3   │ 1.7kg │ ETG708  │ —       │
├─────────────────────────────────────────────────┤
│  Signature livreur │ Signature client │ Date    │
└─────────────────────────────────────────────────┘

Normalisation status v2

Performances (optimisation 31/03/2026)

• initDatabase() : loadData(), loadAgents(), loadToursMeta() en parallèle (était séquentiel)
• loadData() : GPS corrections, tournées, agents, commentaires, labels, mentions en parallèle (était séquentiel)
• getCacheStats() : calcul local depuis les données déjà chargées (suppression de la 2e requête SELECT * sur vr_parcels_cache)
• Labels : propagation vers client.label au chargement + mise à jour immédiate sans refresh

Audit et correction du 01/04/2026. Le système de tournées utilise 3 tables qui doivent rester synchronisées.

Les 3 tables

Matrice d'écriture (après correction)

Mapping des status entre tables

Corrections appliquées (01/04/2026)

Règle pour les futurs développements