[QuFiSQL] MySQL Console Application - Quant Finance

English Version : README.en.md

Application Python en ligne de commande pour gérer les clients d'une société de gestion de patrimoine. Elle se connecte à une base MySQL et propose un menu interactif (CRUD, recherche, statistiques, détail avec données associées).

Démarrage rapide

Les scripts SQL s'exécutent dans MySQL Workbench ou le terminal — pas dans l'IDE Python. L'application Python se contente de se connecter à une base déjà créée.

Par où commencer ?

Votre situation	Commencez ici
MySQL installé et démarré, base pas encore créée	Étape A — scripts SQL
Base `quant_finance` déjà créée et peuplée	Étape B — `.env` + Poetry + lancer l'app
MySQL pas encore installé	Installer MySQL → Installation détaillée §1, puis Étape A → Étape B
Poetry pas installé (`poetry: command not found`)	Installer Poetry, puis Étape B
Erreur au lancement	Dépannage

Étape A — Base de données

Depuis la racine du projet (QuFiSQL/), exécuter dans cet ordre :

macOS / Linux / Git Bash :

mysql -u root -p < sql/script_creation.sql
mysql -u root -p < sql/ScriptDML.sql

Windows — utiliser MySQL Workbench (§2) ; éviter PowerShell pour le DML (accents français mal encodés).

Vérification rapide :

USE quant_finance;
SELECT COUNT(*) FROM Client;       -- doit retourner 8
SELECT COUNT(*) FROM Gestionnaire; -- doit retourner 6

Étape B — Application Python

macOS / Linux :

cp .env.example .env

Windows (PowerShell) :

Copy-Item .env.example .env

Éditer .env — renseigner DB_PASSWORD (mot de passe MySQL root) :

DB_HOST=localhost
DB_USER=root
DB_PASSWORD=votre_mot_de_passe
DB_NAME=quant_finance

Puis (nécessite Poetry — voir Installer Poetry si la commande poetry n'est pas reconnue) :

poetry config virtualenvs.in-project true
poetry install
poetry run python -m src

Sans Poetry : pip install mysql-connector-python python-dotenv puis python -m src (depuis la racine du projet).

Si tout fonctionne :

Quant Finance Console Application
Connecting to MySQL...
Connected successfully.

Checklist

[ ] MySQL démarré
[ ] script_creation.sql exécuté
[ ] ScriptDML.sql exécuté
[ ] Poetry installé (`poetry --version`)
[ ] .env configuré (DB_PASSWORD)
[ ] poetry install
[ ] poetry run python -m src  →  Connected successfully.

Installation détaillée

Le projet comporte deux parties à configurer séparément :

Partie	Rôle	Où l'exécuter
Base de données MySQL	Créer les tables et insérer les données	MySQL Workbench ou terminal (`mysql`)
Application Python	Menu console (CRUD, recherche, stats)	Terminal ou IDE (Cursor, VS Code, PyCharm)

Prérequis

Outil	Version	Vérification
Python	3.10+	`python --version` ou `python3 --version`
Poetry	2.x	`poetry --version`
MySQL Server	8+	Voir §1 ci-dessous

Installer Poetry (si nécessaire)

Poetry, c'est quoi ? C'est le gestionnaire de dépendances Python du projet (équivalent de npm pour Node.js). Il lit pyproject.toml, crée l'environnement virtuel .venv/ et installe les bibliothèques nécessaires (mysql-connector-python, etc.). Les commandes poetry install et poetry run python -m src de l'Étape B passent par Poetry.

Vérifier si Poetry est déjà installé :

poetry --version

Si la commande n'est pas reconnue, installer Poetry :

Windows (PowerShell) :

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

Puis fermer et rouvrir le terminal. Si poetry reste introuvable, ajouter %APPDATA%\Python\Scripts au PATH Windows.

Alternative Windows / macOS / Linux :

pip install poetry
# ou
pip3 install poetry

macOS (Homebrew) :

brew install poetry

macOS / Linux (installateur officiel) :

curl -sSL https://install.python-poetry.org | python3 -

Documentation complète : python-poetry.org

Compatibilité multi-OS

Compatible Windows 10+, macOS 12+ (Intel et Apple Silicon) et Linux. L'application Python utilise pathlib et ne contient aucune dépendance spécifique à un système — le même code fonctionne sur tous les OS.

Élément	Windows	macOS / Linux
Terminal	PowerShell ou CMD	Terminal (bash/zsh)
Copier `.env`	`Copy-Item .env.example .env`	`cp .env.example .env`
Interpréteur Poetry	`.venv/Scripts/python.exe`	`.venv/bin/python`
Scripts SQL (CLI)	Voir alternative PowerShell ci-dessous	`mysql -u root -p < sql/...`

1. Installer MySQL (si nécessaire)

Windows

Option A — MySQL Installer (recommandé)

Télécharger MySQL Installer
Choisir MySQL Server (+ optionnel : MySQL Workbench pour une interface graphique)
Lors de l'installation, définir un mot de passe pour l'utilisateur root (à retenir pour .env)
Laisser le port par défaut : 3306
Vérifier que le service MySQL est démarré :
- Services → chercher MySQL80 (ou similaire) → statut En cours d'exécution
- Ou en PowerShell : Get-Service -Name "*mysql*"

Option B — XAMPP (alternative simple)

Installer XAMPP
Démarrer MySQL depuis le panneau de contrôle XAMPP
Par défaut : utilisateur root, mot de passe vide (DB_PASSWORD= dans .env)

macOS

Option A — Homebrew (recommandé)

Installer Homebrew si nécessaire
Installer MySQL :
```
brew install mysql
```
Démarrer le service :
```
brew services start mysql
```
Sécuriser l'installation (définir le mot de passe root) :
```
mysql_secure_installation
```
Vérifier que MySQL écoute sur le port 3306 :
```
brew services list
```

Option B — Installeur DMG MySQL

Télécharger MySQL Community Server (macOS)
Suivre l'assistant d'installation et définir un mot de passe pour root
Démarrer MySQL :
- Préférences Système → MySQL → Start MySQL Server, ou
- En terminal : mysql.server start

Vérifier la connexion MySQL (tous OS)

Via MySQL Workbench :

Ouvrir Workbench → connexion Local instance MySQL → entrer le mot de passe root

Via terminal :

mysql -u root -p

Si vous voyez le prompt mysql>, la connexion fonctionne. Tapez EXIT; pour quitter.

Sous macOS avec Homebrew, si mysql n'est pas reconnu, ajouter au PATH :
echo 'export PATH="/opt/homebrew/opt/mysql/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
(Intel : remplacer /opt/homebrew par /usr/local)

2. Exécuter les scripts SQL (détails)

Deux scripts, dans cet ordre :

Script	Type	Action
`sql/script_creation.sql`	DDL	Crée la base `quant_finance` et les 7 tables (sans données)
`sql/ScriptDML.sql`	DML	Insère les données de démonstration (clients, gestionnaires, etc.)

Le fichier sql/requetes.sql contient des requêtes SELECT d'analyse (R1–R15) — il ne crée ni tables ni données. À exécuter séparément pour tester des requêtes SQL.

Méthode 1 — MySQL Workbench (recommandé pour débutants, tous OS)

Ouvrir MySQL Workbench et se connecter
File → Open SQL Script… → sélectionner sql/script_creation.sql
Cliquer sur l'icône Execute (éclair) ou Ctrl+Shift+Enter (macOS : Cmd+Shift+Enter)
Vérifier le message de succès dans l'onglet Action Output
Répéter avec sql/ScriptDML.sql

Méthode 2 — Ligne de commande

Depuis la racine du projet (QuFiSQL/) :

macOS / Linux (bash ou zsh) :

mysql -u root -p < sql/script_creation.sql
mysql -u root -p < sql/ScriptDML.sql

Windows (PowerShell) — si la redirection < ne fonctionne pas (préférer Workbench si accents corrompus) :

Get-Content sql/script_creation.sql | mysql -u root -p
Get-Content sql/ScriptDML.sql | mysql -u root -p

Windows (CMD ou Git Bash) — la syntaxe bash fonctionne aussi :

mysql -u root -p < sql/script_creation.sql
mysql -u root -p < sql/ScriptDML.sql

Vérifier que les données sont bien insérées

USE quant_finance;
SELECT COUNT(*) FROM Client;       -- doit retourner 8
SELECT COUNT(*) FROM Gestionnaire; -- doit retourner 6

3. Configurer `.env`

Copier le template et renseigner votre mot de passe MySQL :

macOS / Linux :

cp .env.example .env

Windows (PowerShell) :

Copy-Item .env.example .env

Éditer .env :

DB_HOST=localhost
DB_USER=root
DB_PASSWORD=votre_mot_de_passe    # celui défini à l'installation MySQL
DB_NAME=quant_finance

Important : le fichier .env n'est jamais versionné (secrets). Seul .env.example est commité.

4. Installer et lancer l'application

poetry config virtualenvs.in-project true
poetry install

Cela crée un environnement virtuel .venv/ et installe :

mysql-connector-python — connexion MySQL
python-dotenv — lecture du fichier .env

Terminal (recommandé) — macOS, Linux et Windows :

poetry run python -m src

Alternative (shim à la racine) :

poetry run python main.py

Dans un IDE (Cursor / VS Code / PyCharm) :

Ouvrir le dossier QuFiSQL/ comme projet
Sélectionner l'interpréteur Python selon votre OS :

OS	Chemin de l'interpréteur
Windows	`.venv/Scripts/python.exe`
macOS / Linux	`.venv/bin/python`

Lancer main.py ou exécuter le module src (python -m src)

Sous macOS, ouvrir le Terminal intégré (Cursor/VS Code : Ctrl+`) ou l'application Terminal, se placer dans le dossier QuFiSQL/, puis lancer les commandes Poetry ci-dessus.

Dépannage

Erreur	Cause probable	Windows	macOS
`Can't connect to MySQL server on 'localhost'`	MySQL non démarré	Services → MySQL80, ou XAMPP	`brew services start mysql` ou `mysql.server start`
`Access denied for user 'root'@'localhost'`	Mot de passe incorrect	Vérifier `DB_PASSWORD` dans `.env`	Idem
`Unknown database 'quant_finance'`	Scripts SQL non exécutés	Relancer `script_creation.sql` puis `ScriptDML.sql`	Idem
`Table 'quant_finance.Client' doesn't exist`	DDL non exécuté	Exécuter `script_creation.sql`	Idem
`poetry: command not found`	Poetry non installé	Installer Poetry (`pip install poetry`)	Idem, ou `brew install poetry`
`pyproject.toml changed significantly...`	`poetry.lock` obsolète	`poetry lock` puis `poetry install`	Idem
Erreur `Duplicate entry` à l'INSERT	`ScriptDML.sql` relancé	Réinitialiser la base (ci-dessous)	Idem
`mysql: command not found`	Client MySQL absent du PATH	Réinstaller MySQL ou ajouter au PATH	`brew install mysql` puis configurer le PATH (voir §1)
Menu vide / aucun client	DML non exécuté	Exécuter `ScriptDML.sql`	Idem

Réinitialiser complètement la base (macOS / Linux / Git Bash) :

mysql -u root -p -e "DROP DATABASE IF EXISTS quant_finance;"
mysql -u root -p < sql/script_creation.sql
mysql -u root -p < sql/ScriptDML.sql

Réinitialiser sous PowerShell (Windows) :

mysql -u root -p -e "DROP DATABASE IF EXISTS quant_finance;"
Get-Content sql/script_creation.sql | mysql -u root -p
Get-Content sql/ScriptDML.sql | mysql -u root -p

Documentation

Rapport BDD

Livrable principal du projet — à consulter pour l'évaluation.

Ouvrir le rapport (PDF) → docs/Rapport_BDD.pdf

Contenu du rapport
Modélisation	MCD, MLD, dictionnaire des données, règles métiers
Requêtes SQL	15 requêtes d'analyse (R1–R15)
Application	Description de l'interface console Python
Annexes	Code source, scripts SQL

Vidéo de présentation (temporaire)

Lien ajouté pour l'évaluation — à retirer après correction.

Voir la vidéo de présentation → docs/TRAN_NOUARA_ProjetBDD_Video.mp4

Autres ressources

Ressource	Description
Rapport (PDF, en anglais)	Rapport complet du projet (modélisation, requêtes, application)
Vidéo de présentation (temporaire)	Soutenance du projet (MP4)
MCD (ci-dessous)	Modèle conceptuel de données — 7 entités, relations et cardinalités

Modèle conceptuel de données (MCD)

Le schéma couvre la chaîne Gestionnaire → Client → Portefeuille → Position / Transaction, avec les instruments financiers et leur historique de cours.

Domaine choisi

Gestion de patrimoine / Finance quantitative

Élément	Description
Secteur	Gestion d'actifs pour clients privés et institutionnels
Entité principale (CRUD)	Client — investisseur suivi par un gestionnaire
Données associées (lecture)	Gestionnaire (manager), Portefeuille (portfolios)
Schéma complet	7 tables : Gestionnaire, Client, Portefeuille, Instrument, Position, PrixHistorique, Transaction

L'application console se concentre sur la table Client, tout en affichant les relations avec le gestionnaire assigné et les portefeuilles du client (option 8 du menu).

Règles métiers

Code	Règle métier
RM01	Un client est suivi par exactement un gestionnaire à un instant donné ; un gestionnaire suit 0 à N clients.
RM02	Un client détient au moins un portefeuille ; chaque portefeuille appartient à un seul client.
RM03	Le profil de risque d'un client appartient à : prudent, équilibré, dynamique, agressif.
RM04	L'AUM d'un client est positif ; un profil agressif exige un AUM ≥ 100 000 € (cohérence réglementaire).
RM05	Une position relie un portefeuille, un instrument et une date de valorisation (association ternaire).
RM06	Le poids d'une position est compris entre 0 et 1 (0 % à 100 %).
RM07	La somme des poids des positions d'un même portefeuille à une date donnée ne dépasse pas 1 (100 %).
RM08	La quantité d'une position est strictement positive ; le prix moyen est strictement positif.
RM09	Le PnL latent d'une position peut être positif ou négatif (gain ou perte non réalisé).
RM10	Un instrument a un ticker unique et un type parmi : action, obligation, ETF, dérivé.
RM11	La volatilité d'un instrument est positive ou nulle (exprimée en pourcentage annualisé).
RM12	Une transaction a un sens parmi : ACHAT ou VENTE ; sa quantité et son prix d'exécution sont strictement positifs.
RM13	Les frais d'une transaction sont positifs ou nuls et n'excèdent pas 5 % du montant brut.
RM14	Une transaction concerne un seul portefeuille et porte sur un seul instrument.
RM15	Pour un instrument donné, il existe au plus un prix historique par date de cotation (unicité ticker + date).
RM16	Le cours de clôture d'un prix historique est strictement positif ; le volume est positif ou nul.
RM17	La devise d'un portefeuille et d'un instrument suit le format ISO 4217 (3 lettres majuscules, ex. `EUR`, `USD`).
RM18	La date de valorisation d'une position ne peut pas être antérieure à la date de création du portefeuille.

Certaines règles sont enforced directement dans le schéma MySQL (sql/script_creation.sql) via contraintes CHECK, clés étrangères et unicité ; d'autres (RM02, RM07, RM18) relèvent de la logique métier et doivent être respectées lors de l'insertion des données.

Dictionnaire des données

Gestionnaire

Colonne	Type	Description
`id_gestionnaire`	INT, PK, AUTO	Identifiant unique
`nom`	VARCHAR(100)	Nom de famille
`prenom`	VARCHAR(100)	Prénom
`email`	VARCHAR(150), UNIQUE	Email professionnel
`date_embauche`	DATE	Date d'embauche
`specialite`	VARCHAR(100), NULL	Domaine d'expertise (ex. actions tech)

Client (entité principale de l'application)

Colonne	Type	Description
`id_client`	INT, PK, AUTO	Identifiant unique
`nom`	VARCHAR(100)	Nom de famille
`prenom`	VARCHAR(100)	Prénom
`email`	VARCHAR(150), UNIQUE	Email du client
`aum`	DECIMAL(18,2)	Assets Under Management — actifs totaux gérés
`profil_risque`	ENUM	Tolérance au risque (voir RM03)
`date_entree`	DATE	Date d'entrée en relation
`id_gestionnaire`	INT, FK	Gestionnaire assigné

Portefeuille

Colonne	Type	Description
`id_portefeuille`	INT, PK, AUTO	Identifiant unique
`nom`	VARCHAR(150)	Nom du portefeuille
`devise_base`	CHAR(3)	Devise de référence (ISO)
`strategie`	VARCHAR(100), NULL	Stratégie d'investissement
`date_creation`	DATE	Date de création
`valeur_liquidative`	DECIMAL(18,2)	NAV — valeur nette du portefeuille
`id_client`	INT, FK	Client propriétaire

Instrument (résumé)

Colonne	Type	Description
`id_instrument`	INT, PK	Identifiant
`ticker`	VARCHAR(20), UNIQUE	Symbole boursier
`nom`	VARCHAR(150)	Nom complet
`type_instrument`	ENUM	action / obligation / ETF / dérivé
`secteur`	VARCHAR(100)	Secteur d'activité
`devise`	CHAR(3)	Devise de cotation
`volatilite`	DECIMAL(10,4)	Volatilité annualisée

Position (résumé)

Colonne	Type	Description
`id_portefeuille`	INT, PK/FK	Portefeuille
`id_instrument`	INT, PK/FK	Instrument détenu
`date_valo`	DATE, PK	Date de valorisation
`quantite`	DECIMAL(18,6)	Nombre de titres
`prix_moyen`	DECIMAL(18,4)	Prix moyen d'achat
`poids`	DECIMAL(5,4)	Poids dans le portefeuille (0–1)
`pnl_latent`	DECIMAL(18,2)	Profit/perte latent

PrixHistorique (résumé)

Colonne	Type	Description
`id_prix`	INT, PK	Identifiant
`date_cotation`	DATE	Date du cours
`cours_cloture`	DECIMAL(18,4)	Prix de clôture
`volume`	BIGINT	Volume échangé
`rendement_jour`	DECIMAL(10,6)	Rendement journalier
`id_instrument`	INT, FK	Instrument concerné

Transaction (résumé)

Colonne	Type	Description
`id_transaction`	INT, PK	Identifiant
`sens`	ENUM	ACHAT / VENTE
`quantite`	DECIMAL(18,6)	Quantité
`prix_execution`	DECIMAL(18,4)	Prix d'exécution
`date_transaction`	DATE	Date de l'opération
`frais`	DECIMAL(18,2)	Frais de transaction
`id_portefeuille`	INT, FK	Portefeuille
`id_instrument`	INT, FK	Instrument

Arborescence du projet

Structure des dossiers et rôle de chaque composant :

QuFiSQL/
├── README.md               # Documentation complète (français)
├── README.en.md            # Documentation (English)
├── pyproject.toml          # Dépendances Poetry
├── poetry.lock
├── .env.example            # Template de configuration (sans secrets)
├── .env                    # Config locale (gitignored)
├── main.py                 # Shim → délègue à src/
├── docs/                   # Documentation et livrables
│   ├── Rapport_BDD.pdf     # Rapport complet du projet (Français)
│   ├── BDD_report.pdf      # Rapport complet du projet (English)
│   ├── TRAN_NOUARA_ProjetBDD_Video.mp4  # Vidéo de présentation (temporaire)
│   └── MCD_Quant_Finance.jpg  # Modèle conceptuel de données
├── sql/                    # Scripts SQL
│   ├── script_creation.sql # DDL (schéma)
│   ├── ScriptDML.sql       # Données de test
│   └── requetes.sql        # Requêtes analytiques R1–R15
└── src/                    # Code source (application Python)
    ├── __main__.py         # Point d'entrée
    └── app/
        ├── config.py       # Constantes + chargement .env
        ├── db.py           # Connexion MySQL
        ├── repositories/
        │   └── client_repository.py  # Requêtes SQL
        └── ui/
            ├── menu.py     # Boucle du menu principal
            ├── handlers.py # Logique de chaque option
            ├── prompts.py  # Saisies utilisateur
            └── formatters.py  # Affichage console

Guide de réutilisation

Changer les identifiants MySQL

Éditer .env — aucune modification de code nécessaire.

Ajouter une nouvelle fonctionnalité au menu

Repository — ajouter la requête SQL dans src/app/repositories/client_repository.py
Handler — créer handle_xxx() dans src/app/ui/handlers.py
Menu — enregistrer l'action dans src/app/ui/menu.py (actions dict + print_main_menu)

Commandes de développement

# Vérifier le style et les erreurs
poetry run ruff check .

# Formater automatiquement
poetry run ruff format .

# Corriger les imports et erreurs simples
poetry run ruff check . --fix

Sécurité — que cacher ?

Fichier	Versionner ?	Contenu
`.env.example`	Oui	Template sans mot de passe réel
`.env`	Non	Mot de passe MySQL, credentials
`src/app/config.py`	Oui	Lit les variables d'environnement, pas de secrets en dur

Fonctionnalités du menu

#	Action
1	Ajouter un client
2	Lister tous les clients
3	Rechercher par critère (profil, gestionnaire, plage AUM)
4	Modifier un client
5	Supprimer un client
6	Statistiques et classements
7	Recherche par mot-clé
8	Détail client + gestionnaire + portefeuilles
9	Lister les gestionnaires disponibles
0	Quitter

Version anglaise

Documentation condensée en anglais : README.en.md

Name		Name	Last commit message	Last commit date
docs		docs
sql		sql
src		src
.env.example		.env.example
.gitignore		.gitignore
README.en.md		README.en.md
README.md		README.md
main.py		main.py
poetry.lock		poetry.lock
pyproject.toml		pyproject.toml

Latest commit

History

Folders and files

Repository files navigation

[QuFiSQL] MySQL Console Application - Quant Finance

Table des matières

Démarrage rapide

Par où commencer ?

Étape A — Base de données

Étape B — Application Python

Checklist

Installation détaillée

Prérequis

Installer Poetry (si nécessaire)

Compatibilité multi-OS

1. Installer MySQL (si nécessaire)

Windows

Option A — MySQL Installer (recommandé)

Option B — XAMPP (alternative simple)

macOS

Option A — Homebrew (recommandé)

Option B — Installeur DMG MySQL

Vérifier la connexion MySQL (tous OS)

2. Exécuter les scripts SQL (détails)

Méthode 1 — MySQL Workbench (recommandé pour débutants, tous OS)

Méthode 2 — Ligne de commande

Vérifier que les données sont bien insérées

3. Configurer .env

4. Installer et lancer l'application

Dépannage

Documentation

Rapport BDD

Vidéo de présentation (temporaire)

Autres ressources

Modèle conceptuel de données (MCD)

Domaine choisi

Règles métiers

Dictionnaire des données

Gestionnaire

Client (entité principale de l'application)

Portefeuille

Instrument (résumé)

Position (résumé)

PrixHistorique (résumé)

Transaction (résumé)

Arborescence du projet

Guide de réutilisation

Changer les identifiants MySQL

Ajouter une nouvelle fonctionnalité au menu

Commandes de développement

Sécurité — que cacher ?

Fonctionnalités du menu

Version anglaise

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

3. Configurer `.env`