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

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

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

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

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

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

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

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

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

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é

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

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

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