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é :

Désactivation réelle via entity_registry/device_registry (WebSocket API HA) quand possible
Fallback : masquage/ignore local (flag en DB) — l'UI doit indiquer clairement le mode utilisé

Build & Run Commands

# 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)

Backend : health + scan + entities list
Frontend : page liste + filtres + détails
Flags locaux (ignore/favorite)
Désactiver/masquer via API HA officielle
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

2.5 KiB Raw Permalink Blame History