Chapitre 3 : Guide Opérationnel

Ce chapitre est un guide opérationnel. Il décrit les procédures standard pour développer, maintenir et administrer l'application "Augmented Financial Analyst" (Analyste Financier Augmenté).

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.

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. Modification Locale du Code

Effectuez toutes les modifications de code nécessaires dans votre environnement de développement local (par exemple, VS Code).

3.1.3. Validation par Tests Locaux

Avant de soumettre votre travail, exécutez l'ensemble de la suite de tests pour vous assurer que vos modifications n'ont pas introduit de régressions. 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).

3.1.4. Sauvegarder Votre Travail (`Commit`)

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.5. Partage et Revue (Pull Request)

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. La PR est l'occasion de décrire vos changements et de permettre au système CI/CD d'exécuter les tests une dernière fois dans un environnement propre.

3.1.6. Fusion (Merge)

Une fois la Pull Request approuvée (revue effectuée et tests CI réussis), fusionnez-la dans main.

3.2. Procédures de Maintenance des Données

3.2.1. Mettre à Jour la Composition du Portefeuille

Quand : Lorsque vous achetez ou vendez des actions, ou modifiez les quantités.
Procédure :
1. Ouvrez le fichier data/tipranks_raw.csv sur votre machine locale.
2. Modifiez, ajoutez ou supprimez les lignes nécessaires.
3. Crucial : Pour toute nouvelle ligne, assurez-vous de remplir les colonnes de mappage Marketstack_Ticker et Marketstack_Currency après avoir effectué une recherche sur le site web de Marketstack.
4. Suivez le Flux de Développement Idéal (commit, push, merge). Le pipeline de données traitera les changements à partir du CSV.

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

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 -m code_source_simule.pipeline.
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

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)

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)

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.

3.3. Administration du Serveur de Production (VPS)

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

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`)

Lister les tâches planifiées : crontab -l.
Éditer les tâches planifiées : crontab -e.
- Recommandation : Gardez une planification simple du lundi au samedi matin (heure locale serveur), et laissez les garde-fous du pipeline appliquer le blocage du dimanche et le rattrapage du lundi uniquement en cas d'échec précédent.
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

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.4. Gestion des Dépendances

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

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é

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

3.6.6. Checklist avant la fusion

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