Aller au contenu

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 bug, 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, avec l'environnement virtuel (venv) activé
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 exécutera le pipeline pour le jour précédent (J-1). Par exemple, si vous l'exécutez un mardi à 16h, elle traitera les données du lundi. Elle ne récupérera pas les prix actuels du mardi.

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 : Planifiez une exécution tôt le matin (par exemple, 30 4 * * 2-6 pour 04h30 du mardi au samedi). Cela garantit que les données de clôture du jour précédent sont définitives.
  • 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

  1. Connectez-vous au VPS via SSH.
  2. Naviguez vers le dossier du projet : cd /var/www/qa-automated-pipeline.
  3. Chargez les variables d'environnement : source .env.
  4. 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

Le site de documentation est construit à partir de plusieurs répertoires sources (project_docs/docs, test_cases/, etc.). Une commande est fournie pour assembler ces sources dans un répertoire de construction final que MkDocs peut utiliser.

Le processus est une séquence en deux étapes :

  1. Générer le dossier docs : Exécutez la nouvelle commande de build depuis la racine du projet. Cette commande crée (ou nettoie et recrée) le répertoire docs/, en le peuplant avec tous les fichiers Markdown nécessaires. 

    python manage.py build-docs

  2. Lancer le serveur de prévisualisation local : Une fois le répertoire docs/ généré, lancez le serveur de développement MkDocs. 

    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 project_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 project_docs/docs/.
  • Pour mettre à jour les cas de test fonctionnels, éditez les fichiers Markdown dans test_cases/.
  • Après avoir effectué des modifications, vous devez relancer python manage.py build-docs pour que vos changements soient reflétés dans la prévisualisation locale.