Missions occasionnelles¶
Une commande regroupe les informations client, contact, message et catégorie. Elle contient un aller et éventuellement un retour, chacun avec ses horaires et ses affectations. Les adresses, le véhicule et le conducteur sont facultatifs. Ces routes nécessitent l'option Missions occasionnelles du réseau ; opérateurs et régulateurs peuvent écrire, les lecteurs peuvent consulter. Le périmètre des équipes autorisées s'applique aux commandes et aux trajets.
Opérations¶
Horaires et validation¶
Les heures portent un décalage UTC explicite. Les dates des listes (start_date, end_date, incluses) et la validation du jour de départ utilisent le fuseau du réseau. Une nouvelle date de départ ne peut être passée. L'arrivée doit suivre le départ et tomber au plus le lendemain dans ce fuseau. Le retour ne peut commencer avant l'arrivée de l'aller.
La proposition de retour inverse les adresses, reprend les affectations et ajoute trois heures écoulées à l'arrivée aller. Sa durée est celle de l'aller. Les calculs utilisent les instants UTC, y compris lors des changements d'heure ; l'affichage utilise le fuseau du réseau.
Un refus métier répond 422 avec detail.code, detail.message et, lorsqu'il est connu, detail.field (chemin de champ du payload). Les validations de structure répondent avec la liste Pydantic detail[] et ses loc. Les messages obligatoires incluent « Donnez un nom à la mission. », « Indiquez qui commande le transport. » et « L'arrivée doit tomber au plus le lendemain du départ. ». Le nombre de passagers est un entier supérieur ou égal à zéro.
Édition, annulation et duplication¶
Après le départ réel, seuls les champs partagés contact, téléphone, message et catégorie restent modifiables dans ces routes de gestion. Une annulation est définitive et impossible dès le départ prévu. Un retour annulé reste dans l'historique ; un nouveau retour reçoit une nouvelle identité. Le PUT ne crée ni ne réactive de trajet.
La duplication conserve uniquement les trajets non annulés, avec de nouvelles identités et sans reprendre les faits d'exécution, affectations ou lien de suivi. Si l'aller est annulé, le retour restant devient l'aller de la copie. planned_departure_at fixe le nouveau premier départ. Les overrides optionnels permettent d'enregistrer le formulaire entièrement modifié en une demande ; le premier départ doit correspondre à cette date. Les affectations expressément saisies et le nouveau brouillon de lien expressément demandé sont des créations neuves. Quand tous les trajets sont annulés, une date seule ne suffit pas : un formulaire entièrement ressaisi est nécessaire.
Catégories, clients et conflits¶
Les six catégories initiales sont Scolaire, Mariage, Entreprise, Événementiel, Sport et Tourisme. Elles sont créées au premier accès aux catégories du réseau, avec une couleur chacune : blue, yellow, orange, purple, green et teal, dans cet ordre. Ces couleurs restent modifiables. Un réseau dont les catégories existent déjà n'est pas modifié, et une catégorie initiale supprimée n'est pas recréée. Une catégorie utilisée est archivée pour préserver l'historique ; une catégorie inutilisée est supprimée définitivement.
La recherche client ignore casse, accents et ponctuation. Les conflits utilisent un chevauchement strict des horaires prévus : deux trajets qui se touchent exactement ne se chevauchent pas. Les missions annulées sont exclues. La réponse donne le nom et les horaires de la mission concernée. Un véhicule sans équipement associé expose vehicle_without_license=true.
Actualisation du suivi¶
Après le début de l'approche et jusqu'à la fin du suivi, une modification ou une annulation publie un message WebSocket occasional_mission_updated ou occasional_mission_cancelled avec mission_id et occurred_at. Le consommateur relit les données après réception. L'exécution et les opérations de lien de suivi sont des tranches distinctes ; un brouillon de lien créé par la gestion reste inactif.
Modifications concurrentes¶
Une modification concurrente peut répondre 422 et demander de recharger la commande. Les écritures de gestion d’une commande sont atomiques : une mission ou une référence de catégorie ne reste pas partiellement modifiée après un refus. Le changement d’équipe couvre également les trajets omis et annulés. Après une modification de contact partagé, chaque trajet en cours de suivi reçoit une notification. Un PUT de catégorie supprimée répond 404, y compris si la suppression termine pendant la préparation de la modification ; le PUT ne recrée jamais la catégorie.
Itinéraire prévu et approche¶
La création et la modification des adresses calculent l’itinéraire départ–arrivée côté serveur. Le tracé utilise une polyline de précision 6, une distance en mètres et une durée en secondes. Une distance entered reste prioritaire ; le recalcul ne la remplace pas. Sans deux adresses, aucun appel au moteur n’est effectué. Une panne du moteur conserve l’enregistrement sans tracé ni distance calculée ; le prochain enregistrement réessaie.
GET /api/v4/groups/<group_id>/occasional/missions/<mission_id>/route retourne le tracé enregistré, ou 404 no_route. POST sur la même URL demande un recalcul avant le départ réel ; en cas d’indisponibilité, il répond 503 routing_unavailable, sans annuler les autres données enregistrées.
Driver V6 demande un tracé d’approche distinct via POST /nav-data-processor-api/v5/groups/<group_id>/devices/<device_id>/occasional-missions/<mission_id>/approach-route, avec latitude et longitude. L’appareil doit être celui de la session et porter le conducteur affecté en service, ainsi qu’un véhicule de service ; ce car peut différer du véhicule prévu. Une mission démarrée ou annulée répond 409 ; sans départ géolocalisé, 422 missing_coordinates ; sans route possible, 422 no_route ; moteur indisponible, 503 routing_unavailable. Ce calcul ne modifie aucune donnée de mission.
Exécution Driver V6¶
La liste Driver GET /nav-data-processor-api/v5/groups/<group_id>/devices/<device_id>/occasional-missions?service_date=2026-10-06 renvoie uniquement les missions affectées au conducteur de la tablette. La journée s'étend de 4 h locale à 4 h le lendemain dans le fuseau du réseau, y compris aux changements d'heure. Le détail conserve le contexte client, contact et catégorie. La réponse de liste expose timezone (identifiant IANA du réseau) pour le cache et l’affichage locaux.
Les commandes POST .../<mission_id>/approach, /start, /count, /pause et /end acceptent event_id stable et occurred_at facultatif (réception par défaut). Driver conserve l'horodatage d'origine et l'identité dans sa file persistante sans expiration. /count porte total_on_board, /pause porte paused, /end porte ended_by (manual ou auto). Les mutations renvoient la mission sans le contexte de commande : fusionner les champs d'exécution dans le cache, ou recharger le détail.
curl --request POST "$API/nav-data-processor-api/v5/groups/$GROUP/devices/$DEVICE/occasional-missions/$MISSION/start" \
--header "Authorization: Bearer $TOKEN" --header 'Content-Type: application/json' \
--header 'x-pysae-api-request-id: stable-request-id' \
--data '{"event_id":"stable-event-id","occurred_at":"2026-10-06T08:00:00Z"}'
La session doit appartenir à l'appareil. Le service et l'affectation à l'instant du fait autorisent les événements hors ligne ; rejouer les prises de service avant les missions. Le journal Mongo assure l'idempotence après les 24 h du cache HTTP. Réutiliser une identité pour un autre fait est refusé. Les comptages et pauses arrivés dans le désordre suivent l'instant d'origine. Une fin reçue avant le départ est conservée pour le rejeu ; aucune fin n'est déduite de l'horaire prévu.
Le car du service reste distinct du car prévu. L'écart est historisé ; le car ne peut plus changer après le départ réel. La relève authentifiée par la prise de service sur la même tablette conserve la mission et historise le nouveau conducteur. Un rejeu d'un ancien service ne remplace pas la mission du service courant. Le départ libère la course régulière et rattache les positions à occasional_mission_id, même sans GTFS. La distance réalisée est GPS à partir de 80 % de la distance prévue, sinon prévue ; toutes les dates sont sommées et la distance terminée est mise à jour atomiquement avec les kilomètres si des positions arrivent ensuite.
GET /api/v4/groups/<group_id>/occasional/missions/<mission_id>/history expose les faits, les affectations et positions (coordonnées et heures GPS/réception), y compris un départ refusé sur une mission annulée. order_events y ajoute les actions faites sur la commande, communes à l'aller et au retour : order_created, link_created, link_activated, link_deactivated, link_code_regenerated, link_protection_enabled et link_protection_removed. Chacune porte user_id et user_email (l'adresse du compte au moment de l'action, comme dans le journal d'audit) ; ces deux champs sont nuls pour une commande créée avant leur enregistrement. La commande expose aussi son auteur dans created_by. La messagerie conducteur accepte kind: "occasional_mission_not_found" ; omettre kind conserve le comportement existant.
Avant prise de service, la liste accepte driver_id et le code dans l’en-tête X-Driver-Code, validés comme au check-in. Sans ces paramètres, elle utilise le conducteur du service courant. Les missions annulées restent visibles. La mission active reste dans la liste après relève, même hors journée planifiée.
Les positions retardées sont attribuées au service et à l’affectation historiques à leur heure GPS. Avant le départ, elles exigent un fait d’approche explicite avec le même appareil, service, conducteur et véhicule. Chaque sélection ou reprise émet un nouveau fait : le plus récent à l’heure GPS choisit la mission ; une égalité entre missions est refusée. La mission commerciale active reste prioritaire. Un départ ferme les anciens focus d’approche ; après la fin, une nouvelle sélection d’approche est nécessaire. Le premier horaire d’approche reste inchangé. Aucun kilomètre d’approche ni segment traversant le départ réel ne contribue à la distance commerciale. Elles restent lisibles dans history.positions après la fin ; leur réception ne déplace pas une tablette désormais sur un autre service. Le journal déduplique par appareil et heure GPS, sans TTL. Les kilomètres sont recalculés entre positions chronologiquement voisines, avec les gardes GPS existantes ; le delta client n’identifie pas son prédécesseur et n’est donc pas utilisé pour ces insertions hors ordre. Une position sans preuve historique n’est pas rattachée à la mission actuellement affichée.
La relève existante est en ligne : Driver acquitte sa file de faits de mission avant de changer de conducteur. Le départ et la fin n’ont plus à être acquittés avant le backlog GPS : à leur réception, les positions déjà reçues sont réattribuées au départ et à la fin réels, la distance de la mission est recalculée et les positions postérieures à la fin rejoignent le kilométrage régulier du véhicule. Le fait d’approche doit toujours parvenir à l’API avant les positions d’approche. Un fait déjà connu peut être rejoué sans relire le service ; un nouveau fait tardif exige que le service historique et l’affectation soient encore disponibles. Aucun délai maximal supplémentaire n’est appliqué.
Le champ privé history.current_message_recipient vaut {device_id, duty_id, driver_id} (trois chaînes) ou null. Il désigne uniquement le conducteur actuellement en service : mission non terminée/non annulée, un seul appareil non archivé portant la mission, un seul service ouvert commencé sur cet appareil, identifiant du service égal au pointeur courant et conducteur renseigné identique à celui de l’appareil. Toute ambiguïté renvoie null. Le conducteur planifié et les anciens conducteurs ne servent jamais de repli ; une relève valide donne le nouveau conducteur. Le suivi public ne contient pas ce champ.
Op rafraîchit cet historique avant ouverture et avant envoi du message. Il rend le bouton indisponible sans destinataire certain et ferme la saisie si l’identité appareil/service/conducteur change ou si le rafraîchissement échoue. Cette lecture décrit un état courant ; elle ne réserve pas le service. La messagerie existante conserve un délai réseau résiduel entre vérification et envoi, sans garantie d’atomicité avec une relève.
Appareils en mission¶
GET /api/v2/groups/<group_id>/devices et GET /api/v2/groups/<group_id>/devices/<device_id> exposent deux identifiants de mission, pour un réseau qui a la feature et le flag des missions occasionnelles (sinon absents) :
approaching_occasional_mission: mission dont l’appareil a déclaré l’approche. Il est retiré au départ, à l’annulation de la mission, quand elle est replanifiée pour un autre conducteur et à tout changement de service sur l’appareil. Il ne change nidrive_modeni les kilomètres.current_occasional_mission: mission en cours, du départ à la fin, avecdrive_modeàoccasional.
Chaque pose ou retrait arrive dans le flux d’événements d’appareil sous le même nom de champ : occasional_mission_approach (identifiant ou null), occasional_mission_start, occasional_mission_end, et duty_check_in / duty_check_out quand ils mettent fin à une approche.
Lien et page de suivi¶
Le GET /orders/<order_id>/link rend l’adresse, l’activation et la présence d’un code. Le POST crée un brouillon ; /activate conserve son adresse, /regenerate remplace le code (ou retire la protection), et /deactivate invalide l’ancienne adresse et crée un nouveau brouillon. Seuls création et régénération rendent le code en clair, une seule fois. Le GET /link/preview utilise les droits Op et les équipes du lecteur, sans saisir le code et sans compter une consultation. La liste et le détail des commandes résument le lien courant dans link : {"active": …, "protected": …}, ou null si aucun lien n’a été créé. Ce résumé ne contient ni l’adresse ni le code.
La page utilise GET /api/v4/occasional-tracking/<token>. Un token inconnu ou un réseau non habilité répond 404. Les états draft, invalid et code_required ne portent aucune donnée de trajet : seulement group_name et group_logo_url (nullable), pour que le voyageur sache quel réseau lui envoie le lien, y compris quand il est désactivé ou expiré. Les états ouverts schedule, live, arrived contiennent le programme et les informations disponibles. POST /code accepte les six chiffres et rend un grant valable au plus quinze jours, envoyé ensuite exclusivement dans Authorization. Il est invalidé par remplacement du code, désactivation ou expiration. Cinq échecs sur une même IP bloquent quinze minutes ; cinquante sur le lien bloquent une heure. Le 429 donne detail.retry_at.
Le temps réel s’ouvre une heure avant le départ et suit la fin réelle ; un trajet en cours prime sur une autre fenêtre ouverte. L’expiration se recalcule sur les trajets non annulés : dernière arrivée + 2 h, ou arrivée prévue + 4 h pour un trajet démarré sans fin. Cette borne publique reste prioritaire même pour un départ très tardif ; elle ne clôture jamais le suivi Op. Une position vieille d’au moins dix minutes reste affichable avec son horodatage et stale=true, sans ETA.
record_opening=true est réservé au premier chargement réussi ; les polls gardent sa valeur par défaut false. Les robots connus et l’aperçu Op ne sont pas comptés. Le journal ne contient ni IP ni identifiant de visiteur. L’avis RGPD de la page reste à finaliser avant activation.