Sprint 20 — UAT sur données réelles (MyAgrichem)

Guide opérationnel pour la recette utilisateur finale et le bilan d’ouverture FAC_ sur données réelles (ou copie de production anonymisée). Aligné sur §14.24 (validation Agrichem), §20.4 (risque bilan), AO-05 (sandbox avant prod).

---

1. Principes

Principe	Exigence
Sandbox d’abord	Répliquer le jeu de données réel dans un environnement isolé ; UAT signée avant bascule production.
Timezone	Toutes les dates métier : Africa/Algiers (config/app.php).
Append-only	Après verrouillage bilan (LOCKED), aucune modification des lignes bilan ; correction = nouveau cycle validation (rejet → IN_PROGRESS).
Traçabilité	Conserver exports CSV source, captures réponses API / écrans, et journal d’audit (sys_audit_logs / commande export audit si disponible).

---

2. Portail web (consoles UAT)

Hub : /portail/sprint20 — regroupe les consoles suivantes (connexion API Sanctum par page) :

Console	URL
Guide recette (ce document)	/portail/uat-sprint20
Bilan FAC_ (lecture statut)	/portail/sprint20/bilan-fac
Init. commerciale BUS_	/portail/sprint20/init-commerciale
Inventaire physique BUS_	/portail/sprint20/inventaire-physique
Profil légal société	/portail/sprint20/profil-legal
Expédition e-mail IPO	/portail/sprint20/ipo-dispatch
Modèles PDF	/portail/modeles-documents

---

3. Prérequis techniques

1. Base :dump restauré depuis prod anonymisé (NIF/RC/téléphones fictifs si obligation légale).
2. Utilisateurs UAT : comptes distincts par rôle (Back Office, DFC, DCM, CEO, profils module PURCH/TRANS/DRH selon périmètre §14.24).
3. Saisons : au moins une saison commerciale active dans time_season_config, cohérente avec la campagne testée.
4. Paramètres : sys_configurations initialisé (seeder ou import prod filtré) — notamment FAC_INVOICE_NUMBER_FORMAT, séquences FAC_INVOICE_SEQ_*.

Vérification rapide :

php artisan agrichem:uat-sprint20-readiness

---

4. UAT — Bilan d’ouverture FAC_ (données réelles)

Objectif : prouver sur jeu réel que le workflow DFC → DCM → CEO, l’import CSV, le verrouillage et l’émission FAC_ sont cohérents avec la comptabilité et les stocks.

3.1 Préparation des données sources (hors appli)

• Fichier clients FAC conformes (NIF, RC, AI, adresse) — rapproché avec la compta.
• Créances ouvertes par client (montants HT, références).
• Stock FAC initial : quantités physiques / valorisation HT par produit — rapproché inventaire J-1 cible go-live.

3.2 Parcours API (ordre logique)

Toutes les routes nécessitent Bearer Sanctum et permissions du registre (voir config/api_permissions.php : api.fac.bilan.*).

Étape	Méthode	Endpoint	Rôle	Contrôle recette
A	GET	/api/fac/bilan-ouverture?saison_id={id}	DFC / BO	Statut NOT_STARTED ou existant ; pas de doublon saison.
B	POST	/api/fac/bilan-ouverture body { "saison_id": … }	FAC_BILAN_MANAGE	201, bilan_id retourné.
C	POST	/api/fac/bilan-ouverture/{id}/lines	BO / DFC	Lignes CLIENT ( entity_id = acteur existant conforme), CREANCE, STOCK (product_id, quantity, valeur_ht).
D	POST	/api/fac/bilan-ouverture/{id}/import-csv body { "csv": "…" }	idem	CSV UTF-8 ; en-tête minimal : type ; colonnes possibles : type, entity_id, product_id, quantity, valeur_ht, notes. Vérifier imported vs erreurs ligne par ligne.
E	POST	/api/fac/bilan-ouverture/{id}/submit	DFC (ou permission FAC_BILAN_LOCK)	Réponse correlation_id ; statut PENDING_VALIDATION. Conserver ce correlation_id.
F	POST	/api/fac/bilan-ouverture/{id}/approve body { "correlation_id": "…" }	DCM puis CEO	Après CEO : statut LOCKED, locked_at renseigné.
G	Rejet éventuel	POST …/rejectavecnote`	DCM ou CEO	Retour IN_PROGRESS ; corriger lignes puis repasser par E.

Contrôles post-lock obligatoires

• Table fac_stock_entries : présence des mouvements issus des lignes STOCK du bilan (quantités / valorisation attendues).
• Clé FAC_INVOICE_SEQ_{année} : séquence réinitialisée / cohérente avec la politique DFC ; première facture : format FAC_INVOICE_NUMBER_FORMAT (ex. 00001/AAAA).
• POST facture test (ou équivalent service) : ne doit pas renvoyer « bilan non verrouillé » si saison = celle du bilan locked.
• Totaux créances et stocks rapprochés d’un export comptable / Excel de référence (signature DFC sur l’écart max toleré).

3.3 Scénarios négatifs (échantillon)

• Ligne CLIENT avec acteur sans NIF → rejet attendu à la saisie.
• Émission FAC_ avant lock bilan → 422 message bilan non verrouillé.
• approve sans bon correlation_id → échec contrôlé.

---

5. UAT transverse (données réelles, hors bilan)

Checklist minimale alignée §14.24 (à décliner par module déjà en production cible) :

• DCM : parcours commerciaux critiques (commande, BL, remise, mobile bootstrap si applicable).
• DFC : facturation, timbre, double stock BUS/FAC, périodes de gel FAC_ si paramétrées.
• CEO : dashboards/agréments, escalade workflow.
• Modules récents (selon déploiement) : PURCH_, TRANS_, DRH — cas nominaux + un cas permission refusée (403).

---

6. Journal de recette (sign-off)

Domaine	Responsable	Date	Résultat OK / KO	Réf. pièces
Bilan FAC_ lock + stocks	DFC
Cohérence créances	DFC
Validation commerciale	DCM
Go / no-go production	CEO

No-go : documenter blocking issues, tickets, et plan de reprise sandbox avant nouvelle tentative.

---

7. Références code

• Service : App\Services\Fac\FacBilanOuvertureService
• Import CSV : App\Services\Fac\FacBilanImportService
• Contrôleur API : App\Http\Controllers\Api\Fac\FacBilanController
• Tests de non-régression : tests/Feature/FacBilanOuvertureTest.php, tests/Feature/GapClosureTest.php

---

Document vivant — Sprint 20 UAT. Dernière mise à jour : Mai 2026.