Aller au contenu

Chapitre 1 : Vision et objectifs du projet

1.1. Introduction : la problématique

La gestion moderne d'un portefeuille d'investissement, bien qu'accessible, présente une complexité croissante. Les investisseurs actifs interagissent avec de multiples plateformes : courtiers pour les transactions, services d'analyse pour la recherche (ex : TipRanks), et sources de données de marché pour le suivi des prix (ex : Marketstack).

Cette fragmentation crée une charge de travail manuelle significative et rend difficile l'obtention d'une vue d'ensemble unifiée, précise et historique de la performance du portefeuille. Répondre à des questions simples comme "Quelle a été la performance réelle de mon titre X, toutes devises confondues ?" ou "Quels sont les actifs qui surperforment aujourd'hui ?" nécessite une consolidation fastidieuse et sujette aux erreurs.

1.2. La solution : le projet "AI"

Le projet AI (Augmented Investor) a été conçu pour résoudre cette problématique en fournissant une plateforme d'analyse de portefeuille privée, centralisée et automatisée.

L'application agit comme un hub personnel qui :

  1. Consolide les titres suivis et leurs métriques depuis le CSV importé, et les actions détenues depuis les achats et ventes enregistrés dans l'application.
  2. Enrichit automatiquement ces données avec les prix de clôture de la veille de marché, soit la dernière séance disponible de manière fiable pour le pipeline.
  3. Analyse l'évolution et la performance du portefeuille, tant au niveau global que pour chaque titre individuel.
  4. Présente ces informations de manière claire et visuelle via une interface web privée et sécurisée.

L'objectif final est de transformer des données brutes et dispersées en informations exploitables, permettant à l'utilisateur de prendre des décisions d'investissement plus éclairées et de suivre la performance de ses actifs avec une confiance absolue.

1.3. Objectifs Clés

Les objectifs du projet se divisent en deux catégories : les objectifs fonctionnels (ce que l'application fait) et les objectifs non fonctionnels (les principes de qualité qui régissent son fonctionnement).

1.3.1. Objectifs Fonctionnels

  • Registre des transactions : les achats et ventes sont saisis directement dans l'application. Leur solde détermine les actions détenues, sans reprendre les quantités du CSV.
  • Importation du portefeuille : le CSV maintient la liste des titres et actualise les métriques importées. Un titre absent du nouveau fichier est retiré de l'application, avec ses relevés et transactions. L'ajout d'un titre au CSV ne crée pas d'achat : sans transaction, il compte zéro action.
  • Enrichissement automatisé des données : le système doit, de manière autonome et quotidienne, récupérer les prix de clôture de la veille de marché pour chaque titre via une API financière externe (Marketstack).
  • Historisation des données : chaque relevé de prix quotidien doit être stocké de manière persistante, créant un historique complet qui permet de suivre l'évolution de la valeur de chaque titre et du portefeuille global dans le temps.
  • Accès sécurisé : les données privées sont réservées au propriétaire authentifié. La connexion renforcée demande le nom d'utilisateur, le mot de passe et un code temporaire dans un seul formulaire. Après activation, le mot de passe seul ne permet plus d'entrer. L'activation et le remplacement du téléphone sont administrés depuis le serveur ; la démonstration publique reste indépendante et accessible sans code.
  • Présentation visuelle :
    • Un dashboard global doit présenter une vue d'ensemble du portefeuille, incluant sa valeur totale, sa performance journalière, et des graphiques d'évolution.
    • Des pages de détail doivent permettre une analyse approfondie pour chaque titre, incluant un graphique de performance historique et des données techniques.
  • Analyse de Performance :
    • Calculer la performance quotidienne du portefeuille global.
    • Identifier et classer les titres les plus et les moins performants sur la dernière date de marché traitée ("Top/Flop Performers").
    • Analyser la position du prix actuel de chaque titre par rapport à ses plus hauts et plus bas sur 52 semaines.

1.3.2. Objectifs Non-Fonctionnels

  • Fiabilité et précision : les données financières affichées doivent être irréprochables. Les calculs doivent être exacts, et les incohérences de données (ex. : devises, tickers, fichiers d'entrée corrompus) doivent être gérées de manière robuste. C'est l'objectif de qualité le plus important.
  • Automatisation : le système doit fonctionner sans intervention manuelle quotidienne. Les mises à jour de données sont automatisées; le déploiement du code l'est après les décisions humaines, l'intégration à main et la réussite des contrôles.
  • Maintenabilité : l'architecture logicielle doit être propre, modulaire et facile à comprendre. Ceci inclut la maintenance d'une documentation claire et d'une suite de tests complète qui valide le comportement de l'application.
  • Sécurité : l'application doit suivre les bonnes pratiques de sécurité web pour protéger les données de l'utilisateur et les clés d'accès aux services externes.

1.3.3. Le développement assisté par l'IA, sous contrôle humain

Le développement s'appuie sur un assistant IA encadré par les règles du projet, ses documents de référence, des tests automatiques et une validation locale par moi, le propriétaire du produit. Le temps humain est donc surtout consacré à définir le besoin, à trancher les choix métier et à vérifier que le résultat répond aux attentes.

L'IA peut préparer le travail, modifier le code et corriger les problèmes relevés par les contrôles. Elle ne décide pas seule de ce qu'il faut construire et ne reçoit pas, par ce seul processus, l'autorisation de publier une nouvelle version. La mise en production demeure un jalon distinct.

1.4. Principes directeurs et philosophie d'architecture

Pour atteindre ces objectifs, le projet "Augmented Investor" a été construit sur une fondation de principes DevOps modernes. Ces décisions d'architecture ne sont pas accidentelles ; elles sont le fruit d'une volonté de construire un système de qualité professionnelle.

1.4.1. L'infrastructure comme du code (IaC) : la fiabilité par la conteneurisation

Le projet rejette l'approche fragile de la configuration manuelle d'un serveur. L'intégralité de l'application (le code Python, la base de données) est encapsulée dans des conteneurs Docker.

  • Pourquoi ? Cette approche rend la construction et le déploiement de l'application plus reproductibles. Les environnements ne sont toutefois pas strictement identiques : les tests locaux et ceux de GitHub utilisent des bases différentes de celle de production. Les contrôles et la démonstration locale restent donc nécessaires.

1.4.2. Les contrôles et le déploiement automatisés (CI/CD)

Le déploiement est réalisé par GitHub Actions après intégration du changement à main et réussite des contrôles configurés. Le propriétaire doit donner son accord sur la démonstration locale avant cette intégration, conformément au processus du projet; cet accord n'est pas encore un verrou technique dans GitHub.

  • Pourquoi ? Le déploiement automatisé suit une procédure répétable et limite les manipulations manuelles sur le serveur. Les tests contribuent à la qualité, sans remplacer le jugement métier ni l'accord du propriétaire.

1.4.3. Le Filet de sécurité permanent (tests automatisés)

Avant le déploiement, les contrôles automatisés comprennent des tests Pytest et des vérifications de parcours navigateur.

  • Pourquoi ? Ces contrôles repèrent de nombreux défauts et régressions avant la livraison. Ils ne peuvent toutefois pas confirmer seuls que le résultat correspond au besoin métier; la démonstration et la décision du propriétaire restent nécessaires.

1.4.4. La Source de Vérité Explicite : l'Humain au Contrôle

Pour les logiques métier complexes et sujettes à l'interprétation (comme la correspondance des tickers entre différentes sources ou la gestion des devises), le projet adopte un principe clair : le code ne doit pas "deviner".

  • Pourquoi ? La fiabilité des données prime sur la "magie" du code. C'est l'utilisateur, via des fichiers de configuration enrichis (le CSV de portefeuille avec ses colonnes de mappage, le fichier config.ini), qui fournit des instructions explicites au système. Le code devient alors un exécutant simple et fiable de ces instructions, ce qui rend le comportement du pipeline prévisible et facile à déboguer.

1.4.5. Le cadre de travail de l'IA (harness engineering)

Le terme anglais harness engineering désigne ici le cadre qui aide l'assistant IA à bien travailler et qui permet de vérifier ses résultats. Il regroupe les consignes, les documents de référence, les outils, les tests et les étapes de validation humaine. Il ne signifie pas que le développement est entièrement autonome.

Dans ce projet, ce cadre évolue avec l'expérience du propriétaire : lorsqu'un besoin ou un risque se répète, les règles, les tests ou les documents peuvent être précisés afin que les prochains travaux soient mieux guidés et contrôlés.

1.5. Processus interne : Pont GitHub Issue avec approbation owner-only

Le même principe de contrôle s'applique aux issues GitHub : l'agent IA peut les lire, proposer des changements et exécuter uniquement les actions approuvées par le propriétaire du dépôt.

1.5.1. Règles de gouvernance

  • La portée d'accès par dépôt (owner/repo) est obligatoire avant toute opération.
  • Les lectures sont autorisées uniquement si le grant est actif.
  • Les écritures (create/update) passent par une proposition pending_approval.
  • Seul le propriétaire du dépôt peut approuver l'exécution.
  • Toutes les opérations sont auditées (logs/github_issue_audit.jsonl).

1.5.2. Commandes opérateur principales

python scripts/manage_github_issue.py grant --repo owner/repo --owner repo-owner
python scripts/manage_github_issue.py status --repo owner/repo
python scripts/manage_github_issue.py read --repo owner/repo --issue-number 123 --actor ai-agent
python scripts/manage_github_issue.py create --repo owner/repo --actor ai-agent --title "Titre" --body "Description"
python scripts/manage_github_issue.py update --repo owner/repo --actor ai-agent --issue-number 123 --status "In Progress"
python scripts/manage_github_issue.py approve --repo owner/repo --proposal-id prp_xxxxx --approver repo-owner
python scripts/manage_github_issue.py revoke --repo owner/repo --actor repo-owner

1.5.3. Cas limites documentés

  • Grant absent/inactif : ACCESS_SCOPE_DENIED
  • Approbateur non owner : APPROVER_NOT_OWNER
  • Statut invalide : STATUS_VALUE_INVALID
  • Sous-issue inaccessible : marquage accessibility=denied avec reason_code