Statuts des colis

Un colis sur Swaloo suit un cycle de vie en 8 statuts. En interne, chaque colis est compose de taches (collecte, livraison, transfert, rescue) qui suivent leur propre machine a etats a 11 statuts. Le statut du colis est derive automatiquement de la progression de ses taches.

Statuts du colis (Shipment)

Cycle de vie principal

Ces statuts representent la progression normale d'un colis du depot au destinataire :

Statut	Code	Couleur	Description
En attente d'approbation	`pending_approval`	Gris	Le colis a ete soumis via le portail marchand ou le formulaire public. Il attend la validation d'un operateur avant d'etre pris en charge.
En attente	`pending`	Gris	Le colis est confirme et attend sa premiere action (assignation a un chauffeur, collecte, ou depart en livraison). C'est le statut par defaut a la creation.
Ramassage en cours	`pickup_in_progress`	Bleu info	Un chauffeur est en route vers le point de collecte pour recuperer le colis.
Recupere	`picked_up`	Cyan	Le colis a ete recupere par un chauffeur au point de collecte. Il est en possession du transporteur mais pas encore en livraison.
En route	`in_transit`	Bleu	Le colis est en cours d'acheminement vers le destinataire.
Livre	`delivered`	Vert	Le colis a ete remis avec succes au destinataire. Statut terminal.

Statuts exceptionnels

Statut	Code	Couleur	Description
Retour	`returned`	Orange	Le colis a ete retourne a l'expediteur apres un echec definitif de livraison. Voir Retours. Statut terminal.
Annule	`cancelled`	Rouge	L'expedition a ete annulee, avant ou pendant l'operation. Statut terminal.

Enchainement typique

pending_approval ──(approuver)──> pending
                                     │
            ┌────────────────────────┤
            │                        │
    (avec collecte)          (sans collecte)
            │                        │
            v                        │
   pickup_in_progress                │
            │                        │
            v                        │
        picked_up                    │
            │                        │
            v                        v
       in_transit ──────────> in_transit
                                     │
                                     v
                                 delivered

Les statuts terminaux (delivered, returned, cancelled) mettent fin au cycle de vie : aucune modification n'est possible apres.

Statuts des taches (Task)

Chaque colis genere une ou plusieurs taches : collecte (pickup), livraison (delivery), transfert (transfer), rescue, etc. Chaque tache suit sa propre machine a etats, plus fine que celle du colis.

Statut	Code	Couleur	Description
En attente du ramassage	`waiting_for_pickup`	Gris	La tache de livraison attend que le colis soit d'abord recupere via une tache de collecte ou un transfert depot.
Pre-assignee (en attente)	`assigned_waiting`	Indigo	Un chauffeur est pre-assigne a la tache, mais elle attend encore la collecte du colis avant de devenir active.
En attente	`pending`	Gris	La tache est prete a etre prise en charge. Elle peut etre assignee a un chauffeur.
Assignee	`assigned`	Bleu	La tache est assignee a un chauffeur. Il peut demarrer l'approche.
En route (collecte)	`pickup_in_progress`	Bleu ciel	Le chauffeur est en route vers le point de collecte.
Recuperee	`picked_up`	Violet	Le chauffeur a recupere le colis. Il peut maintenant demarrer la livraison.
En route (livraison)	`delivery_in_progress`	Violet	Le chauffeur est en route vers le destinataire.
En livraison	`in_transit`	Orange	Le colis est en cours de livraison active.
Livree	`delivered`	Vert	La tache est terminee avec succes. Statut terminal.
Echec	`failed`	Rouge	La tache a echoue (destinataire absent, adresse incorrecte, refus, etc.). Le dispatcher peut retenter ou creer une tache rescue. Statut terminal.
Annulee	`cancelled`	Rouge	La tache a ete annulee par un dispatcher. Statut terminal.

Transitions des taches

Les transitions sont contrôlees par le moteur de workflow Symfony. Certaines sont reservees a des roles specifiques.

Assignation

Transition	De	Vers	Role requis
`assign`	`pending`	`assigned`	Dispatcher
`claim`	`pending`	`assigned`	Chauffeur (marketplace uniquement)
`assign_waiting`	`waiting_for_pickup`	`assigned_waiting`	Dispatcher
`unassign`	`assigned`	`pending`	Dispatcher
`unassign_waiting`	`assigned_waiting`	`waiting_for_pickup`	Dispatcher

Collecte

Transition	De	Vers	Role requis
`start_approach`	`pending`, `assigned`	`pickup_in_progress`	Chauffeur
`pick_up`	`pending`, `assigned`, `pickup_in_progress`	`picked_up`	Chauffeur
`unlock_delivery`	`waiting_for_pickup`	`pending`	Systeme
`unlock_delivery_assigned`	`assigned_waiting`	`assigned`	Systeme

Livraison

Transition	De	Vers	Role requis
`start_delivery`	`pending`, `assigned`	`in_transit`	Chauffeur ou Dispatcher
`start_transit`	`picked_up`	`in_transit`	Chauffeur
`start_delivery_approach`	`picked_up`	`delivery_in_progress`	Chauffeur
`deliver`	`in_transit`, `delivery_in_progress`	`delivered`	Chauffeur

Echec et reprise

Transition	De	Vers	Role requis
`fail_pickup`	`pickup_in_progress`, `picked_up`	`failed`	Chauffeur ou Dispatcher
`fail_transit`	`in_transit`, `delivery_in_progress`	`failed`	Chauffeur ou Dispatcher
`retry`	`failed`	`pending`	Dispatcher

Annulation

Transition	De	Vers	Role requis
`cancel_pending`	`pending`	`cancelled`	Dispatcher
`cancel_waiting`	`waiting_for_pickup`	`cancelled`	Dispatcher
`cancel_assigned`	`assigned`, `assigned_waiting`	`cancelled`	Dispatcher
`cancel_approaching`	`pickup_in_progress`	`cancelled`	Dispatcher
`cancel_delivering`	`delivery_in_progress`	`cancelled`	Dispatcher
`cancel_in_transit`	`in_transit`	`cancelled`	Dispatcher

Relation entre taches et statut du colis

Le statut du colis est derive automatiquement de la progression de ses taches :

Evenement sur la tache	Statut du colis
Tache de collecte passe en `pickup_in_progress`	`pickup_in_progress`
Tache de collecte passe en `picked_up`	`picked_up`
Tache de livraison passe en `in_transit` ou `delivery_in_progress`	`in_transit`
Tache de livraison passe en `delivered`	`delivered`
Toutes les taches annulees	`cancelled`
Retour au depot apres echec definitif	`returned`

Evenements du colis

Chaque changement de statut ou action importante genere un evenement dans l'historique du colis :

Evenement	Code	Description
Colis cree	`shipment_created`	Le colis a ete cree
Statut modifie	`status_changed`	Le statut du colis a change
Collecte terminee	`task_pickup_completed`	La tache de collecte est terminee
Livraison terminee	`task_delivery_completed`	La tache de livraison est terminee
Tache echouee	`task_failed`	Une tache a echoue
Reprise incident	`incident_recovery`	Reprise apres un incident
Rescue cree	`rescue_created`	Une tache rescue a ete creee pour retenter la livraison
Chauffeur assigne	`driver_assigned`	Un chauffeur a ete assigne a une tache
Livraison deverrouillee	`delivery_unlocked`	La tache de livraison a ete deverrouillee apres la collecte
Transfert cree	`transfer_created`	Un transfert entre depots a ete cree
Colis depose	`package_deposited`	Le colis a ete depose dans un depot
Colis collecte	`package_collected`	Le colis a ete collecte depuis un depot
Collecte groupee creee	`grouped_pickup_created`	Le colis a ete ajoute a une collecte groupee
Retire de la collecte groupee	`removed_from_grouped_pickup`	Le colis a ete retire d'une collecte groupee
Modifie par le marchand	`shipment_updated_by_merchant`	Le marchand a modifie les informations du colis
Tournee creee	`delivery_run_created`	Une tournee de livraison a ete creee
Ajoute a la tournee	`delivery_run_task_added`	La tache a ete ajoutee a une tournee
Retire de la tournee	`delivery_run_task_removed`	La tache a ete retiree d'une tournee
Ejecte de la tournee	`delivery_run_task_ejected`	La tache a ete ejectee d'une tournee
Commentaire	`comment`	Un commentaire a ete ajoute
Systeme	`system`	Evenement systeme automatique

Notifications

Chaque changement de statut declenche :

Une mise a jour en temps reel via Mercure (WebSocket/SSE)
Un email de notification (si configure)
Un evenement webhook (si configure)

Voir aussi : Gestion des colis | Creer une expedition

Statuts des colis

On this page