# Décisions architecturales 0.2.0-dev.3

Les décisions sont ajoutées au fil des checkpoints. Les modèles existants sont privilégiés avant toute nouvelle table.

## D-005 — Centre de configuration permanent et setup progressif

**CONTEXTE** : le setup initial ne doit pas devenir une page jetable ; une GMAO utile doit accepter une configuration partielle et expliciter les actions restantes.

**OPTIONS ÉTUDIÉES** : checklist statique de fin d'installation ; tableau calculé et permanent avec liens d'action.

**CHOIX** : créer/faire évoluer un Centre de configuration permanent, organisé par domaines (Essentiel, Maintenance, Patrimoine, Entreprises, Compteurs, Cartographie technique, Intégrations), avec états calculés et intégrations facultatives non bloquantes.

**JUSTIFICATION** : rendre la configuration progressive observable et exploitable sans SQL ni connaissance de l'architecture.

**CONSÉQUENCES** : chaque contrôle doit avoir une règle de calcul et une destination UI ; Pronote, ENT, Outlook, Yeastar, IA, compteurs, logements et cartographie restent facultatifs.

**DATE/COMMIT** : 2026-08-23 / préparation checkpoint B.

## D-006 — RoomType structurel, RoomProfile séparé à étudier

**CONTEXTE** : `RoomType` classe actuellement les locaux et est utilisé par Pronote et les écrans de patrimoine, mais ne porte aucun catalogue d'équipements, de quantités ou d'ouvrages.

**OPTIONS ÉTUDIÉES** : enrichir `RoomType` ; créer un `RoomProfile` distinct relié à `RoomType` ; stocker des JSON dans `RoomType`.

**CHOIX** : `RoomProfile` séparé, avec `RoomProfileItem` et `RoomSurface` normalisés. `RoomType` reste structurel et n'est pas modifié.

**JUSTIFICATION** : éviter de casser les usages de classification/enseignement et permettre plusieurs profils de proposition pour un même type structurel.

**CONSÉQUENCES** : migrations `k6f7a8b9c0d1` et `l7a8b9c0d1e2` ajoutées ; association de profil nullable ; aucune création automatique d'équipement sans validation utilisateur.

**DATE/COMMIT** : 2026-08-23 / implémentation checkpoint B en cours.

## D-007 — Origine d’une proposition de profil

**CONTEXTE** : une réapplication d’un RoomProfile doit ajouter uniquement le delta sans rechercher les équipements par nom.

**OPTIONS ÉTUDIÉES** : comparaison fragile nom/catégorie ; table de liaison ; identifiant nullable sur Equipment.

**CHOIX** : ajouter `Equipment.room_profile_item_id`, nullable, indexé et relié à `RoomProfileItem`. Les équipements historiques sans origine restent valides.

**JUSTIFICATION** : l’identifiant de proposition est stable, compatible avec les noms en doublon et permet une idempotence explicite sans mutation silencieuse.

**CONSÉQUENCES** : migration non destructive `m8b9c0d1e2f3`; le service commun renseigne l’origine lors de l’application d’un profil.

**DATE/COMMIT** : 2026-08-23 / checkpoint B.

## D-008 — Centre de configuration sans faux état d’erreur

**CONTEXTE** : le lot d’un équipement est facultatif et les modèles de contrats exposent des colonnes ORM dont certaines propriétés métier ne sont pas directement filtrables.

**CHOIX** : afficher un équipement sans lot comme information facultative ; filtrer les contrats via `Contract.__table__.c` pour éviter les erreurs de rendu du Centre.

**JUSTIFICATION** : une configuration progressive ne doit pas bloquer l’inventaire ni produire une page de synthèse cassée.

**CONSÉQUENCES** : les liens du nouveau menu pointent vers Centre, profils, bulk et horaires ; les intégrations avancées restent facultatives.

**DATE/COMMIT** : 2026-08-23 / validation B.

## D-000 — Checkpoints indépendants

**CONTEXTE** : le chantier couvre plusieurs domaines avec migrations et risques différents.

**OPTIONS ÉTUDIÉES** : un gros développement continu ; checkpoints commitables.

**CHOIX** : checkpoints A à E, chacun documenté, testé et versionné.

**JUSTIFICATION** : reprise fiable, absence de régression masquée, dépôt source de vérité.

**CONSÉQUENCES** : aucun checkpoint suivant ne démarre avant validation du précédent.

**DATE/COMMIT** : 2026-08-23 / initialisation.

## D-001 — Service de création Equipment

**CONTEXTE** : les routes fiche avancée et wizard construisaient des objets différents et le wizard retrouvait ensuite des équipements par nom.

**OPTIONS ÉTUDIÉES** : conserver les routes indépendantes ; centraliser la construction dans un service.

**CHOIX** : `core.services.equipment_creation.create_equipment`, lot et catégorie facultatifs, retour de l'instance persistée.

**JUSTIFICATION** : évite les collisions de noms et garantit la même gestion de quantité, parent, localisation et génération préventive.

**CONSÉQUENCES** : les anciens parcours sont progressivement migrés ; les relations techniques restent hors `parent_id`.

**DATE/COMMIT** : 2026-08-23 / checkpoint A en cours.

## 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.

**CHOIX** : créer `MeterReadingSchedule` pour la règle, `MeterReadingOccurrence` pour chaque échéance logique, `MeterReadingRound`/`MeterReadingRoundMember` pour la définition d'une tournée et `MeterReadingRoundOccurrence` pour sa réalisation datée. L'unicité `(schedule_id, target_date)` et l'unicité d'une occurrence de tournée par date rendent la génération idempotente.

La date cible reste distincte de la date opérationnelle. L'anticipation réutilise le moteur horaire/calendrier existant pour les règles scolaires ; les logements sont hors calendrier scolaire par défaut. Sans horaires explicites, le système conserve la date cible plutôt que d'inventer un jour travaillé.

**TRAITEMENT** : une occurrence avec relevé appelle le service C1 `record_meter_reading`. Une occurrence sans relevé conserve un motif distinguant notamment inaccessible, absent, refus et relevé non connu, sans créer de mesure artificielle. Une occurrence ouverte d'un compteur remplacé est annulée immédiatement dans la transaction de remplacement avec une raison système et reste historisée.

**INTÉGRATION** : les occurrences sont une source du `DayPlanner`, avec responsable, durée et retard calculé ; elles ne créent pas d'intervention et ne simulent pas de créneau si le planificateur ne sait pas en attribuer un. Les routes de configuration sont administrateur ; le traitement d'une occurrence est limité à l'utilisateur assigné ou à un administrateur.

**LIMITES C2** : génération à horizon borné autour de « Ma journée » (365 jours de regard arrière et 31 jours d'avance) ; aucune analyse de consommation, conversion, alerte, coût, contrat ou quota n'est implémentée.

**DATE/COMMIT** : 2026-08-24 / checkpoint C2.

## D-012 — Intervalles et contexte analytique C3

**CHOIX** : calculer les intervalles à la demande à partir de deux relevés réels successifs, conserver les mesures brutes et annoter chaque intervalle par sa composition calendaire et ses régimes de chauffage. Les logements ne sont pas reclassés selon les vacances scolaires. Les régimes sont datés par compteur et réseau pour éviter l'hypothèse d'un chauffage global unique.

**JUSTIFICATION** : éviter une table de cache difficile à invalider après correction de relevé, tout en gardant des requêtes explicites et des données historiques intactes. Une rupture de compteur ou un reset ne produit jamais de delta analytique trompeur.

## D-013 — Alertes, gaz et coûts C3

**CHOIX** : persister les règles et alertes C3 séparément des seuils historiques ; conserver une évidence par intervalle, dédupliquer tant qu'une alerte équivalente est ouverte, utiliser une médiane avec minimum configurable (défaut 3), puis permettre un lien relationnel vers une intervention. Les coefficients gaz sont datés et manuels prioritaires sur ceux issus de facture ; le tarif applicable est celui de la date du relevé final et le coût reste informatif.

**HORS PÉRIMÈTRE** : aucune consommation avancée, contrat/quota photocopieur, moteur comptable ou C4.

## D-014 — Compléments C3

Les périodicités DAY/WEEK/MONTH réutilisent le même agrégateur. Les métriques contextuelles répartissent proportionnellement la quantité selon le nombre de jours du contexte et sont présentées comme analytiques, jamais comme une mesure physique directe. La médiane et le seuil d’écart configurable (défaut 30 %) sont réservés à l’anomalie statistique ; l’estimation d’un sous-compteur utilise la moyenne journalière des derniers intervalles fiables. L’eau en m³ ne déclenche jamais la conversion gaz : seul `meter_type == "gaz"` peut utiliser un coefficient.

Les preuves d’alerte sont uniques par alerte et intervalle. Les conclusions `CONFIRMED_LEAK` et `READING_ERROR` excluent leurs preuves de la baseline ; `BAD_THRESHOLD` et `NORMAL_EXPLAINED` ne les excluent pas automatiquement. Les régimes chauffage restent liés au compteur avec `network_name` : cette solution permet plusieurs réseaux sans duplication obligatoire d’une nouvelle entité, et reste remplaçable par une alimentation GTB future.

## D-016 — Type de règle statistique C3

`MeterAlertRule.rule_type` distingue explicitement `MANUAL_THRESHOLD` et `STATISTICAL_ANOMALY`. Les règles historiques et les nouvelles règles sans type explicite restent manuelles par défaut. Le service de relevé appelle l'évaluation manuelle ou la médiane statistique selon ce type, en réutilisant `min_comparable_intervals` et `min_deviation_percent`. Une correction réévalue uniquement les intervalles voisins et conserve l'idempotence des preuves. La colonne est ajoutée par la migration additive `r3f4g5h6i7j8`, sans modifier les migrations C3 déjà appliquées.

## D-015 — Clôture C3 : recalcul ciblé et exposition opérationnelle

Les nouveaux relevés déclenchent un recalcul limité aux intervalles voisins ; une correction ne réévalue que les segments précédent et suivant. Les preuves ouvertes dépendant d'une valeur corrigée sont neutralisées et l'alerte est clôturée si elle ne possède plus de preuve valide ; les alertes déjà clôturées restent historiques. Le recalcul est appelé dans la transaction du service de relevé, sans worker externe ni rescannage complet à chaque GET.

La route de clôture d'alerte réutilise le RBAC `planning.manage`. « Ma journée » ne montre que les alertes ouvertes liées à un compteur attribué au compte ou à une occurrence qui lui est attribuée ; l'administrateur conserve la vision globale. Le dashboard utilise une fenêtre explicite de 30 jours et agrège les unités séparément. Les mesures C3-CLOSE instrumentées sur le jeu de performance donnent notamment 83 requêtes dashboard, 24 fiche analytique, 4 évaluation d'alerte et 86 Ma journée ; les temps restent dépendants de l'environnement MariaDB.

## 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.

**OPTIONS ÉTUDIÉES** : bloquer toute création sans lot ; accepter un équipement incomplet et le compléter plus tard.

**CHOIX** : la création reste valide sans lot (et sans catégorie dans les parcours wizard) ; un lot fourni est validé et peut déclencher la génération préventive.

**JUSTIFICATION** : respecter le principe de configuration progressive sans fabriquer de maintenance implicite.

**CONSÉQUENCES** : l'interface doit pouvoir signaler ultérieurement « Lot non renseigné » ; les relations techniques restent indépendantes.

**DATE/COMMIT** : 2026-08-23 / checkpoint A.

## D-004 — Versionnement du checkpoint A

**CONTEXTE** : le chantier interdit `0.1.0-dev.13` et demande des versions correspondant à des checkpoints réellement validés.

**CHOIX** : le checkpoint A validé passe de `0.1.0-dev.12` à `0.2.0-dev.1` ; B, C, D et E restent séparés.

**JUSTIFICATION** : la création Equipment est consolidée et testée sans nouvelle régression ; les erreurs restantes sont exactement la baseline historique.

**CONSÉQUENCES** : Docker doit être reconstruit avec la nouvelle version ; aucune migration n'est ajoutée au checkpoint A.

**DATE/COMMIT** : 2026-08-23 / version commit.

## D-002 — Durée d'intervention inconnue

**CONTEXTE** : `Intervention.effective_estimated_duration` retournait silencieusement 60 minutes.

**CHOIX** : retourner 0 si aucune estimation ou moyenne historique n'existe ; DayPlanner affiche alors une tâche sans durée à renseigner.

**JUSTIFICATION** : ne pas présenter une estimation arbitraire comme une contrainte métier.

**CONSÉQUENCES** : les statistiques historiques restent inchangées ; les workflows doivent renseigner les interventions planifiables.

**DATE/COMMIT** : 2026-08-23 / checkpoint A en cours.