Chapitre 3 : Guide Opérationnel

Ce chapitre explique comment développer, maintenir et administrer l'application AI (Augmented Investor). Il suit le chemin d'un changement, depuis la définition du besoin jusqu'à sa mise en service, puis présente les opérations nécessaires au fonctionnement quotidien.

Commencez par le flux de développement pour comprendre comment une modification est préparée et vérifiée. Les sections suivantes distinguent ensuite la maintenance des données, l'administration du serveur et la gestion des dépendances et de la documentation. Enfin, le plan de débogage reprend ce même cadre pour le cas particulier d'une correction de bogue.

3.1. Le Flux de Développement Idéal

Tout changement apporté au projet, qu'il s'agisse d'une correction de bogue, d'une nouvelle fonctionnalité ou d'une simple mise à jour de texte, doit suivre ce processus rigoureux pour garantir la stabilité de la production.

Le propriétaire consacre principalement son temps à explorer le besoin, à préciser les résultats attendus et à prendre les décisions métier. L'assistant IA prépare et réalise le travail dans le cadre du projet; il ne remplace ni ces décisions ni la validation du résultat.

3.1.1. Créer une Branche de Travail

Ne travaillez jamais directement sur la branche main. Chaque nouvelle tâche commence par la création d'une branche dédiée à partir de la version la plus à jour de main.

# S'assurer que la branche locale `main` est à jour
git checkout main
git pull origin main

# Créer et basculer sur une nouvelle branche descriptive
git checkout -b <type-de-changement>/<courte-description>

Exemples de noms de branches : feature/ajout-nouveau-graphique, fix/bug-page-connexion.

3.1.2. Cadrer le besoin et les critères de réussite

Une fois la branche créée, précisez ce que le changement doit apporter avant de décider comment le réaliser. Décrivez le problème à résoudre, les personnes concernées, le résultat souhaité et les cas qui pourraient changer la décision. L'assistant peut poser des questions et aider à comparer les options; le propriétaire confirme les choix métier et les points concrets qui permettront d'accepter le résultat.

3.1.3. Préparer le travail avec Spec Kit

Ce cadrage sert ensuite de point de départ à Spec Kit, l'outil de préparation du projet. Pour une nouvelle fonctionnalité, il décrit le besoin en détail, fait préciser les ambiguïtés si nécessaire, prépare un plan et une liste de tâches, puis vérifie leur cohérence. Le propriétaire vérifie que ces documents reflètent bien les décisions prises avant de commencer la réalisation.

3.1.4. Réaliser le changement par étapes

À partir de ce plan, l'assistant IA met en œuvre les tâches dans l'environnement local. Les tests qui définissent le résultat attendu sont préparés avant le code correspondant; les contrôles sont exécutés pendant le travail afin que les problèmes observés puissent être corrigés avant la revue. Les règles du projet, le wiki et les documents de la fonctionnalité servent de référence.

3.1.5. Vérifier les tests et la démonstration locale

Les contrôles effectués pendant la réalisation vérifient chaque changement ciblé. Avant de partager le travail, complétez-les par l'ensemble de la suite de tests pour vérifier qu'aucune régression n'a été introduite. Cette commande doit être lancée depuis la racine du dépôt de l'application.

# Depuis la racine du projet
python -m pytest -v

Tous les tests doivent réussir (ou être intentionnellement ignorés via skipped). Pour un changement visible, démarrez également une version locale représentative avec des données séparées de la production. Vérifiez le vrai parcours, y compris les écrans liés et la conservation des modifications après navigation; une démonstration publique qui se réinitialise ne suffit pas à cette vérification. Utilisez explicitement Google Chrome pour les vérifications navigateur.

Les tests automatisés et cette démonstration répondent à deux questions complémentaires : le code respecte-t-il les règles attendues, et le parcours répond-il au besoin ? Présentez au propriétaire l'adresse locale et les points à vérifier, puis attendez son accord explicite avant d'intégrer le changement à main. Cet accord est une règle de travail, et non un verrou configuré dans GitHub. Le workflow actuel déploie automatiquement après une mise à jour de main si les contrôles réussissent; l'ajout d'une protection d'environnement avec approbateur obligatoire serait nécessaire pour rendre ce contrôle technique.

3.1.6. Sauvegarder Votre Travail (`Commit`)

Une fois le travail vérifié, enregistrez vos modifications dans l'historique Git avec un message de commit clair et concis, en suivant la convention "Conventional Commits".

# Ajouter les fichiers modifiés
git add .

# Créer le commit
git commit -m "type(portée): description du changement"

Exemples : feat(dashboard): Ajout du panneau d'analyse sur 52 semaines, fix(pipeline): Correction de la logique de conversion de devises.

3.1.7. Partage et Revue (Pull Request)

Le commit conserve le travail localement; la Pull Request le rend disponible pour la revue. Poussez votre branche de travail vers le dépôt GitHub et ouvrez une "Pull Request" (PR).

git push --set-upstream origin <nom-de-votre-branche>

Sur GitHub, créez la Pull Request ciblant la branche main. Cette demande permet de décrire et de relire les changements avant leur intégration. Les tests applicatifs du processus de déploiement ne sont pas déclenchés par cette ouverture : ils s'exécutent après l'intégration à main.

3.1.8. Exécuter la revue IA de la Pull Request

La Pull Request donne à la revue IA un périmètre précis : les différences entre la branche de travail et main. Avant de lancer cette revue, vérifiez systématiquement les prérequis suivants :

La PR est bien ouverte sur GitHub (branche source poussée, cible = main).
La PR n'est pas en mode Draft et le diff correspond bien au périmètre attendu.
Les tests locaux sont passés sur votre branche (python -m pytest -v).
Les checks CI critiques déjà disponibles sur la PR ne sont pas en échec bloquant.
Le contexte de travail est propre : pas de modification locale non commitée sur les fichiers de la feature.

Procédure d'exécution (depuis VS Code, dans le dépôt du projet) :

Ouvrez la conversation Copilot dans le contexte de la branche de la PR.
Lancez la commande agent : /speckit.review.
Attendez la génération du rapport de revue dans le terminal de session.

Résultats attendus :

La revue génère un rapport structuré pour la décision de merge.
Le verdict est explicite : validation ou blocage motivé.
En cas de relance sur la même PR, le rapport le plus récent devient la référence de décision.
Aucun commentaire, statut APPROVE ou statut REQUEST_CHANGES n'est publié automatiquement sur GitHub.

Contrôle final après exécution :

Lire le rapport structuré et confirmer que les points bloquants (s'il y en a) sont actionnables.
Reporter la décision de revue dans la PR (commentaire manuel si nécessaire).
Si la revue bloque, corriger, pousser, puis relancer /speckit.review.

Résumé (Checklist exécutable) :

[ ] Clarifier le besoin métier et les résultats attendus.
[ ] Examiner la spécification, les tâches et l'analyse de cohérence pour une fonctionnalité.
[ ] Exécuter les tests ciblés et les vérifications complètes requises.
[ ] Présenter la démonstration locale isolée et obtenir l'accord explicite du propriétaire avant le merge dans main.
[ ] Finaliser les changements sur la branche de travail.
[ ] Faire le commit.
[ ] Pousser la branche sur GitHub.
[ ] Ouvrir la Pull Request vers main.
[ ] Exécuter /speckit.review.

3.1.9. Fusion et déploiement

Une fois la Pull Request revue, les contrôles disponibles sur cette demande réussis et l'accord local du propriétaire obtenu, fusionnez-la dans main. Les tests du processus de déploiement s'exécutent alors, puis la publication est automatique s'ils réussissent. GitHub ne demande pas aujourd'hui une approbation manuelle distincte au moment du déploiement.

3.2. Procédures de Maintenance des Données

Le flux précédent concerne les changements apportés au projet. Pour entretenir le portefeuille au quotidien, il faut d'abord distinguer les opérations enregistrées dans l'application des données de marché fournies par les imports. Les procédures ci-dessous précisent quel outil utiliser dans chaque cas, puis comment contrôler ou dépanner le résultat.

3.2.1. Mettre à Jour la Composition du Portefeuille

Pour un achat, une vente ou une correction de quantité : ouvrez la fiche du titre et enregistrez l'opération dans son tableau de transactions. Vérifiez la ligne Total, puis les totaux du tableau de bord. Il n'est pas nécessaire de modifier le CSV pour répercuter cette transaction.

Pour actualiser les métriques ou la liste des titres : préparez puis importez manuellement le CSV selon la procédure existante. Pour un nouveau titre, renseignez les correspondances Marketstack et la devise. Le fichier reste utile tant que toutes les métriques ne proviennent pas d'une source automatisée.

Avant l'import : vérifiez la liste complète. Tout titre absent du nouveau fichier est supprimé de l'application avec ses relevés et transactions. Un nouveau titre n'acquiert aucune action par sa seule présence dans le CSV : ses achats doivent être enregistrés dans l'application. Un fichier vide ne sert pas à vider le portefeuille.

À retenir : la colonne de quantités du CSV ne fait plus autorité. Pour corriger les actions détenues, corrigez le registre; ne modifiez pas le CSV pour compenser une opération manquante. Les nouveaux relevés tiennent compte des opérations à leur date; les anciens relevés ne sont pas corrigés automatiquement.

3.2.2. Exécuter Manuellement le Pipeline de Données

Une transaction met à jour la position détenue; le pipeline, lui, actualise les données de marché. Si cette actualisation doit être relancée sans attendre la prochaine exécution planifiée, utilisez la procédure suivante.

Quand : Pour un rafraîchissement ponctuel des données ou pour forcer le traitement d'une journée spécifique après une erreur.
Procédure :
1. Connectez-vous au VPS via SSH.
2. Naviguez vers le dossier du projet : cd /var/www/qa-automated-pipeline.
3. Exécutez la commande : docker compose exec app python code_source_simule/import_data.py.
Comportement Important : Cette commande cible la veille de marché. Les exécutions du dimanche sont bloquées ; le lundi est bloqué par défaut et autorisé uniquement en rattrapage matinal si l'exécution précédente enregistrée est en échec.

3.2.3. Configurer les Alertes SMTP

Pour suivre ces exécutions sans consulter systématiquement leurs journaux, configurez les notifications par courriel. Elles signalent les problèmes du pipeline, mais leur propre indisponibilité ne doit pas interrompre l'import.

Quand : Avant d'activer les notifications courriel opérateur en production.
Procédure : Configurez ces variables d'environnement dans l'environnement cible (shell local, VPS, ou coffre de secrets CI) :
- SMTP_HOST
- SMTP_PORT
- SMTP_USER
- SMTP_PASSWORD
- ALERT_EMAIL_TO
- SMTP_SECURITY (starttls, ssl, none) — défaut starttls
- SMTP_TIMEOUT_SECONDS — défaut 10
Profils recommandés :
- 587 + SMTP_SECURITY=starttls
- 465 + SMTP_SECURITY=ssl
Comportement fail-open : si SMTP est mal configuré ou indisponible, le pipeline continue et journalise un avertissement/événement pour le diagnostic.

3.2.4. Dépanner les prix API manquants (Marketstack)

Lorsqu'une alerte ou la consultation du portefeuille révèle des prix manquants, cherchez d'abord si le problème vient de l'exécution planifiée ou de la réponse du fournisseur. Cette distinction permet de cibler la correction plutôt que de modifier le code sans avoir reproduit le défaut.

Quand : Quand l'historique UI ne progresse plus ou que les alertes indiquent un volume élevé de prix API manquants.
Procédure :
1. Confirmez d'abord l'horaire cron (crontab -l) et vérifiez le journal de dernière exécution (tail -n 80 /var/log/cron-pipeline.log).
2. Reproduisez la date en échec directement sur les endpoints fournisseur via Postman ou curl.
3. Comparez v1/eod et v2/eod pour les mêmes symboles et la même plage de dates avant tout changement de code.
4. Si v2/eod renvoie des données valides et v1/eod non, traitez l'incident comme une incompatibilité d'endpoint et alignez l'usage du pipeline.
5. Relancez une importation manuelle puis validez le rafraîchissement BDD/UI avant clôture de l'incident.
Règle : Pour tout incident d'API externe, la reproduction endpoint/version côté fournisseur est obligatoire avant d'implémenter un correctif applicatif.

3.2.5. Exécuter les commandes utilisateurs E2E/API (local Windows)

Après une opération de maintenance ou une correction, les tests de parcours permettent de vérifier ce que l'utilisateur obtient dans l'application. Les commandes ci-dessous couvrent la connexion et le tableau de bord; les commandes API contrôlent séparément les échanges avec Marketstack.

Quand : Pour valider manuellement la connexion applicative, l'authentification réutilisable, l'affichage du dashboard et les scénarios API Marketstack.
Procédure standard :
1. Ouvrez PowerShell dans e2e/.
2. Sauvegardez les secrets une première fois (ou après changement):
  - npm run secrets:save:windows
3. Régénérez l'état de session de connexion:
  - npm run test:auth:setup:windows
4. Vérifiez l'accès sans ressaisir le login:
  - npm run test:skip-login:windows
5. Si seule la clé API Marketstack change:
  - npm run secrets:save:windows:marketstack
6. Lancez les tests API Marketstack sécurisés:
  - npm run test:marketstack:windows
7. Lancez la suite dashboard dédiée sans ouverture du navigateur:
  - npm run test:dashboard
8. Lancez la même suite dashboard avec navigateur visible:
  - npm run test:dashboard:headed
Raccourcis utiles :
- Suite E2E complète: npm run test:e2e
- Sous-ensemble CI local aligné sur la suite métier Marketstack: npm run test:e2e:ci
- Sous-ensemble Marketstack CI local: npm run test:marketstack:ci
Règle sécurité : ne jamais stocker MARKETSTACK_API_KEY en clair dans le dépôt; utiliser uniquement les secrets Windows locaux (DPAPI) et les secrets GitHub en CI.

Ces commandes utilisent des identifiants protégés, mais la connexion TOTP exige également un code temporaire. Pour une connexion distante, le lanceur Windows demande ce code sans écho et ne conserve ni code ni facteur permanent dans le coffre. La génération automatique est réservée au serveur loopback isolé; les suites de connexion désactivent les captures et traces contenant les saisies. Les tests Marketstack restent distincts : ils ne constituent pas une validation du TOTP.

3.3. Administration du Serveur de Production (VPS)

Les procédures de maintenance supposent que les services qui hébergent l'application fonctionnent correctement. Cette section passe donc des données à leur environnement d'exécution : observer les services, intervenir si nécessaire, vérifier la planification et administrer l'accès privé.

3.3.1. Vérifier l'État de l'Application

Voir les conteneurs actifs : docker ps (devrait afficher qa-automated-pipeline-app-1 et qa-automated-pipeline-db-1 avec le statut Up).
Logs de l'application (Gunicorn/Flask) : cd /var/www/qa-automated-pipeline && docker compose logs -f app (-f pour suivre en temps réel).
Logs d'erreur du serveur web : sudo tail -f /var/log/nginx/error.log.

3.3.2. Redémarrer les Services

Si le diagnostic précédent justifie un redémarrage, choisissez le service concerné plutôt qu'un redémarrage complet par défaut.

Redémarrage complet (App + DB) : cd /var/www/qa-automated-pipeline && docker compose restart.
Redémarrer l'application uniquement : cd /var/www/qa-automated-pipeline && docker compose restart app.
Redémarrer Nginx : sudo systemctl restart nginx.

3.3.3. Gérer le Pipeline Automatisé (`cron`)

Un service actif ne garantit pas que les imports soient déclenchés à l'heure prévue. Vérifiez aussi la planification du pipeline et le journal de sa dernière exécution.

Lister les tâches planifiées : crontab -l.
Éditer les tâches planifiées : crontab -e.
- Horaire de référence : sur le VPS configuré en Etc/UTC, utiliser 06 h UTC du lundi au samedi, soit 02 h à Montréal en heure d'été (EDT) et 01 h en heure d'hiver (EST). Le pipeline cible alors la veille ouvrée, notamment le vendredi lors de l'exécution du samedi.
- Vérifiez le fuseau avec timedatectl show -p Timezone et utilisez l'entrée versionnée dans scripts/pipeline.crontab. Remplacez uniquement l'entrée du pipeline; n'écrasez pas les autres tâches avec crontab scripts/pipeline.crontab.
- Les garde-fous du pipeline bloquent le dimanche et autorisent le rattrapage du lundi matin uniquement en cas d'échec précédent pour la même date de marché.
Vérifier les logs de la dernière exécution : cat /var/log/cron-pipeline.log.

3.3.4. Interagir avec la Base de Données

Lorsque les journaux ne suffisent pas au diagnostic, l'accès au client MariaDB permet d'examiner directement les données enregistrées.

Connectez-vous au VPS via SSH.
Naviguez vers le dossier du projet : cd /var/www/qa-automated-pipeline.
Chargez les variables d'environnement : source .env.
Lancez le client MariaDB : docker compose exec db mysql -u"$DB_PROD_USER" -p"$DB_PROD_PASSWORD" "$DB_PROD_NAME".

3.3.5. Activer ou remplacer le facteur TOTP

Le code d'authentification devient obligatoire après activation sur votre compte. La clé de chiffrement configurée sur le serveur protège les secrets TOTP, mais n'enregistre pas automatiquement votre téléphone. Pour activer cette protection, suivez les étapes ci-dessous depuis votre terminal SSH sur le serveur, avec votre téléphone à côté. Aucun redémarrage de l'application n'est nécessaire.

1. Préparer le téléphone et le terminal

Installez une application d'authentification compatible TOTP et activez la date et l'heure automatiques du téléphone. Connectez-vous ensuite au VPS par SSH et ouvrez le dossier du projet :

cd /var/www/qa-automated-pipeline

Les commandes utilisent le conteneur applicatif et sa configuration existante ; vérifiez au préalable la base et les clés selon la préparation de l'environnement décrite plus bas. Remplacez VOTRE_COMPTE par votre identifiant de connexion au site, pas votre compte SSH.

2. Vérifier l'état actuel

Avant de préparer un nouveau facteur, consultez l'état du compte :

docker compose exec app python scripts/manage_totp.py status --username VOTRE_COMPTE

L'état ne révèle aucun secret. Si vous voyez Activé : False, poursuivez l'activation initiale. Si vous voyez Activé : True, le facteur est déjà activé : ne lancez pas begin. Pour changer de téléphone, utilisez la procédure de remplacement ci-dessous.

3. Enregistrer la clé dans l'application du téléphone

Pour un compte non activé, lancez la préparation :

docker compose exec app python scripts/manage_totp.py begin --username VOTRE_COMPTE

Une clé secrète s'affiche dans votre terminal. Sur le téléphone, choisissez Ajouter un compte → Saisir une clé manuellement, donnez un nom reconnaissable au compte et saisissez cette clé. Choisissez le mode basé sur le temps ; si l'application demande les paramètres, utilisez SHA-1, six chiffres et trente secondes.

Ne partagez pas la clé dans un chat ou un rapport, ne faites pas de capture du terminal et n'utilisez pas de générateur QR en ligne. La préparation est valable dix minutes. Si vous relancez begin pendant ce délai, répondez explicitement oui pour reprendre la même clé en attente ; après expiration, relancez la préparation et mettez à jour la clé sur le téléphone.

4. Confirmer l'activation

Une fois le compte enregistré sur le téléphone, confirmez avant l'expiration :

docker compose exec app python scripts/manage_totp.py confirm --username VOTRE_COMPTE

Saisissez le code à six chiffres affiché par votre application. La saisie n'apparaît pas dans le terminal : c'est normal. Aucun mot de passe, code ou secret ne doit être passé en argument ; les actions d'activation et de remplacement exigent un terminal interactif.

Le message attendu est : Facteur confirmé. Les anciennes sessions sont révoquées. Vérifiez ensuite le résultat :

docker compose exec app python scripts/manage_totp.py status --username VOTRE_COMPTE

L'état doit afficher Activé : True. La protection n'est active qu'après cette confirmation réussie.

5. Vérifier la connexion

Attendez que le téléphone affiche le prochain code, car celui utilisé pour confirmer est déjà consommé. Ouvrez ensuite la page de connexion du site en HTTPS, idéalement dans une fenêtre privée :

Vérifiez une fois que le mot de passe seul est refusé.
Connectez-vous avec votre identifiant, votre mot de passe et le nouveau code.
Vérifiez l'accès au dashboard. Dans l'ancien navigateur, vérifiez aussi qu'une session ouverte avant l'activation ne permet plus l'accès privé.

Remplacer le facteur après un changement ou une perte de téléphone

Conservez votre accès SSH administratif : il permet de remplacer le facteur sans désactiver la protection. Depuis le même dossier du projet, lancez :

docker compose exec app python scripts/manage_totp.py replace --username VOTRE_COMPTE

Répondez oui pour autoriser le remplacement, puis enregistrez la nouvelle clé sur le téléphone comme à l'étape 3. Exécutez ensuite confirm, vérifiez status et testez la connexion avec le code suivant, comme aux étapes 4 et 5. L'ancien facteur reste actif jusqu'à confirmation du nouveau ; aucune désactivation temporaire n'est permise.

Si le serveur web refuse de démarrer, la commande administrative reste indépendante de sa garde de démarrage. En cas de perte de la clé de chiffrement, la récupération exige une clé serveur valide et la confirmation d'un nouveau facteur ; elle n'autorise jamais l'accès au mot de passe seul.

Validation locale isolée. Pour vérifier ce parcours sans toucher au portefeuille réel, utilisez les commandes et prérequis TOTP : AUTH_LOCAL_MODE=1, base SQLite fichier absolue hors dépôt (E2E_DB_PATH), clés indépendantes et identifiants éphémères dans l'environnement. Le serveur scripts/start_e2e_test_server.py et la commande administrative visent la même base. Le serveur écoute uniquement 127.0.0.1 et conserve les transactions, le facteur et les limites après redémarrage. Ne l'alimentez jamais avec les secrets ni le .env de production.

Préparation de l'environnement. Les essais isolés vérifient le parcours; la mise en service exige aussi de contrôler l'environnement qui le protège. Vérifiez la migration et la concurrence sur MariaDB, les parcours dans Chrome, Nginx, HTTPS et la fermeture distante du port 8000 ; préparez et sauvegardez séparément la clé persistante et la base. Une réussite sur SQLite ne remplace pas les contrôles MariaDB. Les validations GitHub de branche, PR et lancement manuel ne déploient pas : seul un push sur main peut lancer la livraison après réussite des contrôles.

Retour arrière sûr. Enfin, si une intervention impose de revenir à une version précédente, la protection de l'accès doit rester effective. Conservez le schéma et les facteurs. Après activation, ne réexposez jamais une version ignorant le TOTP : refusez l'accès privé, diagnostiquez et corrigez en avant. Une panne de clé ou de base n'autorise aucun contournement. Sans accès au serveur, la récupération relève de l'hébergement ; aucun code de secours n'est proposé.

3.4. Gestion des Dépendances

Au-delà de la configuration des services, certaines évolutions nécessitent une nouvelle bibliothèque. Son installation locale et sa déclaration dans le projet sont deux étapes complémentaires : la première permet de travailler, la seconde permet de reproduire cet environnement.

Pour ajouter une nouvelle bibliothèque Python (par exemple, new-library) : 1. Sur votre machine locale, avec le venv activé, installez la bibliothèque : pip install new-library. 2. Mettez à jour le fichier requirements.txt. C'est la commande la plus importante pour garantir la reproductibilité.

pip freeze > requirements.txt

3. Vérifiez que l'application fonctionne toujours en exécutant les tests locaux (pytest -v). 4. Suivez le Flux de Développement Idéal (commit, push, etc.). Le processus de déploiement devrait reconstruire l'image Docker avec la nouvelle bibliothèque (--build), rendant la dépendance disponible en production.

3.5. Gestion de la Documentation du Projet

Pour que ces procédures restent utilisables, la documentation doit évoluer avec le code et ses dépendances. La prévisualisation permet de relire le résultat avant publication, tandis que les sources des cas de test assurent la traçabilité des vérifications.

La documentation du projet (les chapitres que vous lisez actuellement), le rapport de couverture des tests et le journal de l'architecte sont gérés avec MkDocs.

3.5.1. Générer et Visualiser la Documentation Localement

Les fichiers sources de la documentation se trouvent directement dans le répertoire docs/. Pour prévisualiser localement, lancez le serveur de développement MkDocs depuis la racine du projet :

mkdocs serve

Vous pouvez maintenant ouvrir votre navigateur à l'adresse http://127.0.0.1:8000 pour voir la prévisualisation en direct.

Note : Vous devez avoir les dépendances de documentation installées : pip install -r docs/docs-requirements.txt.

3.5.2. Mettre à Jour la Documentation

Pour modifier la documentation principale (comme ce guide), éditez les fichiers Markdown situés dans docs/.
Pour mettre à jour les cas de test fonctionnels, éditez les fichiers Markdown dans test_cases/.
Les modifications sont reflétées immédiatement dans le serveur de prévisualisation local.

3.6. Plan de débogage formalisé

Lorsqu'un défaut est observé, le flux de développement présenté en début de chapitre s'applique toujours. Le plan suivant le précise pour une correction : partir du symptôme, le reproduire par un test, puis vérifier et documenter la solution.

Pour assurer des corrections de bogues cohérentes, fiables et bien documentées, tous les bogues doivent suivre ce flux de travail standardisé :

3.6.1. Vue d'ensemble du plan standardisé

Créer un billet GitHub — Énoncé bref du problème (constat initial) sans détails de diagnostic.
Créer une branche dédiée — Convention de nommage : fix/<description-courte>.
Développer des tests TDD — Écrire des tests qui valident le comportement attendu ou exposent le bogue.
Implanter la correction — Faire les modifications de code pour passer les nouveaux tests.
Tester la correction — Exécuter les nouveaux tests et valider que la correction fonctionne.
Exécuter les tests de régression — S'assurer que tous les tests existants passent toujours.
Mettre à jour la couverture de test — Générer et mettre à jour les rapports de couverture.
Documenter dans un rapport d'activité — Créer un rapport selon le format établi (voir exemples dans docs/activity_report/).
Mettre à jour la documentation liée — Relire et mettre à jour les chapitres 1, 2 et 3 si la correction affecte l'architecture ou les procédures.
Formaliser comme règle du projet — Vérifier que ce plan reste codifié et à jour au chapitre 3.

3.6.2. Modèle de billet GitHub

Chaque billet doit être concis et inclure uniquement l'observation initiale (sans investigation ni diagnostic) :

## Titre du Bogue

### Constat

Description brève du symptôme ou de la défaillance observée en production.
Incluez les messages d'erreur, les dates et les informations de reproductibilité si disponibles.

---

(Les détails d'investigation et la solution seront documentés dans la PR et le rapport d'activité.)

3.6.3. Convention de nommage des branches

Corrections de bugs : fix/<description-courte> (ex: fix/ticker-column-length-bug)
Nouvelles fonctionnalités : feature/<description-courte>
Refactorisations : refactor/<description-courte>

3.6.4. Écriture des tests TDD

Les nouveaux tests doivent être ajoutés au fichier de test approprié et : - Utiliser des ID de test descriptifs (ex: tc-pipe-ticker01). - Inclure une docstring expliquant ce qui est validé. - Valider le chemin heureux et les cas limites (ex: longueur maximale, valeurs vides, types invalides).

Exemple de structure :

@pytest.mark.test_id("tc-pipe-ticker01")
def test_insert_ticker_with_reasonable_length(self, clean_db):
    """Valide qu'un ticker de longueur raisonnable s'insère correctement."""
    # GIVEN: setup
    # WHEN: action
    # THEN: assertion

Une fois les tests écrits, leur inventaire documentaire permet au lecteur de retrouver les scénarios couverts. Pour synchroniser uniquement l'authentification, sans réécrire les autres inventaires :

python scripts\sync_tests.py --feature Authentication --language fr
python scripts\sync_tests.py --feature Authentication --language en

Les sources sont dans test_cases\authentication\ ; title_en porte la traduction des titres. Les pages générées sont docs\fr\tests\authentication.md et docs\tests\authentication.md. Le statut Actif indique un marqueur pytest correspondant, pas un résultat d'exécution ni un taux de couverture. Vérifiez les tests séparément ; les variantes MariaDB ignorées ne sont pas des succès.

3.6.6. Checklist avant la fusion

Cette dernière liste réunit les preuves et les documents produits au fil du diagnostic, de la correction et de la revue.

Billet GitHub créé avec constat clair
Branche dédiée créée et poussée
Tests TDD écrits et passants
Correction du bogue implémentée et fonctionnelle
Tous les tests de régression passent (40+ tests)
Rapports de couverture de test mis à jour
Rapport d'activité documenté
Chapitres de documentation liée relus et mis à jour
Messages de commit respectent "Conventional Commits"
Pull Request révisée et approuvée
Fusionnée dans main et programmée pour le déploiement en production