aissia/plans/PROMPT_WEBMODULE.md

# Prompt pour Implémenter WebModule

Salut ! Je reprends l'implémentation du **WebModule** pour AISSIA.

## Contexte

AISSIA est un assistant vocal agentique en C++17 basé sur GroveEngine. Le projet utilise une architecture modulaire avec hot-reload et communication pub/sub via IIO.

**État actuel** :
- ✅ 6 modules fonctionnels (Scheduler, Notification, Monitoring, AI, Voice, Storage)
- ✅ 110/110 tests passent
- ✅ LLM Service avec Claude Sonnet 4
- ✅ HttpClient.hpp déjà implémenté et fonctionnel

## Objectif

Implémenter un **WebModule** qui permet aux autres modules de faire des requêtes HTTP de manière dynamique via IIO pub/sub.

## Plan d'Implémentation

Le plan complet est dans `plans/webmodule-implementation.md`. Lis-le attentivement avant de commencer.

**Résumé des étapes** :

### Phase 1: Core Module (1h)
1. Créer `src/modules/WebModule.h` (voir plan section 2.1)
2. Créer `src/modules/WebModule.cpp` (voir plan section 2.1)
3. Créer `config/web.json` (voir plan section 2.2)
4. Ajouter le module au `CMakeLists.txt`
5. Ajouter le module au `src/main.cpp`

### Phase 2: Tests (1h)
6. Créer `tests/modules/WebModuleTests.cpp` (10 tests - voir plan section 2.3)
7. Exécuter et valider tous les tests

### Phase 3: Documentation (30min)
8. Mettre à jour `README.md`
9. Mettre à jour `CLAUDE.md`
10. Créer un exemple d'utilisation

## Contraintes Importantes

### Règles GroveEngine (voir CLAUDE.md)
- **200-300 lignes max** par module
- **Logique métier pure** : pas de threading/network dans les modules
- **Communication JSON** via IIO pub/sub
- **Hot-reload ready** : sérialiser l'état dans `getState()` / `setState()`

### Protocole IIO

**Requête** (`web:request`) :
```json
{
    "requestId": "unique-id-123",
    "url": "https://api.example.com/data",
    "method": "GET",
    "headers": {},
    "body": "",
    "timeoutMs": 30000
}
```

**Réponse** (`web:response`) :
```json
{
    "requestId": "unique-id-123",
    "success": true,
    "statusCode": 200,
    "body": "{...}",
    "durationMs": 234
}
```

### Réutiliser l'existant

**IMPORTANT** : Utilise `src/shared/http/HttpClient.hpp` qui est déjà implémenté et fonctionnel. Regarde comment il est utilisé dans `src/shared/llm/ClaudeProvider.cpp` pour un exemple.

Exemple d'utilisation :
```cpp
#include "../shared/http/HttpClient.hpp"

HttpClient client;
HttpResponse response = client.get("https://example.com");
// response.statusCode, response.body, response.headers
```

## Fichiers à Créer/Modifier

**Nouveaux fichiers** :
- [ ] `src/modules/WebModule.h`
- [ ] `src/modules/WebModule.cpp`
- [ ] `config/web.json`
- [ ] `tests/modules/WebModuleTests.cpp`

**Fichiers à modifier** :
- [ ] `CMakeLists.txt` (ajouter WebModule target)
- [ ] `src/main.cpp` (charger WebModule)
- [ ] `README.md` (documenter WebModule)

## Tests à Implémenter

Liste des 10 tests (voir plan section 2.3) :
1. `TI_WEB_001_SimpleGetRequest`
2. `TI_WEB_002_PostRequestWithBody`
3. `TI_WEB_003_InvalidUrlHandling`
4. `TI_WEB_004_TimeoutHandling`
5. `TI_WEB_005_MultipleConcurrentRequests`
6. `TI_WEB_006_RequestIdTracking`
7. `TI_WEB_007_StatisticsTracking`
8. `TI_WEB_008_StateSerialization`
9. `TI_WEB_009_ConfigurationLoading`
10. `TI_WEB_010_ErrorResponseFormat`

Utilise le pattern des tests existants (voir `tests/modules/AIModuleTests.cpp` pour exemple).

## Validation

Avant de considérer le travail terminé :

### Build & Tests
```bash
# Build
cmake --build build --target modules -j4
cmake --build build --target aissia_tests -j4

# Tests
./build/tests/aissia_tests "[web]"

# Vérifier que tous les tests passent toujours
./build/tests/aissia_tests --reporter compact
```

**Critère de succès** : 120/120 tests passent (110 existants + 10 nouveaux)

### Hot-Reload
Teste manuellement le hot-reload :
```bash
# 1. Lance AISSIA
./run.sh

# 2. Modifie WebModule.cpp (change un log)

# 3. Rebuild juste le module
cmake --build build --target modules

# 4. Vérifie que le module se recharge automatiquement
# Les stats doivent être préservées
```

### Code Review
- [ ] Pas de warnings de compilation
- [ ] Code suit le style existant
- [ ] Commentaires clairs
- [ ] Gestion d'erreurs complète
- [ ] Logs informatifs

## Commandes Utiles

```bash
# Build complet
cmake -B build && cmake --build build -j4

# Build modules seulement
cmake --build build --target modules

# Tests avec filtre
./build/tests/aissia_tests "[web]"

# Tous les tests
./build/tests/aissia_tests --reporter compact

# Git
git add -A
git commit -m "feat: Add WebModule for HTTP requests via IIO"
git push
```

## Ressources

### Fichiers de référence
- `src/modules/AIModule.cpp` - Exemple de module bien structuré
- `src/modules/MonitoringModule.cpp` - Exemple de pub/sub IIO
- `src/shared/http/HttpClient.hpp` - Client HTTP à réutiliser
- `src/shared/llm/ClaudeProvider.cpp` - Utilisation de HttpClient
- `tests/modules/AIModuleTests.cpp` - Pattern de tests

### Documentation
- `plans/webmodule-implementation.md` - Plan complet détaillé
- `docs/GROVEENGINE_GUIDE.md` - Guide GroveEngine complet
- `CLAUDE.md` - Règles de développement

## Notes Importantes

1. **Pas de threading** : Les requêtes HTTP sont synchrones via HttpClient. C'est OK car le module process() est appelé dans la main loop.

2. **State management** : Les stats (total, success, failed) doivent être sauvegardées dans `getState()` et restaurées dans `setState()` pour le hot-reload.

3. **Error handling** : Toutes les erreurs doivent être catchées et transformées en message `web:response` avec `success: false`.

4. **Request ID** : Le `requestId` permet aux modules clients de matcher les requêtes/réponses. C'est crucial pour le pub/sub asynchrone.

5. **Testing** : Utilise MockIO pour les tests (voir tests existants). Pas besoin de vrai serveur HTTP, les tests peuvent mocker les réponses.

## Questions Fréquentes

**Q: Comment tester sans vrai serveur HTTP ?**
R: Utilise MockIO pour injecter des messages `web:request` et vérifier les `web:response`. Tu peux aussi créer un simple echo server en Python pour les tests d'intégration (optionnel).

**Q: Le module doit-il gérer le retry ?**
R: Non, pas dans la v1. Le module client doit gérer le retry s'il en a besoin.

**Q: Faut-il supporter websockets ?**
R: Non, seulement HTTP/HTTPS classique pour la v1.

**Q: Cache HTTP ?**
R: Non pour la v1. C'est une extension future (voir plan section 7).

---

**Bonne chance !** Suis le plan étape par étape et n'hésite pas si tu as des questions. L'objectif est d'avoir un module clean, testé, et qui s'intègre parfaitement avec l'architecture existante.

**Timeline suggérée** :
- Jour 1 : Phase 1 (Core Module)
- Jour 2 : Phase 2 (Tests)
- Jour 3 : Phase 3 (Documentation) + Validation finale

**Auteur du plan** : Claude Code (Session précédente)
**Date** : 2025-11-28