Aller au contenu principal

ADR-0204 : Navin Enterprise Agent Gestion des Magasins et Performance, couche produit retail au-dessus du Control Plane

  • Statut : proposé (2026-11-05)
  • Décideurs : équipe plateforme Navin Enterprise AI, mission UC-15 (agent_uses_cases/15_Retail_Gestion_Magasins_Performance.md)
  • Références : ADR-0180 (socle frontend), ADR-0191 (modèle supply-chain dont les modules génériques sont copiés), ADR-0174 (fournisseur de mémoire), paquet OPA eai.retail_magasins (deploy/policies/opa/retail_magasins.rego), fragment OpenFGA deploy/policies/openfga/products/retail-magasins-performance.fga, contrats contracts/v1/retail-magasins-performance-action-request.schema.json et contracts/v1/retail-magasins-performance-copilot-event.schema.json, gabarit Manager navin-retail-magasins-performance-agent (published: false).

Contexte​

Un réseau de magasins veut consolider les indicateurs de chaque point de vente (CA net, marge, tickets, panier, conversion, disponibilité, retours, pertes, productivité agrégée), les comparer à périmètre comparable, détecter des écarts, préparer un diagnostic et des plans d'actions, suivre leur exécution terrain et en mesurer l'effet. Le cahier des charges impose huit modules (§7), une machine à états serveur (§6), des KPI déterministes dont une donnée absente n'est jamais zéro, et interdit toute surveillance individuelle des salariés.

Décision​

  1. Produit séparé navin-enterprise-retail-magasins-performance/, paquet navin_magasins, schéma PostgreSQL magasins avec RLS sur chaque table tenant, préfixe /api/v1/retail-magasins-performance, ports api 8487, redis 6408, web 3488 (rendu par le shell partagé, ADR-0180).
  2. Les modules génériques du modèle supply-chain (auth, authz, audit, Action Gateway, jobs, worker, documents, copilote, observabilité) sont copiés et adaptés, jamais importés d'un autre produit.
  3. Les KPI sont calculés de façon déterministe à partir des données des sources (POS, ERP, gestion des temps, compteurs) selon des définitions versionnées en données ; montants en chaînes décimales avec devise, jamais sommés entre devises ; un dénominateur nul ou absent rend le KPI not_available.
  4. Les comparaisons suivent des règles à périmètre comparable (cohorte constante, magasins non stables exclus et documentés) ; les anomalies sont des signaux pour un humain, jamais un jugement sur une personne.
  5. Les plans d'actions sont approuvés en maker-checker (le préparateur n'approuve jamais, ni le copilote ni un robot) puis assignés par l'Action Gateway avec Idempotency-Key, If-Match et confirmation de la source ; une réponse incertaine devient unknown_pending_confirmation.
  6. La mesure d'efficacité compare avant et après, nomme les facteurs confondants et reste observational sans groupe de contrôle : jamais présentée comme un effet causal prouvé.
  7. RAG et mémoire passent par le Control Plane (API de connaissances, fournisseur de mémoire de l'ADR-0174) ; aucun second moteur.

Conséquences​

  • Les connecteurs réels (POS, ERP, compteurs, gestion des temps, gestion des tâches) restent à brancher ; seul un bac à sable déclaré sandbox est exercé.
  • Le gabarit reste prepared et absent du catalogue tant qu'aucune validation explicite n'est donnée.