gilles/ha_explore
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
ha_explore/consigne.md
gilles 1b8bf79d46 first
2026-02-21 16:55:10 +01:00

7.3 KiB
Raw Permalink Blame History

CONSIGNE — Claude Code — Webapp “HA Entity Scanner & Manager”

Objectif

Développer une webapp self-hosted (Docker) qui se connecte à Home Assistant (URL : http://10.0.0.2:8123 et token:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhNjI1NzkyYjZhZmE0MTliOTEwMmFiMGQ4YjExNDZjNiIsImlhdCI6MTc3MTY4MTE2NSwiZXhwIjoyMDg3MDQxMTY1fQ.uus2-4HCDFajj2oFPiiW9b3KjhxF-DdhFN0XuZ_n5E8) pour :

  1. Scanner / récupérer la liste des entités,
  2. Afficher une page web avec liste + filtres,
  3. Permettre de désactiver une ou plusieurs entités (ou, si la désactivation native n’est pas possible via API HA, fournir une alternative fiable et clairement indiquée à l’utilisateur).

Contraintes et attentes générales

  • Langue UI : français.
  • UI : claire, orientée “admin”, table + panneaux, responsive.
  • Architecture standard : Backend API + Frontend.
  • Stockage : SQLite par défaut (persistant via volume Docker).
  • Auth : au minimum token HA côté backend (jamais exposé côté frontend). Idéalement variable d’environnement.
  • Journalisation : logs backend lisibles + page “Journal” simple (dernières actions : scan, désactivation, erreurs).
  • Fournir un README (installation, variables d’env, utilisation).
  • Ne jamais bloquer l’UI : scan asynchrone + état d’avancement.

Périmètre fonctionnel (MVP)

A. Connexion Home Assistant

  • Paramètres :
    • HA_BASE_URL = http://10.0.0.2:8123
    • HA_TOKEN = eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhNjI1NzkyYjZhZmE0MTliOTEwMmFiMGQ4YjExNDZjNiIsImlhdCI6MTc3MTY4MTE2NSwiZXhwIjoyMDg3MDQxMTY1fQ.uus2-4HCDFajj2oFPiiW9b3KjhxF-DdhFN0XuZ_n5E8
  • Tester la connexion via l’API REST Home Assistant.
  • Si erreur : message UI explicite (HTTP code + cause probable).

B. Récupération des entités

  • Récupérer la liste des entités (au minimum : entity_id, state, attributes, last_changed, last_updated).
  • Normaliser les champs utiles pour l’affichage :
    • domain (ex: light, switch, sensor)
    • friendly_name
    • device_class, unit_of_measurement, icon
    • area_id / device_id / integration si accessibles (sinon marquer “non disponible”)
    • booléen is_hidden / is_disabled / is_available si déductible
  • Mettre en cache en base (table entities_cache) et timestamp du dernier scan.

C. UI de listing + actions

  • Page principale : tableau (virtualisé si besoin) avec colonnes configurables.
  • Action : sélection multiple (checkbox) + actions en lot :
    • “Désactiver”
    • “Réactiver” (si applicable)
    • “Masquer (UI)” (fallback si désactivation native impossible)
  • Afficher un panneau “Détails” à droite quand on clique une entité :
    • attributs bruts JSON
    • infos clés (domain, nom, device_class, etc.)
    • boutons d’action sur cette entité

“Désactiver une entité” — règles d’implémentation

Home Assistant n’offre pas toujours une “désactivation” universelle via une simple API REST. Claude Code doit :

  1. Rechercher la méthode la plus correcte selon le type d’entité :
    • Si l’entité est gérable via registry (entity_registry / device_registry) via WebSocket API, utiliser la méthode officielle.
    • Sinon, proposer un fallback :
      • “Masquer” (côté HA si possible via registry) ou “Ignorer dans l’app” (flag local DB) avec libellé clair.
      • Option “Désactiver en empêchant les services” : non (trop intrusif) sauf si explicitement demandé.
  2. L’UI doit indiquer clairement ce que fait l’action (désactivation HA réelle vs masquage/ignore local).
  3. Toute action doit être journalisée (quoi, qui, quand, résultat, erreur).

Brainstorming — filtres “judicieux” à implémenter

Implémenter une barre de filtres combinables + chips actives :

  1. Recherche texte (entity_id, friendly_name).
  2. Domain (multi-select) : light/switch/sensor/… + compteur par domaine.
  3. État :
    • state exact (on/off/…)
    • “Indisponible” (unavailable, unknown)
  4. Disponibilité :
    • disponibles vs indisponibles
  5. Dernier changement :
    • “modifié dans les 5 min / 1 h / 24 h”
  6. Attributs :
    • device_class (multi-select)
    • unit_of_measurement (multi-select)
  7. Source / intégration (si accessible) :
    • ZHA / Zigbee2MQTT / ESPHome / MQTT / Tapo / Reolink / …
  8. Zone / Pièce (area) si accessible.
  9. Entités problématiques (smart filters) :
    • “spam logbook” : change très souvent (détecter fréquence)
    • “entités orphelines” : pas de device_id / integration inconnue
    • “noms manquants” : pas de friendly_name
  10. Statut de gestion (dans l’app) :
  • “Désactivées”
  • “Masquées”
  • “Ignorées localement”
  1. Favoris :
  • Marquer favori (flag local) pour accès rapide.

UX attendue

  • En-tête :
    • bouton “Scanner maintenant”
    • indicateur “Dernier scan : …”
    • statut connexion HA (OK/KO)
  • Zone filtres :
    • champ recherche + filtres en dropdown + chips
  • Table :
    • tri colonnes (domain, nom, last_changed, state)
    • pagination ou virtual scroll
    • multi-sélection + actions groupées
  • Panneau latéral détails :
    • affichage propre des attributs JSON
    • actions rapides (désactiver/masquer/ignorer/favori)

Tech recommandée (choix par défaut)

  • Backend : Python FastAPI
    • Client HA via REST + WebSocket (si nécessaire pour registry)
    • SQLite via SQLModel ou SQLAlchemy
  • Frontend : Vue 3 + Vite (ou React si préféré), UI simple
  • Docker :
    • docker-compose.yml avec volumes (db + config)
    • variables d’environnement pour HA_BASE_URL, HA_TOKEN

Endpoints backend (à produire)

  • GET /api/health : état de l’app + état HA
  • POST /api/scan : lance un scan (asynchrone)
  • GET /api/entities : liste paginée + filtres (query params)
  • GET /api/entities/{entity_id} : détails
  • POST /api/entities/actions : actions bulk (disable/enable/hide/unhide/ignore/unignore/favorite/unfavorite)
  • GET /api/audit : dernières actions

Données (SQLite)

Tables minimales :

  • entities_cache : entity_id (PK), domain, friendly_name, state, attrs_json, last_changed, last_updated, fetched_at
  • entity_flags : entity_id (PK), ignored_local (bool), favorite (bool), notes (text)
  • audit_log : id, ts, action, entity_ids_json, result, error

Exigences qualité

  • Gestion d’erreurs explicite (HA down, token invalide, timeout).
  • Timeout réseau configurable.
  • Tests minimaux :
    • test de parsing entités
    • test filtre domain/state
    • test “action bulk” (mock HA)
  • Sécurité :
    • le token HA ne doit jamais apparaître dans le HTML/JS.
    • CORS maîtrisé.

Livrables attendus

  • Arborescence projet complète.
  • docker-compose.yml
  • Backend FastAPI prêt à lancer.
  • Frontend page unique fonctionnelle.
  • README.md clair.
  • Une section “Limitations” expliquant la différence entre :
    • désactivation réelle HA via registry (si implémentée)
    • masquage/ignore local si non possible selon entité.

Ordre de réalisation imposé

  1. Backend : health + scan + entities list (sans disable)
  2. Frontend : page liste + filtres + détails
  3. Ajout flags locaux (ignore/favorite)
  4. Implémenter “désactiver/masquer” via API HA la plus officielle possible
  5. Audit log + finitions UI + README final
Reference in New Issue View Git Blame Copy Permalink