ha_explore/README.md

HA Entity Scanner & Manager

Webapp self-hosted pour scanner, lister, filtrer et gérer les entités Home Assistant. UI en français, orientée admin.

Fonctionnalités

• Scanner les entités HA (REST API + WebSocket registry)
• Lister avec tri, pagination, recherche texte
• Filtrer par domaine, état, disponibilité, device_class, intégration, zone
• Gérer : favori, ignorer, désactiver/réactiver
• Désactivation via HA entity_registry (WebSocket) avec fallback local
• Journal des actions (audit log)

Installation (Docker)

# Cloner le projet
git clone <url> && cd ha_explore

# Configurer
cp .env.example .env
# Éditer .env avec votre HA_BASE_URL et HA_TOKEN

# Lancer
docker-compose up --build

L'application est accessible sur http://localhost:8080.

Variables d'environnement

Variable	Description	Défaut
HA_BASE_URL	URL de Home Assistant	http://10.0.0.2:8123
HA_TOKEN	Token d'accès longue durée HA	(requis)

Développement

Backend

cd backend
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

Frontend

cd frontend
npm install
npm run dev

Le frontend (port 5173) proxy les appels /api vers le backend (port 8000).

Tests

cd backend
pytest -v

Architecture

frontend/     Vue 3 + Vuetify 3 (SPA)
backend/      FastAPI + SQLite (SQLModel)
  app/
    routers/  health, scan, entities, actions, audit
    services/ scanner, entity_actions
    models.py, database.py, ha_client.py, config.py

API Endpoints

Méthode	Route	Description
GET	/api/health	État app + connexion HA + statut scan
POST	/api/scan	Lance un scan asynchrone (202)
GET	/api/entities	Liste paginée + filtres
GET	/api/entities/{id}	Détails d'une entité
POST	/api/entities/actions	Actions bulk (disable/enable/favorite/ignore)
GET	/api/audit	Journal des actions

Limitations

Désactivation des entités

Deux modes existent selon le type d'entité :

1. Désactivation HA réelle : via config/entity_registry/update (WebSocket). Fonctionne pour les entités enregistrées dans le registry HA. L'entité est marquée disabled_by: "user" côté HA.

2. Fallback local : si la désactivation via registry échoue (entité non enregistrée, erreur WS), l'entité est marquée ignored_local: true en base locale. Elle reste active côté HA mais est masquée dans l'app.

L'UI indique clairement le mode utilisé via des badges distincts.