rpa_vision_v3/docs/PLAN_ACTION_VWB.md

Plan d'action VWB — 13 avril 2026

Audit ciblé du Visual Workflow Builder (visual_workflow_builder/) — backend Flask port 5002, frontend React+Vite port 3002 — suite aux retours flous de Dom : « la bibliothèque s'efface tout le temps » + idée d'importer les workflows Léa pour les corriger.

---

Section A — État des lieux

Stack réelle en production (PIDs live)

• Backend 5002 → backend/app.py (Flask complet, blueprints v3, SQLAlchemy) — c'est celui qui sert le VWB
• Backend 5003 → backend/app_lightweight.py (serveur HTTP natif fallback, 1451 lignes, mode quasi-inutile aujourd'hui)
• Frontend 3002 → frontend_v4/ (Vite + React 18, @xyflow/react, TypeScript) — actif
• BDD utilisée → backend/instance/workflows.db (via .env DATABASE_URL=sqlite:///workflows.db) — 3 workflows dedans (« Classement de dossier », « bloc notes », « Onlyoffice »), tous source='manual', aucun review_status
• BDD fantôme → backend/instance/vwb_v3.db (schema identique, 0 workflows) — zombie de app.py ligne 47 ('sqlite:///vwb_v3.db' en défaut)

Ce qui marche bien

• API v3 est complète et propre : 44 routes réparties (session, workflow, capture, execute, match, review, learned_workflows, dag_execute). Modèles SQLAlchemy avec champs review (source, review_status, review_feedback, reviewed_at).
• Pont Léa ↔ VWB déjà implémenté et câblé :
  • Backend : api_v3/learned_workflows.py (459 l.) + services/learned_workflow_bridge.py (604 l.)
  • Frontend : services/api.ts expose getLearnedWorkflows, importLearnedWorkflow, exportForLea ; components/WorkflowSelector.tsx charge et propose d'importer les workflows non-importés
  • Endpoints fonctionnels : logs du 15 avril montrent GET /api/v3/learned-workflows?os=linux → 200
• Système de review : composants ReviewModal.tsx, WorkflowValidation.tsx, WorkflowManagerModal.tsx + backend api_v3/review.py prêt. Un workflow importé arrive en review_status='pending_review'.
• Tests backend localisés : backend/tests/ (test_models.py, test_coaching_api.py). Workflow CRUD complet.
• Logs rotatifs propres (backend/logs/vwb.log, 5 MB × 3).

Ce qui est cassé / douteux

1. BUG CRITIQUE — Bibliothèque de captures qui s'efface Fichier : frontend_v4/src/components/CaptureLibrary.tsx lignes 25-62

   • Stockage dans sessionStorage (clé captureLibrary_v2) → purgé à chaque fermeture d'onglet ou redémarrage du navigateur
   • Cap arbitraire à 50 captures max (slice(0, 49))
   • Les captures sont des base64 PNG → sessionStorage ne tient pas plus de quelques dizaines de Mo au total
   • C'est très probablement le bug que Dom décrit

2. BUG — Deux composants concurrents pour la même bibliothèque

   • CaptureLibrary.tsx écrit dans sessionStorage['captureLibrary_v2']
   • CapturePanel.tsx lignes 51-62 écrit dans sessionStorage['captureLibrary'] (ancienne clé, jamais migrée à l'envers)
   • Résultat : deux listes de captures tenues en parallèle, désynchronisées, invisibles l'une pour l'autre

3. Base fantôme vwb_v3.db

   • app.py l.47 : 'sqlite:///vwb_v3.db' en défaut
   • Si un jour .env n'est pas chargé (ex : systemd mal configuré), le VWB passe silencieusement sur l'autre BDD vide et Dom voit ses workflows disparaître
   • Dette : deux fichiers instance/ (backend/instance/ et visual_workflow_builder/instance/) créent de la confusion

4. 404 en prod — /api/correction-packs/stats

   • Logs récents : deux 404 à chaque chargement
   • La route n'existe pas côté backend, elle est appelée par le frontend legacy (frontend/src/hooks/useCorrectionPacks.ts)
   • Dom voit sans doute des erreurs CORS/404 dans la console réseau selon quel frontend il ouvre

5. Double logging (tous les logs en double)

   • app.py attache un handler au root logger + Flask attache le sien → chaque ligne loguée deux fois
   • Bruit dans les logs, rend le debug plus dur

6. Confusion run.sh vs run_v4.sh

   • run.sh lance frontend legacy port 3000 (via webpack react-scripts) + app.py
   • run_v4.sh lance frontend_v4 port 3002 + app.py
   • Les deux coexistent, Dom peut cliquer sur l'un ou l'autre sans savoir
   • launch.sh mentionné dans le README n'existe pas (README obsolète)

7. Workflow « Unnamed Workflow »

   • Les JSON Léa ont souvent "name": "Unnamed Workflow" (cf. notepad_enriched.json)
   • L'import les reprend tel quel — la liste du VWB devient illisible vite

8. Tests d'intégration VWB datent de janvier

   • tests/integration/test_vwb_*.py : 6 fichiers
   • tests/property/test_vwb_frontend_v2_* : 14 fichiers — ciblent frontend/ (v2), pas frontend_v4/
   • Aucun test cible le pont learned_workflows → pas de garde-fou pour C2

Dette technique identifiable

• 3 backends Flask (app.py, app_lightweight.py, app_catalogue_simple.py) pour 403 + 1451 + 1370 lignes = 3224 lignes. Un seul tourne.
• 2 frontends (frontend/ = react-scripts v2, frontend_v4/ = Vite v4) avec duplication partielle des composants — seul le v4 est vivant
• 2 bases SQLite nommées différemment, schéma identique
• catalog_routes.py.backup_20260122_163105 (127 Ko) traîne dans le repo
• Screenshots .screenshot2026-*.png (8 fichiers × ~220 Ko) traînent à la racine backend
• Migrations Alembic présentes mais un seul fichier (001_initial_schema.py) alors que le schéma a évolué (review_status ajouté après)

---

Section B — Quick wins (< 1 jour chacun)

Classés par ratio impact/effort décroissant :

B1. 🔥 Migrer la bibliothèque de captures de sessionStorage vers localStorage

Effort : 30 min Impact : résout le bug principal rapporté par Dom

• Remplacer sessionStorage.* par localStorage.* dans CaptureLibrary.tsx et CapturePanel.tsx
• Unifier sur une seule clé captureLibrary_v3 (migration ascendante depuis les deux anciennes)
• Augmenter le cap à 200 captures + ajouter un bouton « vider la bibliothèque »
• Attention : localStorage plafonne ~5 Mo, les PNG base64 saturent vite — meilleure option : persister côté backend via /api/v3/capture/library (ajout d'une petite table) et ne garder que des IDs+thumbnails en localStorage

B2. 🔥 Renommer le fichier « Unnamed Workflow » à l'import

Effort : 20 min Impact : moyen (lisibilité immédiate dans la liste)

• api_v3/learned_workflows.py l.210 : si wf_meta["name"] == "Unnamed Workflow" → f"Appris {datetime:%d/%m %H:%M}"
• Idem exposer ce nom dans WorkflowSelector.tsx ligne 120 quand on affiche la liste learned

B3. Supprimer la BDD fantôme

Effort : 15 min Impact : élimine un foot-gun discret

• Modifier app.py l.47 : défaut 'sqlite:///workflows.db' (aligné sur .env)
• Supprimer backend/instance/vwb_v3.db + visual_workflow_builder/instance/workflows.db (vestige)
• Documenter dans le .env.example le chemin absolu recommandé

B4. Corriger le double logging

Effort : 15 min Impact : faible (quality-of-life debug)

• app.py l.40 : remplacer logging.getLogger().addHandler(...) par app.logger.addHandler(...) et logging.getLogger('werkzeug').addHandler(...), puis propagate = False

B5. Supprimer le 404 /api/correction-packs/stats

Effort : 20 min Impact : faible (erreurs dans la console navigateur)

• Option A (propre) : stubber la route dans api/correction_packs.py qui retourne {"success": true, "stats": {"total": 0}}
• Option B : retirer l'appel côté frontend/src/hooks/useCorrectionPacks.ts ligne 229
• Option B préférable si le frontend legacy est condamné (voir E1)

B6. Nettoyer les fichiers parasites

Effort : 10 min Impact : cosmétique + réduire la confusion

• Supprimer backend/catalog_routes.py.backup_20260122_163105 (127 Ko)
• Supprimer les 8 screenshots .screenshot2026-*.png à la racine backend
• .gitignore : ajouter *.screenshot*.png, *.backup_*

B7. Clarifier run.sh

Effort : 20 min Impact : moyen (Dom et moi perdons du temps sur quel frontend lancer)

• Renommer run.sh → run_legacy.sh avec bandeau warning
• Mettre à jour README.md du VWB pour refléter run_v4.sh comme canonique
• Supprimer la mention launch.sh qui n'existe pas

Total Quick Wins : ~2h30 de dev pour résoudre la douleur principale + 4 dettes visibles.

---

Section C — Chantiers moyens (1-3 jours)

C1. Finaliser le flux « Import Léa → review VWB → replay »

Effort : 1 jour Contexte : toute la plomberie existe (backend+frontend), mais la boucle n'est pas testée end-to-end depuis le premier replay réussi du 13 avril. Actuellement source='learned_import' déclenche bien review_status='pending_review', mais :

• Le frontend n'a pas de banner « ⚠ 2 workflows importés en attente de review » visible au démarrage (il y a bien un pendingReviewCount dans App.tsx mais je n'ai pas vérifié son affichage)
• Quand Dom ouvre un workflow en pending_review, aucun indicateur visuel sur les étapes automatiquement générées par le bridge (ex: warning sur les compound décomposés, warning sur les by_position convertis en x_pct/y_pct)
• Pas de bouton « rejouer le workflow tel quel sans review » pour tester vite

Actions :

1. Vérifier l'affichage pendingReviewCount dans le header + ajouter un badge coloré
2. Dans StepNode.tsx, afficher un ⚠️ quand step.parameters.compound_steps existe ou quand metadata.core_edge_id manque d'info
3. Exposer les warnings retournés par l'import dans un panneau dépliant sur le workflow importé
4. Bouton « Valider et exécuter » qui passe review_status='approved' puis lance le replay via /execute

C2. Persister la bibliothèque de captures côté serveur

Effort : 1,5 jour Contexte : extension de B1 si on veut une bibliothèque réellement persistante et partagée entre sessions/machines

• Nouvelle table captures_library(id, screenshot_b64, timestamp, label, favorite, workflow_id NULL)
• Endpoints GET/POST/DELETE /api/v3/captures/library
• CaptureLibrary.tsx : fetch initial + mutations, plus de localStorage
• Bonus : associer une capture à un step (fav pour référence future)

C3. Unifier les deux frontends — retirer frontend/ (legacy)

Effort : 2 jours (avec vérif de non-régression) Contexte : frontend/ (v2 React 19 + MUI + Redux) n'est plus maintenu, frontend_v4/ (Vite + xyflow) est la cible. 14 tests tests/property/test_vwb_frontend_v2_* pointent vers le v2.

• Auditer ce que le v4 ne fait pas encore (CorrectionPacksDashboard, CoachingPanel, etc.) → décider si on porte ou si on abandonne
• Archiver frontend/ dans _archives/ ou le supprimer
• Désactiver run.sh ou le refaire pointer sur v4
• Porter ou supprimer les tests test_vwb_frontend_v2_*

C4. Consolider les 3 app*.py

Effort : 1 jour Contexte : app.py est le seul utilisé pour le VWB. app_lightweight.py sert uniquement à l'endpoint catalogue VLM sur 5003 (un seul endpoint utile). app_catalogue_simple.py n'est plus référencé.

• Supprimer app_catalogue_simple.py
• Déplacer le seul endpoint utile de app_lightweight.py dans app.py + retirer le port 5003 de services.conf
• Supprimer app_lightweight.py
• Gain : -2800 lignes, un seul point d'entrée

C5. Lier étape VWB ↔ screenshot source du workflow Léa

Effort : 2 jours Contexte : actuellement quand on importe un workflow Léa, les steps sont des actions sans contexte visuel. Pour pouvoir « corriger visuellement » (idée Dom), il faut que chaque step affiche :

• Le screenshot from_node (état avant l'action)
• Le screenshot to_node (état après)
• Les bbox cliquées (target)
• Les workflows Léa contiennent déjà des screenshot_hash dans leurs nodes (à vérifier dans notepad_enriched.json)
• Modifier convert_learned_to_vwb_steps pour persister les screenshots en tant que VisualAnchor + anchor_id sur le step
• Enrichir StepNode.tsx pour afficher la vignette

Note : c'est ce qui donne du sens à l'idée de Dom. Sans ça, l'import Léa→VWB donne des étapes abstraites « click(x=42%, y=68%) » que personne ne peut corriger visuellement.

---

Section D — Chantiers lourds (>1 semaine)

D1. Refonte du stockage workflow : un seul format canonique

Effort : 1-2 semaines Justification : aujourd'hui on a 2 formats (core JSON de Léa vs SQLite VWB) avec un bridge. Le bridge perd de l'information (ex: compound décomposé, metadata core/screenshots abandonnés en route). À chaque nouvelle feature du core (C2 aujourd'hui, grounding, extraction, etc.) il faut mettre à jour le bridge.

Proposition : VWB stocke directement le format core JSON (ou un surset strict). Les « steps » VWB deviennent une vue dérivée du graphe core, pas une copie. Les corrections humaines modifient le JSON core.

À faire seulement si l'import Léa→VWB devient un flux majeur et que le bridge montre ses limites. Pour l'instant, le bridge fait le job.

D2. Mode collaboratif / multi-utilisateurs

Effort : 2-3 semaines Justification : aucune pour aujourd'hui. Dom est seul à utiliser le VWB. À garder dans le coin de la tête pour quand les premiers clients testeront.

---

Section E — Non-décisions

Choses qu'on ne fera pas, pour se prémunir des tentations.

E1. Ne PAS réécrire le frontend en v5

Pourquoi : le v4 Vite+xyflow est récent (mars 2026), propre, bien structuré. Pas de raison architecturale. La migration v3→v4 a déjà coûté cher (cf. nombreux CORRECTION_TYPESCRIPT_*.md en janvier).

E2. Ne PAS unifier instance/*.db en PostgreSQL

Pourquoi : SQLite convient pour un outil desktop mono-utilisateur. PostgreSQL ajoute une dépendance runtime sans valeur tangible tant qu'on est seul. Le .env mentionne déjà l'option, gardée pour plus tard.

E3. Ne PAS porter CorrectionPacksDashboard sur le v4

Pourquoi : la fonctionnalité « correction packs » est en doublon conceptuel avec le nouveau flux review_status + learned_workflow_bridge. Autant fermer proprement correction_packs (C4 bis) plutôt que le migrer.

E4. Ne PAS rajouter de tests property pour le v4 tout de suite

Pourquoi : 14 tests test_vwb_frontend_v2_* existent déjà et ne tournent plus (pointent vers le v2). Avant de recréer des tests property, il faut décider si on garde le v2 ou pas (C3). Refaire 14 tests pour les jeter dans 2 semaines = gâchis.

E5. Ne PAS implémenter le mode WebSocket realtime pour le VWB

Pourquoi : le polling actuel (500 ms dans App.tsx) suffit pour l'usage. WebSocket existe déjà (socketio) mais n'est câblé nulle part dans le v4. On peut l'ajouter quand une vraie feature le demande (ex: collaborative editing = E1/D2 → pas maintenant).

---

Section F — Recommandation d'ordre

Semaine 1 — quick wins utilisateur (jour J)

1. B1 — localStorage pour CaptureLibrary (30 min) → résout le bug principal
2. B2 — nom lisible à l'import (20 min) → la liste devient utilisable
3. B3 — supprimer BDD fantôme (15 min) → évite un bug futur
4. B6 — nettoyer les fichiers parasites (10 min) → hygiène
5. B7 — clarifier run.sh (20 min) → moins de confusion

Total : ~2h de dev pour un retour utilisateur net dès demain.

Semaine 1 — chantier moyen utile (jours J+1 à J+3) 6. C1 — finaliser le flux « Import Léa → review → replay ». C'est la VALEUR DIRECTE de l'idée de Dom : « importer les workflows Léa pour les corriger visuellement ».

Semaine 2 — étendre la valeur (si C1 tient la route) 7. C5 — lier step ↔ screenshot source. C'est ce qui transforme le VWB en vrai outil de correction visuelle. Sans ça, l'import Léa est abstrait.

Semaine 3+ — consolidation (quand bande passante) 8. C3 — retirer frontend legacy (gain de clarté) 9. C4 — consolider les 3 app*.py (gain dette) 10. C2 — bibliothèque captures serveur (si B1 montre ses limites)

Justification globale :

• Les 2h de quick wins donnent à Dom une expérience visible et immédiate (bibliothèque qui ne s'efface plus, liste lisible, moins de bruit).
• C1 capitalise sur l'investissement existant (le pont Léa/VWB est déjà codé à 80%, il faut juste finir le dernier kilomètre — les warnings visuels et le bouton « valider et exécuter »).
• C5 est le vrai game-changer pour l'idée de Dom, mais ne vaut le coup que si C1 a confirmé que le flux globalement fonctionne. Si C1 révèle que le bridge perd trop d'info, on saute direct à D1 (refonte).
• C3/C4 sont de la dette : on s'en occupe quand on a quelqu'un sous la main pour pas ralentir les features.

À éviter : commencer par C3 ou C4 (dette) parce qu'aucun impact utilisateur visible → pas de ROI court terme.

---

Risques identifiés

• Backup BDD : backend/instance/backups/ contient un seul backup du 23/01. Aucune rotation automatique. Risque de perte : 3 workflows seulement mais ce sont ceux de Dom → ajouter un backup quotidien via backup_ssd.sh (déjà existant à la racine ~/ai/).
• localStorage quota : B1 seul ne suffira pas à long terme. Prévoir C2 si Dom fait plus de 50-100 captures en PNG base64.
• Modèle Workflow sans cascade sur source='learned_import' : si Dom supprime un workflow importé, rien ne met à jour le JSON core sur disque → divergence. Acceptable tant que l'import est monodirectionnel (disque → VWB) mais à surveiller.

---

Métriques de succès

• Bibliothèque persiste après reload navigateur : testable manuellement en 30 s
• Liste de workflows ne contient plus « Unnamed Workflow » : testable via SQL
• Un workflow Léa importé a un badge « à réviser » visible, et le bouton « Valider et exécuter » le fait tourner sans quitter le VWB
• 0 warning 404 dans backend/logs/vwb.log après B5
• run_v4.sh unique script documenté dans README