# Protocole de test humain E2E — POC Aiva-vision

**Date** : 2026-06-01
**Version** : 1.0
**Objet** : valider le POC en conditions réelles — apprentissage → restitution → correction → persistance → replay supervisé → verdict
**Durée estimée** : 45-60 minutes

---

## 1. Checklist pré-test

### 1.1 Services à vérifier

| Service | Port | Comment vérifier | GO/NO-GO |
|---------|------|------------------|----------|
| Ollama | 11434 | `curl http://localhost:11434/api/tags` — doit retourner la liste des modèles | ☐ |
| Streaming server | 5005 | `curl http://localhost:5005/health` ou `./svc.sh status` | ☐ |
| Web Dashboard | 5001 | `curl http://localhost:5001/health` ou ouvrir `http://localhost:5001` | ☐ |
| Agent Chat | 5004 | `curl http://localhost:5004/health` ou ouvrir `http://localhost:5004` | ☐ |
| VWB Backend | 5002 | `./svc.sh status` (optionnel si on ne teste pas via VWB) | ☐ |
| VWB Frontend | 3002 | `curl http://localhost:3002` (optionnel) | ☐ |

Commande rapide pour tout vérifier d'un coup :
```bash
./svc.sh status
```

### 1.2 Modèles Ollama requis

```bash
ollama list
```

Vérifier la présence de :
- `qwen2.5vl:7b` (ou `qwen2.5vl:7b-rpa`) — grounding visuel
- `qwen2.5:7b` — raisonnement texte
- `qwen2.5:0.5b` — intent recognition léger (fallback)

**Si un modèle manque** : `ollama pull <nom>` avant de continuer.

### 1.3 Compétences existantes dans le catalogue

Ouvrir le dashboard → onglet **Knowledge Base**. Vérifier la présence de :

| Compétence | État attendu |
|------------|-------------|
| `key_win_r_wait_explorer_exe` | `candidate` |
| `key_ctrl_s_wait_notepad_exe` | `candidate` |
| `key_alt_f4_wait_windowsterminal_exe` | `candidate` |

**Si le catalogue est vide** : les fichiers YAML doivent exister dans `data/competences/candidate/`. Vérifier :
```bash
ls -la data/competences/candidate/
```
Si les fichiers existent mais n'apparaissent pas dans le dashboard, redémarrer le streaming server (`./svc.sh restart streaming`).

### 1.4 Agent Windows connecté

- Dans le dashboard, vérifier que la machine cible apparaît (ex: `DESKTOP-XXXXX_windows`).
- Si l'agent n'est pas connecté : le lancer depuis le poste Windows (`Lea_v*.zip` → `lea_agent.exe`).
- **Machine cible** : noter le `machine_id` exact (affiché dans le dashboard ou dans `data/agents/`).

### 1.5 État initial de la machine Windows

Avant toute manipulation :

- [ ] **Fermer tous les dialogues parasites** : boîtes de dialogue "Enregistrer", "Exécuter", confirmations, pop-up Windows Update
- [ ] **Fermer les applications non nécessaires** : tout garder minimal (bureau + applications de test uniquement)
- [ ] **Vérifier que le bureau est visible** : pas d'application plein écran
- [ ] **Couper les notifications Windows** : mode "Ne pas déranger" activé (Win+A → activer)
- [ ] **Noter la résolution écran** : `Win+I → Système → Écran` (utile si un problème de positionnement survient)

### 1.6 Dossier de collecte des preuves

Créer un dossier de travail pour cette session de test :
```bash
mkdir -p /home/dom/ai/rpa_vision_v3/docs/demo/e2e-poc-$(date +%Y%m%d)
```

Ce dossier recevra les screenshots, logs, et verdicts collectés pendant le test.

---

## 2. Protocole pas-à-pas

### Phase 1 — Démarrer Léa / agent Windows

**Ce que l'opérateur fait** :
1. Vérifier que l'agent Windows est connecté (dashboard → page principale)
2. Noter le `machine_id` affiché
3. Ouvrir l'agent chat (`http://localhost:5004`) dans un navigateur

**Ce que Léa fait** : Rien (état IDLE)

**Ce qu'on doit voir** :
- Dashboard : machine connectée, statut "online"
- Agent chat : interface de conversation vide, bouton "Apprendre" visible

**Critère GO/NO-GO** :
- GO : agent chat accessible, machine connectée
- NO-GO : relancer l'agent Windows, vérifier le réseau, vérifier que le streaming server tourne

**Preuve à collecter** :
- Screenshot du dashboard montrant la machine connectée
- Copier le `machine_id` dans un fichier `preuves/machine_id.txt`

---

### Phase 2 — Déclencher l'apprentissage depuis agent-chat

**Ce que l'opérateur fait** :
1. Dans l'agent chat, taper : `lea apprends-moi` ou cliquer le bouton "Apprendre" si disponible
2. Observer la réponse de Léa

**Ce que Léa fait** :
- Transition IDLE → LISTENING → WAITING_USER_STOP
- Répond : *"Je te regarde. Fais ce que tu veux m'apprendre, et dis-moi « stop » ou « j'ai fini » quand c'est terminé."*
- Appelle `shadow_start` côté streaming server

**Ce qu'on doit voir** :
- Message de Léa confirmant qu'elle observe
- Side shadow actif côté streaming server (vérifiable via `curl http://localhost:5005/api/v1/shadow/sessions` si endpoint existe)

**Critère GO/NO-GO** :
- GO : Léa a répondu avec le message d'observation
- NO-GO : si `shadow_start` échoue → vérifier streaming server, token API (`RPA_API_TOKEN`), relancer

**Preuve à collecter** :
- Screenshot de la conversation agent-chat
- Copier le `session_id` (affiché dans la réponse ou dans les logs `agent_chat/state/`)

---

### Phase 3 — Observer une tâche courte

**Tâche cible** : `Win+R` → ouverture de la boîte "Exécuter"

**Ce que l'opérateur fait** (sur le poste Windows) :
1. **Basculer sur la session Windows** (via RDP ou directement)
2. Appuyer sur `Win+R`
3. Vérifier que la boîte "Exécuter" s'ouvre
4. **Ne pas fermer** la boîte "Exécuter" (elle servira de preuve visuelle)
5. Revenir à l'agent chat

**Ce que Léa fait** :
- Capture les événements clavier (`key_press` pour `win` + `r`)
- Capture les screenshots avant/après
- Enregistre la session brute

**Ce qu'on doit voir** :
- La boîte "Exécuter" apparaît à l'écran Windows
- Dans les logs du streaming server, des événements `key_press` et des screenshots sont reçus

**Critère GO/NO-GO** :
- GO : la boîte "Exécuter" est visible à l'écran
- NO-GO : si `Win+R` ne fonctionne pas → vérifier que le clavier Windows n'est pas bloqué, que RDP ne capture pas les touches

**Preuve à collecter** :
- Screenshot de la boîte "Exécuter" ouverte (depuis le poste Windows)
- Noter l'heure exacte de l'action

---

### Phase 4 — Arrêter l'observation

**Ce que l'opérateur fait** :
1. Dans l'agent chat, taper : `stop` ou `j'ai fini`

**Ce que Léa fait** :
- Reconnaît l'intent `USER_STOP_OBSERVE` (regex, confiance > 0.9)
- Transition WAITING_USER_STOP → ANALYZING → PRESENTING
- Appelle `shadow_stop` + `shadow_understanding` côté streaming server
- Formate la restitution Option C

**Ce qu'on doit voir** :
- Léa répond avec un résumé de ce qu'elle a compris, par exemple :
  ```
  Voilà ce que j'ai compris :

  1. Touche → raccourci utilisé : « win + r »
  2. Fenêtre « Exécuter » → ouverte

  C'est bien ça ou je me suis trompée quelque part ?
  ```

**Critère GO/NO-GO** :
- GO : Léa a restitué au moins 1 étape correcte
- NO-GO : si Léa dit "aucune étape comprise" → vérifier que les screenshots ont bien été capturés, que le shadow était actif

**Preuve à collecter** :
- Screenshot de la restitution Léa dans l'agent chat
- Copier le contenu JSON de `understanding` depuis `curl http://localhost:5005/api/v1/shadow/<session_id>/understanding`

---

### Phase 5 — Restitution et correction (Option C — formateur)

**Ce que l'opérateur fait** :
1. **Lire attentivement** la restitution de Léa
2. Si c'est correct : taper `oui` ou `c'est bon` ou `parfait`
3. Si c'est incorrect : taper `corrige l'étape 1 : [description correcte]`

**Ce que Léa fait** :
- Si validation : transition ITERATING_FEEDBACK → NAMING
- Si correction : envoie le feedback au streaming server (`shadow_feedback`), reçoit la nouvelle compréhension, reformule
- Compte les corrections par étape (max 3 → sortie d'urgence)

**Ce qu'on doit voir** :
- Si corrigée : Léa reformule avec la correction appliquée
- Si validée : Léa demande le nom de la compétence

**Critère GO/NO-GO** :
- GO : Léa a soit validé soit corrigé avec reformulation
- NO-GO : si Léa ne comprend pas la correction → vérifier l'intent parser (logs), le regex, le fallback Ollama

**Preuve à collecter** :
- Screenshot de l'échange de correction (si applicable)
- Noter le nombre de corrections apportées

---

### Phase 6 — Nommer la compétence et marquer les paramètres

**Ce que l'opérateur fait** :
1. Donner un nom : `ouverture executer` ou `lancer executer`
2. Si Léa demande si une valeur est un paramètre : répondre "toujours" ou "c'est l'exemple du jour"
3. Pour `Win+R`, il n'y a pas de valeur saisie → aucun paramètre à marquer

**Ce que Léa fait** :
- Enregistre le nom de la compétence
- Cherche les steps avec des valeurs saisies → demande si ce sont des paramètres
- Transition NAMING → PERSISTING quand tout est marqué

**Ce qu'on doit voir** :
- Léa confirme : *"C'est enregistré sous « ouverture executer » (slug `ouverture_executer`). Paramètres : aucun."*

**Critère GO/NO-GO** :
- GO : Léa a confirmé la persistance
- NO-GO : si `shadow_build` ou `competence_persist` échoue → vérifier logs streaming server, endpoint `/api/v1/lea/competences/candidate/persist`

**Preuve à collecter** :
- Screenshot du message de confirmation
- Vérifier que le YAML a été créé : `ls -la data/competences/candidate/`
- Copier le contenu du YAML dans `preuves/competence_<slug>.yaml`

---

### Phase 7 — Tester via le dashboard (replay supervisé)

**Ce que l'opérateur fait** :
1. Ouvrir le dashboard → onglet **Knowledge Base**
2. Trouver la compétence fraîchement créée
3. Cliquer **Tester**
4. Une modale s'ouvre : "Prépare le test supervisé..."
5. **Avant de cliquer "Continuer le test"** :
   - Fermer la boîte "Exécuter" si elle est encore ouverte (étape critique — voir section 5 sur les faux succès)
   - Vérifier que le bureau Windows est visible, aucune application parasite
6. Cliquer **Continuer le test**

**Ce que Léa fait** :
- Envoie `Win+R` automatiquement sur le poste Windows via l'agent
- Attend que la boîte "Exécuter" apparaisse (wait_state)
- Se met en pause après l'action

**Ce qu'on doit voir** :
- La boîte "Exécuter" s'ouvre sur le poste Windows (~1-2 secondes après le clic "Continuer")
- La modale affiche "Valide le résultat de la compétence..." avec 3 boutons : **Valide**, **Invalide**, **Incertain**

**Critère GO/NO-GO** :
- GO : la boîte "Exécuter" apparaît et la modale de verdict est affichée
- NO-GO : si rien ne se passe → vérifier que l'agent Windows est connecté, que le replay a bien été lancé (logs streaming server)

**Preuve à collecter** :
- Screenshot de la boîte "Exécuter" ouverte (depuis Windows)
- Screenshot de la modale de verdict dans le dashboard

---

### Phase 8 — Enregistrer le verdict

**Ce que l'opérateur fait** :
1. Évaluer le résultat selon les critères :
   - **Valide** ✅ : la boîte "Exécuter" apparaît, au premier plan, correcte
   - **Invalide** ❌ : rien ne se passe, ou une autre fenêtre s'ouvre
   - **Incertain** ⚠️ : la boîte apparaît mais n'est pas au premier plan
2. Cliquer le bouton correspondant
3. La modale se ferme, le dashboard se rafraîchit

**Ce que Léa fait** :
- Persiste le verdict dans `data/competence_verdicts/verdicts.jsonl`
- Le replay reprend puis se termine

**Ce qu'on doit voir** :
- Le dashboard revient à la liste Knowledge Base
- Un nouveau verdict est enregistré (vérifiable dans le fichier JSONL)

**Critère GO/NO-GO** :
- GO : le verdict est enregistré, le fichier JSONL contient une nouvelle entrée
- NO-GO : si le verdict n'est pas persisté → vérifier logs dashboard, endpoint `/api/v1/lea/competences/<id>/verdict`

**Preuve à collecter** :
- Copier la dernière ligne du fichier `data/competence_verdicts/verdicts.jsonl` dans `preuves/verdict.jsonl`
- Screenshot du dashboard après verdict

---

### Phase 9 — Nettoyer et recommencer (itération)

Pour un test robuste, **répéter les phases 3-8 au moins 3 fois** avec des contextes différents :

| Itération | Contexte | Tâche |
|-----------|----------|-------|
| 1 | Bureau propre | `Win+R` → Exécuter |
| 2 | Avec Notepad ouvert + texte non sauvegardé | `Ctrl+S` → Enregistrer sous |
| 3 | Avec Notepad ouvert au premier plan | `Alt+F4` → Fermer |

**Ou** répéter 3 fois la même tâche avec des contextes légèrement différents (fenêtres ouvertes différentes, résolution modifiée, etc.) pour valider la robustesse.

---

## 3. Critères GO/NO-GO globaux

### 3.1 Qu'est-ce qui valide le POC ?

| Critère | Seuil |
|---------|-------|
| **Apprentissage par observation** | ✅ Léa doit restituer correctement au moins **1 tâche sur 3** tentées |
| **Restitution compréhensible** | ✅ Le texte Option C doit être lisible par un humain non-technique (phrases françaises, pas JSON) |
| **Correction acceptée** | ✅ Léa doit accepter et appliquer au moins **1 correction** |
| **Persistance** | ✅ Le YAML doit être créé dans `data/competences/candidate/` |
| **Replay supervisé** | ✅ Au moins **2 replays réussis sur 3** (la tâche est rejouée automatiquement) |
| **Verdict humain** | ✅ Les verdicts doivent être persistés dans le JSONL |

**Le POC est validé si** : au moins **2 des 3 compétences** du batch 1 passent le cycle complet (apprentissage → restitution → persistance → replay → verdict) avec un verdict **Valide**.

### 3.2 Échecs acceptables

| Échec | Acceptable ? | Condition |
|-------|-------------|-----------|
| `Alt+F4` → verdict Incertain | ✅ Oui | Le gap `alt_f4_confirmation_dialog_not_covered` est documenté |
| Ollama fallback timeout | ✅ Oui | Si les regex passent quand même (confiance > 0.9) |
| 1 correction sur 3 nécessaires | ✅ Oui | C'est dans le design (max 3 corrections/step) |
| Wait_state timeout sur Alt+F4 | ✅ Oui | Le success_marker est trop spécifique (artefact de session) |

### 3.3 Échecs bloquants

| Échec | Bloquant ? | Action |
|-------|-----------|--------|
| `shadow_start` échoue systématiquement | 🔴 BLOQUANT | L'agent Windows ne communique pas avec le streaming server |
| Aucune restitution (understanding vide) | 🔴 BLOQUANT | Le pipeline shadow ne reconstruit pas les étapes |
| `competence_persist` échoue | 🔴 BLOQUANT | La persistance ne fonctionne pas |
| Replay ne déclenche aucune action | 🔴 BLOQUANT | L'agent Windows ne reçoit pas les ordres |
| Verdict non persisté | 🔴 BLOQUANT | Le contrat de verdict n'est pas implémenté |

---

## 4. Preuves à collecter

### 4.1 Fichiers à vérifier après le test

| Fichier | Contenu | Comment vérifier |
|---------|---------|------------------|
| `data/competences/candidate/*.yaml` | Compétences persistées | `ls -la` + `cat` pour vérifier le contenu |
| `data/competence_verdicts/verdicts.jsonl` | Verdicts humains | `tail -n 5` pour voir les derniers verdicts |
| `agent_chat/state/learn_*.json` | États des sessions d'apprentissage | `ls -la agent_chat/state/` |
| `data/raw_sessions/<session_id>/` | Sessions brutes (screenshots + événements) | Vérifier la présence de screenshots |
| Logs streaming server | `journalctl -u rpa-streaming` ou stdout du process | Chercher les erreurs HTTP 5xx |
| Logs agent chat | stdout du process ou `logs/agent_chat.log` | Vérifier les transitions d'état |
| Logs dashboard | stdout du process ou `logs/dashboard.log` | Vérifier les appels replay/verdict |

### 4.2 Comment documenter un succès

Créer un fichier `preuves/succes_<competence_slug>.md` avec :

```markdown
# Succès — <nom de la compétence>

**Date** : 2026-06-01
**Session ID** : learn_xxx
**Machine** : DESKTOP-XXXXX_windows

## Preuves
- Screenshot restitution : `preuves/screenshot_restitution_<slug>.png`
- Screenshot replay : `preuves/screenshot_replay_<slug>.png`
- YAML : `data/competences/candidate/<slug>.yaml`
- Verdict : dernière ligne de `data/competence_verdicts/verdicts.jsonl`

## Observations
- Nombre de corrections : X
- Temps d'apprentissage : ~X minutes
- Temps de replay : ~X secondes
```

### 4.3 Comment documenter un échec

Créer un fichier `preuces/echec_<competence_slug>.md` avec :

```markdown
# Échec — <nom de la compétence>

**Date** : 2026-06-01
**Session ID** : learn_xxx
**Phase d'échec** : apprentissage / restitution / persistance / replay / verdict

## Symptôme
<description de ce qui s'est passé>

## Logs pertinents
<extraits de logs>

## Cause probable
<hypothèse>

## Reproduire
<étapes pour reproduire>
```

---

## 5. Risques de faux succès

### 5.1 Comment distinguer un vrai succès d'un faux positif

| Risque | Comment le détecter | Mitigation |
|--------|-------------------|------------|
| **Dialogue déjà ouvert** avant le replay | Vérifier visuellement **avant** de cliquer "Continuer le test" | Fermer tous les dialogues parasites (checklist phase 1.5) |
| **machine_id spoofé** ou wrong target | Vérifier que le `machine_id` dans le verdict correspond à la machine de test | Noter le `machine_id` en phase 1, le comparer dans le verdict JSONL |
| **Léa envoie les touches mais une autre app les reçoit** | Vérifier que la fenêtre cible est **au premier plan** avant le replay | Mettre la fenêtre cible au premier plan avant de cliquer "Continuer" |
| **Wait_state passe par chance** (la fenêtre était déjà là) | Le wait_state doit détecter un **changement d'état**, pas un état statique | Vérifier que le wait_state est bien un "appear" et pas un "already present" |
| **Verdict enregistré mais replay non exécuté** | Vérifier que `step_results[]` dans le verdict contient des steps avec `status: success` | Lire le JSONL et vérifier le contenu de `step_results` |

### 5.2 Pièges spécifiques à éviter

1. **RDP et les touches Windows** : en session RDP, `Win+R` peut être capturé par la machine locale au lieu de la machine distante.
   - **Solution** : dans le client RDP, options → Clavier local → "Appliquer les combinaisons de touches Windows : Sur le serveur distant"

2. **Notifications Windows** : une notification pop-up peut voler le focus pendant le replay.
   - **Solution** : activer le mode "Ne pas distrub" avant le test

3. **Windows Update** : un redémarrage intempestif pendant le test.
   - **Solution** : suspendre Windows Update temporairement

4. **Agent Windows déconnecté** : le replay est envoyé mais l'agent ne le reçoit pas.
   - **Solution** : vérifier la connexion avant chaque replay (dashboard → statut machine)

5. **Session shadow non fermée** : si `shadow_stop` n'a pas été appelé correctement, la session reste ouverte et peut interférer.
   - **Solution** : vérifier `agent_chat/state/` — aucune session ne doit être dans un état non-terminal avant de recommencer

---

## 6. Bonus — Learning pack portable

### 6.1 Structurer les artefacts POC

Le risque : se retrouver avec des milliers de fichiers éparpillés entre `data/raw_sessions/`, `data/competences/`, `data/competence_verdicts/`, `agent_chat/state/`, et les screenshots.

**Structure recommandée** pour un POC exportable :

```
learning-poc-<date>/
├── manifest.json              # Métadonnées : date, machine, opérateur, version du code
├── competences/
│   ├── <slug_1>.yaml          # Compétences persistées
│   └── <slug_2>.yaml
├── verdicts/
│   └── verdicts.jsonl         # Verdicts humains (copie du JSONL)
├── sessions/
│   ├── <session_id>/
│   │   ├── events.jsonl       # Événements bruts
│   │   └── screenshots/       # Screenshots (compressés)
│   └── <session_id>/
├── audit/
│   ├── promotions.jsonl       # Audit de promotion (si applicable)
│   └── test-log.md            # Journal du test humain
└── proofs/
    ├── screenshot_restitution_*.png
    ├── screenshot_replay_*.png
    └── succes_*.md / echec_*.md
```

### 6.2 Script d'export rapide

```bash
#!/bin/bash
# export_learning_poc.sh — créer un zip portable du POC
DATE=$(date +%Y%m%d)
DEST="learning-poc-${DATE}"

mkdir -p "$DEST"/{competences,verdicts,sessions,audit,proofs}

# Compétences candidate
cp data/competences/candidate/*.yaml "$DEST/competences/" 2>/dev/null

# Verdicts
cp data/competence_verdicts/verdicts.jsonl "$DEST/verdicts/" 2>/dev/null

# Audit
cp data/competences/promotions.jsonl "$DEST/audit/" 2>/dev/null

# Sessions récentes (dernières 24h)
find data/raw_sessions/ -maxdepth 1 -mtime -1 -type d -exec cp -r {} "$DEST/sessions/" \; 2>/dev/null

# States agent chat
cp agent_chat/state/learn_*.json "$DEST/audit/" 2>/dev/null

# Manifest
cat > "$DEST/manifest.json" <<EOF
{
  "created_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "machine": "$(hostname)",
  "operator": "${OPERATOR:-dom}",
  "code_version": "$(git rev-parse --short HEAD 2>/dev/null || echo 'unknown')",
  "competences_count": $(ls "$DEST/competences/"*.yaml 2>/dev/null | wc -l),
  "verdicts_count": $(wc -l < "$DEST/verdicts/verdicts.jsonl" 2>/dev/null || echo 0)
}
EOF

# Zip
zip -r "${DEST}.zip" "$DEST/"
echo "Pack créé : ${DEST}.zip"
```

### 6.3 Export vers DGX Spark

Le learning pack ainsi structuré est **autonome** :

1. Transférer le zip vers le DGX Spark : `scp learning-poc-*.zip user@dgx-spark:/path/to/imports/`
2. Importer côté DGX : le script d'import lit le `manifest.json`, place les YAML dans `data/competences/candidate/`, les verdicts dans `data/competence_verdicts/`, et les sessions dans `data/raw_sessions/`
3. Vérifier l'import : `ls data/competences/candidate/` + `tail data/competence_verdicts/verdicts.jsonl`

**Invariant** : le learning pack ne contient **pas** de modèles Ollama, pas de dépendances Python, pas de fichiers système. Uniquement des artefacts métier (YAML, JSONL, screenshots, events).

---

## Annexe — Résumé visuel du flux

```
[IDLE] ──(apprends-moi)──> [LISTENING] ──> [WAITING_USER_STOP]
                                                      │
                                               (stop / j'ai fini)
                                                      │
                                                      v
[DONE] <── [PERSISTING] <── [NAMING] <── [ITERATING_FEEDBACK] <── [ANALYZING]
  │                                                      │
  │                                          (oui / corrige étape N)
  │                                                      │
  +──> YAML + verdict JSONL <── Dashboard: Tester ──> Replay supervisé
                                                        │
                                                    Valide/Invalide/Incertain
```

---

*Document créé le 2026-06-01. À suivre pas-à-pas pendant la démo.*