# Tâches : Résolution du Problème de Palette Vide Cross-Machine

## Vue d'Ensemble

Ce document détaille les tâches spécifiques pour résoudre le problème de palette vide dans le Visual Workflow Builder lorsqu'utilisé sur une machine distante.

**Auteur :** Dom, Alice, Kiro - 10 janvier 2026

## Phase 1 : Service Catalogue Configurable

### Tâche 1.1 : Modification du Service Catalogue
**Priorité :** Critique  
**Estimation :** 4 heures  
**Assigné :** Équipe Frontend

#### Description
Modifier `catalogService.ts` pour supporter la détection automatique d'URL et les fallbacks multiples.

#### Sous-tâches
- [ ] Ajouter interface `CatalogServiceConfig` avec URLs multiples
- [ ] Implémenter méthode `detectBackendUrl()` avec tentatives multiples
- [ ] Ajouter gestion de cache localStorage pour URL fonctionnelle
- [ ] Implémenter timeouts et retry logic
- [ ] Ajouter logging détaillé pour diagnostic

#### Critères d'Acceptation
- Service teste automatiquement : origine courante, localhost:5004, IP locale:5004
- URL fonctionnelle mise en cache pour 24h
- Timeouts de 2s par tentative maximum
- Logs détaillés des tentatives de connexion

#### Fichiers Modifiés
- `visual_workflow_builder/frontend/src/services/catalogService.ts`

### Tâche 1.2 : Configuration Environnement
**Priorité :** Haute  
**Estimation :** 2 heures  
**Assigné :** Équipe Frontend

#### Description
Ajouter support pour configuration via variables d'environnement et paramètres URL.

#### Sous-tâches
- [ ] Ajouter variables d'environnement `REACT_APP_CATALOG_URL`
- [ ] Support paramètre URL `?catalogUrl=...`
- [ ] Interface de configuration dans les paramètres utilisateur
- [ ] Validation des URLs de configuration

#### Critères d'Acceptation
- Variables d'environnement prises en compte au build
- Paramètres URL overrident la détection automatique
- URLs invalides rejetées avec message d'erreur

#### Fichiers Modifiés
- `visual_workflow_builder/frontend/src/services/catalogService.ts`
- `visual_workflow_builder/frontend/.env.example`

## Phase 2 : Catalogue Statique de Secours

### Tâche 2.1 : Création du Catalogue Statique
**Priorité :** Critique  
**Estimation :** 6 heures  
**Assigné :** Équipe Frontend

#### Description
Créer un catalogue statique avec les actions Vision UI de base pour mode hors ligne.

#### Sous-tâches
- [ ] Créer fichier `staticCatalog.ts` avec actions de base
- [ ] Définir actions : ClickAnchor, TypeText, WaitForAnchor, ExtractText, HotKey
- [ ] Ajouter métadonnées complètes (icônes, descriptions, exemples)
- [ ] Respecter interface `VWBCatalogAction` existante
- [ ] Ajouter catégories statiques avec compteurs

#### Critères d'Acceptation
- Au moins 5 actions Vision UI de base définies
- Chaque action a nom, description, icône, paramètres, exemples
- Compatible avec interface existante du catalogue
- Organisé en catégories cohérentes

#### Fichiers Créés
- `visual_workflow_builder/frontend/src/data/staticCatalog.ts`

### Tâche 2.2 : Intégration du Fallback
**Priorité :** Critique  
**Estimation :** 4 heures  
**Assigné :** Équipe Frontend

#### Description
Intégrer le catalogue statique dans le hook `useCatalogActions` comme fallback automatique.

#### Sous-tâches
- [ ] Modifier `useCatalogActions` pour détecter échec du service
- [ ] Basculer automatiquement vers catalogue statique
- [ ] Maintenir interface identique pour composants consommateurs
- [ ] Ajouter indicateur de mode (dynamique/statique)
- [ ] Permettre retry vers mode dynamique

#### Critères d'Acceptation
- Bascule transparente vers catalogue statique en cas d'échec
- Interface hook inchangée pour composants existants
- Indicateur visuel du mode actuel
- Possibilité de forcer retry vers mode dynamique

#### Fichiers Modifiés
- `visual_workflow_builder/frontend/src/hooks/useCatalogActions.ts`

## Phase 3 : Interface Utilisateur Améliorée

### Tâche 3.1 : Indicateurs de Statut Améliorés
**Priorité :** Moyenne  
**Estimation :** 3 heures  
**Assigné :** Équipe Frontend

#### Description
Améliorer les indicateurs de statut dans la palette pour informer l'utilisateur de l'état du catalogue.

#### Sous-tâches
- [ ] Ajouter icônes distinctes pour : en ligne, hors ligne, mode statique, erreur
- [ ] Tooltips explicatifs en français pour chaque état
- [ ] Badge avec nombre d'actions disponibles
- [ ] Indicateur de dernière mise à jour
- [ ] Animation de chargement pendant détection

#### Critères d'Acceptation
- Statut clairement visible en haut de la palette
- Messages en français explicatifs
- Différenciation visuelle entre modes dynamique/statique
- Information sur nombre d'actions disponibles

#### Fichiers Modifiés
- `visual_workflow_builder/frontend/src/components/Palette/index.tsx`

### Tâche 3.2 : Messages d'Erreur et Actions Correctives
**Priorité :** Moyenne  
**Estimation :** 2 heures  
**Assigné :** Équipe Frontend

#### Description
Ajouter messages d'erreur explicatifs et boutons d'action pour résoudre les problèmes.

#### Sous-tâches
- [ ] Messages d'erreur spécifiques : réseau, service, configuration
- [ ] Bouton "Réessayer" pour recharger le catalogue
- [ ] Bouton "Forcer re-détection" pour relancer la détection d'URL
- [ ] Lien vers documentation de dépannage
- [ ] Suggestions d'actions selon le type d'erreur

#### Critères d'Acceptation
- Messages d'erreur clairs et actionnables en français
- Boutons fonctionnels pour résoudre les problèmes
- Suggestions contextuelles selon l'erreur
- Liens vers aide et documentation

#### Fichiers Modifiés
- `visual_workflow_builder/frontend/src/components/Palette/index.tsx`
- `visual_workflow_builder/frontend/src/utils/errorMessages.ts`

## Phase 4 : Tests et Validation

### Tâche 4.1 : Tests Unitaires Service Catalogue
**Priorité :** Haute  
**Estimation :** 4 heures  
**Assigné :** Équipe Test

#### Description
Créer tests unitaires complets pour le service catalogue modifié.

#### Sous-tâches
- [ ] Tests de détection automatique d'URL
- [ ] Tests de fallback vers catalogue statique
- [ ] Tests de mise en cache de configuration
- [ ] Tests de gestion d'erreurs réseau
- [ ] Tests de timeouts et retry logic

#### Critères d'Acceptation
- Couverture de code > 90% pour catalogService
- Tests de tous les scénarios de fallback
- Validation des timeouts et retry
- Tests de persistance localStorage

#### Fichiers Créés
- `tests/unit/test_catalog_service_cross_machine_10jan2026.py`

### Tâche 4.2 : Tests d'Intégration Cross-Machine
**Priorité :** Critique  
**Estimation :** 6 heures  
**Assigné :** Équipe Test

#### Description
Créer tests d'intégration pour valider le fonctionnement sur machines distantes.

#### Sous-tâches
- [ ] Test avec backend sur localhost, frontend sur IP différente
- [ ] Test avec backend indisponible (mode statique)
- [ ] Test de basculement dynamique/statique
- [ ] Test de persistance de configuration entre sessions
- [ ] Test de performance de détection d'URL

#### Critères d'Acceptation
- Tests passent sur configuration cross-machine réelle
- Validation du mode fallback automatique
- Performance de détection < 5 secondes
- Persistance de configuration fonctionnelle

#### Fichiers Créés
- `tests/integration/test_palette_cross_machine_resolution_10jan2026.py`

### Tâche 4.3 : Tests End-to-End Palette
**Priorité :** Haute  
**Estimation :** 4 heures  
**Assigné :** Équipe Test

#### Description
Valider le fonctionnement complet de la palette dans différents scénarios réseau.

#### Sous-tâches
- [ ] Test palette complète avec catalogue dynamique
- [ ] Test palette avec catalogue statique uniquement
- [ ] Test basculement en temps réel
- [ ] Test interface utilisateur (boutons, messages)
- [ ] Test drag-and-drop des actions statiques

#### Critères d'Acceptation
- Palette fonctionnelle dans tous les modes
- Actions drag-and-drop correctement
- Interface utilisateur responsive et informative
- Pas de régression sur fonctionnalités existantes

#### Fichiers Créés
- `tests/integration/test_palette_complete_cross_machine_10jan2026.py`

## Phase 5 : Documentation et Déploiement

### Tâche 5.1 : Documentation Utilisateur
**Priorité :** Moyenne  
**Estimation :** 2 heures  
**Assigné :** Équipe Documentation

#### Description
Créer documentation pour les utilisateurs sur la résolution des problèmes de catalogue.

#### Sous-tâches
- [ ] Guide de dépannage pour palette vide
- [ ] Explication des modes dynamique/statique
- [ ] Instructions de configuration manuelle
- [ ] FAQ sur problèmes réseau courants
- [ ] Captures d'écran des indicateurs de statut

#### Critères d'Acceptation
- Documentation claire et illustrée
- Procédures de dépannage étape par étape
- FAQ couvrant les cas courants
- Intégration dans l'aide contextuelle

#### Fichiers Créés
- `docs/GUIDE_RESOLUTION_PALETTE_CROSS_MACHINE_10JAN2026.md`

### Tâche 5.2 : Tests de Validation Finale
**Priorité :** Critique  
**Estimation :** 3 heures  
**Assigné :** Équipe Test

#### Description
Validation finale sur environnements réels avec différentes configurations réseau.

#### Sous-tâches
- [ ] Test sur machine locale (localhost)
- [ ] Test sur réseau local (IP privée)
- [ ] Test avec VPN/proxy
- [ ] Test avec firewall restrictif
- [ ] Test de performance et stabilité

#### Critères d'Acceptation
- Fonctionnement validé sur au moins 3 configurations différentes
- Performance acceptable dans tous les cas
- Pas de régression sur fonctionnalités existantes
- Messages d'erreur appropriés pour chaque scénario

#### Fichiers Créés
- `tests/integration/test_validation_finale_cross_machine_10jan2026.py`

## Critères de Définition de Fini (DoD)

### Pour Chaque Tâche
- [ ] Code implémenté et testé
- [ ] Tests unitaires passent avec couverture > 80%
- [ ] Documentation technique mise à jour
- [ ] Revue de code effectuée
- [ ] Tests d'intégration passent

### Pour le Projet Complet
- [ ] Palette fonctionne sur machines locales et distantes
- [ ] Fallback automatique vers catalogue statique
- [ ] Messages d'erreur clairs en français
- [ ] Performance de détection < 5 secondes
- [ ] Tests passent sur au moins 2 configurations réseau
- [ ] Documentation utilisateur complète
- [ ] Aucune régression sur fonctionnalités existantes

## Métriques de Succès

1. **Taux de succès de chargement** : > 95% sur configurations testées
2. **Temps de détection d'URL** : < 5 secondes en moyenne
3. **Couverture de tests** : > 90% pour code modifié
4. **Satisfaction utilisateur** : Messages d'erreur compréhensibles
5. **Robustesse** : Fonctionnement même avec service catalogue indisponible

## Notes d'Implémentation

### Priorités
1. **Critique** : Service catalogue configurable et catalogue statique
2. **Haute** : Tests et validation cross-machine
3. **Moyenne** : Interface utilisateur améliorée et documentation

### Dépendances
- Tâche 2.2 dépend de 2.1 (catalogue statique)
- Tâches 4.x dépendent des phases 1-3
- Tâche 5.2 dépend de toutes les autres

### Risques Techniques
- Détection d'IP locale peut échouer selon configuration réseau
- localStorage peut être désactivé dans certains environnements
- Timeouts réseau variables selon infrastructure

### Points d'Attention
- Maintenir compatibilité avec interface existante
- Éviter les régressions sur fonctionnalités actuelles
- Assurer performance acceptable même en mode fallback
- Messages d'erreur toujours en français