a7de6a488b
Validé sur PC Windows (DESKTOP-58D5CAC, 2560x1600) : - 8 clics résolus visuellement (1 anchor_template, 1 som_text_match, 6 som_vlm) - Score moyen 0.75, temps moyen 1.6s - Texte tapé correctement (bonjour, test word, date, email) - 0 retries, 2 actions non vérifiées (OK) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
391 lines
13 KiB
Markdown
391 lines
13 KiB
Markdown
# 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
|
|
|
|
```mermaid
|
|
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)
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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é)
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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)
|
|
|
|
```typescript
|
|
interface ValidationError {
|
|
parameter: string;
|
|
message: string;
|
|
severity: 'error' | 'warning' | 'info';
|
|
code: string;
|
|
suggestions?: string[];
|
|
context?: Record<string, any>;
|
|
}
|
|
```
|
|
|
|
### PropertiesState
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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. |