Plan d'Assurance Qualité (PAQ)

La qualité n'est pas un accident. Nous adhérons à une stratégie stricte pour garantir la fiabilité, la maintenabilité et la sécurité du projet FirstBreath.

📏 Cohérence de Style & Standards

Stratégie de Branches (Git Flow)

Nous utilisons une structure de branches rigoureuse pour organiser le développement.

Branches Principales

• dev : Branche principale de développement. Contient le code destiné à la prochaine mise en production.
• master / main : Branche de production. Chaque "push" ou merge sur cette branche correspond à une nouvelle version.

Branches Secondaires

Toutes les branches de travail doivent partir de dev (ou master /main pour les hotfixes) et être fusionnées via Pull Request.

• feature/ : Ajout d'une nouvelle fonctionnalité.
  • Cycle en V : Implémentation, Tests Unitaires, Tests d'Intégration.
  • Exemple : feature/google-analytics
• bugfix/ : Correction d'un bug non critique (hors production).
  • Cycle en V : Phase de test et recette.
  • Exemple : bugfix/upload-fix
• hotfix/ : Correction urgente d'un bug critique en production.
  • Cycle en V : Implémentation -> Tests de Validation -> Recette.
  • Exemple : hotfix/connection-crash
• chore/ : Maintenance, nettoyage de code, mises à jour de dépendances.
  • Exemple : chore/update-react
• experiment/ : POC ou expérimentation technique.
  • Cycle en V : Conception et Faisabilité.
  • Exemple : experiment/webrtc-video-flow

Convention de nommage : type/nom-description (ex. feature/add-login).

Standards de Commit

Nous suivons la convention Conventional Commits pour garantir un historique lisible et permettre la génération automatique de changelogs.

Format : type: sujet

Types de Commits Autorisés

1. feat: : Ajout d'une nouvelle fonctionnalité.
   • Exemple : feat: add user authentication
2. fix: : Correction de bug.
   • Exemple : fix: fix crash during image loading
3. chore: : Tâches techniques sans impact fonctionnel (deps, config).
   • Exemple : chore: update React version
4. refactor: : Amélioration du code sans changement de comportement.
   • Exemple : refactor: simplify validation logic
5. style: : Changements esthétiques du code (espaces, formatage).
   • Exemple : style: fix indentations
6. test: : Ajout ou modification de tests.
   • Exemple : test: add tests for user validation
7. docs: : Modifications de la documentation.
   • Exemple : docs: add Docker instructions
8. build: : Changements liés au système de build ou aux dépendances externes.
   • Exemple : build: add Webpack
9. ci: : Changements des fichiers de configuration CI/CD.
   • Exemple : ci: add E2E test to pipeline
10. perf: : Améliorations de performance.
    • Exemple : perf: improve API response time
11. revert: : Annulation d'un commit précédent.
    • Exemple : revert: remove feature X
12. hotfix: : Correction urgente en production (souvent utilisé comme nom de branche, parfois comme type de commit pour souligner l'urgence).
13. experiment: : Code expérimental ou POC.

🧪 Stratégie de Tests

Nous appliquons la pyramide de tests pour garantir une couverture optimale.

1. Analyse Statique (Automatisée)

• Outils : ESLint, Prettier, SonarQube.
• Quand : À chaque commit (via Hooks ou CI).
• Vérifications : Style du code, bugs potentiels, complexité cognitive, failles de sécurité.

2. Tests Unitaires (Back & Front)

• Backend : Japa (AdonisJS).
• Frontend : Vitest (React/Next.js), Jest (Mobile).
• Périmètre : Validation de la logique métier isolée.

3. Tests d'Intégration

• Périmètre : Vérification des interactions entre modules (ex. API <-> Base de données).

4. Tests End-to-End (E2E)

• Outil : Playwright (Infrastructure configurée, tests en attente).
• Statut : Tests manuels uniquement. Les tests automatisés restent à implémenter.
• Périmètre : Parcours utilisateur critiques (Connexion, Création de compte, Flux principal).
• Environnement : Staging (Local via Docker Compose).

5. Tests de Charge & Performance

• Statut actuel : Non implémentés en tant que phase dédiée.
• Justification : La plateforme FirstBreath est un outil B2B interne avec une base d'utilisateurs limitée et contrôlée (élevages équins). Le volume de trafic ne nécessite pas de tests de charge dédiés à ce stade.
• Surveillance : Les limites de ressources Docker et les health checks des conteneurs assurent un suivi de performance de base.
• Perspective future : Si le service camera-manager évolue pour gérer de nombreux flux RTSP simultanés, un profilage de performance dédié sera introduit.

📅 Phases du Protocole de Test

Les tests sont intégrés à chaque phase du cycle de développement :

Phase	Activités	Responsable	Outils
Développement	Tests unitaires, analyse statique (lint, format), tests de composants Storybook	Développeur	Vitest, Jest, Japa, ESLint, Prettier, Storybook
Pull Request	Pipeline CI : lint + typecheck + tests unitaires + tests d'intégration + vérification du build	CI (GitHub Actions)	GitHub Actions, SonarQube
Revue de Code	Revue par les pairs obligatoire, vérification du Quality Gate SonarQube	Relecteur de l'équipe	GitHub PR Review, SonarQube
Pré-Release	Tests E2E manuels des parcours critiques sur staging (Docker Compose)	QA / Développeur	Docker Compose, tests manuels
Post-Déploiement	Surveillance, vérification manuelle de non-régression	Équipe	Health checks Docker, logs

🎯 Justification des Choix d'Outils

Chaque outil a été sélectionné en fonction de son adéquation avec notre stack technique, l'expertise de l'équipe et les contraintes du projet.

Outil	Utilisé Dans	Pourquoi Cet Outil
Vitest	Frontend, Showcase	Support natif ESM, intégré à Vite, significativement plus rapide que Jest pour les projets React/Next.js modernes. Compatible avec vitest.config.ts et @testing-library/react.
Japa	Backend	Runner de tests natif d'AdonisJS. Intégration zéro-config avec le framework, supporte les suites de tests unitaires et fonctionnels (intégration) nativement.
Jest	Application Mobile	Runner de tests par défaut et officiellement supporté pour Expo/React Native (jest-expo). Le choisir évite une complexité de configuration pour un environnement mobile.
pytest	Vision	Standard Python pour les tests. Écosystème de plugins riche (pytest-cov, pytest-mock), syntaxe simple et excellent support pour le mocking des dépendances matérielles (caméra, GPU).
Playwright	Frontend (CI)	Tests E2E multi-navigateurs avec auto-waiting fiable. Choisi par rapport à Cypress pour son support natif multi-navigateurs et sa meilleure intégration CI. Actuellement configuré dans la CI, tests en attente.
Storybook	Frontend, Showcase	Isolation de composants et tests de régression visuelle. Intègre Chromatic pour les diffs visuels et @storybook/addon-a11y pour les vérifications d'accessibilité.
ESLint	Tous les repos JS/TS	Standard de l'industrie pour le linting JavaScript/TypeScript. Configs spécifiques aux frameworks disponibles (eslint-config-next, config Expo).
Prettier	Backend, Frontend	Formateur de code opinioné assurant un style cohérent au sein de l'équipe sans débat.
Black	Vision	« Le formateur Python intransigeant. » Élimine les discussions de style pour le code Python.
Flake8	Vision	Linter Python léger complétant Black pour détecter les erreurs logiques et les noms non définis.
SonarQube	Tous les repos	Plateforme d'analyse statique auto-hébergée. Fournit des tableaux de bord de qualité centralisés, des Quality Gates, et suit la dette technique dans le temps. Choisi par rapport aux alternatives cloud pour la souveraineté des données.
GitHub Actions	Tous les repos	Intégration CI/CD native avec les dépôts GitHub. Runners auto-hébergés pour un contrôle total des environnements de build.

🔄 Intégration Continue (CI/CD)

Nos pipelines GitHub Actions appliquent les règles suivantes :

1. Build Pass : Le code doit compiler sans erreurs.
2. Lint Pass : Le code doit respecter les standards de formatage.
3. Tests Pass : Tous les tests unitaires doivent passer.
4. Quality Gate (SonarQube) :
   • 0 Bugs Critiques.
   • Duplication < 3%.
   • Note de Maintenabilité A.
   • Couverture de code minimale (selon le module).

♿ Accessibilité

Nous intégrons l'accessibilité dans notre processus de développement en suivant les standards de l'industrie.

Standards

• WCAG 2.1 (Niveau AA) : Niveau de conformité visé pour toutes les applications web destinées aux utilisateurs.
• RGAA 4.1 : Référentiel Général d'Amélioration de l'Accessibilité, largement aligné avec WCAG 2.1 AA.

Implémentation par Plateforme

Plateforme	Approche	Outils
Frontend (Control-Hub)	Vérifications automatisées lors du développement des composants et en CI	@storybook/addon-a11y, eslint-plugin-jsx-a11y, tests A11y Playwright
Showcase	Vérifications automatisées via l'addon Storybook A11y, intégration CI	@storybook/addon-a11y, runner de tests Storybook
Application Mobile	Tests manuels avec lecteurs d'écran	VoiceOver (iOS), TalkBack (Android)
Backend / Vision	Non applicable	—

Pratiques Clés

• HTML Sémantique : Hiérarchie de titres correcte, labels ARIA, texte alternatif pour les images.
• Navigation au Clavier : Tous les éléments interactifs doivent être accessibles au clavier.
• Contraste des Couleurs : Ratio minimum 4.5:1 pour le texte normal (WCAG AA).
• Compatibilité Lecteur d'Écran : Testé avec VoiceOver et TalkBack pour le mobile.

🔒 Sécurité

• Audit des Dépendances : npm audit et safety check (Python) exécutés en CI.
• Scan de Code : SonarQube détecte les « Security Hotspots ».
• Revue de Code : Obligatoire pour toute Pull Request avant fusion dans develop ou master.

📊 Métriques de Couverture

Métriques de couverture actuelles depuis SonarQube (au dernier run CI) :

🛠️ Outils AQ par Dépôt

Dépôt	Langage	Linting & Formatage	Tests	Analyse Statique & CI
Control-Hub-Back	TypeScript (AdonisJS)	ESLint, Prettier	Japa (Unit & Int), c8 (Coverage)	SonarQube, GitHub Actions
Control-Hub (Frontend)	TypeScript (Next.js)	ESLint, Prettier	Vitest (Unit), Playwright (E2E), Storybook	SonarQube, GitHub Actions
Application Mobile	TypeScript (React Native)	ESLint	Jest (Unit)	SonarQube, GitHub Actions
Firstbreath Showcase	TypeScript (Next.js)	ESLint	Vitest (Unit), Storybook	SonarQube, GitHub Actions
Firstbreath Vision	Python	Black, Flake8	Pytest (Unit)	SonarQube, GitHub Actions

Application du Pipeline CI

Chaque dépôt applique des vérifications de qualité via GitHub Actions.

1. ✅ Tous les jobs CI passés (lint, typecheck, tests, build).
2. ✅ Quality Gate SonarQube passé.

Suivi de Qualité SonarQube

Notre instance SonarQube auto-hébergée assure le suivi continu de :

• L'évolution de la couverture de code dans le temps.
• La dette technique et les notes de maintenabilité.
• Les hotspots de sécurité et la détection de vulnérabilités.
• Le taux de duplication (< 3%).

Processus de Revue des Pull Requests

Chaque Pull Request suit ce processus :

1. Le développeur crée une branche suivant la convention de nommage (feature/, bugfix/, etc.).
2. Le pipeline CI s'exécute automatiquement sur le push.
3. L'analyse SonarQube s'exécute en parallèle.
4. Au moins un membre de l'équipe examine le code.
5. Le relecteur vérifie : la logique du code, la couverture des tests, le respect des standards.
6. Une fois la CI passée et la revue approuvée, la PR est fusionnée.

Exemples de Corrections Pilotées par la QA

Les types de corrections suivants sont régulièrement générés par notre processus QA :

• Remontées SonarQube : Code smells, réductions de complexité cognitive et résolutions de hotspots de sécurité sont suivis et traités dans le cadre du cycle de développement régulier.
• Échecs CI : Les échecs de build ou de tests sur les PRs sont corrigés avant fusion, assurant que dev et master / main restent stables.
• Retours de revue de code : Améliorations architecturales, conventions de nommage et gestion des cas limites sont détectés lors de la revue par les pairs.