docs(development): document checkpoint C1

docs/development/DECISIONS_020_DEV3.md

@@ -84,6 +84,28 @@ 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-009 — Rattachement explicite des compteurs
+
+**CONTEXTE** : les compteurs historiques étaient obligatoirement rattachés à `Equipment`, alors que l'exploitation nécessite aussi des compteurs de bâtiment, zone, local et logement.
+
+**OPTIONS ÉTUDIÉES** : cible polymorphe `scope_type/scope_id` ; FK nullable distinctes ; création d'un faux équipement pour chaque compteur patrimoine.
+
+**CHOIX** : conserver `equipment_id` nullable et ajouter `building_id`, `zone_id`, `room_id` et `housing_unit_id`, avec une contrainte SQL imposant exactement un rattachement principal. `Room` est supporté directement.
+
+**JUSTIFICATION** : les FK garantissent l'intégrité référentielle MariaDB, rendent les requêtes explicites et évitent le faux équipement. Le polymorphisme aurait supprimé les FK natives et complexifié les jointures.
+
+**CONSÉQUENCES** : l'index historique des compteurs Equipment reste valide ; les listes ne font plus de `join(Equipment)` obligatoire ; migration non destructive `n9c0d1e2f3g4`.
+
+## D-010 — Hiérarchie, relevés audités et remplacement
+
+**CHOIX** : `Meter.parent_id` porte une hiérarchie indépendante d'`Equipment.parent_id`, avec plusieurs racines possibles et validation des cycles. `MeterReading` reste une mesure physique dans l'unité native. `record_meter_reading` est le service unique ; une baisse exige un reset explicite et justifié. Une correction met à jour la mesure tout en conservant ancienne valeur, nouvelle valeur, auteur, date et justification dans `MeterReadingCorrection`. Un remplacement crée une nouvelle identité reliée par `replaces_meter_id` et clôt l'ancien compteur.
+
+**PHOTOS** : une photo facultative est stockée sur le relevé (`photo_filename`, `photo_path`) en réutilisant les extensions et la racine d'upload existantes ; aucune association artificielle à `EquipmentDocument`.
+
+**HORS C1** : échéances, consommations, coefficients gaz, alertes, coûts, contrats et quotas restent respectivement C2, C3 et C4.
+
+**DATE/COMMIT** : 2026-08-23 / checkpoint C1.
+
 ## D-003 — Catégorie et lot facultatifs
 
 **CONTEXTE** : un inventaire peut être saisi avant que le référentiel de maintenance soit complet.

docs/development/ROADMAP_020_DEV3.md

@@ -51,6 +51,10 @@ Alban, watchdogs, ENT, Outlook, Pronote, Yeastar, IA, secrets, données TEST_UI_
 
 ### C — Compteurs, consommations, contrats → après validation B
 
+- [x] C1 : socle Meter/MeterReading, rattachements patrimoine, hiérarchie et relevés audités ;
+- [ ] C2 : échéances périodiques, Ma journée et tournées de relevés ;
+- [ ] C3 : consommations, estimations, anomalies, alertes et coûts ;
+- [ ] C4 : contrats et quotas photocopieurs ;
 - [ ] Meter/MeterReading réutilisés ;
 - [ ] périmètre générique et calendrier scolaire ;
 - [ ] relevés dans Ma journée ;
@@ -66,6 +70,20 @@ Alban, watchdogs, ENT, Outlook, Pronote, Yeastar, IA, secrets, données TEST_UI_
 - [ ] calendrier scolaire contextuel pour collège, `school_calendar_aware=false` par défaut pour HousingUnit ;
 - [ ] photocopieurs N&B/couleur, quotas globaux de contrat, agrégation, projection et historique de périmètre.
 
+#### C1 — Socle compteurs et relevés
+
+- [x] rattachement explicite par FK nullable à Equipment, Building, Zone, Room ou HousingUnit ;
+- [x] plusieurs compteurs racines possibles et relation Meter parent/enfants ;
+- [x] relevé physique centralisé, baisse refusée sans reset explicite et justifié ;
+- [x] corrections relationnelles auditées et index courant recalculé ;
+- [x] remplacement explicite conservant l'ancien compteur et son historique ;
+- [x] photo facultative du relevé, stockée selon les conventions d'upload existantes ;
+- [x] unités physiques conservées, sans conversion gaz ni calcul de consommation ;
+- [x] aucune utilisation de `Equipment.parent_id` pour la hiérarchie des compteurs ;
+- [ ] service des échéances et intégration « Ma journée » : C2 ;
+- [ ] consommation, coefficients gaz, alertes et coûts : C3 ;
+- [ ] contrats et quotas photocopieurs : C4.
+
 ### D — Graphe technique générique
 
 - [ ] décision et migration non destructive ;

docs/development/STATUS_020_DEV3.md

@@ -1,12 +1,12 @@
 CURRENT VERSION: 0.2.0-dev.2
-CURRENT CHECKPOINT: B — validation fonctionnelle finale
-CURRENT COMMIT: à committer (version dev.2)
-CURRENT MIGRATION: m8b9c0d1e2f3 (appliquée Docker)
+CURRENT CHECKPOINT: C1 — socle compteurs et relevés
+CURRENT COMMIT: à finaliser dans les commits C1
+CURRENT MIGRATION: n9c0d1e2f3g4 (appliquée sur la base applicative)
 DOCKER VERSION: gmao-college:0.2.0-dev.2 (reconstruite, healthy, MariaDB connectée)
-LAST FULL TEST: 166 passed, 1 failed, 1 error — uniquement lookback/configuration GMAO historique et son teardown
-LAST TARGETED TEST: 12 passed (navigation, profil HTTP, bulk 200, horaires UI, Centre de configuration, duplication)
+LAST FULL TEST: 172 passed, 1 failed, 1 error ; le failed et l'error sont les deux anomalies historiques lookback/teardown
+LAST TARGETED TEST: 15 passed (socle C1, workflows historiques compteurs, maintenance, version)
 BLOCKERS: validation responsive visuelle non exécutée ; aucun défaut fonctionnel B restant
-NEXT ACTION: committer/pousser la version dev.2 sur origin/main et audit/main
+NEXT ACTION: committer puis pousser C1 sans changer la version
 
 ## Avancement
 
@@ -91,3 +91,22 @@ Lire ROADMAP_020_DEV3.md et DECISIONS_020_DEV3.md, puis reprendre sur NEXT ACTIO
 - Les fixtures SQLAlchemy de test isolent parfois les données créées dans une requête HTTP ; la route bulk a néanmoins été ajoutée et le workflow doit être rejoué sur le Docker authentifié.
 - La version `0.2.0-dev.2` est retenue : les workflows sont démontrés par tests HTTP authentifiés et aucune nouvelle régression n’est apparue ; la validation visuelle reste une limitation explicitement documentée.
 - Le Centre de configuration a été corrigé pour les contrats (utilisation des colonnes ORM réelles) et les liens profils/bulk/horaires ont été ajoutés au nouveau menu.
+
+## Checkpoint C1 — socle compteurs et relevés
+
+- [x] audit des modèles `Meter` / `MeterReading`, routes historiques et templates ;
+- [x] création unifiée des compteurs par service ;
+- [x] rattachement direct à Equipment, Building, Zone, Room ou HousingUnit ;
+- [x] plusieurs racines et hiérarchie `Meter.parent_id`, avec protection contre les cycles ;
+- [x] service unique `core.services.meter_service.record_meter_reading` pour les routes de relevé ;
+- [x] baisse refusée sans remise à zéro explicite et motif ;
+- [x] corrections auditées dans `meter_reading_corrections` ;
+- [x] remplacement explicite avec conservation de l'ancien compteur et de son historique ;
+- [x] photo facultative rattachée à `MeterReading` ;
+- [x] migration `n9c0d1e2f3g4` appliquée ;
+- [x] mesure SQL : liste 75 requêtes dans le contexte applicatif complet (navigation incluse), détail + historique 2 requêtes après chargement explicite ;
+- [ ] C2, C3 et C4 non commencés ;
+- [ ] validation Playwright visuelle complète non exécutée ;
+- [ ] installation complète sur base vide non validée : l'utilisateur MariaDB applicatif n'a pas le privilège de création de base temporaire.
+
+La version reste `0.2.0-dev.2`. Les seuils historiques de compteur ne sont pas réutilisés pour les alertes de consommation futures.