docs: track design docs, plans, audits, coordination infrastructure, handoffs

- 21 docs/*.md: audits, design notes, deployment plans, checklists, memos - Coordination: ROLES, runbooks (DGX reboot, Lea live), patches, registre, syntheses, systemd, QG template - Handoffs: 6 Codex handoff documents + README + template
2026-07-02 13:29:58 +02:00
parent 7dd5c872df
commit 6907ecc82f
42 changed files with 5267 additions and 0 deletions
--- a/docs/INSTALLATION_MULTI_SITE.md
+++ b/docs/INSTALLATION_MULTI_SITE.md
@@ -0,0 +1,540 @@
+# Guide d'installation Lea - POC, MVP, production et multi-site
+
+- Date: 2026-06-19
+- Statut: version initiale exploitable, a durcir avant production
+- Scope: installations Lea/RPA Vision V3 sur DGX + postes ou VM Windows
+- Source: etat POC DGX, runbooks coordination, installeur Windows, systemd, dashboard/VWB/worker
+
+## Objectif
+
+Ce document sert de base d'installation reproductible pour plusieurs phases:
+
+1. **POC**: installation controlee sur un site pilote, avec assistance technique forte.
+2. **MVP**: installation repetable avec artefacts figes, checklist, rollback et preuves.
+3. **Production**: installation industrialisee, secrets par site, supervision, sauvegardes, signature de l'installeur, support.
+4. **Multi-etablissement**: meme produit, mais variables reseau, comptes, tokens, politiques de securite et donnees separees par etablissement.
+
+Le principe directeur: une installation Lea ne doit pas dependre de la memoire d'un agent ou d'une session de debug. Elle doit etre executable par une checklist, testable, rollbackable et auditable.
+
+## Architecture cible d'une installation
+
+### Composants cote serveur
+
+| Composant | Role | Port POC | Exposition attendue |
+|---|---|---:|---|
+| Dashboard Flask | supervision, verite produit, fleet, workflow status | 5001 | LAN/VPN autorise avec auth |
+| VWB backend | workflows, anchors, base SQLite VWB | 5002 | local ou LAN controle selon packaging |
+| Agent Chat | chat Lea, bulles, feedback temps reel | 5004 | accessible depuis poste/VM Windows |
+| Streaming/Fleet | ingestion agent Windows, sessions, API agent | 5005 | accessible depuis poste/VM Windows |
+| Upload/API core | API interne upload/traitement | 8000 | loopback par defaut |
+| Worker | compilation/apprentissage/replay | n/a | service systemd |
+| Ollama/VLM | inference locale | 11434 | local DGX, pas expose sauf decision explicite |
+| VM/VNC Windows | console Windows DGX si utilisee | 5902 | tunnel SSH/VPN uniquement |
+
+### Composants cote Windows
+
+| Composant | Role | Artefact |
+|---|---|---|
+| Lea agent | capture, tray, chat, apprentissage, streaming | `deploy/lea_package` ou installeur Inno |
+| `config.txt` | URL serveur, token API, machine id, label utilisateur | genere par dashboard ou installeur |
+| Installeur Inno | installation MVP/prod, Python embedded, silent install | `deploy/installer/Lea.iss` |
+| VM Windows | poste de test ou execution clinique | VMware, Hyper-V, QEMU standalone ou poste physique |
+
+## Niveaux d'installation
+
+| Niveau | Usage | Acceptable | Interdit |
+|---|---|---|---|
+| POC labo | tests rapides, validation technique | scripts manuels documentes, tunnel VNC, debug coordonne | secrets reutilises sans trace, actions non consignees |
+| POC site | installation pilote chez client | artefact fige, runbook, rollback, preuves | activer reseau/site sans fenetre et rollback |
+| MVP | repetition sur plusieurs postes | installeur signe ou controle, config par poste, smoke automatique | ZIP manuel non versionne comme seul chemin |
+| Production | support multi-etablissement | CI release, signature, supervision, backups, rotation secrets | `DASHBOARD_AUTH_DISABLED`, tokens partages, ports remote ouverts |
+
+## Fiche site obligatoire
+
+Chaque etablissement doit avoir une fiche separee avant installation.
+
+```text
+SITE_ID=
+Nom etablissement=
+Contact technique=
+Contact metier=
+Fenetre installation=
+Fenetre rollback=
+
+DGX_HOSTNAME=
+DGX_IP_LAB=
+DGX_IP_SITE=
+DGX_PREFIX=
+DGX_GATEWAY=
+DGX_DNS_1=
+DGX_DNS_2=
+IPv6=off/on
+VLAN=non/oui + id
+Interface Ethernet cible=
+
+Dashboard URL=
+Streaming URL agent=
+Agent Chat URL=
+VWB URL=
+
+Windows cible=
+Type Windows=poste physique / VMware / Hyper-V / QEMU DGX
+Nom machine Windows=
+Utilisateur Windows=
+Mode acces distant=VNC / RDP / console hyperviseur / aucun
+
+RPA_API_TOKEN=
+DASHBOARD_USER=
+DASHBOARD_PASSWORD=
+ENCRYPTION_PASSWORD=
+SECRET_KEY=
+
+Politique retention=
+Chemin backup=
+Responsable validation GO=
+```
+
+Regle: aucun token ou mot de passe d'un site ne doit etre reutilise sur un autre site.
+
+## Pre-requis avant installation
+
+### Pre-requis DGX ou serveur Linux
+
+- OS Linux valide pour le deploiement.
+- Acces admin local ou fenetre avec administrateur.
+- Python 3.10 a 3.12.
+- GPU NVIDIA si inference VLM locale attendue.
+- Ollama installe si le mode VLM local l'utilise.
+- Repo disponible sur la branche cible, par exemple `poc-dgx` pour le POC.
+- Ports internes/externes arbitres avant installation.
+- Disque libre suffisant pour sessions, captures, backups et modeles.
+- Politique backup validee avant toute migration ou reset.
+
+### Pre-requis Windows
+
+- Windows 10/11.
+- Droits suffisants pour installer Lea.
+- Acces reseau au DGX sur les ports agent requis.
+- Pour MVP/prod, privilegier l'installeur Inno avec Python embedded.
+- Pour POC, le ZIP `deploy/Lea_v<version>.zip` reste acceptable si documente.
+
+### Pre-requis securite
+
+- `DASHBOARD_AUTH_DISABLED` interdit hors dev local.
+- `RPA_AUTH_DISABLED` interdit hors dev local.
+- `RPA_API_TOKEN` obligatoire.
+- `DASHBOARD_PASSWORD` obligatoire.
+- Remote desktop/VNC/RDP ouverts uniquement en tunnel/VPN, jamais en LAN large par defaut.
+- Les secrets sont stockes hors git.
+- Le poste Windows doit afficher clairement l'etat d'enregistrement/apprentissage.
+
+## Procedure POC actuelle
+
+Cette section decrit l'etat connu du POC DGX. Elle n'est pas encore le chemin production final.
+
+### 1. DGX - recuperer le code
+
+```bash
+git clone <repo> rpa_vision_v3
+cd rpa_vision_v3
+git checkout poc-dgx
+```
+
+Si le DGX contient deja des donnees runtime, ne jamais faire de reset destructif sans backup des chemins suivants:
+
+```text
+visual_workflow_builder/backend/instance/workflows.db
+visual_workflow_builder/backend/data/
+data/training/
+data/runtime/
+data/workflows
+graphify-out/ si l'historique graphe doit etre preserve
+```
+
+### 2. DGX - environnement Python
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+### 3. DGX - configuration runtime
+
+Creer `.env.local` depuis le modele:
+
+```bash
+cp deploy/systemd/rpa_vision_v3.env.example .env.local
+```
+
+Valeurs obligatoires a remplacer:
+
+```text
+ENCRYPTION_PASSWORD=CHANGE_ME
+SECRET_KEY=CHANGE_ME
+RPA_API_TOKEN=CHANGE_ME
+DASHBOARD_USER=lea
+DASHBOARD_PASSWORD=CHANGE_ME
+ENVIRONMENT=production
+RPA_PROCESSING_WORKER=external
+RPA_API_HOST=127.0.0.1
+RPA_DASHBOARD_HOST=0.0.0.0
+RPA_VLM_MODEL=gemma4:26b
+RPA_GROUNDING_ENGINE=qwen3vl_vllm
+VLLM_MODEL=Qwen/Qwen3-VL-4B-Instruct
+```
+
+Pour un site, documenter explicitement quels services restent en loopback et quels services sont accessibles depuis la VM/poste Windows. En POC DGX, le dashboard est expose au LAN sur `0.0.0.0:5001` avec auth. En clinique durcie, preferer un reverse proxy HTTPS ou un bind loopback derriere proxy/VPN.
+
+### 4. DGX - services
+
+Services systemd attendus ou equivalents:
+
+```text
+rpa-agent-chat.service
+rpa-firewall.service
+rpa-streaming.service
+rpa-vision-v3-api.service
+rpa-vision-v3-dashboard.service ou fallback rpa-vision-v3-dashboard-user
+rpa-vision-v3-worker.service
+rpa-vision-v3-stream-worker.service
+rpa-vision-v3-vwb-backend.service
+rpa-vision-v3-vwb-frontend.service
+rpa-vllm-grounder.service si active
+rpa-vision.target
+```
+
+Commandes de controle:
+
+```bash
+systemctl status rpa-agent-chat.service
+systemctl status rpa-firewall.service
+systemctl status rpa-streaming.service
+systemctl status rpa-vision-v3-dashboard.service
+systemctl status rpa-vision-v3-worker.service
+systemctl status rpa-vision-v3-stream-worker.service
+systemctl status rpa-vision-v3-vwb-backend.service
+systemctl status rpa-vision-v3-vwb-frontend.service
+systemctl list-units 'rpa*'
+```
+
+En POC dev, `svc.sh` reste utilisable:
+
+```bash
+./svc.sh status
+./svc.sh start
+./svc.sh restart api
+./svc.sh stop
+```
+
+### 5. DGX - modele local
+
+Verifier Ollama et les modeles attendus. Le POC DGX distingue:
+
+- cerveau/lecteur Ollama: par exemple `gemma4:26b` selon `.env.local`;
+- grounder VLM via vLLM: `Qwen/Qwen3-VL-4B-Instruct` avec `think=false`.
+
+```bash
+curl http://localhost:11434/api/tags
+ollama list
+# Si le modele site manque:
+ollama pull <modele_ollama_site>
+```
+
+Ne pas exposer `11434` au LAN sans decision explicite.
+
+### 6. DGX - donnees VWB/apprentissage
+
+Verifier:
+
+```bash
+test -f visual_workflow_builder/backend/instance/workflows.db
+find visual_workflow_builder/backend/data -maxdepth 3 -type f | head
+find data/training -maxdepth 3 -type f | head
+```
+
+Endpoints utiles:
+
+```bash
+curl -s http://127.0.0.1:5002/health
+curl -s http://127.0.0.1:5005/health
+curl -s http://127.0.0.1:5001/api/system/status
+```
+
+Selon l'auth dashboard, `5001` peut repondre `401`; c'est attendu si l'auth est active.
+
+## Installation Windows
+
+### Chemin POC ZIP
+
+Construire le package:
+
+```bash
+./deploy/build_package.sh --clean
+./deploy/build_package.sh
+```
+
+Copier `deploy/Lea_v<version>.zip` sur la machine Windows, puis:
+
+1. Dezipper.
+2. Modifier `config.txt`.
+3. Lancer `install.bat`.
+4. Lancer `Lea.bat`.
+
+`config.txt` minimum:
+
+```text
+RPA_SERVER_URL=http://<DGX_IP>:5005/api/v1
+RPA_API_TOKEN=<token_site_ou_poste>
+RPA_MACHINE_ID=<site-machine-unique>
+RPA_USER_LABEL=<nom_utilisateur_ou_poste>
+RPA_BLUR_SENSITIVE=false
+RPA_LOG_RETENTION_DAYS=180
+```
+
+### Chemin MVP/prod installeur
+
+Le chemin cible est l'installeur Inno Setup:
+
+```bash
+./deploy/installer/build_installer.sh
+```
+
+Sortie attendue:
+
+```text
+deploy/releases/Lea-Setup-v1.0.1.exe
+```
+
+Installation silencieuse type:
+
+```cmd
+Lea-Setup-v1.0.1.exe /VERYSILENT /CONFIG=C:\temp\enroll.txt /DIR="C:\Lea" /LOG="C:\temp\lea-install.log"
+```
+
+`enroll.txt`:
+
+```text
+USER_NAME=Prenom Nom
+USER_EMAIL=prenom.nom@example.local
+USER_ID=EMP-00123
+SERVER_URL=http://<DGX_IP>:5005/api/v1
+API_TOKEN=<token>
+```
+
+Production: l'installeur doit etre signe pour eviter les alertes SmartScreen et faciliter le deploiement IT.
+
+## VM Windows DGX - etat POC et regles
+
+Etat confirme le 2026-06-19:
+
+- Windows 11 ARM DGX fonctionne via QEMU standalone.
+- Acces utilisateur via VNC tunnel `localhost:5902`.
+- Le runtime actif utilise `disk.qcow2` cote utilisateur `aivanov`.
+- La definition libvirt `win11-arm-lea` peut apparaitre arretee pendant que le standalone tourne.
+
+Regles:
+
+- Ne pas demarrer la VM libvirt `win11-arm-lea` pendant que QEMU standalone utilise deja `disk.qcow2`.
+- Ne pas lancer deux VM sur le meme disque.
+- En standalone, `disk.qcow2` doit etre accessible a l'utilisateur qui lance QEMU, actuellement `aivanov`.
+- Si retour libvirt, prevoir de remettre l'ownership attendu par libvirt, par exemple `libvirt-qemu:libvirt-qemu`, apres arret complet du standalone.
+- Le VNC doit rester en loopback/tunnel, par exemple `127.0.0.1:5902`, pas en exposition LAN large.
+
+Loose ends a traiter avant MVP:
+
+1. Persister proprement le VNC loopback dans le script original ou dans un wrapper.
+2. Decider si le VNC a un password pose automatiquement via monitor, ou pas de password car tunnel obligatoire.
+3. Choisir un seul runtime officiel pour la VM DGX: standalone documente ou libvirt corrige.
+4. Documenter le rollback disk owner standalone <-> libvirt.
+5. Decider et implementer l'auto-start au reboot DGX si la VM Windows doit etre disponible apres redemarrage:
+   - script persiste, pas `/tmp/vmvnc.sh`;
+   - service systemd `User=aivanov` ou user service avec `loginctl enable-linger`;
+   - `After=network-online.target`;
+   - garde-fou contre un demarrage libvirt parallele;
+   - choix VNC: sans password car loopback+tunnel, ou wrapper qui pose le password via monitor.
+
+## Reseau site
+
+Chaque site doit avoir un plan reseau valide avant installation.
+
+Exemple clinique prepare:
+
+```text
+DGX_IP_SITE=192.168.1.178
+PREFIX=/24
+GATEWAY=192.168.1.243
+DNS_1=192.168.1.9
+DNS_2=192.168.1.8
+IPv6=off
+VLAN=non
+Interface=Ethernet uniquement
+```
+
+Regles:
+
+- Ne pas activer le profil Ethernet site pendant les tests labo sans GO.
+- Prevoir un acces local ou une console avant toute bascule reseau.
+- Noter le rollback exact avant modification IP.
+- Valider depuis Windows: dashboard, chat, streaming.
+
+## Smoke tests d'acceptation
+
+### Serveur
+
+| Test | Attendu |
+|---|---|
+| `systemctl status rpa-streaming` | actif |
+| `systemctl status rpa-vision-v3-dashboard` | actif ou fallback documente |
+| `curl :5005/health` | 200/healthy |
+| dashboard `:5001` | login/401 ou UI, pas 500 |
+| `/api/system/status` | coherent, pas de faux vert |
+| `/api/workflows` | workflows VWB visibles |
+| worker status | `healthy` ou `idle` non degrade si aucun job |
+| ports remote VNC/RDP | fermes au LAN, tunnel only |
+
+### Windows
+
+| Test | Attendu |
+|---|---|
+| `config.txt` | valeurs site/poste remplacees, aucun `CONFIGURE_ME` |
+| lancement Lea | tray visible |
+| chat Lea | connexion au DGX |
+| capture/apprentissage | demarre avec consentement utilisateur |
+| stop apprentissage | session ecrite cote DGX |
+| dashboard fleet | machine visible |
+| streaming | session recue sur `5005` |
+
+### VWB/apprentissage
+
+| Test | Attendu |
+|---|---|
+| `workflows.db` | present, backup effectue |
+| workflows dashboard | liste chargee |
+| anchors | images visibles |
+| replay supervise | action ou demande de confirmation, pas de clic non controle |
+| worker | session traitee puis retour sain |
+
+## Criteres GO / NO-GO
+
+GO installation site si:
+
+- artefacts versionnes et identifies;
+- fiche site complete;
+- secrets generes pour le site;
+- DGX accessible et services verts;
+- Windows connecte au DGX;
+- dashboard/VWB/worker coherents;
+- ports remote non exposes hors tunnel/VPN;
+- rollback documente;
+- preuves archivees.
+
+NO-GO si:
+
+- un secret `CHANGE_ME` ou `CONFIGURE_ME` reste en place;
+- dashboard auth desactive hors dev;
+- `RPA_AUTH_DISABLED=true` hors dev;
+- VWB/workflows absents sans decision;
+- Windows ne rejoint pas le streaming;
+- VM ou poste controle le mauvais DGX;
+- deux runtimes VM utilisent le meme disque;
+- ports VNC/RDP exposes au LAN sans validation;
+- pas de backup `workflows.db` avant reset/deploy.
+
+## Sauvegarde et rollback
+
+Avant chaque installation ou upgrade:
+
+```bash
+STAMP=$(date +%Y%m%dT%H%M%S)
+mkdir -p .codex_backups/install-$STAMP
+cp -a visual_workflow_builder/backend/instance/workflows.db .codex_backups/install-$STAMP/ 2>/dev/null || true
+cp -a visual_workflow_builder/backend/data .codex_backups/install-$STAMP/vwb-data 2>/dev/null || true
+cp -a data/training .codex_backups/install-$STAMP/training 2>/dev/null || true
+cp -a .env.local .codex_backups/install-$STAMP/env.local 2>/dev/null || true
+```
+
+Rollback code:
+
+```bash
+git fetch origin
+git checkout <commit_valide>
+systemctl restart rpa-streaming rpa-vision-v3-dashboard rpa-vision-v3-worker rpa-agent-chat
+```
+
+Rollback donnees: restaurer uniquement les chemins sauvegardes, jamais faire `git clean -xfd` sur le DGX POC avec donnees runtime non trackees.
+
+## Journal de preuve d'installation
+
+Pour chaque installation, creer un dossier de preuve:
+
+```text
+installations/<SITE_ID>/<YYYY-MM-DD>/
+  site-sheet.md
+  versions.txt
+  services.txt
+  ports.txt
+  dashboard-smoke.txt
+  windows-agent-smoke.txt
+  vwb-smoke.txt
+  backups.txt
+  incidents.md
+  verdict.md
+```
+
+`versions.txt` doit contenir:
+
+```bash
+git rev-parse HEAD
+git status -sb
+python --version
+pip freeze | sort
+systemctl --version
+ollama list
+```
+
+## Industrialisation requise avant production
+
+| Sujet | Etat POC | Attendu MVP/prod |
+|---|---|---|
+| Installeur Windows | Inno disponible | release signee, tests install/desinstall |
+| Enrollment | config/token manuel ou dashboard | token par poste, expiration/revocation |
+| Secrets | `.env.local` manuel | coffre ou procedure secrete auditee |
+| Services | systemd partiel selon DGX | target unique, healthcheck, recover |
+| Supervision | dashboard + logs | alerting, retention, export incident |
+| Backups | manuels | job planifie, test de restauration |
+| VM Windows DGX | standalone VNC manuel fonctionnel | runtime officiel choisi, persiste et auto-start arbitre |
+| Multi-site | variables en coordination | fiche site versionnee, aucun secret partage |
+| Documentation utilisateur | `LISEZMOI.txt` | guide utilisateur + admin par site |
+| Support | agents war-room | procedure support N1/N2/N3 |
+
+## Check-list courte jour d'installation
+
+1. Valider fiche site et fenetre rollback.
+2. Verifier artefact serveur et installeur Windows.
+3. Generer secrets site/poste.
+4. Sauvegarder donnees DGX existantes.
+5. Installer ou mettre a jour serveur.
+6. Configurer reseau sans perdre l'acces de rollback.
+7. Demarrer services.
+8. Installer Lea sur Windows.
+9. Lancer smoke serveur.
+10. Lancer smoke Windows.
+11. Tester dashboard, VWB, chat, streaming, worker.
+12. Archiver preuves.
+13. Donner verdict GO/NO-GO.
+14. Si GO, remettre les acces temporaires en mode securise.
+
+## Documents sources
+
+- `README.md`
+- `deploy/systemd/rpa_vision_v3.env.example`
+- `deploy/lea_package/LISEZMOI.txt`
+- `deploy/lea_package/config.txt`
+- `deploy/build_package.sh`
+- `deploy/installer/README.md`
+- `deploy/installer/Lea.iss`
+- `docs/coordination/RUNBOOK-DGX-POST-REBOOT-CHECK.md`
+- `docs/coordination/RUNBOOK-LEA-LIVE-DRAFT.md`
+- `docs/coordination/active/2026-06-19_1418_postaction-windows-dgx-fonctionne.md`
+- `docs/coordination/inbox_codex/2026-06-19_1420_claude-to-codex_ACK-STOP-DIAG-VM-LOOSE-ENDS.md`