gmao/docs/development/ROADMAP_020_DEV3.md

Roadmap 0.2.0-dev.3

Objectif

Faire évoluer la GMAO par checkpoints indépendants, reprenables et testables, depuis la consolidation de la création d'équipements jusqu'aux compteurs, au graphe technique et à la page « À documenter ».

État initial

• Version de départ : 0.2.0-dev.1
• Checkpoint A : validé
• Migration : j5e6f7a8b9c0
• Docker local : gmao-college:0.2.0-dev.1
• Pytest baseline : 159 passed, 1 failed, 1 error (lookback GMAO historique)
• Benchmark 100 équipements : 214 requêtes après optimisation, génération 3,22 s.

Protections

Alban, watchdogs, ENT, Outlook, Pronote, Yeastar, IA, secrets, données TEST_UI_* et Ancien menu 76/76 doivent rester inchangés sauf nécessité démontrée.

Checkpoints

A — Fondations équipements → 0.2.0-dev.1

• service métier unique de création Equipment ;
• lot facultatif et équipement incomplet accepté ;
• création quantitative/individuelle/groupe/parent homogène ;
• suppression des recherches par nom dans les nouveaux workflows ;
• audit du fallback Intervention 60 minutes ;
• validation des parcours et génération préventive ;
• tests ciblés et pytest complet sans nouvelle régression ;
• version 0.2.0-dev.1 commitée séparément.

B — Patrimoine, profils, setup → après A

• décision RoomType enrichi ou RoomProfile (RoomProfile séparé) ;
• profils de locaux et propositions d'équipements (première tranche) ;
• ouvrages facultatifs (RoomSurface) ;
• création en masse avec prévisualisation et duplication contrôlée ;
• setup Essentiel/Maintenance/Avancé affiché et Centre permanent ;
• logements existants conservés et non obligatoires ;
• charge 200 locaux (benchmark isolé et test anti-doublon).

Exigences transverses B

• Centre de configuration permanent, organisé en Essentiel, Maintenance, Patrimoine, Entreprises, Compteurs, Cartographie technique et Intégrations ;
• états calculés « Configuré », « Incomplet », « À configurer », « Facultatif », « Attention » avec liens d'action ;
• setup progressif : Essentiel, Maintenance/Patrimoine, Avancé facultatif ;
• horaires de travail rattachés explicitement à l'utilisateur/technicien ; aucun horaire fictif ;
• Site → Building → Zone → Room et HousingUnit réutilisés ; logements facultatifs ;
• TaskExecutionSegment et propriétés interruptible/splittable conservés sans régression.

C — Compteurs, consommations, contrats → après validation B

• 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 ; C3-FINAL en cours de revue (migration additive r3f4g5h6i7j8)
• 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 ;
• consommation normalisée et alertes ;
• quotas globaux photocopieurs ;
• tests ciblés, complets, migration et version.

Exigences C conservées pour la reprise

• Meter/MeterReading : eau, gaz, électricité, heures, copies, cycles, autre ; nature général/divisionnaire/individuel ;
• périmètres Site, Building, Zone, Room, HousingUnit, Equipment et plusieurs compteurs par équipement ;
• périodicité de relevé, Ma journée, delta et consommation normalisée ; seuil absolu/relatif avec message « Surconsommation inhabituelle — fuite possible » ;
• 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

• rattachement explicite par FK nullable à Equipment, Building, Zone, Room ou HousingUnit ;
• plusieurs compteurs racines possibles et relation Meter parent/enfants ;
• relevé physique centralisé, baisse refusée sans reset explicite et justifié ;
• corrections relationnelles auditées et index courant recalculé ;
• remplacement explicite conservant l'ancien compteur et son historique ;
• photo facultative du relevé, stockée selon les conventions d'upload existantes ;
• unités physiques conservées, sans conversion gaz ni calcul de consommation ;
• aucune utilisation de Equipment.parent_id pour la hiérarchie des compteurs ;
• service des échéances, intégration « Ma journée » et tournées : C2 ;
• consommation, coefficients gaz, alertes et coûts : C3 ;
• contrats et quotas photocopieurs : C4 socle implémenté, migration s4g5h6i7j8k9.

C3-COMPLETE — finalisation analytique

La finalisation C3 ajoute les agrégations DAY/WEEK/MONTH, les métriques contextuelles à répartition temporelle approximative, les seuils statistiques et preuves idempotentes, l’exclusion de baseline, la détection zero/low, la facture gaz, les coûts informatifs, les alertes informatives dans « Ma journée » et les graphiques locaux. La version reste 0.2.0-dev.2 jusqu’à validation indépendante. C4 (contrats, quotas et consommables photocopieurs) reste non commencé.

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 ;
• relations techniques génériques ;
• cascades électricité/eau/gaz/CVC/SSI/informatique ;
• points de coupure progressifs.

Exigences D conservées pour la reprise

• Equipment.parent_id reste limité à la hiérarchie d'inventaire ; graphe technique séparé ;
• relations extensibles : alimente, protège, isole, commande, dessert, connecté à, report de, asservi à ;
• cascades électricité/eau/gaz/chauffage/VMC/SSI/informatique et relations multiples (ex. CCF–VMC–SSI–électricité) ;
• page future « À documenter » et réutilisation du Centre documentaire.

E — Exploitation / complétude → 0.2.0-dev.3

• page Patrimoine → À documenter ;
• navigation des relations ;
• intégration Centre documentaire ;
• compteur en retard et anomalies visibles ;
• benchmark final ;
• version 0.2.0-dev.3 uniquement si tous les critères sont démontrés.

Critère bêta E

0.2.0-dev.3 signifie une bêta utilisable au quotidien sur patrimoine, équipements, interventions, préventif, entreprises, planning, Ma journée, setup et Centre de configuration. Les fonctions avancées non configurées doivent rester non bloquantes.

Migrations prévues

Uniquement Alembic, non destructives, testées sur installation existante et neuve. Chaque checkpoint décide ses tables après audit des modèles existants.

Risques / dépendances

• workflows historiques multiples pour Equipment ;
• données de test locales non équivalentes à une validation UI ;
• absence éventuelle de compte fonctionnel de validation ;
• coût N+1 des périmètres et des graphes ;
• règles contractuelles de quotas et calendrier.

Définition de DONE

Un checkpoint est DONE quand son code, sa migration éventuelle, ses tests ciblés, le pytest complet, sa documentation, son statut et ses commits sont cohérents et poussés sur les deux dépôts configurés : Forgejo (origin/main) et GitHub principal (audit/main). audit désigne le remote du GitHub principal du projet ; il n'existe pas de troisième dépôt d'audit.

C2 — Planification des relevés

C2 introduit une règle MeterReadingSchedule, des occurrences bornées et idempotentes MeterReadingOccurrence, ainsi que les définitions et occurrences de tournées. Les fréquences hebdomadaire, mensuelle, semestrielle, annuelle et annuelle à date fixe sont conservées comme valeurs extensibles, sans enum SQL fermée. La date cible/contractuelle est conservée séparément de la date opérationnelle.

L'anticipation vers le dernier jour travaillé précédent réutilise PlanningService.get_working_hours() lorsque le périmètre est scolaire et qu'une configuration horaire explicite existe. Les compteurs de logements utilisent par défaut un périmètre hors calendrier scolaire. En l'absence d'horaires explicites, aucune fermeture n'est inventée et la date cible est conservée.

Les occurrences en retard restent ouvertes jusqu'à leur traitement. Le traitement avec valeur appelle record_meter_reading() ; le traitement sans relevé conserve un motif, un commentaire, l'utilisateur et l'horodatage sans créer de MeterReading. Le remplacement d'un compteur annule explicitement ses occurrences ouvertes lors de la génération suivante et ne crée plus d'occurrence future.

Les occurrences sont agrégées par DayPlanner dans « Ma journée » avec responsable, durée estimée et échéance, sans création de fausse intervention ni créneau horaire simulé. Une tournée regroupe les règles membres par position et expose une occurrence datée avec progression et reprise.

C3 — décisions de périmètre

Les intervalles sont calculés à la demande depuis les relevés bruts et ne sont pas une nouvelle source de vérité. Les resets, baisses et changements de compteur physique ne sont jamais soustraits naïvement. Le contexte scolaire réutilise le calendrier existant ; les logements restent hors calendrier scolaire par défaut. Les régimes de chauffage sont datés et liés au compteur/réseau, afin de permettre plusieurs réseaux indépendants. Les règles et alertes C3 sont distinctes des seuils historiques de Meter, et les alertes ouvertes sont enrichies plutôt que dupliquées. Les conversions gaz et tarifs sont facultatifs ; aucun contrat ou quota photocopieur n'est implémenté en C3.