315 lines
9.4 KiB
Markdown
315 lines
9.4 KiB
Markdown
# 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
|