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) :

{
    "requestId": "unique-id-123",
    "url": "https://api.example.com/data",
    "method": "GET",
    "headers": {},
    "body": "",
    "timeoutMs": 30000
}

Réponse (web:response) :

{
    "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 :

#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

# 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 :

# 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

# 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