Crons & chronologie quotidienne

Cette page est la vue temporelle du moteur stock/réappro : quelles tâches planifiées tournent en production, à quelle heure, dans quel ordre, et pourquoi cet ordre est délibéré. Depuis le passage au réappro événementiel, les crons ne portent plus la charge principale — ils sont des filets de sécurité et des passes de consolidation autour d'un flux temps réel. Pour l'échelle au-dessus — comment ces journées s'assemblent en vagues fournisseurs, tournées client et fenêtres de comptage — voir La semaine type.

Inventaire des tâches planifiées

Vérifié sur la box de production (/etc/crontab géré par Ploi + drop-ins /etc/cron.d/) :

Deux précisions sur cet inventaire :

• Le sync commandes a en plus des créneaux ponctuels hebdomadaires posés par Ploi (lundi 10:00–10:30, mercredi 19:45–20:15) — des renforts, pas un rythme différent.
• L'auto-validate a deux entrées qui se recouvrent : la ligne quotidienne 12:01 de /etc/crontab et le drop-in 1 */2 * * * de /etc/cron.d/auto-validate-stock-actions-extra (ajouté avec #2886, quand le cron est passé de moteur primaire à filet). Les deux tirent à 12:01 le même jour. Le chevauchement est neutralisé sur deux plans : dans la tâche, l'idempotence (elle saute les lignes déjà scellées) et un scellé par transaction ; dans le wrapper, un flock qui sérialise les deux passes — le run perdant sort en 0 (un recouvrement attendu n'est pas une alerte). Le verrou ferme la fenêtre TOCTOU que l'idempotence seule laissait ouverte : les deux runs pouvaient lire « pas encore scellé » et sceller tous les deux.

La journée en un coup d'œil

Le rythme de fond (30 min + 3 h) tourne en continu ; les événements uniques du matin (06:00 → 07:15) forment la séquence de consolidation détaillée plus bas ; l'auto-validate balaie toutes les 2 heures avec sa passe canonique à 12:01.

Une journée type en Gantt

Les durées sont illustratives (quelques minutes chacune) — c'est le séquencement qui compte :

gantt
  title Journée type (heures serveur UTC)
  dateFormat HH:mm
  axisFormat %H:%M
  section Sync PrestaShop
    Commandes + produits (passe 06:00) : 06:00, 20m
    Commandes + produits (passe 09:00) : 09:00, 20m
  section Réappro
    Auto-supplier 06:00 : 06:00, 5m
    Auto-supplier 06:30 : 06:30, 5m
    Auto-supplier 07:00 : 07:00, 5m
  section Emails
    Stage des previews (render-only) : milestone, 06:00, 0m
  section Contrôles
    Sonde stock-health (lecture seule) : 06:30, 10m
    Reconcile --apply --removeOrphans : 07:15, 15m
  section Filet stock
    Auto-validate (passe canonique) : 12:01, 10m

Le séquencement du matin — pourquoi cet ordre

La fenêtre 06:00 → 07:15 n'est pas arbitraire. Trois raisons s'emboîtent :

1. Stage (06:00) avant tout le reste. Le stage rend les emails fournisseur dans SupplierOrder.emailPreview et fige une empreinte des items (itemsFingerprint, sha256 des lignes triées). L'opérateur relit ces previews dans la file de review du back-office avant l'envoi. Stager tôt donne à l'opérateur toute la matinée pour relire.
2. Sonde (06:30) après le stage. La sonde est en lecture seule ; elle photographie l'état après le stage et après les passes auto-supplier de 06:00 et 06:30, ce qui rend ses métriques (précision du reconcile, brouillons rétro-datés, autoValidateSealed24h) comparables jour après jour.
3. Reconcile (07:15) en dernier. Le reconcile recalcule l'état attendu des commandes fournisseurs depuis les commandes client et applique le diff. Il tourne après les passes auto-supplier de 06:00 et 06:30 exprès : il attrape la dérive que celles-ci ont manquée, et il est le seul à remplir les commandes fournisseurs des produits non suivis en stock (manageStock=false), que le cron auto-supplier exclut de ses candidats.

Une matinée heure par heure

Pour visualiser la densité de la fenêtre du matin (le rythme 30 min + 3 h autour des événements uniques) :

Sémantique de grâce de l'auto-validate

Les dates deliveryDate / expectedDeliveryDate sont des dates prévues — pas la preuve qu'une livraison a physiquement eu lieu. L'auto-validate ne scelle donc que ce qui est suffisamment ancien pour avoir réellement eu lieu :

Éligibilité côté réceptions : les SupplierOrder SENT/CONFIRMed sans livraison, sur expectedDeliveryDate avec repli sur scheduledSendDate quand elle est absente. Côté livraisons client : les commandes dont les items ne sont pas tous fulfilled. Dans les deux cas le scellé crée les enregistrements réels (SupplierOrderDelivery + SA SUPPLIER_DELIVERY, ou OrderFulfillment + SA DECREMENT) via le même contrat d'écriture que l'UI — voir Chemins d'écriture.

Scénarios concrets

Le marchand corrige un stock à 10:00. L'écriture passe par recordPhysicalMovement (compteur + StockAction dans la même transaction), puis un job supplier-orders-recalc (raison manual-stock) est mis en file avec ~30 s de délai/dédup. Les brouillons fournisseurs du produit sont recalculés dans la minute — pas besoin d'attendre la passe cron de 10:30, qui ne fera que confirmer l'état.

Une commande client arrive à 11:59 vs 12:02. Quasiment aucune différence. Dans les deux cas la file événementielle recalcule le réappro en ~30 s. Et l'auto-validate de 12:01 est indifférent à une commande neuve : sa date de livraison prévue est dans le futur, donc à plus de 12 h de toute éligibilité. La seule chose qui change, c'est quelle passe du filet finira par sceller la livraison si le marchand l'oublie — un décalage d'au plus 2 h vu le sweep 2-horaire.

Une livraison est prévue aujourd'hui à 09:00. Le geste attendu est le scellé au moment physique : le bouton de fulfillment ou « Valider la tournée du jour » dans le back-office. Si personne ne le fait, la ligne devient éligible à 21:00 (09:00 + 12 h de grâce) et la première passe auto-validate suivante — 22:01 — la scelle. Sous l'ancien planning quotidien seul, elle aurait attendu le lendemain 12:01. La métrique autoValidateSealed24h de la sonde compte précisément ces oublis.

Alerting : la réalité des codes de sortie

Le monitoring des crons repose sur le code de sortie du wrapper. Deux pièges historiques se cumulaient — les deux sont désormais fermés :

1. bun run cli --task X sort toujours en 0 sauf si la tâche throw. Une tâche qui signalait l'échec en retournant {success: false} était avalée — le cron « réussissait ». ✅ Les trois tâches-gates (auto-validate, auto-supplier-orders-service, supplier-order-email) throw maintenant : sur échec global, et dès qu'il reste des échecs par item — le throw survient après tout le travail sûr (un item cassé ne bloque pas le balayage, mais le run échoue bruyamment à la fin).
2. Plusieurs wrappers scripts/cron/*.sh n'avaient ni set -e ni exit $EXIT_CODE final : même un vrai code non-zéro était écrasé en 0 avant d'atteindre Ploi. ✅ Les 24 wrappers propagent aujourd'hui leur code de sortie (exit $EXIT_CODE explicite, exec, ou commande finale sous set -e).

Un cron qui échoue sort donc réellement en non-zéro et Ploi alerte. Le pattern correct, à reproduire pour tout nouveau wrapper :

# Bon : exécuter le fichier de tâche directement + propager le code
# (modèle : scripts/cron/supplier-stock-health.sh)
bun packages/scripts/src/tasks/ma-tache.ts "$@"
EXIT_CODE=$?
exit $EXIT_CODE

et côté tâche : throw en cas d'échec (modèle : reconcile-supplier-orders.ts, qui throw sur toute erreur Prisma par item au lieu de l'avaler — c'est ce silence qui avait masqué des semaines de reconcile cassé en 2026-05).

Le contrat est verrouillé par des tests : cron-wrappers.shape.test.ts fait échouer tout wrapper nouveau ou modifié qui avale son code de sortie (il retire les commentaires # d'abord — de la prose à propos des codes de sortie ne peut pas satisfaire l'assertion), et auto-validate-stock-actions.shape.test.ts épingle le contrat de gate.

Le chip « Cron 5 » du back-office

En complément de l'alerting par exit-code, le back-office porte un détecteur de panne silencieuse : la page Stock ledger (/manage/ecommerce/inventory/stock-ledger) affiche un chip qui distingue deux questions délibérément séparées.

1. Liveness (le titre du chip) — le cron a-t-il TOURNÉ ? Lue sur le heartbeat que la tâche estampille dans bext-KV à la fin de chaque run (clé health:auto-validate:{tenantId}:{siteId}, TTL 7 jours ; l'écriture est best-effort — une panne de bext ne fait jamais échouer le run) :

2. Activité (secondaire, « dernière activité ») — le cron a-t-il ÉCRIT ? L'âge de la dernière validation système, par côté (⇣ réception fournisseur / ⇡ livraison client).

Pourquoi cette séparation : la dernière StockAction mesure l'activité, pas la liveness. Une semaine calme n'écrit aucune ligne — l'ancien chip la lisait comme « cron mort » ; et à l'inverse un cron mort juste après une journée chargée s'affichait vert. Le heartbeat répond directement à « a-t-il tourné ? ». Si bext est injoignable (page ouverte hors de la box du tenant), le chip retombe sur l'ancien statut par âge d'activité et le signale dans le popover — jamais un faux « mort ».

C'est la classe de panne rencontrée le 2026-05-26 : un cron qui « tourne » (exit 0) mais ne produit plus rien. Le chip la rend visible sans attendre l'alerting.

Voir aussi

• Vue d'ensemble — le modèle stock/réappro en une page
• Le ledger de stock — autorité signée, backorder, invariants
• Chemins d'écriture — recordPhysicalMovement et le contrat transactionnel
• Commandes fournisseurs — le réappro événementiel et ses gates
• Sync PrestaShop — syncs 3-horaires et webhooks temps réel
• Back-office — les surfaces /manage, dont le chip Cron 5
• Filets de sécurité — audit --strict, replay-diff, sonde quotidienne
• Configuration — les flags (AUTO_VALIDATE_GRACE_HOURS, gates, etc.)