# Décisions structurantes

Chaque décision ci-dessous a été prise explicitement, avec une raison. Les
revenir sur sans connaître cette raison risque de recréer un problème déjà
résolu.

---

## Aucune bibliothèque PDF

**Décidé** : l'export PDF passe par l'impression du navigateur sur un gabarit
dédié, pas par une bibliothèque comme dompdf ou tcpdf.

**Pourquoi** : ajouter une bibliothèque romprait la contrainte « zéro
dépendance » posée au premier jour, pour un seul écran. Une feuille de style
`@media print` dédiée existe déjà : elle masque navigation et boutons, évite
les coupures de page au milieu d'un bloc. Le rendu est maîtrisé, pas une
capture brute de la page.

**Si à reconsidérer** : ce serait un choix d'architecture à part entière, pas
un ajout mineur.

---

## Excel généré à la main

**Décidé** : les fichiers `.xlsx` sont construits directement avec
`ZipArchive`, extension native de PHP.

**Pourquoi** : un `.xlsx` est structurellement une archive ZIP contenant du
XML. L'écrire à la main évite PhpSpreadsheet, donc respecte la contrainte de
dépendances.

**Validé par trois lecteurs indépendants** : `xmllint` sur chaque partie XML,
`openpyxl` (Python), et une conversion réelle par LibreOffice. Un matricule
commençant par zéro, les accents, les guillemets et les sauts de ligne en
cellule ressortent intacts.

**Piège** : le typage des cellules est explicite. Un `int` ou `float` PHP
devient un nombre Excel ; **toute chaîne reste du texte**, même si elle
ressemble à un nombre. C'est volontaire : deviner le type ferait perdre les
zéros non significatifs d'une référence comme `0123456`.

---

## Graphiques en SVG côté serveur

**Décidé** : aucune bibliothèque JavaScript de visualisation (Chart.js, D3).
`lib/svg.php` produit des courbes, barres et anneaux en SVG directement.

**Pourquoi** : cohérence avec la contrainte zéro dépendance, et les graphiques
restent visibles sans JavaScript — y compris à l'impression d'un rapport.

---

## Satisfaction basse : validation interne, jamais réouverture automatique

**Décidé** : une note ≤ 2/5 entre dans une file de validation
(`satisfaction_a_valider`). Un humain tranche : rouvrir, ou maintenir en l'état
avec un motif obligatoire.

**Pourquoi** : un client peut noter 2 pour une raison sans rapport avec la
résolution (un livreur désagréable). Rouvrir automatiquement un dossier
réellement réglé, sur un seul chiffre, serait faux. Cohérent avec l'esprit CAPA
du reste de l'outil : rien ne se referme sans regard humain.

---

## Le code client vient de l'ERP, le client ne le saisit pas

**Décidé** : le rapprochement se fait automatiquement par matricule fiscal.

**Pourquoi** : une saisie manuelle serait une source d'erreur, et le client ne
connaît généralement pas son code dans notre ERP.

---

## Modèle ERP : hypothèse assumée, pas vérité terrain

**Décidé** : la chaîne structurée (`erp_*`) a été conçue **sans accès réel** à
l'ERP Systematic de Workman Group.

**Trois paris explicites**, notés aussi dans les commentaires du code et de la
migration : un OF a au plus un sous-traitant, une matière vient d'un seul
fournisseur, un lot vient d'un seul OF.

**Si l'accès réel contredit ces hypothèses**, la migration se corrige à ce
moment-là — pas avant, faute de terrain pour trancher.

---

## L'IA : aide à la qualification (phase 1, octobre 2026)

**Décidé** : appel à une API de langage externe, fournisseur Claude (Haiku pour
la classification, Sonnet pour la rédaction en phase ultérieure).

**Construit (phase 1)** : `lib/ia.php`, table `ia_suggestions` (migration 23),
bloc « Aide à la qualification (IA) » dans la fiche dossier côté qualité. Un
agent clique sur « Obtenir une suggestion » ; l'IA propose type, catégories et
urgence ; l'agent coche ce qu'il applique. Les doublons possibles (même client,
même document ou mêmes catégories, 90 jours) sont calculés localement, sans IA.

**Garde-fous, vérifiés par `tests/testia.php`** :
- aucune fonction IA ne touche au statut d'un dossier ;
- une urgence bloquante ne peut pas être abaissée depuis une suggestion ;
- un dossier résolu ou rejeté n'est plus modifiable par ce biais ;
- la réponse du modèle est confrontée à des listes fermées (le texte du client
  est non fiable et peut contenir des instructions) ;
- seuls l'objet, la description et les catégories sont envoyés : ni identité,
  ni code ERP, ni numéro de commande ;
- désactivé par défaut, jamais déclenché au dépôt (un dépôt ne dépend pas de
  l'API), une demande par minute et par dossier, tout est journalisé.

**Limite connue** : la phase 1 a été testée avec un transport HTTP simulé. Le
vrai appel à l'API n'a pas pu être vérifié faute de clé : lancer
`php outils/tester-ia.php` dès que la clé est configurée.

**Brouillon de réponse au client (livré)** : bouton « Rédiger un brouillon » avec
consigne facultative ; le texte est placé dans le champ « Message » de la fiche,
jamais publié ni enregistré seul. Modèle de rédaction distinct (`modele_redaction`).
Le prompt interdit de promettre avoir/remplacement/remboursement sans consigne de
l'agent et impose des emplacements `[DATE]`, `[MONTANT]` pour ce qui manque.
Le transport réel (`curl`) a été vérifié contre un faux serveur d'API local
(option `url` de la config, réservée aux tests).

**Résumé et traduction (livrés)** : « Résumer le dossier » (3 à 5 puces, notes
internes incluses, réservé à l'équipe qualité) et « Traduire » (description du
dossier ou texte libre, vers français, anglais ou arabe). Résultats affichés,
jamais stockés ni envoyés ; une demande par 30 secondes et par dossier ; tracés
dans le journal. Disponibles aussi sur un dossier clos (lecture seule).

**Reste à faire** (non commencé, attend validation) : aide aux analyses de
causes (5 Pourquoi, Ishikawa, 8D).

---

## Catégories commerciales : additif, pas remplacement

**Décidé** : les 5 catégories demandées en phase 3 (retard de devis, erreur de
devis, erreur de commande, engagement non respecté, absence de retour) se sont
**ajoutées** aux 17 existantes. Total : 22.

« Absence de retour » a été traitée comme une catégorie distincte plutôt que
fusionnée avec `reponse`, `suivi` ou `injoignable` — décision prise faute de
précision, à corriger si elle ne correspond pas à l'intention.

---

## Réclamation commerciale dédiée : un formulaire à part, le même socle

Octobre 2026. La réclamation commerciale a son propre écran
(`public/reclamation-commerciale.php`, 4 étapes : le sujet, les détails, les
attentes, justificatifs et envoi). `reclamation.php?type=commerciale`
redirige vers lui. Le dépôt passe par les mêmes `valider_reclamation()` et
`creer_reclamation()` que la qualité : un seul chemin de validation.

- Les 22 catégories sont regroupées en 5 familles (`FAMILLES_COMMERCIALES`) ;
  chaque famille porte ses champs de détail, rangés en JSON dans
  `reclamations.details_commerciaux` (aucune migration pour ajouter un champ).
- Les champs de détail sont facultatifs et jamais bloquants : une valeur
  invalide est ignorée, pas refusée.
- `details_commerciaux` est écrit par un `UPDATE` séparé : un dépôt qualité ne
  dépend donc jamais de la migration 22 (leçon du « L'enregistrement a échoué »
  causé par la migration 19 non appliquée).
- Solutions attendues propres au commercial (`RESOLUTIONS_COMMERCIALES`) ;
  `valider_reclamation()` contrôle la liste selon le type. Mêmes clés que les
  gravités pour l'urgence : le SLA n'est pas touché.
- Le commercial se choisit dans une liste (`commerciaux`, gérée sur
  `qualite/commerciaux.php`). Liste vide ou table absente : saisie libre.
  « Autre / je ne sais pas » est toujours possible et n'est jamais bloquant.
- Sans JavaScript, toutes les catégories et tous les champs restent visibles.

## Ce qui n'a pas pu être vérifié

**Le canal Teams** (`envoyer_teams()` dans `lib/alertes.php`) suit le format
MessageCard de Microsoft mais **n'a jamais été testé en conditions réelles**,
faute de webhook disponible. À valider manuellement au premier envoi.

**Les tâches Cron** (sauvegarde, relances quotidiennes) sont documentées mais
leur activation réelle sur l'hébergement OVH n'est pas vérifiable depuis un
poste de développement.

## Jetons de design (refonte UI, lot 1)
Toutes les couleurs sont définies une seule fois dans `:root` de `style.css` ; plus aucune couleur hexadécimale ailleurs (vérifié par `testcss.php`). Les teintes quasi identiques ont été fusionnées (fond `--toile` #F2F1EC, `--surface` #F7F6F2, séparateurs `--trait-doux`). Jetons sémantiques : erreur, succès, alerte, information (fond + bordure). Correction au passage : `--bleu-pale` était utilisée sans être définie (note de satisfaction sélectionnée sans fond).

## Composants unifiés (refonte UI, lot 2)
Rayons en jetons (`--rayon-s` 6 px pour boutons, champs, options ; `--rayon-m` 8 px pour alertes ; `--rayon-l` 12 px pour cartes ; `--rayon-pill` pour badges). Champs de 44 px minimum, texte 16 px (évite le zoom automatique sur iPhone) et bordure `--gris` pour un contraste de 3:1 au moins. Bouton désactivé lisible (texte gris sur fond clair). Badges d'état en pilule. Entête de tableau sur `--surface`, survol des lignes. Nouvelles classes d'alerte `.wk-info` et `.wk-avert` (disponibles, pas encore utilisées dans les pages).

## Classes utilitaires (refonte UI, lot 3)
Les `style="…"` répétés des pages (marges, alignements, largeurs, gris atténué) sont remplacés par des classes `u-*` définies en fin de `style.css` avec `!important`, pour garder la priorité qu'avait le style en ligne. Les valeurs de marge gardent leurs pixels d'origine (aucun changement visuel voulu). Restent en ligne : les styles uniques, et tout `lib/mail.php` (les courriels exigent des styles en ligne). Les textes en `--gris-clair` passent en `--gris` (contraste).

## Typographie (refonte UI, lot 4)
Échelle de tailles : 12 / 13 / 14 / 15 / 16 / 18 / 22 / 30 px, plus les titres d'accueil (25, 33, 46). Les demi-tailles (12,5, 13,5, 14,5, 15,5) et 17/19/20/21 ont été ramenées à l'échelle (`testcss.php` interdit toute autre taille). Interligne 1,5 sur paragraphes et listes via `:where()` (spécificité nulle : les classes gardent leur propre interligne), titres équilibrés (`text-wrap:balance`), chiffres tabulaires dans tableaux et statistiques, longueur de ligne limitée à 75 caractères pour aides et citations. Classe `u-t17` renommée `u-t18`.

## Natures regroupées par famille (formulaire qualité)
Les 30 natures qualité sont rangées dans 8 familles repliables (`FAMILLES_QUALITE` dans `lib/vue.php`). Une famille s'ouvre seule si une de ses natures est déjà cochée. Recherche et pastilles de choix sont ajoutées par `type.js` ; sans JavaScript, le formulaire reste complet et les familles se déplient à la main. Seul l'affichage change : les clés des natures, la base et les statistiques sont inchangées. Les natures commerciales gardent leurs familles existantes (`FAMILLES_COMMERCIALES`), reprises dans la même liste. `testfam.php` vérifie qu'aucune nature n'est oubliée ni rangée deux fois.

## Mouvement (refonte, architecture PHP + design system CSS)
Choix : rester en PHP procédural et CSS sans dépendance (décision validée), plutôt que React/Tailwind/ShadCN. Pas de mode sombre (demande du DSI). Trois jetons sémantiques séparent les usages : `--texte` (texte courant), `--marque-nuit` (fonds de marque fixes : barre latérale, bandeau de connexion), `--sur-hivis` (texte sur jaune). Mouvement : entrée douce des sections et cartes (0,32 s), retour tactile des boutons, désactivé avec `prefers-reduced-motion`. Contrastes du thème clair vérifiés par `testcss.php`.

## Correctif : boucle de redirection hors session
Un visiteur non connecté qui ouvrait une page de `qualite/` tombait dans une boucle (`index.php` relatif pointait vers `qualite/index.php`). `url_connexion()` (lib/auth.php) remonte d'un niveau depuis ce dossier ; `testsession.php` le vérifie.

## Menu, en-tête et logo (refonte page par page : étape 1)
- En-tête client : le logo mène à l'accueil de l'espace ; dimensions déclarées (pas de décalage au chargement) ; sur petit écran, seuls logo, cloche et déconnexion restent (le nom et le sous-titre se cachent).
- Menu qualité : logo cliquable vers l'accueil, libellé « Espace qualité », navigation étiquetée. Sur mobile, le bouton annonce son état (`aria-expanded`), un voile ferme le menu en touchant le fond, Échap le ferme et le focus revient sur le bouton.
- Cibles tactiles : cloche et bouton de menu à 44 px. Libellés des boutons de la barre supérieure sur une seule ligne.
Vérifié dans un navigateur réel (mobile et bureau), sans erreur JavaScript.

## Design system documenté et logo SAV (proposition)
- `docs/DESIGN-SYSTEM.md` décrit tous les jetons, composants, règles d'accessibilité et règles du logo. `testcss.php` vérifie que chaque jeton du CSS y figure.
- Correction : `--ombre-2` et `--ombre-3` se définissaient elles-mêmes après un remplacement trop large ; `testcss.php` interdit désormais ce cas.
- Durées et courbe d'animation en jetons (`--duree-rapide`, `--duree-entree`, `--ease-sortie`).
- Logo SAV proposé (non déployé) : `logo-sav/` — version claire, version inverse, pictogramme. Marque d'origine : bulle de support avec coche, bande réfléchissante jaune de la charte. À valider avant tout remplacement dans le portail.
