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