rpa_vision_v3/.kiro/specs/visual-rpa-properties-enhancement/design.md

# Document de Conception: Amélioration des Propriétés RPA 100% Visuel

## Vue d'Ensemble

Cette conception transforme le Visual Workflow Builder pour qu'il soit entièrement basé sur la vision, éliminant toute référence aux sélecteurs CSS/XPath et améliorant significativement la visualisation des captures d'écran. Le système utilisera uniquement des méthodes de reconnaissance visuelle basées sur les embeddings CLIP et la détection d'objets pour identifier et cibler les éléments UI.

L'architecture s'appuie sur les composants existants du système RPA Vision V3 (FusionEngine, UIDetector, TargetResolver) tout en introduisant de nouveaux composants spécialisés pour la gestion visuelle pure et l'interface utilisateur améliorée.

## Architecture

### Composants Principaux

```mermaid
graph TB
    subgraph "Interface Utilisateur"
        VPP[VisualPropertiesPanel]
        VSS[VisualScreenSelector]
        IPA[InteractivePreviewArea]
        VMD[VisualMetadataDisplay]
    end
    
    subgraph "Logique Visuelle"
        VTM[VisualTargetManager]
        SVM[ScreenshotValidationManager]
        VEM[VisualEmbeddingManager]
        CCS[ContextualCaptureService]
    end
    
    subgraph "Système RPA Existant"
        FE[FusionEngine]
        UD[UIDetector]
        TR[TargetResolver]
        SC[ScreenCapturer]
    end
    
    VPP --> VTM
    VSS --> VTM
    VTM --> VEM
    VTM --> SVM
    VEM --> FE
    SVM --> UD
    CCS --> SC
    IPA --> CCS
```

### Flux de Données

1. **Sélection Visuelle**: L'utilisateur clique sur "Sélectionner" → Capture d'écran → Mode sélection interactive → Extraction des caractéristiques visuelles → Stockage de l'embedding
2. **Affichage des Propriétés**: Chargement de l'élément → Récupération de la capture → Validation en temps réel → Affichage enrichi
3. **Validation Continue**: Vérification périodique → Comparaison d'embeddings → Mise à jour du statut → Notifications utilisateur

## Composants et Interfaces

### 1. VisualPropertiesPanel

**Responsabilité**: Panneau principal des propriétés entièrement visuel

```typescript
interface VisualPropertiesPanelProps {
  node: VisualNode;
  onNodeUpdate: (nodeId: string, visualConfig: VisualNodeConfig) => void;
  onClose: () => void;
}

interface VisualNodeConfig {
  visualTarget?: VisualTarget;
  parameters: Record<string, any>;
  visualMetadata: VisualMetadata;
}

interface VisualTarget {
  embedding: Float32Array;
  screenshot: string; // Base64 encoded image
  boundingBox: BoundingBox;
  confidence: number;
  contextualInfo: ContextualInfo;
  signature: string; // Unique visual signature
}
```

**Fonctionnalités**:
- Affichage des captures d'écran haute qualité
- Sélection visuelle interactive
- Validation en temps réel
- Métadonnées visuelles enrichies
- Interface sans éléments techniques

### 2. VisualScreenSelector

**Responsabilité**: Sélecteur d'écran interactif pour la sélection visuelle pure

```typescript
interface VisualScreenSelectorProps {
  onElementSelected: (target: VisualTarget) => void;
  onCancel: () => void;
  isOpen: boolean;
}

interface SelectionMode {
  type: 'hover' | 'click' | 'drag';
  highlightColor: string;
  showTooltips: boolean;
}
```

**Fonctionnalités**:
- Capture d'écran en temps réel
- Détection d'éléments au survol
- Surbrillance visuelle interactive
- Extraction automatique des caractéristiques
- Validation immédiate de la sélection

### 3. InteractivePreviewArea

**Responsabilité**: Zone d'aperçu interactif pour les captures d'écran

```typescript
interface InteractivePreviewAreaProps {
  screenshot: string;
  boundingBox: BoundingBox;
  onZoom: (level: number) => void;
  onPan: (x: number, y: number) => void;
  showAnnotations: boolean;
}

interface PreviewControls {
  zoom: number;
  pan: { x: number; y: number };
  annotations: Annotation[];
  highlightTarget: boolean;
}
```

**Fonctionnalités**:
- Zoom fluide avec molette
- Navigation par glisser-déposer
- Annotations contextuelles
- Surbrillance de l'élément cible
- Contrôles de navigation intuitifs

### 4. VisualTargetManager

**Responsabilité**: Gestionnaire central pour les cibles visuelles

```typescript
class VisualTargetManager {
  async captureAndSelectElement(position: Point): Promise<VisualTarget>;
  async validateTarget(target: VisualTarget): Promise<ValidationResult>;
  async updateTargetScreenshot(target: VisualTarget): Promise<VisualTarget>;
  async findSimilarElements(target: VisualTarget): Promise<VisualTarget[]>;
  generateVisualSignature(element: UIElement): string;
}

interface ValidationResult {
  isValid: boolean;
  confidence: number;
  suggestions?: VisualTarget[];
  issues?: ValidationIssue[];
}
```

**Fonctionnalités**:
- Capture et analyse d'éléments
- Validation continue des cibles
- Génération de signatures visuelles
- Détection d'éléments similaires
- Gestion des mises à jour

### 5. VisualEmbeddingManager

**Responsabilité**: Gestion des embeddings visuels et de la reconnaissance

```typescript
class VisualEmbeddingManager {
  async generateEmbedding(screenshot: ImageData, boundingBox: BoundingBox): Promise<Float32Array>;
  async compareEmbeddings(embedding1: Float32Array, embedding2: Float32Array): Promise<number>;
  async findBestMatch(targetEmbedding: Float32Array, candidates: VisualTarget[]): Promise<MatchResult>;
  cacheEmbedding(signature: string, embedding: Float32Array): void;
}

interface MatchResult {
  target: VisualTarget;
  confidence: number;
  alternatives: VisualTarget[];
}
```

**Fonctionnalités**:
- Génération d'embeddings CLIP
- Comparaison de similarité
- Mise en cache intelligente
- Recherche de correspondances
- Optimisation des performances

## Modèles de Données

### VisualMetadata

```typescript
interface VisualMetadata {
  elementType: ElementType;
  visualDescription: string;
  relativePosition: RelativePosition;
  textContent?: string;
  contextualElements: ContextualElement[];
  visualStates: VisualState[];
  lastValidated: Date;
}

enum ElementType {
  BUTTON = 'button',
  INPUT_FIELD = 'input_field',
  LINK = 'link',
  IMAGE = 'image',
  TEXT = 'text',
  DROPDOWN = 'dropdown',
  CHECKBOX = 'checkbox',
  RADIO_BUTTON = 'radio_button',
  UNKNOWN = 'unknown'
}

interface RelativePosition {
  description: string; // "en haut à droite", "au centre", etc.
  quadrant: Quadrant;
  distanceFromEdges: EdgeDistances;
}
```

### ContextualInfo

```typescript
interface ContextualInfo {
  surroundingElements: SurroundingElement[];
  parentContainer?: ContainerInfo;
  siblingElements: SiblingElement[];
  visualHierarchy: HierarchyLevel[];
}

interface SurroundingElement {
  type: ElementType;
  position: RelativePosition;
  distance: number;
  relationship: SpatialRelationship;
}

enum SpatialRelationship {
  ABOVE = 'above',
  BELOW = 'below',
  LEFT = 'left',
  RIGHT = 'right',
  INSIDE = 'inside',
  ADJACENT = 'adjacent'
}
```

## Stratégies de Validation

### Validation en Temps Réel

```typescript
class RealtimeValidator {
  private validationInterval: number = 5000; // 5 secondes
  
  async startValidation(target: VisualTarget): Promise<void> {
    setInterval(async () => {
      const result = await this.validateTarget(target);
      this.notifyValidationResult(result);
    }, this.validationInterval);
  }
  
  private async validateTarget(target: VisualTarget): Promise<ValidationResult> {
    // 1. Capturer l'écran actuel
    // 2. Rechercher l'élément par embedding
    // 3. Comparer avec la signature originale
    // 4. Retourner le résultat avec confiance
  }
}
```

### Stratégies de Récupération

1. **Élément Non Trouvé**: Recherche d'éléments similaires dans la zone élargie
2. **Changement d'Apparence**: Proposition de mise à jour de l'embedding
3. **Déplacement**: Recherche dans l'écran complet avec tolérance spatiale
4. **Modification Structurelle**: Analyse du contexte pour retrouver l'élément

## Interface Utilisateur

### Panneau des Propriétés Amélioré

```typescript
const VisualPropertiesPanel: React.FC<VisualPropertiesPanelProps> = ({ node, onNodeUpdate, onClose }) => {
  return (
    <Box sx={{ height: '100%', display: 'flex', flexDirection: 'column' }}>
      {/* En-tête avec type d'élément */}
      <VisualHeader elementType={node.visualTarget?.metadata.elementType} />
      
      {/* Zone de capture principale */}
      <ScreenshotDisplay 
        screenshot={node.visualTarget?.screenshot}
        boundingBox={node.visualTarget?.boundingBox}
        onPreviewClick={() => setPreviewOpen(true)}
      />
      
      {/* Métadonnées visuelles */}
      <VisualMetadataSection metadata={node.visualTarget?.metadata} />
      
      {/* Paramètres de configuration */}
      <VisualParametersSection 
        parameters={node.parameters}
        onChange={handleParameterChange}
      />
      
      {/* Validation en temps réel */}
      <ValidationStatusIndicator target={node.visualTarget} />
    </Box>
  );
};
```

### Sélecteur Visuel Interactif

```typescript
const VisualScreenSelector: React.FC<VisualScreenSelectorProps> = ({ onElementSelected, onCancel, isOpen }) => {
  return (
    <Dialog fullScreen open={isOpen} onClose={onCancel}>
      <Box sx={{ position: 'relative', height: '100vh' }}>
        {/* Overlay de sélection */}
        <SelectionOverlay 
          onElementHover={handleElementHover}
          onElementClick={handleElementClick}
        />
        
        {/* Contrôles de sélection */}
        <SelectionControls 
          onCancel={onCancel}
          onConfirm={handleConfirm}
        />
        
        {/* Tooltip d'information */}
        <ElementTooltip 
          element={hoveredElement}
          position={mousePosition}
        />
      </Box>
    </Dialog>
  );
};
```

## Gestion des Erreurs

### Types d'Erreurs Visuelles

1. **Élément Non Trouvé**: L'élément n'existe plus ou a changé
2. **Confiance Faible**: L'embedding ne correspond pas suffisamment
3. **Ambiguïté**: Plusieurs éléments similaires trouvés
4. **Contexte Modifié**: L'environnement de l'élément a changé

### Stratégies de Récupération

```typescript
class VisualErrorRecovery {
  async handleElementNotFound(target: VisualTarget): Promise<RecoveryAction> {
    // 1. Recherche élargie dans l'écran
    // 2. Recherche par contexte
    // 3. Proposition de re-sélection
    // 4. Suggestion d'éléments similaires
  }
  
  async handleLowConfidence(target: VisualTarget, confidence: number): Promise<RecoveryAction> {
    // 1. Analyse des changements visuels
    // 2. Proposition de mise à jour
    // 3. Validation manuelle
    // 4. Apprentissage adaptatif
  }
}
```

## Propriétés de Correction

*Une propriété est une caractéristique ou un comportement qui doit être vrai pour toutes les exécutions valides d'un système - essentiellement, une déclaration formelle sur ce que le système doit faire. Les propriétés servent de pont entre les spécifications lisibles par l'homme et les garanties de correction vérifiables par machine.*

### Propriété 1: Élimination Complète des Sélecteurs Techniques
*Pour tout* panneau de propriétés affiché, aucun champ CSS ou XPath ne doit être visible à l'utilisateur
**Valide: Exigences 1.1, 1.4**

### Propriété 2: Sélection Visuelle Pure
*Pour toute* configuration de cible, le système doit utiliser uniquement des méthodes de sélection visuelle interactive et stocker des embeddings visuels
**Valide: Exigences 1.2, 1.3, 1.5**

### Propriété 3: Affichage de Captures Haute Qualité
*Pour tout* élément sélectionné, une capture d'écran de haute qualité avec contour coloré doit être affichée dans le panneau des propriétés
**Valide: Exigences 2.1, 2.3**

### Propriété 4: Différenciation Visuelle des Éléments Similaires
*Pour tout* ensemble d'éléments similaires détectés, le système doit afficher des indicateurs visuels de différenciation
**Valide: Exigences 2.4**

### Propriété 5: Mise à Jour Automatique des Captures
*Pour tout* élément dont l'apparence change, le système doit automatiquement mettre à jour sa capture d'écran
**Valide: Exigences 2.5**

### Propriété 6: Surbrillance Interactive en Mode Sélection
*Pour tout* survol d'élément en mode sélection visuelle, le système doit afficher une surbrillance avec contours colorés
**Valide: Exigences 3.2**

### Propriété 7: Génération de Signatures Visuelles Uniques
*Pour tout* clic sur un élément en mode sélection, le système doit extraire les caractéristiques visuelles et créer une signature unique
**Valide: Exigences 3.3, 3.4**

### Propriété 8: Réactivité de l'Affichage des Captures
*Pour tout* élément sélectionné, sa capture doit immédiatement apparaître dans le panneau des propriétés
**Valide: Exigences 3.5**

### Propriété 9: Métadonnées en Langage Naturel
*Pour tout* élément sélectionné, ses métadonnées (type, position, caractéristiques) doivent être affichées en langage naturel compréhensible
**Valide: Exigences 4.1, 4.2, 4.3, 4.4**

### Propriété 10: Avertissements de Confiance Faible
*Pour tout* élément avec une confiance de reconnaissance faible, le système doit afficher un avertissement visuel clair
**Valide: Exigences 4.5**

### Propriété 11: Fonctionnalité de Zoom Interactif
*Pour tout* aperçu d'image ouvert, les événements de molette de souris doivent permettre le zoom avec maintien de la qualité
**Valide: Exigences 5.2**

### Propriété 12: Contour Animé pour Éléments Cibles
*Pour tout* élément cible visible dans l'aperçu, un contour animé doit être affiché pour le mettre en évidence
**Valide: Exigences 5.4**

### Propriété 13: Persistance de Configuration lors de la Fermeture d'Aperçu
*Pour tout* aperçu fermé, le panneau des propriétés doit revenir avec la configuration intacte
**Valide: Exigences 5.5**

### Propriété 14: Validation Périodique Automatique
*Pour tout* élément configuré, le système doit vérifier périodiquement sa présence et afficher des indicateurs de statut appropriés
**Valide: Exigences 6.1, 6.2, 6.3**

### Propriété 15: Récupération Intelligente d'Éléments
*Pour tout* élément qui change d'apparence ou disparaît, le système doit proposer des actions de récupération (mise à jour ou re-sélection)
**Valide: Exigences 6.4, 6.5**

### Propriété 16: Capture du Contexte Environnant
*Pour tout* élément sélectionné, le système doit capturer et afficher le contexte environnant avec métadonnées contextuelles
**Valide: Exigences 7.1, 7.2, 7.3**

### Propriété 17: Détection d'États Visuels
*Pour tout* élément ayant des états visuels (hover, focus), le système doit les détecter et les signaler
**Valide: Exigences 7.4**

### Propriété 18: Mise à Jour Automatique des Métadonnées
*Pour tout* changement de contexte détecté, les métadonnées de l'élément doivent être automatiquement mises à jour
**Valide: Exigences 7.5**

### Propriété 19: Interface Entièrement Visuelle
*Pour tout* panneau de propriétés ouvert, seuls des contrôles visuels et intuitifs doivent être affichés, avec terminologie métier compréhensible
**Valide: Exigences 8.1, 8.2, 8.3**

### Propriété 20: Messages d'Erreur Visuels
*Pour toute* erreur survenant, le système doit l'expliquer en termes visuels avec suggestions d'action
**Valide: Exigences 8.4**

### Propriété 21: Aide Visuelle Contextuelle
*Pour toute* demande d'aide, le système doit fournir des exemples visuels et des captures d'écran
**Valide: Exigences 8.5**

### Propriété 22: Persistance Complète des Données Visuelles
*Pour tout* workflow sauvegardé puis chargé, toutes les données visuelles (embeddings, captures, métadonnées) doivent être préservées
**Valide: Exigences 9.1, 9.2, 9.5**

### Propriété 23: Validation Post-Chargement
*Pour tout* workflow chargé, le système doit vérifier la validité actuelle des captures et proposer une re-sélection si nécessaire
**Valide: Exigences 9.3, 9.4**

### Propriété 24: Performance de Traitement des Captures
*Pour toute* capture d'écran prise, le traitement et l'affichage doivent s'effectuer en moins de 2 secondes
**Valide: Exigences 10.1**

### Propriété 25: Réactivité du Mode Sélection
*Pour tout* survol d'élément en mode sélection, la réaction visuelle doit s'afficher en moins de 100ms
**Valide: Exigences 10.2**

### Propriété 26: Optimisation par Cache des Captures
*Pour tout* affichage de multiples captures, le système doit utiliser un mécanisme de cache pour optimiser les performances
**Valide: Exigences 10.4**

### Propriété 27: Traitement Non-Bloquant des Embeddings
*Pour tout* traitement d'embeddings, l'opération doit s'effectuer en arrière-plan sans bloquer l'interface utilisateur
**Valide: Exigences 10.5**

## Stratégie de Test

### Approche de Test Dual

- **Tests unitaires**: Vérifier des exemples spécifiques, cas limites et conditions d'erreur
- **Tests basés sur les propriétés**: Vérifier les propriétés universelles sur tous les inputs
- Les deux approches sont complémentaires et nécessaires pour une couverture complète

### Configuration des Tests Basés sur les Propriétés

- **Bibliothèque**: Hypothesis pour Python (backend) et fast-check pour TypeScript (frontend)
- **Itérations minimales**: 100 par test de propriété
- **Format de tag**: **Feature: visual-rpa-properties-enhancement, Property {number}: {property_text}**
- Chaque propriété de correction doit être implémentée par un SEUL test basé sur les propriétés