lafrite/zebra-power
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
293422478763d01afabb695f8496be292f9872a6
zebra-power/CLAUDE.md

9.4 KiB
Raw Blame History

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)

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

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

Manuel (développement local)

# 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

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 :

/* 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