feat: première version fonctionnelle
This commit is contained in:
237
CLAUDE.md
Normal file
237
CLAUDE.md
Normal file
@@ -0,0 +1,237 @@
|
||||
# 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 de serveurs via Wake-on-LAN et le contrôle de machines virtuelles Proxmox. 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.11+
|
||||
- **Framework**: FastAPI 0.104.1 avec SQLAlchemy 2.0.23
|
||||
- **Base de données**: SQLite (fichier local `./data/zebra.db`)
|
||||
- **Services**: Wake-on-LAN, API Proxmox, 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
|
||||
- **Composants**: Headless UI + Heroicons
|
||||
- **Point d'entrée**: `frontend/src/main.js`
|
||||
|
||||
### Infrastructure
|
||||
|
||||
- **Containerisation**: Docker Compose
|
||||
- **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
|
||||
├── views/ # Pages/routes principales
|
||||
├── services/ # API client
|
||||
└── main.js # Bootstrap Vue
|
||||
```
|
||||
|
||||
## Commandes de Développement
|
||||
|
||||
### Backend
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
pip install -r requirements.txt
|
||||
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
||||
```
|
||||
|
||||
### Frontend
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
npm run dev # Développement (port 3000)
|
||||
npm run build # Production
|
||||
```
|
||||
|
||||
### Docker (Production)
|
||||
|
||||
```bash
|
||||
docker-compose up -d
|
||||
docker-compose logs -f [service]
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
#### 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/servers.py` - Gestion serveurs WOL
|
||||
- `backend/app/api/wol.py` - Wake-on-LAN et ping
|
||||
- `backend/app/api/proxmox.py` - Clusters et VMs Proxmox
|
||||
|
||||
#### Services Métier
|
||||
|
||||
- `backend/app/services/wol_service.py` - Logique Wake-on-LAN
|
||||
- `backend/app/services/proxmox_service.py` - Intégration Proxmox
|
||||
- `backend/app/services/logging_service.py` - Journalisation
|
||||
|
||||
### 🔧 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
|
||||
|
||||
- `servers` - Serveurs Wake-on-LAN
|
||||
- `proxmox_clusters` - Configuration clusters
|
||||
- `action_logs` - Historique des actions
|
||||
- `wol_logs` - Logs spécifiques WOL (legacy)
|
||||
|
||||
#### 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/`
|
||||
- Codes status HTTP standards
|
||||
- JSON uniquement
|
||||
- CORS permissif (à restreindre)
|
||||
|
||||
#### Client Frontend
|
||||
|
||||
- Axios dans `services/api.js`
|
||||
- Base URL via variable d'environnement
|
||||
- Error handling centralisé
|
||||
- Loading states dans les composants
|
||||
|
||||
### ⚡ 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
|
||||
|
||||
### 🚀 Déploiement
|
||||
|
||||
#### Développement Local
|
||||
|
||||
1. Clone du repo
|
||||
2. `mkdir -p data` pour SQLite
|
||||
3. `docker-compose up -d`
|
||||
4. Interface sur http://localhost
|
||||
|
||||
#### Production
|
||||
|
||||
- Même stack Docker
|
||||
- Variables d'environnement sécurisées
|
||||
- HTTPS recommandé (nginx SSL)
|
||||
- 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
|
||||
Reference in New Issue
Block a user