rpa_vision_v3/.kiro/specs/tool-documentation-ui/design.md

Design Document - Documentation Interactive des Outils

Overview

Ce document décrit l'architecture et l'implémentation d'un système de documentation interactive intégré dans le Visual Workflow Builder. Le système fournit une aide contextuelle complète en français pour tous les outils disponibles, accessible via deux interfaces complémentaires : des boutons d'aide dans la palette et un onglet documentation dans le panneau des propriétés.

Architecture

Architecture Générale

┌─────────────────────────────────────────────────────────────┐
│                    Frontend (React/TypeScript)              │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐ │
│  │   Palette       │  │ Properties Panel│  │ Documentation│ │
│  │   Component     │  │   Component     │  │   Service    │ │
│  │                 │  │                 │  │              │ │
│  │ ┌─────────────┐ │  │ ┌─────────────┐ │  │              │ │
│  │ │ Help Button │ │  │ │ Doc Tab     │ │  │              │ │
│  │ └─────────────┘ │  │ └─────────────┘ │  │              │ │
│  └─────────────────┘  └─────────────────┘  └──────────────┘ │
├─────────────────────────────────────────────────────────────┤
│                    Documentation Store                      │
│  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐ │
│  │ Tool Definitions│  │ Content Cache   │  │ Search Index │ │
│  └─────────────────┘  └─────────────────┘  └──────────────┘ │
└─────────────────────────────────────────────────────────────┘

Composants Principaux

1. DocumentationService : Service central de gestion de la documentation
2. HelpButton : Composant bouton d'aide dans la palette
3. DocumentationPopup : Popup modal pour afficher la documentation
4. DocumentationTab : Onglet documentation dans le panneau des propriétés
5. SearchEngine : Moteur de recherche interne à la documentation
6. ContentRenderer : Rendu adaptatif du contenu selon le contexte

Components and Interfaces

DocumentationService

interface DocumentationService {
  // Récupération de documentation
  getToolDocumentation(toolId: string): ToolDocumentation;
  getGeneralHelp(): GeneralDocumentation;
  
  // Recherche
  searchInDocumentation(query: string, toolId?: string): SearchResult[];
  
  // Contextualisation
  getContextualHelp(toolId: string, currentConfig: any): ContextualHelp;
  getRelatedTools(toolId: string): RelatedTool[];
  
  // Cache et performance
  preloadDocumentation(): Promise<void>;
  invalidateCache(toolId?: string): void;
}

ToolDocumentation

interface ToolDocumentation {
  id: string;
  name: string;
  category: ToolCategory;
  
  // Contenu principal
  description: string;
  purpose: string;
  useCases: UseCase[];
  
  // Configuration
  parameters: ParameterDocumentation[];
  examples: Example[];
  
  // Guides
  bestPractices: string[];
  limitations: string[];
  troubleshooting: TroubleshootingItem[];
  
  // Relations
  relatedTools: string[];
  prerequisites: string[];
  
  // Métadonnées
  lastUpdated: Date;
  version: string;
}

HelpButton Component

interface HelpButtonProps {
  toolId: string;
  position: 'palette' | 'inline';
  size: 'small' | 'medium';
  onHelpClick: (toolId: string) => void;
}

interface HelpButtonState {
  isVisible: boolean;
  isHovered: boolean;
}

DocumentationPopup Component

interface DocumentationPopupProps {
  toolId: string;
  isOpen: boolean;
  onClose: () => void;
  initialSearchQuery?: string;
}

interface DocumentationPopupState {
  documentation: ToolDocumentation;
  searchQuery: string;
  searchResults: SearchResult[];
  activeSection: string;
  isLoading: boolean;
}

DocumentationTab Component

interface DocumentationTabProps {
  selectedNodeId?: string;
  nodeType?: string;
  currentConfiguration?: any;
}

interface DocumentationTabState {
  documentation: ToolDocumentation | GeneralDocumentation;
  contextualHighlights: string[];
  relatedSuggestions: RelatedTool[];
}

Data Models

Documentation Content Structure

// Structure principale de la documentation
interface ToolDocumentation {
  // Identification
  id: string;
  name: string;
  category: 'actions-web' | 'donnees' | 'logique' | 'controle' | 'integrations';
  
  // Contenu de base
  overview: {
    description: string;
    purpose: string;
    icon: string;
    color: string;
  };
  
  // Cas d'usage
  useCases: {
    title: string;
    description: string;
    scenario: string;
    example: string;
  }[];
  
  // Paramètres
  parameters: {
    name: string;
    type: ParameterType;
    required: boolean;
    description: string;
    defaultValue?: any;
    examples: string[];
    validation?: ValidationRule[];
  }[];
  
  // Guides pratiques
  guides: {
    quickStart: string;
    bestPractices: string[];
    commonMistakes: string[];
    troubleshooting: TroubleshootingItem[];
  };
  
  // Relations
  relationships: {
    relatedTools: string[];
    prerequisites: string[];
    followUpTools: string[];
  };
  
  // Contenu spécialisé par catégorie
  categorySpecific?: CategorySpecificContent;
}

// Contenu spécialisé selon la catégorie
interface CategorySpecificContent {
  // Pour Actions Web
  webActions?: {
    targetSelection: string;
    browserCompatibility: string[];
    securityConsiderations: string;
  };
  
  // Pour Données
  dataTools?: {
    supportedFormats: string[];
    transformationExamples: DataTransformation[];
    performanceNotes: string;
  };
  
  // Pour Logique
  logicTools?: {
    conditionExamples: ConditionExample[];
    flowDiagrams: string[];
    debuggingTips: string[];
  };
  
  // Pour Intégrations
  integrationTools?: {
    protocols: string[];
    authenticationMethods: string[];
    connectionExamples: ConnectionExample[];
  };
}

Search and Context Models

interface SearchResult {
  toolId: string;
  section: string;
  content: string;
  relevanceScore: number;
  highlightedText: string;
}

interface ContextualHelp {
  highlights: string[];
  warnings: Warning[];
  suggestions: Suggestion[];
  relatedActions: RelatedAction[];
}

interface Warning {
  type: 'error' | 'warning' | 'info';
  message: string;
  affectedParameters: string[];
  resolution: string;
}

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 devrait 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 Reflection

Après analyse du prework, plusieurs propriétés peuvent être consolidées :

• Les propriétés 1.1-1.5 (palette) et 2.1-2.5 (panneau) testent des interactions UI similaires
• Les propriétés 3.1-3.6 et 4.1-4.6 testent la présence de contenu documentaire
• Les propriétés 5.1-5.5 testent la fonctionnalité de recherche
• Les propriétés 7.1-7.5 testent l'accessibilité et l'ergonomie
• Les propriétés 8.1-8.5 testent les performances

Core Properties

Property 1: Documentation UI Integration For any tool in the palette, hovering should show a help button, clicking it should open documentation, and the popup should contain all required content sections (title, description, parameters, examples) Validates: Requirements 1.1, 1.2, 1.3

Property 2: Properties Panel Documentation For any selected node on the canvas, the properties panel should display a documentation tab with content matching the node type, and automatically update when selection changes Validates: Requirements 2.1, 2.2, 2.4

Property 3: Complete French Documentation For any tool in the system, documentation should exist in French and include all required sections: description, parameters with explanations, practical examples, and use cases Validates: Requirements 3.1, 3.2, 3.3, 3.4, 3.6

Property 4: Category-Specific Content For any tool category (Actions Web, Données, Logique, Intégrations), documentation should include category-appropriate specialized content and formatting Validates: Requirements 4.1, 4.2, 4.3, 4.4, 4.5

Property 5: Search Functionality For any search query in documentation, the system should highlight matching terms, allow navigation between results, and search across all content sections (title, description, parameters, examples) Validates: Requirements 5.1, 5.2, 5.3, 5.4

Property 6: Contextual Enhancement For any configured node, documentation should highlight relevant sections, suggest related tools, and display warnings for risky configurations Validates: Requirements 6.1, 6.2, 6.4, 6.5

Property 7: Accessibility Support For any documentation interface, keyboard navigation should work (F1 shortcut, tab navigation), font size should be adjustable, and responsive design should adapt to different screen sizes Validates: Requirements 7.1, 7.2, 7.4, 7.5

Property 8: Performance Requirements For any documentation request, content should display within 200ms, use caching to avoid reloads, and support offline access after initial load Validates: Requirements 8.2, 8.3, 8.5

Error Handling

Documentation Loading Errors

interface DocumentationError {
  type: 'LOAD_FAILED' | 'CONTENT_MISSING' | 'SEARCH_FAILED' | 'CACHE_ERROR';
  toolId?: string;
  message: string;
  fallbackContent?: string;
}

class DocumentationErrorHandler {
  handleLoadError(error: DocumentationError): void {
    // Afficher contenu de fallback
    // Logger l'erreur pour debugging
    // Proposer rechargement manuel
  }
  
  handleSearchError(query: string): void {
    // Afficher message d'erreur utilisateur
    // Suggérer termes alternatifs
    // Permettre recherche manuelle
  }
}

Graceful Degradation

1. Documentation manquante : Afficher un message informatif avec lien vers documentation générale
2. Erreur de recherche : Désactiver temporairement la recherche, maintenir navigation manuelle
3. Problème de cache : Recharger depuis la source, informer l'utilisateur du délai
4. Erreur de rendu : Afficher version texte simple en fallback

Testing Strategy

Dual Testing Approach

Unit Tests :

• Composants React individuels (HelpButton, DocumentationPopup, DocumentationTab)
• Service de documentation (chargement, cache, recherche)
• Rendu du contenu et formatage
• Gestion d'erreurs et cas limites

Property-Based Tests :

• Validation que toute documentation contient les sections requises
• Test de l'intégration UI sur tous les types d'outils
• Vérification des performances sur différentes tailles de contenu
• Test de la recherche sur du contenu généré aléatoirement

Test Configuration

• Minimum 100 iterations par test de propriété
• Tags de référence : Feature: tool-documentation-ui, Property X: [description]
• Couverture : Tous les types d'outils, toutes les catégories, tous les cas d'usage
• Performance : Tests de charge avec documentation volumineuse

Testing Framework

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