docs(development): document checkpoint C4 foundation

docs/development/DECISIONS_020_DEV3.md

@@ -84,6 +84,18 @@ Les décisions sont ajoutées au fil des checkpoints. Les modèles existants son
 
 **DATE/COMMIT** : 2026-08-23 / checkpoint A en cours.
 
+## D-017 — Contrats photocopieurs et consommables C4
+
+Les photocopieurs et imprimantes restent des `Equipment` et leurs compteurs restent des `Meter`. Les contrats sont pluriannuels ; la date globale du contrat est distincte de la date de début des périodes de quota et de l'anniversaire configurable. Les quotas N&B/couleur appartiennent à la période contractuelle, jamais à une machine.
+
+Le parc est historisé par une association datée contrat/machine. Un remplacement ferme l'association précédente avec un motif et conserve les compteurs/relevés de l'ancienne machine. Les projections utilisent prioritairement les jours scolaires connus ; une insuffisance de données est affichée comme telle. Les alertes de dépassement sont dédupliquées par période et couleur.
+
+Les références `Consumable` existantes sont le stock global partagé. `EquipmentConsumable` porte la compatibilité multi-machines, `ConsumableUsage` porte les sorties, et les nouvelles commandes/réceptions augmentent le stock uniquement lors d'une réception réelle. La durée est calculée séparément pour chaque couple équipement/référence ; l'installation courante n'entre pas dans la moyenne terminée.
+
+**MIGRATION** : `s4g5h6i7j8k9` est additive depuis `r3f4g5h6i7j8` et conserve les consommables historiques. La validation base vide et la validation visuelle restent ouvertes.
+
+**PERFORMANCE** : le calcul contractuel charge les compteurs et relevés en lot ; le détail contrat précharge fournisseur, périodes et parc. Sur le jeu `TEST_UI_C4_PERF_*`, le calcul est passé de 75 à 11 requêtes et le détail de 234 à 98 requêtes. Le détail consommable mesuré à 4 requêtes reste séparé.
+
 ## D-011 — Échéances et tournées de relevés C2
 
 **CONTEXTE** : un relevé est un travail opérationnel planifiable, mais ne doit pas être modélisé comme une intervention. Les fréquences simples ne suffisent pas pour les dates contractuelles et les logements.

docs/development/ROADMAP_020_DEV3.md

@@ -54,7 +54,7 @@ Alban, watchdogs, ENT, Outlook, Pronote, Yeastar, IA, secrets, données TEST_UI_
 - [x] C1 : socle Meter/MeterReading, rattachements patrimoine, hiérarchie et relevés audités ;
 - [x] C2 : échéances périodiques, Ma journée et tournées de relevés ;
 - [x] C3 : consommations, estimations, anomalies, alertes et coûts ; C3-FINAL en cours de revue (migration additive `r3f4g5h6i7j8`)
-- [ ] C4 : contrats et quotas photocopieurs ;
+- [x] C4 : socle contrats pluriannuels, quotas, parc daté et consommables partagés ; validation indépendante restante ;
 - [ ] Meter/MeterReading réutilisés ;
 - [ ] périmètre générique et calendrier scolaire ;
 - [ ] relevés dans Ma journée ;
@@ -82,7 +82,7 @@ Alban, watchdogs, ENT, Outlook, Pronote, Yeastar, IA, secrets, données TEST_UI_
 - [x] aucune utilisation de `Equipment.parent_id` pour la hiérarchie des compteurs ;
 - [x] service des échéances, intégration « Ma journée » et tournées : C2 ;
 - [x] consommation, coefficients gaz, alertes et coûts : C3 ;
-- [ ] contrats et quotas photocopieurs : C4.
+- [x] contrats et quotas photocopieurs : C4 socle implémenté, migration `s4g5h6i7j8k9`.
 
 ### C3-COMPLETE — finalisation analytique
 
@@ -90,6 +90,12 @@ La finalisation C3 ajoute les agrégations DAY/WEEK/MONTH, les métriques contex
 
 La clôture C3 ajoute le recalcul ciblé après création/correction d'un relevé, la clôture HTTP d'alerte avec permissions, le filtrage RBAC des alertes informatives de « Ma journée », l'idempotence de l'intervention liée et les synthèses dashboard sur les 30 derniers jours. Les synthèses conservent les unités : eau en m³, gaz en m³ et kWh seulement si converti, électricité en kWh. Les performances mesurées sur `TEST_UI_C3_CLOSE_PERF_*` restent dépendantes de MariaDB ; aucune optimisation ne doit masquer le coût historique de C2.
 
+### C4 — socle contrats, quotas et consommables
+
+C4 ajoute les contrats photocopieurs pluriannuels et leurs périodes annuelles de quota, avec anniversaire configurable, parc historisé par association datée, remplacement de machine, quotas N&B/couleur, projection selon les jours scolaires et alertes de dépassement dédupliquées. Les photocopieurs et imprimantes restent des `Equipment` et leurs compteurs restent ceux de C1-C3.
+
+Le stock réutilise les références `Consumable`, les compatibilités `EquipmentConsumable` et les sorties `ConsumableUsage`. Les commandes/réceptions C4 augmentent le stock uniquement à la réception ; les références partagées restent uniques et la durée est calculée par couple équipement/consommable. La migration additive est `s4g5h6i7j8k9`; validation base vide, couverture UI/mobile et revue indépendante restent à effectuer.
+
 ### D — Graphe technique générique
 
 - [ ] décision et migration non destructive ;

docs/development/STATUS_020_DEV3.md

@@ -1,12 +1,27 @@
 CURRENT VERSION: 0.2.0-dev.2
-CURRENT CHECKPOINT: C3-FINAL — branchement automatique des anomalies
-CURRENT COMMIT: 95a3ed4 — docs(development): document automatic statistical alerts
-CURRENT MIGRATION: r3f4g5h6i7j8 (down_revision q2f3g4h5i6j7)
+CURRENT CHECKPOINT: C4 — contrats photocopieurs et consommables
+CURRENT COMMIT: 1fe9e91 — perf(c4): batch contract usage and detail loading
+CURRENT MIGRATION: s4g5h6i7j8k9 (down_revision r3f4g5h6i7j8)
 DOCKER VERSION: gmao-college:0.2.0-dev.2 (reconstruite, healthy, MariaDB connectée)
 LAST FULL TEST: baseline précédente 202 passed, 1 failed, 1 error ; les deux anomalies historiques restent visibles
-LAST TARGETED TEST: 39 passed (C1/C2/C3) ; 17 tests C3 incluant les anomalies statistiques automatiques
+LAST TARGETED TEST: 46 passed (C1/C2/C3/C4) ; 7 tests C4, dont instrumentation performance
 BLOCKERS: validation responsive visuelle et base vide non exécutées ; anomalies pytest historiques conservées
-NEXT ACTION: revue indépendante finale de C3-FINAL ; ne pas commencer C4
+NEXT ACTION: compléter la couverture C4, tester Docker puis revue indépendante ; ne pas bump la version
+
+## C4 — contrats photocopieurs, quotas et consommables
+
+- [x] photocopieurs et imprimantes restent des `Equipment`, avec type d'appareil, S/N, IP, hostname et MAC facultatifs ;
+- [x] contrats pluriannuels, date globale, date de début des quotas et anniversaire configurable ;
+- [x] périodes annuelles de quota, quotas N&B/couleur facultatifs et association machine datée ;
+- [x] remplacement de machine dans le même contrat avec historique et motif ;
+- [x] consommation contractuelle séparée N&B/couleur et projection simple selon les jours scolaires ;
+- [x] alerte de dépassement quota dédupliquée ;
+- [x] références `Consumable` partagées entre plusieurs machines, stock global, cible de stock et quantité à commander ;
+- [x] commandes, réceptions partielles/complètes, sorties via `ConsumableUsage` et durée par couple machine/référence ;
+- [x] migration additive `s4g5h6i7j8k9`, appliquée sur la base existante, données stock existantes conservées ;
+- [x] instrumentation C4 : calcul contrat 11 SQL / 0,110 s ; détail contrat 98 SQL / 1,052 s ; détail consommable 4 SQL / 0,111 s ;
+- [ ] couverture HTTP/mobile complète, base vide et validation Playwright ;
+- [ ] C4 complètement validé indépendamment.
 
 ## C3 — socle analytique