first

README.md

@@ -0,0 +1,102 @@
+# 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.