rpa_vision_v3/.kiro/specs/visual-workflow-builder-frontend-v2/design.md

Document de Design : Frontend Visual Workflow Builder V2

Vue d'ensemble

Ce document présente la conception technique complète pour la reconstruction du frontend du Visual Workflow Builder (VWB). Le système sera une application React moderne avec TypeScript, utilisant Material-UI pour l'interface utilisateur et intégrant parfaitement le backend Flask existant.

L'architecture privilégie la modularité, la réutilisabilité des composants et une expérience utilisateur fluide pour la création de workflows d'automatisation RPA basés sur la vision.

Architecture

Architecture Générale

graph TB
    subgraph "Frontend React/TypeScript"
        UI[Interface Utilisateur]
        Store[Redux Store]
        API[API Client]
    end
    
    subgraph "Backend Existant"
        Flask[API Flask]
        Screen[ScreenCapturer]
        Vision[Services Vision]
    end
    
    UI --> Store
    Store --> API
    API --> Flask
    Flask --> Screen
    Flask --> Vision

Architecture des Composants

graph TB
    subgraph "Composants Principaux"
        App[App Container]
        Canvas[Canvas Workflow]
        Palette[Palette d'Étapes]
        Props[Panneau Propriétés]
        Exec[Panneau Exécution]
        Doc[Onglets Documentation]
    end
    
    subgraph "Services"
        API[API Service]
        Validation[Service Validation]
        Storage[Service Stockage]
    end
    
    App --> Canvas
    App --> Palette
    App --> Props
    App --> Exec
    App --> Doc
    Canvas --> API
    Props --> Validation
    Exec --> Storage

Composants et Interfaces

Composant Canvas Principal

Responsabilités :

• Rendu visuel des workflows avec @xyflow/react
• Gestion du drag-and-drop des étapes
• Affichage des états d'exécution en temps réel
• Navigation avec minimap pour les gros workflows

Interface TypeScript :

interface CanvasProps {
  workflow: Workflow;
  selectedStep: Step | null;
  executionState: ExecutionState;
  onStepSelect: (step: Step) => void;
  onStepMove: (stepId: string, position: Position) => void;
  onConnection: (source: string, target: string) => void;
}

interface Workflow {
  id: string;
  name: string;
  steps: Step[];
  connections: Connection[];
  variables: Variable[];
}

Palette d'Étapes

Responsabilités :

• Affichage des types d'étapes disponibles en français
• Recherche et filtrage des étapes
• Drag-and-drop vers le canvas
• Tooltips explicatifs

Interface TypeScript :

interface PaletteProps {
  categories: StepCategory[];
  searchTerm: string;
  onSearch: (term: string) => void;
  onStepDrag: (stepType: StepType) => void;
}

interface StepCategory {
  id: string;
  name: string; // "Actions Web", "Logique", etc.
  icon: string;
  steps: StepType[];
}

Panneau de Propriétés

Responsabilités :

• Configuration des paramètres d'étapes
• Validation en temps réel
• Sélection d'éléments visuels
• Gestion des variables

Interface TypeScript :

interface PropertiesPanelProps {
  selectedStep: Step | null;
  variables: Variable[];
  onParameterChange: (stepId: string, param: string, value: any) => void;
  onVisualSelection: (stepId: string) => void;
}

interface Step {
  id: string;
  type: StepType;
  name: string;
  parameters: Record<string, any>;
  position: Position;
  visualElement?: VisualElement;
}

Sélecteur Visuel

Responsabilités :

• Capture d'écran via l'API ScreenCapturer
• Interface de sélection d'éléments
• Création d'embeddings visuels
• Stockage des références visuelles

Interface TypeScript :

interface VisualSelectorProps {
  isOpen: boolean;
  onClose: () => void;
  onElementSelected: (element: VisualElement) => void;
}

interface VisualElement {
  id: string;
  embedding: number[];
  referenceImage: string; // Base64
  boundingBox: BoundingBox;
  context: ScreenContext;
}

Onglets de Documentation

Responsabilités :

• Documentation contextuelle pour chaque outil
• Guides étape par étape avec exemples visuels
• Exemples interactifs
• Glossaire des termes techniques

Interface TypeScript :

interface DocumentationTabProps {
  toolName: string;
  isActive: boolean;
  onActivate: () => void;
}

interface DocumentationContent {
  title: string;
  sections: DocumentationSection[];
  examples: InteractiveExample[];
  glossary: GlossaryTerm[];
}

Modèles de Données

Modèle Workflow

interface Workflow {
  id: string;
  name: string;
  description?: string;
  version: number;
  createdAt: Date;
  updatedAt: Date;
  steps: Step[];
  connections: Connection[];
  variables: Variable[];
  metadata: WorkflowMetadata;
}

interface WorkflowMetadata {
  author: string;
  tags: string[];
  category: string;
  isTemplate: boolean;
}

Modèle Step (Étape)

interface Step {
  id: string;
  type: StepType;
  name: string;
  description?: string;
  parameters: StepParameters;
  position: Position;
  visualElement?: VisualElement;
  validationErrors: ValidationError[];
  executionState: StepExecutionState;
}

interface StepParameters {
  [key: string]: any;
  timeout?: number;
  retryCount?: number;
  continueOnError?: boolean;
}

enum StepExecutionState {
  IDLE = 'idle',
  RUNNING = 'running',
  SUCCESS = 'success',
  ERROR = 'error',
  SKIPPED = 'skipped'
}

Modèle Variable

interface Variable {
  id: string;
  name: string;
  type: VariableType;
  defaultValue?: any;
  description?: string;
  scope: VariableScope;
}

enum VariableType {
  TEXT = 'text',
  NUMBER = 'number',
  BOOLEAN = 'boolean',
  LIST = 'list',
  OBJECT = 'object'
}

enum VariableScope {
  WORKFLOW = 'workflow',
  STEP = 'step',
  GLOBAL = 'global'
}

Correctness Properties

Une propriété est une caractéristique ou un comportement qui doit être vrai dans 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.

Avant d'écrire les propriétés de correction, je dois analyser les critères d'acceptation pour déterminer leur testabilité.

Propriétés de Correction

Basées sur l'analyse de testabilité des critères d'acceptation, voici les propriétés de correction qui doivent être respectées :

Propriété 1 : Drag-and-Drop Universel Pour toute étape de la palette et toute position valide sur le canvas, glisser l'étape vers cette position doit résulter en la création d'une nouvelle étape à cette position exacte Valide : Exigences 2.2, 3.5

Propriété 2 : Sélection Visuelle Cohérente Pour toute étape présente sur le canvas, cliquer sur cette étape doit la marquer comme sélectionnée visuellement et désélectionner toute autre étape précédemment sélectionnée Valide : Exigences 2.3

Propriété 3 : Mouvement Temps Réel Pour toute étape sélectionnée et tout mouvement de glissement, la position visuelle de l'étape doit être mise à jour en temps réel pendant le glissement Valide : Exigences 2.4

Propriété 4 : Création de Connexions Pour toute paire d'étapes valides sur le canvas, connecter la première à la seconde doit créer une connexion visuelle entre elles Valide : Exigences 2.5

Propriété 5 : Affichage Minimap Conditionnel Pour tout workflow contenant plus de 20 étapes, une minimap doit être affichée pour faciliter la navigation Valide : Exigences 2.6

Propriété 6 : Organisation par Catégories Françaises Pour toute étape disponible dans la palette, elle doit appartenir à une catégorie nommée en français Valide : Exigences 3.1

Propriété 7 : Tooltips Français Universels Pour tout élément interactif de l'interface, survoler cet élément doit afficher un tooltip explicatif en français Valide : Exigences 3.2, 10.2

Propriété 8 : Recherche par Nom Français Pour tout terme de recherche saisi dans la palette, seules les étapes dont le nom français contient ce terme doivent être affichées Valide : Exigences 3.3

Propriété 9 : Affichage Propriétés Contextuelles Pour toute étape sélectionnée, le panneau de propriétés doit afficher exactement les paramètres configurables de cette étape Valide : Exigences 4.1

Propriété 10 : Validation Temps Réel Complète Pour toute modification de paramètre, la validation doit s'exécuter immédiatement et afficher les erreurs appropriées si le paramètre est invalide ou manquant Valide : Exigences 4.2, 4.3

Propriété 11 : Adaptation Interface par Type Pour tout paramètre d'étape, l'interface de saisie doit s'adapter au type de données attendu (texte, nombre, liste, booléen) Valide : Exigences 4.4

Propriété 12 : Intégration ScreenCapturer Pour toute demande de sélection d'élément visuel, l'API ScreenCapturer existante doit être appelée pour capturer l'écran Valide : Exigences 5.1

Propriété 13 : Création Embeddings Visuels Pour toute zone cliquée dans le sélecteur visuel, un embedding visuel unique doit être créé et stocké avec l'image de référence Valide : Exigences 5.3, 5.4

Propriété 14 : Gestion Variables CRUD Pour toute opération de création, modification ou suppression de variable, l'opération doit être exécutée avec validation d'unicité des noms Valide : Exigences 6.1, 6.2

Propriété 15 : Autocomplétion Variables Pour toute saisie commençant par "${" dans un champ de paramètre, une liste d'autocomplétion des variables disponibles doit être proposée Valide : Exigences 6.3

Propriété 16 : Support Types Variables Pour toute variable créée, elle doit pouvoir être d'un des types supportés (texte, nombre, booléen, liste) avec une valeur par défaut optionnelle Valide : Exigences 6.4, 6.5

Propriété 17 : Indicateurs Erreur Visuels Pour toute étape avec des paramètres manquants ou invalides, un indicateur rouge doit être affiché sur l'étape Valide : Exigences 7.1

Propriété 18 : Détection Étapes Déconnectées Pour tout workflow contenant des étapes sans connexions d'entrée ou de sortie, ces étapes doivent être surlignées en orange Valide : Exigences 7.2

Propriété 19 : Détection Cycles Pour tout workflow contenant des cycles dans les connexions, un avertissement doit être affiché Valide : Exigences 7.3

Propriété 20 : Prévention Exécution Erreurs Pour tout workflow contenant des erreurs critiques de validation, l'exécution doit être bloquée Valide : Exigences 7.4

Propriété 21 : États Exécution Visuels Pour toute étape pendant l'exécution, son état doit être affiché visuellement (bleu pour en cours, vert pour succès, rouge pour échec) Valide : Exigences 8.2, 8.3, 8.4

Propriété 22 : Envoi Backend Exécution Pour toute demande d'exécution de workflow, les données complètes du workflow doivent être envoyées à l'API Backend_VWB Valide : Exigences 8.1

Propriété 23 : Sauvegarde Backend Pour toute demande de sauvegarde, les données complètes du workflow doivent être envoyées à l'API Backend_VWB avec validation préalable Valide : Exigences 9.1

Propriété 24 : Chargement Workflows Pour toute demande d'ouverture de workflow existant, les données doivent être récupérées depuis l'API Backend_VWB et chargées dans l'interface Valide : Exigences 9.2

Propriété 25 : Cohérence Linguistique Française Pour tout texte affiché dans l'interface, il doit être en français avec une terminologie cohérente et des messages d'erreur clairs Valide : Exigences 10.1, 10.3, 10.4

Propriété 26 : Navigation Clavier Complète Pour toute fonctionnalité accessible à la souris, elle doit également être accessible via navigation clavier avec raccourcis appropriés Valide : Exigences 11.1, 11.3

Propriété 27 : Conformité Accessibilité Pour tout élément de l'interface, il doit respecter les standards WCAG 2.1 niveau AA Valide : Exigences 11.2

Propriété 28 : Responsivité Écrans Pour toute résolution d'écran supportée, les éléments de l'interface doivent s'adapter correctement en taille et disposition Valide : Exigences 11.4

Propriété 29 : Performance Rendu Pour tout mouvement d'étapes sur le canvas, le rendu doit maintenir au moins 60 FPS Valide : Exigences 12.1

Propriété 30 : Performance Chargement Pour tout workflow de 100 étapes ou moins, le temps de chargement ne doit pas dépasser 2 secondes Valide : Exigences 12.2

Propriété 31 : Optimisation Rendu Pour toute opération de mise à jour de l'interface, seuls les composants nécessaires doivent être re-rendus Valide : Exigences 12.5

Propriété 32 : Intégration API REST Pour toute opération CRUD (Create, Read, Update, Delete), l'API REST du Backend_VWB doit être utilisée avec gestion d'erreurs et système de retry Valide : Exigences 13.1, 13.2, 13.3

Propriété 33 : Validation Côté Client Pour toute donnée envoyée au backend, elle doit être validée côté client avant transmission Valide : Exigences 13.4

Propriété 34 : Documentation Contextuelle Pour tout outil ou module majeur, un onglet de documentation doit être disponible avec aide contextuelle en français et exemples interactifs Valide : Exigences 15.1, 15.2, 15.3, 15.4, 15.5

Gestion d'Erreurs

Stratégie de Gestion d'Erreurs

Erreurs de Validation :

• Validation en temps réel des paramètres d'étapes
• Affichage d'indicateurs visuels sur les étapes problématiques
• Messages d'erreur explicites en français
• Prévention de l'exécution en cas d'erreurs critiques

Erreurs de Communication Backend :

• Système de retry automatique (3 tentatives)
• Messages d'erreur utilisateur compréhensibles
• Mode dégradé pour les fonctionnalités offline
• Sauvegarde locale en cas d'échec de sauvegarde distante

Erreurs de Sélection Visuelle :

• Gestion des échecs de capture d'écran
• Validation des embeddings créés
• Fallback vers sélection manuelle si nécessaire
• Messages d'aide pour résoudre les problèmes

Codes d'Erreur

enum ErrorCode {
  VALIDATION_REQUIRED_PARAMETER = 'VALIDATION_001',
  VALIDATION_INVALID_TYPE = 'VALIDATION_002',
  VALIDATION_WORKFLOW_CYCLE = 'VALIDATION_003',
  BACKEND_CONNECTION_FAILED = 'BACKEND_001',
  BACKEND_TIMEOUT = 'BACKEND_002',
  BACKEND_INVALID_RESPONSE = 'BACKEND_003',
  VISUAL_CAPTURE_FAILED = 'VISUAL_001',
  VISUAL_EMBEDDING_FAILED = 'VISUAL_002',
  VISUAL_SELECTION_TIMEOUT = 'VISUAL_003'
}

Stratégie de Tests

Tests Unitaires

Composants React :

• Tests de rendu avec React Testing Library
• Tests d'interactions utilisateur (clicks, saisies)
• Tests de props et états
• Couverture minimale de 80% pour la logique métier

Services et Utilitaires :

• Tests des fonctions de validation
• Tests des appels API avec mocks
• Tests des transformations de données
• Tests des calculs de positions et connexions

Tests Property-Based

Configuration Hypothesis (Python) ou fast-check (JavaScript) :

• Minimum 100 itérations par test de propriété
• Génération de workflows aléatoires pour tests de robustesse
• Génération de paramètres d'étapes aléatoires
• Tests de performance avec données variables

Exemples de Générateurs :

// Générateur de workflows aléatoires
const workflowGenerator = fc.record({
  steps: fc.array(stepGenerator, { minLength: 1, maxLength: 50 }),
  connections: fc.array(connectionGenerator),
  variables: fc.array(variableGenerator)
});

// Générateur d'étapes
const stepGenerator = fc.record({
  id: fc.uuid(),
  type: fc.constantFrom('click', 'type', 'wait', 'condition'),
  parameters: fc.dictionary(fc.string(), fc.anything())
});

Tests d'Intégration

Tests avec Backend Réel :

• Tests de sauvegarde/chargement de workflows
• Tests d'exécution avec feedback temps réel
• Tests d'intégration ScreenCapturer
• Tests de gestion d'erreurs backend

Tests Visuels avec Captures Réelles :

• Tests de sélection d'éléments sur vraies captures
• Validation des embeddings créés
• Tests de reconnaissance d'éléments similaires
• Tests de robustesse avec différents types d'écrans

Annotation des Tests

Chaque test de propriété doit être annoté avec :

// Feature: visual-workflow-builder-frontend-v2, Property 1: Drag-and-Drop Universel
test('drag and drop creates step at correct position', () => {
  // Test implementation
});

Cette stratégie assure une couverture complète avec des tests unitaires pour les cas spécifiques et des tests property-based pour la validation des propriétés universelles.