Exportateur Synthétique des Surfaces de Logements

--- id: "001_export_surfaces" title: "Exportateur Synthétique des Surfaces de Logements" stage: 1 status: "spec-approved" last_updated: "2026-07-25" version: "1.4" --- # Spécification Produit : Exportateur Synthétique des Surfaces de Logements ## 1. Résumé & Objectifs Métier - **Périmètre** : Génération automatisée d’un tableau synthétique récapitulant les surfaces habitables par logement (SHAB, SU) à partir des pièces (`Rooms` / `BuiltInCategory.OST_Rooms`) du modèle Revit actif. - **Gain métier** : Élimination des erreurs de saisie manuelle, gain de temps significatif lors de la préparation des dossiers de permis de construire (PC) et d'études de projet (PRO), et standardisation des livrables de surface de l'agence. - **Conformité & Hygiène (Sprint 6 & RFC-30)** : Respect strict des normes d'architecture logicielle et de sécurité de l'agence : - **Sécurité absolue** : Zéro secret, clé API ou identifiant sensible codé en dur (`HARDCODED_SECRET`). - **Zéro valeur en dur** : Externalisation intégrale de la configuration, des chemins et des noms de paramètres (`HARDCODED_VALUES`). - **Quality Gate CI/CD** : Respect strict du mode `--strict` du script de validation `prebuild.py` (`exit code 0` exigé) avant toute promotion depuis `plugin_ideas/001_export_surfaces/generated_code/` vers le ruban de production `ANMA.tab/` via Pull Request. - **Performance & Traçabilité** : Requêtage optimisé des éléments via l'API Revit pour prévenir toute fuite mémoire et journalisation active des anomalies dans la console PyRevit sans masquage silencieux d'erreurs. ## 2. Cas d'Usage & Scénarios Utilisateur - **Acteur principal** : Architecte / Chef de Projet / BIM Manager. - **Pré-conditions** : - Modèle Revit ouvert avec pièces (`Rooms`) placées et délimitées par des contours valides. - Paramètres de projet d'agence (`ANMA_Logement_ID` et `ANMA_Type_Piece`) correctement configurés et associés à la catégorie Pièces. - Fichier de configuration JSON d'agence accessible et valide. - Code source validé sans erreur ni secret par le contrôle qualité automatisé (`prebuild.py --strict`). - **Flux nominal** : 1. Lancement de l'outil depuis le ruban PyRevit ANMA (onglet dédié). 2. Chargement dynamique du fichier de configuration externalisé (noms des paramètres, unités, chemins par défaut). 3. Extraction optimisée des pièces via le collecteur Revit ciblant explicitement `BuiltInCategory.OST_Rooms`. 4. Analyse et validation des pièces (filtrage des pièces non placées, redondantes ou sans surface). 5. Affichage de l'interface graphique WPF (avec support Dark/Light mode). 6. Consultation et filtrage interactif des logements, des surfaces calculées et du détail des typologies de pièces. 7. Sélection (cocher/décocher) des logements à inclure dans le livrable et choix du format de sortie (CSV ou Excel `.xlsx`). 8. Exécution de l'exportation avec barre de progression en temps réel et logs actifs des opérations. 9. Confirmation de l'export réussi et possibilité d'ouvrir directement le fichier généré. ## 3. Matrice des Données & Paramètres Revit | Paramètre / Attribut | Catégorie Revit (`BuiltInCategory`) | Type de Donnée | Mode (Lecture/Écriture) | Description / Usage | |---|---|---|---|---| | `ANMA_Logement_ID` | Pièces (`OST_Rooms`) | Texte | Lecture | Identifiant unique du logement (ex: "LOG-101"). Configurable via JSON. | | `ANMA_Type_Piece` | Pièces (`OST_Rooms`) | Texte | Lecture | Typologie de pièce (ex: "Séjour", "Chambre 1", "SDB"). Configurable via JSON. | | `Area` | Pièces (`OST_Rooms`) | Surface (Double) | Lecture | Surface mesurée de la pièce dans l'API Revit (unités internes). | | `Number` | Pièces (`OST_Rooms`) | Texte | Lecture | Numéro unique attribué à la pièce dans Revit. | | `Name` | Pièces (`OST_Rooms`) | Texte | Lecture | Nom attribué à la pièce dans Revit. | ## 4. Règles de Gestion & Algorithme Métier 1. **Sécurité, Non-Hardcoding & Quality Gate (RFC-30 / CI-CD)** : - Strictement aucun nom de paramètre, clé d'API, jeton de sécurité ou chemin de fichier absolu ne doit être inscrit en dur dans les fichiers source Python/C#. - Toute clé ou identifiant sensible doit obligatoirement transiter via des variables d'environnement sécurisées. - Les noms des paramètres Revit (`ANMA_Logement_ID`, `ANMA_Type_Piece`) sont lus depuis le fichier de configuration JSON externalisé. - Le code doit impérativement valider le passage du gate de contrôle `prebuild.py --strict` (`sys.exit(0)`) lors des pipelines GitHub Actions avant toute promotion de `plugin_ideas/001_export_surfaces/generated_code/` vers l'extension principale `ANMA.tab/`. 2. **Collecte Optimisée & Validation d'Éléments API** : - Utilisation de `FilteredElementCollector(doc).OfCategory(BuiltInCategory.OST_Rooms).WhereElementIsNotElementType()` combiné à des filtres rapides API (`Room.Area > 0` et `Room.Location != null`). - Importation explicite des énumérations API pour éviter les erreurs `NameError`. - Les pièces non placées, non fermées ou avec une surface nulle (`Area == 0`) sont exclues du calcul global. Leurs identifiants (`Room.Id`) sont consignés dans la zone de log/console. 3. **Regroupement & Calculs** : - Regroupement des pièces selon la valeur stricte du paramètre `ANMA_Logement_ID`. - Les pièces valides ne possédant pas de valeur pour `ANMA_Logement_ID` sont regroupées sous la catégorie `"Non Assigné / Hors Logement"`. 4. **Conversion d'Unités & Précision** : - Conversion systématique des surfaces internes Revit (pieds carrés) vers le mètre carré (m²) à l'aide des méthodes officielles `UnitUtils.ConvertFromInternalUnits()` adaptées à la version de Revit active. - Arrondi réglementaire à 2 décimales (`Math.Round(surface, 2)`). 5. **Structure du Fichier Exporté** : - En-têtes standardisés : `ID Logement`, `Nombre de Pièces`, `Surface Totale Habitable (m²)`, `Détail par Type de Pièce`. ## 5. Exigences d'Ergonomie (UI/UX) - **Charte Graphique & Mode Sombre** : Fenêtre WPF conforme au Design System ANMA, gérant automatiquement le basculement Dark Mode / Light Mode selon le thème du système/Revit. - **Composition de l'Interface** : - **En-tête** : Titre de l'outil, numéro de version et champ de recherche dynamique pour filtrer instantanément la liste des logements. - **Corps central** : `DataGrid` performant avec cases à cocher globales/individuelles, affichage du nombre de pièces et total des m². - **Console / Zone de notification** : Affichage temps réel des avertissements (pièces ignorées, paramètres absents non bloquants). - **Pied de page** : Barre de progression (`ProgressBar`), sélecteur du format de sortie (CSV / Excel `.xlsx`) et boutons d'action ("Tout cocher", "Tout décocher", "Exporter", "Annuler"). - **Réactivité & Raccourcis** : - Exécution asynchrone des traitements lourds d'export afin de préserver la réactivité de l'interface WPF. - Fermeture propre et annulation sécurisée de l'opération via la touche `Échap`. ## 6. Risques, Limites & Gestion des Erreurs - **Contrôle des Pré-requis & Configuration** : - *Détection* : Vérification systématique de l'existence des paramètres d'agence définis dans le JSON avant tout traitement. - *Action* : Si un paramètre requis est manquant dans le modèle, le traitement s'interrompt proprement et affiche une boîte de dialogue explicite listant les paramètres absents. - **Politique de Non-Masquage des Erreurs (Zero Silent Failure)** : - Interdiction stricte des blocs `except: pass` ou `catch (Exception) {}` vides. - Toute exception interceptée doit être capturée, typée et tracée dans le journal d'exécution (console PyRevit) pour audit. - **Conflits d'Accès aux Fichiers (E/S)** : - Détection anticipée des fichiers cibles verrouillés (ex: feuille Excel déjà ouverte par l'utilisateur). - Affichage d'un message d'invite clair proposant de fermer le fichier ou de spécifier un nouveau nom/emplacement d'exportation. - **Isolation des Transactions Revit & Contrôle Qualité** : - Les opérations en lecture seule n'ouvrent pas de transaction inutile. Si une modification temporaire du modèle est nécessaire, elle est isolée dans un bloc `Transaction` sécurisé avec annulation automatique (`Rollback`) en cas d'erreur. - Tout secret résiduel ou erreur d'intégration bloque automatiquement le pipeline CI/CD via le Quality Gate `prebuild.py --strict` en amont du déploiement en production.