Installation

H.A.C.A s'installe en quelques minutes via HACS (recommandé) ou manuellement.

Prérequis

Installation via HACS

Installation manuelle

# Télécharger le projet
git clone https://github.com/JeanMarc-Labs/ha-config-auditor.git

# Copier le composant
mkdir -p /config/custom_components/
cp -r ha-config-auditor/custom_components/config_auditor /config/custom_components/

# Redémarrer HA puis ajouter l'intégration

Dépannage

Tableau de bord

La première page que vous voyez en ouvrant H.A.C.A. Vue d'ensemble instantanée de la santé de votre installation.

Score de santé

Le score (0–100) est affiché en grand en haut. Il se met à jour après chaque scan.

Score = 100 − Σ pénalités

Pénalités par issue :
  HIGH   → −5 points
  MEDIUM → −2 points
  LOW    → −1 point

Intégration dans HA

automation:
  - alias: "HACA : Alerte score santé"
    trigger:
      - platform: numeric_state
        entity_id: sensor.haca_health_score
        below: 70
    action:
      - service: notify.mobile_app
        data:
          title: "⚠️ Score HA bas"
          message: "Score : {{ states('sensor.haca_health_score') }}/100"

Capteurs exposés dans HA

Analyse des Issues

Comprendre, filtrer et agir sur les problèmes détectés par H.A.C.A.

Structure d'une carte d'issue

┌─────────────────────────────────────────────────────┐
│ ⚠️ HIGH   Mode incorrect pour détection de mouvement │
│                                                      │
│ 📍 automation.lumieres_salon                         │
│                                                      │
│ L'automatisation utilise le mode 'single' mais       │
│ contrôle une lampe via un capteur de mouvement.      │
│                                                      │
│ [ ✏️ Ouvrir dans HA ] [ 🤖 IA ] [ 🔧 Fix ]          │
└─────────────────────────────────────────────────────┘

Boutons IA sur les issues

Chaque issue dispose d'un bouton 🤖 IA qui s'adapte au type d'issue :

Filtres disponibles

• 12 sous-onglets — Tous · Sécurité · Automations · Scripts · Scènes · Entités · Helpers · Performance · Blueprints · Dashboards · Carte Zones · Redondances
• Chips de sévérité — HIGH MEDIUM LOW
• Export CSV de la liste filtrée courante

Types d'issues principaux

device_id_in_trigger / action / target

- platform: device
  device_id: abc123def456
  domain: binary_sensor
  type: motion
- platform: state
  entity_id: binary_sensor.capteur_mouvement_salon
  to: "on"

incorrect_mode_motion_single

mode: single
mode: restart   # ✅ Redémarre si nouveau mouvement détecté

expensive_template_states_all

Corrections

H.A.C.A corrige certaines issues directement depuis l'interface, avec prévisualisation et backup automatique.

Issues corrigeables

Flux de correction automatique

Mode simulation

service: config_auditor.fix_device_id
data:
  automation_id: "1234567890abc"
  dry_run: true   # Aucun fichier modifié

Historique & Rapports

Suivez l'évolution de votre installation dans le temps et générez des rapports exportables.

Onglet Historique

Chaque scan produit un point de données conservé. Le graphique montre l'évolution du score sur les 30 derniers scans. Une hausse stable = vos corrections portent leurs fruits. Une baisse soudaine = nouvelles automations avec problèmes.

Fréquence du rapport automatique

Formats de rapport

service: config_auditor.generate_report
data:
  format: pdf    # pdf | markdown | json | all

/config/.haca_reports/
├── haca_report_20260314_143022.pdf
├── haca_report_20260314_143022.md
└── haca_report_20260314_143022.json

Batteries & Recorder DB

Surveillance des niveaux de batterie et analyse de la base de données Recorder.

Module Batteries

automation:
  - alias: "HACA : Alerte batterie faible"
    trigger:
      - platform: numeric_state
        entity_id: sensor.haca_battery_low_count
        above: 0
    action:
      - service: notify.mobile_app
        data:
          title: "🔋 Batterie(s) faible(s)"
          message: >
            {{ states('sensor.haca_battery_low_count') }} appareil(s)
            sous {{ states('sensor.haca_battery_threshold') }}%

Module Recorder DB

service: config_auditor.purge_recorder_orphans

Prédictions batteries

H.A.C.A analyse la tendance des niveaux de batterie par régression linéaire sur l'historique HA et prédit quand chaque appareil aura besoin d'une pile neuve.

Comment ça marche

Pour chaque entité batterie, H.A.C.A récupère les N derniers points de données et calcule une droite de régression linéaire. La pente détermine le taux de décharge journalier moyen. H.A.C.A extrapole ensuite la date à laquelle le niveau atteindra le seuil critique (10%) et le seuil d'alerte configuré.

Alertes préventives 7 jours

Tout appareil prédit pour atteindre le seuil critique dans les 7 prochains jours remonte une issue battery_predict_critical_soon de sévérité HIGH.

Export CSV

Colonnes : entity_id · current_level · days_remaining · predicted_empty_date · discharge_rate_per_day · confidence_r2.

Impact Recorder

Identifie les entités qui saturent votre base de données SQLite et génère le bloc YAML recorder: exclude: prêt à copier-coller.

Métriques calculées

Génération du bloc YAML d'exclusion

recorder:
  exclude:
    entities:
      - sensor.temperature_exterieure   # 1842 writes/day — 2.1 MB/year
      - sensor.cpu_temperature            # 1440 writes/day — 1.6 MB/year

Complexité des zones

Heatmap interactive qui visualise la complexité de chaque zone et propose des suggestions automatiques de restructuration.

Score de complexité composite

Interprétation

Suggestions automatiques

• Découpage (area_split_suggested) — zones rouges > 80 : séparation en 2 sous-zones logiques
• Fusion (area_merge_suggested) — paires de zones vertes < 20 avec entités similaires

Analyseur de redondances

Détecte trois catégories de redondances entre vos automations pour nettoyer, consolider et simplifier votre configuration.

Catégorie 1 — Chevauchements logiques

Deux automations partageant ≥ 80% des mêmes déclencheurs ET ciblant les mêmes entités avec des effets similaires → issue redundancy_overlap. L'IA propose de les fusionner.

Catégorie 2 — Candidates à la blueprintisation

Quand ≥ 3 automations sont structurellement identiques → issue redundancy_blueprint_candidate avec bouton Générer Blueprint.

Catégorie 3 — Remplaçables par des fonctionnalités HA natives

Conformité

Audit de la qualité des métadonnées de votre configuration : noms lisibles, zones, icônes, labels et unique_id.

Types de checks disponibles

Configuration

Dans l'onglet Config de H.A.C.A, section Conformité : chaque type de check peut être activé ou désactivé individuellement.

Corrections

Les issues de conformité ne nécessitent pas d'IA pour être corrigées — elles pointent vers des paramètres simples à renseigner directement dans l'interface HA. Utilisez les boutons Ouvrir dans HA de chaque carte pour accéder directement à la page de configuration correspondante.

Helpers

Onglet dédié à tous vos helpers d'entrée avec détection des helpers jamais utilisés.

Types de helpers surveillés

Détection des helpers inutilisés

H.A.C.A vérifie chaque helper dans les automations, scripts et dashboards. Un helper non référencé génère une issue :

• unused_input_helper — Helper jamais utilisé dans une automation ou un script (MEDIUM)
• unused_timer_helper — Timer non référencé dans une automation, script ou dashboard (LOW)

Graphe de scripts

Analyse les chaînes d'appel entre scripts pour détecter cycles, profondeur excessive et orphelins.

Types d'issues détectées

Graphe de dépendances

Visualisation D3.js force-directed de toutes les dépendances entre entités, automations, scripts et scènes.

Exports disponibles

Navigation dans le graphe

• Zoom — molette de la souris ou pinch sur mobile
• Déplacer — clic + drag sur le fond
• Nœud — clic pour ouvrir la sidebar de relations
• Filtres — barre de filtres en haut pour afficher uniquement certains types de nœuds

Intelligence Artificielle

H.A.C.A utilise votre LLM HA existant via une intégration native. Aucune clé API supplémentaire requise.

Providers supportés

Tout agent conversation configuré dans HA est utilisable :

Fallback automatique

Si l'agent préféré échoue (quota dépassé, timeout, erreur), H.A.C.A essaie automatiquement l'agent suivant disponible. L'agent préféré de vos Assistants vocaux est toujours essayé en premier.

Explication des issues

Le bouton 🤖 IA génère pour chaque issue :

• Pourquoi c'est un problème dans votre contexte
• Quel risque cela représente concrètement
• Comment le corriger (ou l'IA l'exécute directement)
• Bonnes pratiques liées à ce type d'issue

Optimiseur d'automatisations complexes

Pour les automatisations avec un score de complexité ≥ 15, le bouton Optimiser ouvre le Chat avec un prompt complet incluant le YAML de l'automatisation. L'IA propose :

• Extraction en scripts réutilisables
• YAML modernisé et simplifié
• Suggestion de blueprint si applicable

Agent IA Proactif

L'agent en arrière-plan génère un rapport automatique à la fréquence configurée (quotidien / hebdomadaire / mensuel). Il détecte aussi des corrélations entre les issues : par exemple, si 3 automations liées à la même zone ont toutes des problèmes similaires.

Chat IA

Assistant conversationnel avec accès à 65 outils MCP — lire, créer, modifier et recharger toute configuration HA en langage naturel.

Exemples de requêtes

"Crée un blueprint à partir de l'automatisation lumières_cuisine
et applique-le aux 3 pièces similaires"

"Analyse les 5 automations avec le plus fort impact Recorder
et génère un bloc d'exclusion YAML"

"Renomme toutes les entités de la zone Salon pour suivre la
convention snake_case"

"Y a-t-il des automations qui se chevauchent logiquement ?
Montre-les moi et propose une fusion."

"Crée une scène 'Soirée cinéma' avec les lumières du salon à 20%"

Capacités

Rate limiting

Un délai minimum de 3 secondes est imposé entre les messages pour protéger vos quotas IA. Un message de confirmation s'affiche si vous envoyez trop vite.

Conversation ID

Le Chat maintient un conversation_id pour que l'IA se souvienne du contexte d'une message à l'autre au sein de la même session. Rafraîchir la page démarrera une nouvelle conversation.

Serveur MCP — 65 outils

Serveur Model Context Protocol intégré qui expose tous les outils H.A.C.A et HA aux agents IA externes.

Connexion

# URL du serveur MCP
http://homeassistant.local:8123/api/haca/mcp

# Header d'authentification
Authorization: Bearer <votre-token-haca>

# Token créé dans HA
Paramètres → Votre profil → Sécurité → Tokens d'accès longue durée

Agents supportés

65 outils — 11 catégories

Sécurité

Tous les outils destructifs requièrent un token admin. H.A.C.A vérifie les droits administrateur côté serveur avant d'exécuter toute action d'écriture. Les chemins de fichiers sont validés avec os.path.realpath() pour prévenir le path traversal.

Tous les types d'issues

Tableau complet. Légende fix : Auto automatique · Modale IA champ texte éditable · Chat IA prompt MCP · Manuel édition directe dans HA.

Services HA

# Scans
service: config_auditor.scan_all
service: config_auditor.scan_automations
service: config_auditor.scan_entities
service: config_auditor.scan_compliance

# Preview + Fix (backup auto + rollback si reload échoue)
service: config_auditor.preview_device_id
data: { automation_id: "abc123" }

service: config_auditor.fix_device_id
data: { automation_id: "abc123", dry_run: false }

service: config_auditor.restore_backup
data: { backup_path: ".haca_backups/automations_20260314.yaml" }

# Rapport
service: config_auditor.generate_report
data: { format: pdf }   # pdf | markdown | json | all

# Purge Recorder
service: config_auditor.purge_recorder_orphans

Configuration

Options

Structure des fichiers

/config/
├── custom_components/config_auditor/
├── .haca_backups/
│   └── automations_20260314_143022.yaml
└── .haca_reports/
    ├── haca_report_20260314.pdf
    ├── haca_report_20260314.md
    └── haca_report_20260314.json

Niveaux de log

logger:
  logs:
    custom_components.config_auditor: debug

Architecture

Guide développeur

Patterns obligatoires

Écriture YAML — _safe_write_and_reload

# ❌ Dangereux
auto_file.write_text(new_yaml)
await hass.services.async_call("automation", "reload", blocking=True)

# ✅ Atomique + rollback si reload échoue
await _safe_write_and_reload(hass, auto_file, new_yaml, "automation")

Always async

# ✅ Non-bloquant
async def async_load_yaml(hass, path):
    return await hass.async_add_executor_job(lambda: yaml.safe_load(open(path)))

Shadow DOM — appender au body

// ✅ Toujours visible
document.body.appendChild(modal);

Build JS — toujours modifier src/*.js

# 1. Modifier dans www/src/ (jamais haca-panel.js directement)
# 2. Builder
cd www && bash build.sh
# 3. Ctrl+Shift+R dans le navigateur

Ajout d'un module analyseur

Tests

pip install pytest pytest-asyncio homeassistant --break-system-packages
python -m pytest custom_components/config_auditor/tests/ -v
python -m pytest custom_components/config_auditor/tests/test_llm_api.py -v

Contribuer à H.A.C.A

Toute contribution est bienvenue — bug fix, nouvelle fonctionnalité, documentation ou traduction.

Workflow Git

# 1. Fork + clone
git clone https://github.com/VOTRE_USERNAME/ha-config-auditor.git
cd ha-config-auditor

# 2. Branche feature
git checkout -b feature/ma-fonctionnalite

# 3. Développer et tester
python -m pytest custom_components/config_auditor/tests/ -v
cd www && bash build.sh

# 4. Commit (Conventional Commits)
git commit -m "feat: add configurable report frequency"
git commit -m "fix: _async_find_all_ai_task_entities entity_registry match"
git commit -m "security: add @require_admin to handle_apply_field_fix"

# 5. Push + Pull Request
git push origin feature/ma-fonctionnalite

Checklist Pull Request

• Tests unitaires ajoutés/mis à jour pour les nouvelles fonctionnalités
• python -m pytest tests/ passe sans erreur (0 failed)
• cd www && bash build.sh si le JS a été modifié
• Traductions FR et EN mises à jour si nouveaux textes UI
• 13 langues synchronisées (toutes les clés présentes dans chaque fichier)
• CHANGELOG.md et CHANGELOG_fr.md mis à jour
• Version mise à jour dans const.py, manifest.json et translations/*.json
• Handlers WebSocket destructifs protégés par @require_admin
• Pas de secrets ou données personnelles dans le code

Bonnes pratiques HA

Liens utiles

• Repository GitHub
• Signaler un bug
• Documentation HA Developer