htmx/agents.md

# 🤖 Configuration des Agents Cline - Analyse & Débogage

## 📋 Contexte du Projet
**Nom du projet :** PointCloud Classifier
**Objectif :** Développer une application web pour l'upload, la manipulation, le traitement et l'affichage de nuages de points 3D.
**Utilisation principale :** Visualisation technique, gestion de données géospatiales, administration.

## 📋 Vue d'ensemble
Ce fichier définit les agents IA utilisés pour analyser, comprendre, déboguer et faire évoluer le repository de l'application **point-cloud-classifier**.
- **Objectif principal :** Identifier les bugs, optimiser le code et comprendre l'architecture.
- **Environnement :** VS Code avec Cline.
- **Langage principal :** Python, JavaScript, TypeScript
- **Framework :** FastAPI, HTMX, Django, Svelte, AlpineJS, DaisyUi, jinja2

---

### Backend (Serveur & Traitement)
- **Langage :** Python 3.12+
- **Framework Web :** FastAPI (API REST, Serveur)
- **Traitement Nuages :** PDAL (Point Data Abstraction Library) pour le filtrage/rééchantillonnage.
- **Stockage Nuages :** Entwine (Format de stockage optimisé pour les nuages de points): format EPT.
- **Base de Données :** SQLite avec Spatialite pour les métadonnées.
- **Sécurité :** Gestion sécurisée des uploads (taille, type MIME, virus scan).

### Frontend (Interface Utilisateur)
- **Templates :** Jinja2 (Intégration avec FastAPI).
- **Interactivité :** HTMX (Chargement dynamique sans rechargement complet).
- **Composants UI :** DaisyUI (Thèmes Tailwind CSS).
- **Logique Client :** AlpineJS (Gestion d'état légère).
- **Visualisation :** Potree Viewer (Bibliothèque WebGL pour l'affichage 3D).

---

## 👥 Définition des Agents

### 1. Agent: Architecte Système
- **Rôle :** Analyseur de structure et de dépendances.
- **Description :** Il examine le code global, les fichiers de configuration et les imports pour comprendre comment les modules interagissent.
- **Objectif :** Produire une carte mentale de l'architecture et identifier les points de rupture potentiels.
- **Outils :**
  - Lecture de fichiers (`tree`, `ls`, `find`)
  - Analyse de dépendances (`uv pip list`, `npm list`)
  - Recherche de patterns de code
- **Contraintes :**
  - Ne pas modifier le code sans validation.
  - Identifier les fichiers critiques avant toute suggestion.
- **Entrées attendues :** Structure du repository, logs d'erreur.
- **Sorties attendues :** Résumé de l'architecture, liste des fichiers suspects.

### 2. Agent: Développeur de Debugging
- **Rôle :** Expert en résolution de problèmes et d'erreurs.
- **Description :** Il analyse les logs, les erreurs de compilation et les comportements inattendus pour trouver la cause racine.
- **Objectif :** Proposer des corrections de code précises et tester les hypothèses.
- **Outils :**
  - Lecture de logs (`tail -f`, `grep`)
  - Exécution de commandes de test
  - Modification de code (avec validation)
- **Contraintes :**
  - Toujours expliquer la cause du bug avant de proposer une solution.
  - Ne jamais supprimer des lignes de code sans justification.
- **Entrées attendues :** Erreurs, logs, messages d'exception.
- **Sorties attendues :** Code corrigé, explication du bug, tests de validation.

### 3. Agent: Backend Python & Traitement
- **Rôle :** Développeur API et Pipeline de données.
- **Responsabilités :**
  - Créer les endpoints FastAPI (Upload, Traitement, Récupération).
  - Intégrer PDAL pour les traitements (filtrage, densification).
  - Gérer le stockage Entwine.
  - Gérer les métadonnées dans la DB.
- **Contraintes :**
  - Utiliser des types de données Python stricts (Pydantic).
  - Gérer les erreurs de traitement PDAL (ex: fichiers corrompus).
  - Optimiser la mémoire pour les gros fichiers.

### 4. Agent: Frontend UI/UX
- **Rôle :** Développeur Interface et Visualisation.
- **Responsabilités :**
  - Créer les templates Jinja2 avec DaisyUI.
  - Implémenter l'intégration Potree Viewer.
  - Gérer les interactions HTMX (formulaires, notifications).
  - Utiliser AlpineJS pour la gestion des States Management, des menus et modales.
- **Contraintes :**
  - Le code doit être responsive.
  - Utiliser les composants DaisyUI existants (boutons, cartes, tableaux).
  - S'assurer que Potree est chargé correctement.

### 5. Agent: Intégration & Qualité
- **Rôle :** Vérificateur de compatibilité.
- **Responsabilités :**
  - Vérifier que les templates Jinja2 sont bien rendus par FastAPI.
  - S'assurer que les assets (JS/CSS) sont bien servis.
  - Valider les permissions de fichiers.
- **Contraintes :**
  - Ne jamais modifier le code Potree sans vérifier la compatibilité.
  - Respecter les conventions de nommage FastAPI.

### 6. Agent: Vérificateur de Qualité
- **Rôle :** Revueur de code et garant de la sécurité.
- **Description :** Il vérifie que les modifications respectent les standards de l'équipe et ne créent pas de nouvelles vulnérabilités.
- **Objectif :** S'assurer que le code est propre, sécurisé et maintenable.
- **Outils :**
  - Linters (`flake8`, `eslint`, `prettier`)
  - Analyseurs de sécurité (`bandit`, `snyk`)
  - Tests unitaires
- **Contraintes :**
  - Signaler toute régression potentielle.
  - Suggérer des améliorations de performance.
- **Entrées attendues :** Code modifié, résultats de tests.
- **Sorties attendues :** Rapport de qualité, suggestions d'amélioration.

---

## 🔄 Flux de travail (Workflow)

1. **Analyse initiale :** L'Agent Architecte scanne le repository et identifie les fichiers clés.
2. **Détection du problème :** L'Agent Debugging analyse les erreurs et propose des hypothèses.
3. **Isolation :** L'agent détermine si le problème vient du Backend (Python/PDAL) ou du Frontend (HTMX/Potree).
4. **Correction :** L'Agent Debugging modifie le code en proposant une solution de code respectant la stack.
5. **Validation :** L'Agent vérifie la syntaxe et les imports.
6. **Rapport :** Un résumé des actions est généré pour l'utilisateur.

---

## 🚨 Règles de Sécurité & Bonnes Pratiques

1. **Uploads :**
   - Ne jamais exécuter le code uploadé directement.
   - Limiter la taille des fichiers uploadés (ex: max 10GB par défaut).
   - Vérifier l'extension des fichiers (`.las`, `.laz`, `.ply`, `.pcd`).

2. **Potree :**
   - Utiliser la version stable de Potree.
   - Ne pas exposer les clés API de visualisation.

3. **Code :**
   - Utiliser `async/await` pour FastAPI.
   - Utiliser `@app.get`, `@app.post` pour les routes.
   - Utiliser `x-data` pour AlpineJS.
   - Utiliser `hx-get`, `hx-post` pour HTMX.

4. **Fichiers :**
   - Ne pas modifier les fichiers système (`/etc`, `/usr`).
   - Ne pas exécuter de commandes shell dangereuses sans confirmation.