rpa_vision_v3/.kiro/specs/interface-proprietes-etapes-complete/design.md

Design Document - Interface Propriétés d'Étapes Complète

Overview

Ce document détaille la conception d'une interface utilisateur complète et robuste pour l'affichage et la configuration des propriétés d'étapes dans le Visual Workflow Builder. Le système s'appuie sur le StepTypeResolver existant et étend l'architecture actuelle pour fournir une expérience utilisateur cohérente pour tous les types d'étapes.

Architecture

Vue d'ensemble du système

graph TB
    A[PropertiesPanel] --> B[useStepTypeResolver]
    B --> C[StepTypeResolver]
    A --> D[StandardParametersEditor]
    A --> E[VWBActionProperties]
    A --> F[EmptyStateMessage]
    A --> G[LoadingState]
    
    D --> H[ParameterFieldRenderer]
    H --> I[TextFieldRenderer]
    H --> J[NumberFieldRenderer]
    H --> K[BooleanFieldRenderer]
    H --> L[SelectFieldRenderer]
    H --> M[VisualFieldRenderer]
    
    E --> N[VWBParameterRenderer]
    E --> O[VWBValidationDisplay]
    
    C --> P[catalogService]
    C --> Q[Cache System]

Flux de données

1. Sélection d'étape : L'utilisateur sélectionne une étape dans le canvas
2. Résolution de type : Le StepTypeResolver détermine le type et les paramètres
3. Rendu conditionnel : Le PropertiesPanel choisit le bon composant de rendu
4. Affichage des champs : Les champs appropriés sont affichés avec validation
5. Sauvegarde automatique : Les modifications sont sauvegardées automatiquement

Components and Interfaces

PropertiesPanel (Composant principal)

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

interface PropertiesPanelState {
  localParameters: Record<string, any>;
  isVisualSelectorOpen: boolean;
  validationErrors: ValidationError[];
}

Responsabilités :

• Orchestrer l'affichage des propriétés selon le type d'étape
• Gérer les états de chargement et d'erreur
• Coordonner la sauvegarde automatique des paramètres
• Maintenir la cohérence de l'interface utilisateur

StandardParametersEditor

interface StandardParametersEditorProps {
  stepType: string;
  parameterConfigs: ParameterConfig[];
  parameters: Record<string, any>;
  variables: Variable[];
  onParameterChange: (paramName: string, value: any) => void;
  onValidationChange: (errors: ValidationError[]) => void;
}

Responsabilités :

• Rendre les champs de paramètres pour les étapes standard
• Valider les valeurs en temps réel
• Gérer l'autocomplétion des variables
• Maintenir l'état de validation

ParameterFieldRenderer

interface ParameterFieldRendererProps {
  config: ParameterConfig;
  value: any;
  variables: Variable[];
  error?: ValidationError;
  onChange: (value: any) => void;
}

type FieldRendererMap = {
  text: TextFieldRenderer;
  number: NumberFieldRenderer;
  boolean: BooleanFieldRenderer;
  select: SelectFieldRenderer;
  visual: VisualFieldRenderer;
}

Responsabilités :

• Rendre le bon type de champ selon la configuration
• Supporter l'extensibilité pour nouveaux types de champs
• Maintenir la cohérence visuelle
• Gérer les événements de saisie

VWBActionProperties (Amélioré)

interface VWBActionPropertiesProps {
  action: VWBCatalogAction | null;
  parameters: Record<string, any>;
  variables: Variable[];
  isLoading: boolean;
  error?: Error;
  onParameterChange: (paramName: string, value: any) => void;
  onValidationChange: (validation: VWBActionValidationResult) => void;
}

Responsabilités :

• Gérer les cas où l'action VWB n'est pas chargée
• Afficher des messages informatifs pour les actions manquantes
• Supporter la validation spécialisée VWB
• Maintenir la compatibilité avec le catalogue

EmptyStateMessage

interface EmptyStateMessageProps {
  stepType: string;
  reason: 'no-parameters' | 'loading-error' | 'vwb-not-found' | 'unknown-type';
  error?: Error;
  suggestions?: string[];
}

Responsabilités :

• Expliquer clairement pourquoi aucune propriété n'est affichée
• Fournir des suggestions d'actions alternatives
• Distinguer entre différents types d'états vides
• Maintenir un ton informatif et utile

LoadingState

interface LoadingStateProps {
  message: string;
  progress?: number;
  canCancel?: boolean;
  onCancel?: () => void;
}

Responsabilités :

• Afficher des indicateurs de chargement informatifs
• Supporter l'annulation des opérations longues
• Maintenir la réactivité de l'interface
• Fournir un feedback visuel approprié

Data Models

Enhanced ParameterConfig

interface ParameterConfig {
  name: string;
  label: string;
  type: ParameterFieldType;
  required?: boolean;
  description?: string;
  supportVariables?: boolean;
  validation?: ValidationRule[];
  defaultValue?: any;
  
  // Propriétés étendues
  placeholder?: string;
  helpText?: string;
  group?: string;
  order?: number;
  conditional?: ConditionalRule;
  
  // Propriétés spécifiques par type
  options?: SelectOption[];
  min?: number;
  max?: number;
  step?: number;
  multiline?: boolean;
  visualType?: 'element' | 'region' | 'text';
}

ValidationError (Étendu)

interface ValidationError {
  parameter: string;
  message: string;
  severity: 'error' | 'warning' | 'info';
  code: string;
  suggestions?: string[];
  context?: Record<string, any>;
}

PropertiesState

interface PropertiesState {
  resolution: StepTypeResolutionResult | null;
  isResolving: boolean;
  resolutionError: Error | null;
  
  parameters: Record<string, any>;
  validationErrors: ValidationError[];
  isDirty: boolean;
  isSaving: boolean;
  
  vwbAction: VWBCatalogAction | null;
  isLoadingVWBAction: boolean;
  vwbActionError: Error | null;
}

Correctness Properties

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.

Property 1: Affichage cohérent des paramètres standard

Pour toute étape standard avec une configuration de paramètres définie, le StandardParametersEditor doit afficher exactement les champs spécifiés dans la configuration Validates: Requirements 1.1, 1.2, 1.3, 1.4, 1.5

Property 2: Validation temps réel des paramètres

Pour tout paramètre modifié dans l'interface, la validation doit se déclencher immédiatement et afficher les erreurs appropriées Validates: Requirements 1.6, 1.7, 6.1, 6.2

Property 3: Sauvegarde automatique des modifications

Pour toute modification de paramètre, le système doit déclencher une sauvegarde automatique avec debouncing approprié Validates: Requirements 1.8, 5.3

Property 4: Détection correcte des actions VWB

Pour toute étape identifiée comme action VWB par le StepTypeResolver, le PropertiesPanel doit utiliser le composant VWBActionProperties Validates: Requirements 2.1, 2.2

Property 5: Gestion des états de chargement VWB

Pour toute action VWB en cours de chargement, le système doit afficher un indicateur de chargement approprié Validates: Requirements 2.4, 3.1

Property 6: Messages d'erreur informatifs

Pour toute erreur de résolution ou de chargement, le système doit afficher un message d'erreur spécifique et informatif Validates: Requirements 2.6, 3.2, 3.4

Property 7: Cohérence visuelle des champs

Pour tout champ en état d'erreur, le système doit appliquer les couleurs et styles d'erreur définis dans le design system Validates: Requirements 4.3

Property 8: Support des raccourcis clavier

Pour tout raccourci clavier défini, le système doit réagir appropriément et maintenir la navigation cohérente Validates: Requirements 4.4

Property 9: Responsivité de l'interface

Pour toute taille d'écran supportée, le PropertiesPanel doit s'adapter et maintenir l'utilisabilité Validates: Requirements 4.5

Property 10: Accessibilité ARIA

Pour tout élément interactif, les attributs ARIA appropriés doivent être présents et corrects Validates: Requirements 4.6

Property 11: Optimisation des re-rendus

Pour toute modification qui ne change pas les props pertinentes, les composants mémorisés ne doivent pas se re-rendre Validates: Requirements 5.1

Property 12: Utilisation du cache de résolution

Pour toute résolution répétée avec les mêmes paramètres, le StepTypeResolver doit utiliser le cache Validates: Requirements 5.2

Property 13: Chargement asynchrone non-bloquant

Pour tout chargement d'action VWB, l'interface doit rester réactive et non-bloquée Validates: Requirements 5.4

Property 14: Autocomplétion des variables

Pour tout champ supportant les variables, l'autocomplétion doit proposer les variables disponibles Validates: Requirements 6.3, 6.4

Property 15: Prévisualisation des variables

Pour toute variable utilisée dans un champ, sa valeur doit être prévisualisée quand disponible Validates: Requirements 6.5

Property 16: Indicateur de succès de validation

Pour toute configuration où tous les paramètres sont valides, un indicateur de succès doit être affiché Validates: Requirements 6.6

Property 17: Intégration avec StepTypeResolver

Pour toute résolution de type d'étape, le système doit utiliser le StepTypeResolver existant Validates: Requirements 7.1

Property 18: Compatibilité des hooks existants

Pour tout hook existant (useStepTypeResolver), la compatibilité doit être maintenue Validates: Requirements 7.2

Property 19: Respect des interfaces TypeScript

Pour toute interface TypeScript existante, le système doit maintenir la compatibilité Validates: Requirements 7.3

Property 20: Utilisation des services existants

Pour tout service existant (catalogService, apiClient), le système doit les utiliser correctement Validates: Requirements 7.4

Property 21: Logs de débogage structurés

Pour toute opération importante, des logs de débogage appropriés doivent être générés Validates: Requirements 7.5

Property 22: Extensibilité des renderers

Pour tout nouveau type de champ ajouté, le ParameterFieldRenderer doit pouvoir le supporter Validates: Requirements 8.1, 8.2

Property 23: Extensibilité de l'éditeur standard

Pour tout nouveau type d'étape standard, le StandardParametersEditor doit pouvoir l'intégrer Validates: Requirements 8.3

Property 24: Évolution du format VWB

Pour tout changement de format des actions VWB, le VWBActionProperties doit maintenir la compatibilité Validates: Requirements 8.4

Error Handling

Stratégie de gestion d'erreurs

1. Erreurs de résolution : Affichage de messages informatifs avec suggestions
2. Erreurs de validation : Feedback immédiat avec explications claires
3. Erreurs de chargement VWB : États de fallback avec actions alternatives
4. Erreurs de sauvegarde : Retry automatique avec notification utilisateur
5. Erreurs de réseau : Mode dégradé avec cache local

Types d'erreurs gérées

enum ErrorType {
  RESOLUTION_FAILED = 'resolution_failed',
  VALIDATION_ERROR = 'validation_error',
  VWB_LOADING_ERROR = 'vwb_loading_error',
  SAVE_ERROR = 'save_error',
  NETWORK_ERROR = 'network_error',
  UNKNOWN_STEP_TYPE = 'unknown_step_type'
}

Stratégies de récupération

• Retry automatique pour les erreurs temporaires
• Fallback vers cache pour les erreurs de réseau
• Mode dégradé pour les fonctionnalités non-critiques
• Messages d'aide contextuelle pour guider l'utilisateur

Testing Strategy

Approche de test double

Tests unitaires : Vérifier des exemples spécifiques, cas limites et conditions d'erreur Tests de propriétés : Vérifier les propriétés universelles sur tous les inputs

Les deux types de tests sont complémentaires et nécessaires pour une couverture complète.

Configuration des tests de propriétés

• Minimum 100 itérations par test de propriété (due à la randomisation)
• Référence aux propriétés du design : Chaque test doit référencer sa propriété
• Format de tag : Feature: interface-proprietes-etapes-complete, Property {number}: {property_text}

Tests unitaires ciblés

• Exemples spécifiques : Tests pour les types d'étapes click, type, wait, extract
• Cas limites : Paramètres manquants, valeurs invalides, erreurs de réseau
• Intégration : Points d'intégration entre composants
• Accessibilité : Vérification des attributs ARIA et navigation clavier

Tests de propriétés universelles

• Validation cohérente : Toutes les validations fonctionnent correctement
• Performance : Optimisations de re-rendu et cache
• Extensibilité : Nouveaux types de champs et d'étapes
• Robustesse : Gestion d'erreurs et états de fallback

Framework de test

Utilisation de React Testing Library avec Jest pour les tests unitaires et fast-check pour les tests de propriétés, conformément à l'architecture existante du projet.