Documentation Index
Fetch the complete documentation index at: https://docs.colismove.com/llms.txt
Use this file to discover all available pages before exploring further.
Cinq scénarios couvrent les preuves de bonne exécution : expiration automatique des annonces, photos PackSentry obligatoires, traçabilité GPS, et résilience upload S3.
Sc 18 — Annonce expirée (sans booking)
Une annonce dont la date de départ est dépassée et qui n’a aucune réservation associée est nettoyée automatiquement par deux schedulers complémentaires.
Logique
AnnonceExpirationScheduler à 02:30 → flag EXPIRED les annonces sans booking et dateDepart < nowExpiredAnnouncementHandler à 03:00 → exclut de la recherche + notifie le carrier- Si annonce a au moins 1 booking → reste visible jusqu’à fin du cycle booking (ne pas casser une réservation en cours)
Tests
Tests d’intégration scheduler en CI continue.
Sc 21 — Photo AVANT_DEPOT manquante (gate booking)
Le sender ne peut pas générer le QR de dépôt s’il n’a pas uploadé la photo AVANT_DEPOT obligatoire (preuve de l’état du colis avant remise).
Module colismove-packsentry
Hexagonal pur (74 fichiers, 11 use cases). Adapter ImageIOWatermarkAdapter ajoute watermark date/heure/booking-id, puis upload via S3PhotoStorageAdapter.
Endpoint
POST /v1/api/photos
Content-Type: multipart/form-data
file: <binary>
bookingId: 1234
type: AVANT_DEPOT
Sc 22 — Photo DEPOT manquante (gate confirmerDepot)
Au moment du scan QR de dépôt par le carrier, le sender doit avoir uploadé une photo DEPOT (preuve de remise effective). Sans elle, la transition ACCEPTEE → EN_COURS_DE_LIVRAISON est bloquée.
Gates PackSentry
| Gate | Quand | Photos requises |
|---|
confirmerDepot | Scan QR dépôt | AVANT_DEPOT + DEPOT |
confirmerLivraison | Scan QR livraison | LIVRAISON (recipient) |
Particularités
- Watermark non-répudiation : date, heure, booking-id, GPS coords
- Stockage S3 avec URL signée 24h pour preuve litige
- Rétention conforme RGPD : suppression auto J+90 si pas de litige ouvert
Sc 23 — GPS désactivé sur dépôt
Au scan QR dépôt, le statut GPS du téléphone est capturé. Trois états distincts pour gérer la non-répudiation sans bloquer si la précision est dégradée.
Migration domain
V19 a ajouté la colonne gps_status enum (OK, MISSING, INCOHERENT) sur booking_qr_scan.
Logique non-bloquante
- Le GPS désactivé ne bloque pas le scan QR (évite friction utilisateur)
- Mais le statut est persisté → si litige ultérieur, l’admin a la trace
INCOHERENT = précision GPS > 500m OU coords loin du point de RDV de l’annonce
Référence : commit 3697fe8
Sc 24 — Échec upload S3 (résilience PackSentry)
Le réseau échoue pendant l’upload de la photo vers S3. Le système retry automatiquement, et bascule en dead-letter si tous les retries échouent.
Configuration
MAX_ATTEMPTS = 3 avec backoff exponentiel (200ms, 400ms, 800ms)- Dead-letter persistée en table
photo_upload_failures pour replay manuel
- Micrometer counter
packsentry.s3.upload.failures (alerte ops si > 5/min)
Frontend mobile
- En cas de 502 → re-show bouton “Réessayer”
- Photos en attente stockées localement (queue Flutter) → upload différé quand réseau revient
Status
- Dead-letter table + counter Micrometer : Pending (sprint S2 PackSentry-Lean)
Récap modules impactés
| Scénario | Module backend | Schedulers / Gates |
|---|
| Sc 18 | colismove-annonces | AnnonceExpirationScheduler 02:30, ExpiredAnnouncementHandler 03:00 |
| Sc 21 | colismove-packsentry | Gate génération QR dépôt |
| Sc 22 | colismove-packsentry | Gate confirmerDepot |
| Sc 23 | colismove-reservation + colismove-packsentry | Capture GPS au scan QR |
| Sc 24 | colismove-packsentry | Adapter résilient S3 |
Codes d’erreur
| Code | HTTP | Scénario |
|---|
PHOTO_AVANT_DEPOT_MANQUANTE | 422 | Sc 21 |
PHOTO_DEPOT_MANQUANTE | 422 | Sc 22 |
S3_UPLOAD_FAILED | 502 | Sc 24 |
