83 lines
2.5 KiB
Markdown
83 lines
2.5 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
**HA Entity Scanner & Manager** — Webapp self-hosted (Docker) pour scanner, lister, filtrer et gérer les entités Home Assistant. UI en français, orientée admin.
|
|
|
|
Spécification complète : `consigne.md`
|
|
|
|
## Tech Stack
|
|
|
|
- **Backend** : Python FastAPI, SQLite (SQLModel/SQLAlchemy), client HA REST + WebSocket
|
|
- **Frontend** : Vue 3 + Vite
|
|
- **Déploiement** : Docker + docker-compose
|
|
- **Config** : variables d'environnement `HA_BASE_URL`, `HA_TOKEN`
|
|
|
|
## Architecture
|
|
|
|
Backend API (FastAPI) + Frontend SPA (Vue 3), séparés. Le backend sert de proxy vers Home Assistant — le token HA ne doit jamais être exposé côté frontend.
|
|
|
|
### Endpoints backend
|
|
|
|
| Méthode | Route | Description |
|
|
|---------|-------|-------------|
|
|
| GET | `/api/health` | État 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 entité |
|
|
| POST | `/api/entities/actions` | Actions bulk (disable/enable/hide/favorite…) |
|
|
| GET | `/api/audit` | Journal des actions |
|
|
|
|
### Base de données SQLite
|
|
|
|
- `entities_cache` : cache des entités HA (entity_id PK, domain, friendly_name, state, attrs_json, timestamps)
|
|
- `entity_flags` : flags locaux (ignored, favorite, notes)
|
|
- `audit_log` : historique des actions (action, entity_ids, result, error)
|
|
|
|
### Désactivation des entités
|
|
|
|
Deux modes selon le type d'entité :
|
|
1. **Désactivation réelle** via entity_registry/device_registry (WebSocket API HA) quand possible
|
|
2. **Fallback** : masquage/ignore local (flag en DB) — l'UI doit indiquer clairement le mode utilisé
|
|
|
|
## Build & Run Commands
|
|
|
|
```bash
|
|
# Docker
|
|
docker-compose up --build
|
|
docker-compose down
|
|
|
|
# Backend (dev)
|
|
cd backend
|
|
pip install -r requirements.txt
|
|
uvicorn app.main:app --reload --port 8000
|
|
|
|
# Frontend (dev)
|
|
cd frontend
|
|
npm install
|
|
npm run dev
|
|
|
|
# Tests
|
|
cd backend
|
|
pytest
|
|
pytest tests/test_entities.py -k "test_parse" # test unique
|
|
```
|
|
|
|
## Development Order (from spec)
|
|
|
|
1. Backend : health + scan + entities list
|
|
2. Frontend : page liste + filtres + détails
|
|
3. Flags locaux (ignore/favorite)
|
|
4. Désactiver/masquer via API HA officielle
|
|
5. Audit log + finitions UI
|
|
|
|
## Key Constraints
|
|
|
|
- UI langue française uniquement
|
|
- Scan asynchrone — ne jamais bloquer l'UI
|
|
- Token HA en variable d'environnement, jamais dans le HTML/JS
|
|
- CORS maîtrisé côté backend
|
|
- Toute action sur une entité doit être journalisée dans `audit_log`
|