Aller au contenu principal

ADR-0201 : Navin Enterprise Agent Prévision des Ventes et Gestion des Stocks, couche produit retail au-dessus du Control Plane

  • Statut : proposed
  • Date : 2026-11-05
  • Cas d'usage : UC-12 (agent_uses_cases/12_Retail_Prevision_Ventes_Gestion_Stocks.md)
  • Produit : navin-enterprise-retail-previsions-stocks/ (paquet navin_previsions, schéma previsions, API 8484, Redis 6405, web 3485 servi par le shell générique d'ADR-0180)
  • Liens : ADR-0174 (mémoire), ADR-0176 (modules génériques), ADR-0180 (shell frontend), paquet OPA eai.retail_previsions (deploy/policies/opa/retail_previsions.rego), fragment OpenFGA deploy/policies/openfga/products/retail-previsions-stocks.fga, contrats contracts/v1/retail-previsions-stocks-action-request.schema.json et contracts/v1/retail-previsions-stocks-copilot-event.schema.json, gabarit Manager navin-retail-previsions-stocks-agent (non publié).

Contexte​

Un distributeur veut des prévisions par article, magasin et jour ou semaine, des politiques de stock explicites, des propositions de réassort respectant MOQ, colisage, délai, capacité, budget et péremption, et une allocation d'un stock central limité, sans jamais laisser un modèle de langage commander. Le cahier des charges demande de réutiliser le moteur de prévision du Business Analytics Agent ; cet agent n'est pas construit dans le dépôt.

Décision​

  1. Moteur de prévision local derrière l'interface ForecastEngine (navin-enterprise-retail-previsions-stocks/backend/src/navin_previsions/previsions/forecast.py) : méthodes de référence déterministes (naïf, saisonnier naïf, moyennes mobiles 4 et 8, lissage exponentiel simple 0,2 et 0,5), sélection par backtest à origine glissante (WAPE, puis MAE, puis la plus simple), intervalles empiriques issus des résidus du backtest. Python pur et Decimal, aucune dépendance nouvelle. Le moteur du Business Analytics Agent le remplacera en implémentant la même interface, sans changer l'API ni le schéma.
  2. Chaque prévision stocke moteur, méthode et version, fenêtre d'entraînement, horizon, granularité, intervalle, erreurs de backtest et drapeaux de qualité ; elle est restituée avec certainty: estimate_not_certain. Les jours de rupture, fermeture ou panne sont censurés (jamais une demande nulle) ; un facteur décidé après la date de prévision est exclu ; un WAPE sur réels nuls est non défini.
  3. Les positions de stock viennent des sources avec leur date ; une réception planifiée non confirmée n'est pas du stock. Le réassort est une simulation ; la demande devient commande seulement par l'Action Gateway avec maker-checker et confirmation de l'ERP (unknown_pending_confirmation sinon).
  4. Machine à états du cycle de planification en données (409 invalid_transition, 412 sur If-Match périmé). Second humain pour l'approbation d'une prévision, d'un override, d'une politique et d'une commande.
  5. Modules génériques copiés et adaptés depuis le produit modèle UC-09 (aucun import inter-produit).

Conséquences​

  • Positives : produit autonome, isolé par RLS et testé ; moteur remplaçable ; aucune certitude affichée.
  • Négatives : méthodes de référence seulement (pas de modélisation des promotions) ; connecteurs en bac à sable ; recette sur données synthétiques.