Design — HA Entity Scanner & Manager

Date : 2026-02-21 Statut : Approuvé

Architecture globale

Frontend (Vue 3 + Vuetify 3)  ──►  Backend (FastAPI)  ──►  Home Assistant
       SPA :5173                    API :8000                  :8123
                                    SQLite DB                REST + WS

Frontend : SPA Vue 3 + Vite + Vuetify 3, appelle /api/*
Backend : FastAPI, proxy sécurisé vers HA (token jamais exposé côté client)
DB : SQLite via SQLModel, 3 tables (entities_cache, entity_flags, audit_log)
Client HA : aiohttp pour REST (/api/states) et WebSocket (/api/websocket)
Déploiement : Docker + docker-compose, variables d'env HA_BASE_URL / HA_TOKEN

Backend — structure des modules

Module	Responsabilité
`app/main.py`	App FastAPI, CORS, lifespan
`app/config.py`	Settings via pydantic-settings (env vars)
`app/models.py`	SQLModel : EntityCache, EntityFlag, AuditLog
`app/database.py`	Init SQLite, get_session
`app/ha_client.py`	Client aiohttp : REST states + WS registry
`app/routers/health.py`	`GET /api/health`
`app/routers/scan.py`	`POST /api/scan` (async background task)
`app/routers/entities.py`	`GET /api/entities`, `GET /api/entities/{id}`
`app/routers/actions.py`	`POST /api/entities/actions`
`app/routers/audit.py`	`GET /api/audit`
`app/services/scanner.py`	Logique scan : fetch + normalize + upsert DB
`app/services/entity_actions.py`	Logique disable/enable/hide via WS ou fallback

Frontend — composants principaux

Composant	Rôle
`App.vue`	Layout principal, header avec statut HA
`EntityTable.vue`	`v-data-table-server` avec tri, pagination, sélection
`FilterBar.vue`	Recherche texte + dropdowns domaine/état + chips actives
`EntityDetail.vue`	Panneau latéral détails + actions
`AuditLog.vue`	Page journal des actions
`ScanButton.vue`	Bouton scan + indicateur progression

Base de données SQLite

entities_cache

entity_id (PK), domain, friendly_name, state
attrs_json (TEXT — attributs HA complets)
device_class, unit_of_measurement, area_id, device_id, integration
is_disabled, is_hidden, is_available (booléens déduits)
last_changed, last_updated, fetched_at

entity_flags

entity_id (PK), ignored_local (bool), favorite (bool), notes (text)

audit_log

id (PK auto), ts (datetime), action (text), entity_ids_json (text), result (text), error (text)

Scan asynchrone

POST /api/scan lance une BackgroundTask FastAPI. Un état en mémoire (idle/scanning/done/error + progression) est exposé via GET /api/health. Le frontend poll le health pour afficher la progression.

Désactivation des entités

Méthode principale : WS API HA config/entity_registry/update avec disabled_by: "user"
Fallback : flag ignored_local=true en DB locale
L'UI affiche un badge distinct selon le mode utilisé (désactivé HA vs ignoré local)
Toute action journalisée dans audit_log

Choix techniques

Python FastAPI + aiohttp (client HA REST + WS)
SQLModel (SQLAlchemy + Pydantic)
Vue 3 + Vite + Vuetify 3
Docker + docker-compose
UI en français uniquement

3.3 KiB Raw Permalink Blame History