# 📘 Guide d'Architecture & Navigation du Projet

Bienvenue dans le code source de **AI QA Workflow**, votre plateforme de test E2E augmentée par l'Intelligence Artificielle.
Ce document a pour but de vous aider à naviguer dans le projet, comprendre la structure des dossiers et le rôle exact de chaque fichier.

Le projet est divisé en deux grandes parties : le **Moteur CLI (Ligne de commande)** qui s'occupe de la logique d'IA et de Playwright, et le **QA Dashboard (Interface Web)** qui offre une expérience utilisateur premium.

---

## 🏗️ Structure Globale

```text
ai-qa-workflow-template/
├── 📄 ai-qa-workflow.js        # Point d'entrée principal du CLI
├── 📄 package.json             # Dépendances (Express, Playwright, Groq-SDK, etc.)
├── 📁 scripts/                 # Cœur de l'intelligence artificielle (Génération & Exécution)
├── 📁 prompts/                 # Directives et prompts envoyés à l'IA
├── 📁 user-story/              # Les besoins métiers rédigés par l'équipe (Point de départ)
├── 📁 plans/                   # [Généré] Les plans de tests créés par l'IA
├── 📁 tests/                   # [Généré] Les scripts Playwright (.spec.ts)
├── 📁 test-results/            # [Généré] Résultats bruts, traces et logs des exécutions
└── 📁 qa-dashboard/            # Application Web Express.js (Interface Graphique)
```

---

## 🧠 1. Le Moteur CLI & IA (Dossier racine & `scripts/`)

C'est ici que l'intelligence artificielle interagit avec le code et Playwright.

* **`ai-qa-workflow.js`**
  * **Rôle :** C'est le chef d'orchestre en ligne de commande. Il intercepte vos commandes (`plan`, `generate`, `execute`, `run`, `heal`) et appelle le bon script dans le dossier `scripts/`.

* **`scripts/planner.js`**
  * **Rôle :** Lit une "User Story" (Markdown) et utilise l'IA pour rédiger un Plan de Test complet (cas nominaux, cas d'erreurs, assertions attendues).

* **`scripts/generator.js`**
  * **Rôle :** Lit le Plan de Test généré, et demande à l'IA de le traduire en **vrai code exécutable** Playwright (fichiers `.spec.ts`).

* **`scripts/executor.js`**
  * **Rôle :** Lance Playwright sur les tests générés. Il capture les succès, les échecs, la durée, et enregistre un rapport complet (`execution-result.json`) ainsi que les logs bruts (`execution-output.json`).

* **`scripts/healer.js`**
  * **Rôle :** Le module d'auto-guérison (Self-Healing). Si un test échoue, ce script lit la trace d'erreur, l'envoie à l'IA pour comprendre pourquoi (sélecteur cassé, timeout, etc.), corrige le fichier `.spec.ts` et relance le test automatiquement.

* **`scripts/reporter.js`**
  * **Rôle :** Lit les résultats JSON froids et demande à l'IA d'en faire un résumé Markdown humain et lisible (`final-test-report.md`).

* **`scripts/utils.js`**
  * **Rôle :** Fichier utilitaire contenant des fonctions communes (création de dossiers, écriture de fichiers, formatage des dates).

---

## 🎨 2. L'Interface Web (Dossier `qa-dashboard/`)

Le dashboard est une application Node.js (Express) qui lit les fichiers générés par le CLI et permet de lancer les commandes visuellement.

### Serveur & Services
* **`qa-dashboard/app.js`**
  * **Rôle :** Lance le serveur web (sur le port 4000 par défaut). Contient aussi un mécanisme d'extinction automatique si aucun onglet navigateur n'est ouvert (pour économiser de la mémoire).
* **`qa-dashboard/services/project-manager.js`**
  * **Rôle :** Permet au dashboard de "découvrir" automatiquement où se trouve votre projet E2E sur votre disque.
* **`qa-dashboard/services/cli-bridge.js`**
  * **Rôle :** C'est le **pont** entre l'interface et le CLI. C'est ici qu'on exécute les scripts de façon asynchrone (`spawn`), qu'on capture les logs pour les afficher en direct, et qu'on lit les fichiers de résultat avec des sécurités (`try-catch`) pour éviter les plantages.

### Routes (Contrôleurs) (`qa-dashboard/routes/`)
Chaque fichier gère une page spécifique :
* **`index.js`** : Page d'accueil, calcule les statistiques globales (taux de succès, nombre de tests).
* **`stories.js`** : Liste vos User Stories et gère les boutons pour déclencher l'IA (Plan, Generate, Run). C'est lui qui envoie le texte en temps réel à votre navigateur.
* **`runs.js`** : Gère l'affichage de l'historique des exécutions. Permet de voir un run en cours d'exécution, de lister les succès/échecs et de comparer deux exécutions.
* **`analytics.js`** : Prépare les données mathématiques pour les graphiques (durée moyenne, taux de healing).
* **`export.js`** : Transforme vos rapports Markdown en fichiers PDF ou HTML téléchargeables.

### Vues (Gabarits HTML/EJS) (`qa-dashboard/views/`)
Ce sont les interfaces que vous voyez à l'écran, stylisées selon les guidelines "Clay" (esthétique premium, bords arrondis, couleurs vibrantes).
* **`layouts/main.ejs`** : Le "squelette" de toutes les pages. Contient la barre de navigation, les polices Google (Outfit, Inter) et le script `marked.js` pour rendre le Markdown.
* **`story.ejs`** : L'écran le plus interactif. Affiche le terminal noir avec le retour de l'IA en direct.
* **`runs.ejs`** : La liste globale des tests passés.
* **`run.ejs`** : Le détail d'un seul passage de test (avec les erreurs empilées et le log du healing).
* **`analytics.ejs`** : Les superbes graphiques Chart.js (rose fluo, vert, etc.).

### Styles & Assets (`qa-dashboard/public/`)
* **`css/style.css`** : Le cœur de l'esthétique du projet (variables CSS, ombres, effets de survol, animations, classes `card-lavender`, `card-peach`, etc.).
* **`js/main.js`** : Les petits scripts front-end (ex: interactions mineures de l'interface).

---

## 🚀 Résumé du Nouveau Flux de Travail (Workflow à 2 Phases)

Le framework a évolué pour utiliser pleinement la puissance des Agents IA modernes (MCP). La création se fait via le chat de votre éditeur, et l'exécution via le Dashboard.

### Phase 1 : La Création (Via l'Agent IA dans votre éditeur)
1. Vous ajoutez un fichier `.md` dans le dossier `user-story/` ou vous donnez simplement un lien à votre Agent IA (Copilot, Cursor, OpenCode, Antigravity).
2. Vous dites à l'Agent dans le chat : *"Teste cette story ou ce lien"*.
3. L'Agent lit automatiquement son cerveau (`agents/router.md`), allume son navigateur interne via MCP, explore votre site réel, et **génère le plan de test (dans `specs/`) ainsi que le code exact (dans `tests/`)**. Il n'y a plus aucune hallucination de sélecteurs CSS !

### Phase 2 : L'Exécution & Le Suivi (Via le Dashboard Web)
4. Une fois que l'Agent a fait le gros du travail de création, vous ouvrez le Dashboard (`http://localhost:4000`).
5. Vous cliquez sur **Full Pipeline** ou **Execute**. Le script `executor.js` lance Playwright en fond. Si une petite erreur de timing survient, le `healer.js` tente de la corriger.
6. Les résultats JSON atterrissent dans `test-results/`.
7. Vous naviguez dans **Runs** ou **Analytics**, pour voir l'historique complet, les rapports PDF/HTML et les graphiques de qualité !

