103 lines
2.7 KiB
Markdown
103 lines
2.7 KiB
Markdown
# 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)
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
cd backend
|
|
python -m venv venv && source venv/bin/activate
|
|
pip install -r requirements.txt
|
|
uvicorn app.main:app --reload --port 8000
|
|
```
|
|
|
|
### Frontend
|
|
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
Le frontend (port 5173) proxy les appels `/api` vers le backend (port 8000).
|
|
|
|
### Tests
|
|
|
|
```bash
|
|
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.
|