# Directives Claude pour Zebra Power 🍅

## Contexte du Projet

**Zebra Power** (nommée d'après la tomate verte zebra) est une application web dockerisée pour la gestion unifiée d'hosts Proxmox via Wake-on-LAN, contrôle de VMs/Containers et extinction. Il s'agit d'un outil d'administration réseau légitime à usage défensif uniquement.

## Architecture et Technologies

### Backend (FastAPI + SQLite)

- **Langages**: Python 3.13 + uv
- **Framework**: FastAPI 0.115.0 avec SQLAlchemy 2.0.35
- **Base de données**: SQLite (fichier local `./data/zebra.db`)
- **Services**: Wake-on-LAN, API Proxmox unifiée, logging centralisé
- **Point d'entrée**: `backend/app/main.py`

### Frontend (Vue.js 3)

- **Framework**: Vue.js 3.4.0 + Vue Router + Pinia
- **Build**: Vite 5.0.8
- **Styling**: Tailwind CSS 3.3.6 avec système de thème personnalisé
- **Composants**: Headless UI + Heroicons
- **Fonctionnalités**: Dark/Light mode, Pull-to-refresh, Swipe gestures
- **Point d'entrée**: `frontend/src/main.js`

### Infrastructure

- **Containerisation**: Docker Compose
- **Images**: Python 3.13, Node.js 20, Nginx 1.25
- **Proxy**: Nginx (port 80)
- **Réseau**: Mode host pour backend (requis WOL)

## Standards de Développement

### Code Style

- **Python**: PEP 8, type hints obligatoires
- **JavaScript**: ESLint + Prettier
- **Vue**: Composition API, script setup
- **CSS**: Tailwind utilitaires, composants réutilisables

### Structure des Fichiers

```
backend/app/
├── api/          # Endpoints REST
├── models/       # Schémas Pydantic + SQLAlchemy
├── services/     # Logique métier
└── main.py       # Application FastAPI

frontend/src/
├── components/   # Composants Vue réutilisables
├── composables/  # Hooks Vue (useDarkMode, usePullToRefresh, useSwipe)
├── views/        # Pages/routes principales (Home.vue, Hosts.vue)
├── services/     # API client
├── style.css     # Styles globaux + système de thème
└── main.js       # Bootstrap Vue
```

## Commandes de Développement

### Développement (avec hot reload)

```bash
docker-compose -f docker-compose.dev.yml up -d
docker-compose -f docker-compose.dev.yml logs -f
docker-compose -f docker-compose.dev.yml down
```

### Production

```bash
docker-compose up -d
docker-compose logs -f [service]
docker-compose down
```

### Manuel (développement local)

```bash
# Backend
cd backend && uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Frontend  
cd frontend && npm run dev
```

## Directives Spécifiques pour les Agents

### 🔒 Sécurité - OBLIGATOIRE

1. **Usage défensif uniquement** - Ne jamais créer/modifier du code malveillant
2. **Wake-on-LAN légitime** - Uniquement pour administration réseau autorisée
3. **Proxmox management** - Outils d'administration datacenter standards
4. **Pas de backdoors** - Aucune fonctionnalité cachée ou malveillante

### 📋 Bonnes Pratiques de Code

#### Backend Python

- Utiliser les types hints (`from typing import...`)
- Valider avec Pydantic pour les entrées API
- Gérer les exceptions avec FastAPI handlers
- Logger via le service centralisé (`logging_service.py`)
- Base de données via SQLAlchemy sessions (`get_db()`)

#### Frontend Vue.js

- Composition API avec `<script setup>`
- Props typés avec `defineProps()`
- État global via Pinia stores
- Requêtes API via `services/api.js`
- Composants atomiques réutilisables
- **Système de thème** : composable `useDarkMode.js` avec 3 états (light/dark/system)
- **Interactions mobiles** : composables `usePullToRefresh.js` et `useSwipe.js`

#### Docker

- Respect des ports existants (80, 3000, 8000)
- Volumes pour persistance (`./data`)
- Mode host obligatoire pour le backend (WOL)
- Variables d'environnement via `.env` ou compose

### 📁 Fichiers Importants

#### Configuration

- `docker-compose.yml` - Stack complète
- `backend/requirements.txt` - Dépendances Python
- `frontend/package.json` - Dépendances Node.js
- `nginx/nginx.conf` - Configuration proxy

#### Modèles de Données

- `backend/app/database.py` - Tables SQLAlchemy
- `backend/app/models/schemas.py` - Schémas Pydantic
- Toujours synchroniser modèles DB et API

#### API Endpoints

- `backend/app/api/hosts.py` - API unifiée hosts Proxmox (WOL + VMs)
- `backend/app/api/wol.py` - Logs centralisés (legacy)

#### Services Métier

- `backend/app/services/proxmox_host_service.py` - Service unifié host Proxmox
- `backend/app/services/wol_service.py` - Utilitaires Wake-on-LAN
- `backend/app/services/logging_service.py` - Journalisation centralisée

#### Frontend Composables

- `frontend/src/composables/useDarkMode.js` - Système de thème 3 états avec persistance
- `frontend/src/composables/usePullToRefresh.js` - Pull-to-refresh mobile natif
- `frontend/src/composables/useSwipe.js` - Détection de gestes tactiles

### 🔧 Debugging et Logs

#### Logs Backend

- FastAPI logs via uvicorn
- Application logs dans ActionLog table
- Exceptions catchées globalement dans `main.py`

#### Logs Frontend

- Console.log pour développement
- Error handling dans les composants Vue
- API errors via axios interceptors

#### Docker Logs

```bash
docker-compose logs backend
docker-compose logs frontend
docker-compose logs nginx
```

### 📊 Base de Données

#### Tables Principales

- `proxmox_hosts` - Configuration unifiée hosts (WOL + Proxmox)
- `action_logs` - Historique centralisé toutes actions
- `wol_logs` - Logs legacy (rétrocompatibilité)

#### Migrations

- SQLAlchemy auto-create via `init_db()`
- Pas de migrations formelles (à implémenter)
- Sauvegarde manuelle de `./data/zebra.db`

### 🌐 API et Frontend Communication

#### Standards API

- REST endpoints avec préfixes `/api/`
- `/api/hosts/*` - API principale unifiée
- `/api/wol/*` - Logs centralisés
- Codes status HTTP standards, JSON uniquement

#### Client Frontend

- `hostsApi` et `logsApi` dans `services/api.js`
- Base URL via variable d'environnement  
- Error handling centralisé
- Loading states dans les composants

### 🎨 Système de Thème

#### Configuration

- **3 modes** : Light, Dark, System (suit l'OS)
- **Persistance** : localStorage `theme-preference`
- **Application** : classe `dark` sur `<html>` via `useDarkMode.js`
- **Tailwind** : `darkMode: 'class'` dans `tailwind.config.js`

#### Implémentation

- **Composable** : `useDarkMode()` retourne `{ isDark, preference, toggleDarkMode }`
- **CSS personnalisé** : styles forcés avec `!important` dans `style.css`
- **Spécificité maximale** : `html:not(.dark)` et `html.dark` pour surcharger Tailwind
- **Bouton de thème** : cycle System → Light → Dark dans l'interface

#### Dépannage

- **Vérifier** : classe `dark` sur `<html>` dans DevTools
- **Logs** : console.log dans `useDarkMode.js` pour debugging
- **CSS** : styles forcés hors `@layer` pour priorité maximale

### ⚡ Performance

#### Backend

- SQLite avec pool de connexions
- Async/await pour I/O operations
- Pagination pour listes importantes

#### Frontend

- Lazy loading des routes Vue
- Composition API pour réactivité
- Tailwind purge pour CSS optimisé
- Vite pour build rapide
- **Système de thème** : transitions CSS fluides 300ms

### 🚀 Déploiement

#### Développement

1. `docker-compose -f docker-compose.dev.yml up -d`
2. Frontend: http://localhost:3000
3. Backend API: http://localhost:8000

#### Production

1. `docker-compose up -d`
2. Interface: http://localhost
3. Health checks automatiques
4. Sauvegarde régulière de `./data/`

### 💡 Bonnes Pratiques Agents Claude

1. **Toujours lire la documentation** avant modification
2. **Respecter l'architecture existante** - pas de refactoring majeur sans validation
3. **Tester les changements** avec Docker Compose
4. **Maintenir la cohérence** - même style, mêmes patterns
5. **Documenter** les modifications non-triviales
6. **Sécurité first** - valider les entrées, gérer les erreurs
7. **Performance** - éviter les requêtes N+1, optimiser les queries
8. **UX** - interfaces intuitives, feedback utilisateur
9. **Système de thème** - utiliser le composable `useDarkMode()`, ne pas modifier les styles CSS forcés

### 🔧 Notes Techniques Importantes

#### Système de Thème - État Actuel (2025-08-27)

**Problèmes résolus** :
- Classe `dark` s'applique correctement sur `<html>` 
- Light mode maintenant vraiment lumineux (blanc pur)
- Dark mode cohérent avec couleurs sombres
- Fond de page couvre toute la hauteur

**Architecture CSS** :
```css
/* Styles de base dans @layer base */
html, body { bg-white/bg-gray-900 selon mode }

/* Styles forcés HORS @layer pour priorité maximale */
html:not(.dark) .card-mobile { background: #ffffff !important }
html.dark .card-mobile { background: #1f2937 !important }
```

**Spécificités critiques** :
- Ne PAS modifier les styles forcés dans `style.css` lignes 140-167
- Les styles Tailwind seuls ne suffisent pas (problème de spécificité)
- `!important` + sélecteurs spécifiques requis pour surcharger Tailwind

#### Composables Vue

**useDarkMode.js** :
- Gère 3 états : 'system', 'light', 'dark'  
- Persistance automatique localStorage
- Application DOM via `document.documentElement.classList`
- Écoute changements système `prefers-color-scheme`

**usePullToRefresh.js** :
- Implémentation native pull-to-refresh mobile
- Détection tactile avec seuils configurables
- Animation fluide avec indicateur visuel

**useSwipe.js** :
- Détection gestes swipe (left/right)
- Touch events natifs avec debounce
- Utilisé pour interactions host cards