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

```mermaid
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

```mermaid
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 :**
```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 :**
```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 :**
```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 :**
```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 :**
```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

```typescript
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)

```typescript
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

```typescript
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

```typescript
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 :**
```typescript
// 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 :
```typescript
// 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.