Projet de Gestion d'Employés - Architecture Flask & Oracle XE

Ce projet est une application web de gestion d'employés comportant un backend en Python (Flask) et une base de données Oracle XE (21c) virtualisée sur Docker.

💡 Note : Pour accéder aux instructions détaillées d'administration Oracle (requêtes SQL avancées, paramétrage Docker, gestion des PDB/CDB, gestion des roles/profils, résolution d'erreurs de sessions comme ORA-02391, ou utilisation de Data Pump), veuillez consulter le fichier d'ingénierie dédié : DATABASE.md.

Voici une explication détaillée de l'architecture du projet, couvrant à la fois le code applicatif et l'infrastructure de la base de données.

---

1. Architecture de la Base de Données (Oracle XE Multitenant)

L'application s'appuie sur une instance Oracle Database Express Edition (XE) virtualisée via Docker (gvenzl/oracle-xe:21). L'architecture suit le modèle Multitenant (CDB/PDB) introduit par Oracle.

Structure CDB / PDB

• CDB Root (CDB$ROOT) : C'est le conteneur racine. Il gère l'instance globale, les métadonnées globales de la base de données et les utilisateurs communs (système). Aucune donnée applicative n'y est stockée.
• PDB (XEPDB1) : "Pluggable Database". C'est une base de données "enfichable" isolée, hébergée au sein de la CDB. C'est ici que sont stockées nos données.

Modèle de Données et Utilisateur Applicatif

Les données ne sont pas créées avec des comptes systèmes (SYS / SYSTEM), mais via un utilisateur applicatif dédié et cloisonné.

• Utilisateur Applicatif (demo_oracle) : Ce local user vit uniquement à l'intérieur de la XEPDB1.
• Tablespaces : L'utilisateur gère ses données sur son propre tablespace (DEMO_TBS dédié à la data applicative, accompagné de TEMP_TBS pour le travail temporaire).
• Profil (DEV_PROFILE) : Afin de maîtriser les ressources, l'utilisateur possède un profil avec des limites fixées (notamment SESSIONS_PER_USER qui définit combien de requêtes simultanées peuvent arriver sur la DB).

La Table principale

Le projet utilise une table employes :

CREATE TABLE employes (
    id NUMBER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY, 
    nom VARCHAR2(50), 
    prenom VARCHAR2(50), 
    salaire NUMBER(8,2), 
    date_emb DATE DEFAULT SYSDATE
);

---

2. Architecture Applicative (Flask)

Le backend est construit en Python avec le micro-framework Flask. L'application suit un modèle Frontend <> Logique <> Base de Données.

Structure des dossiers

oraclePY/
 ├── backend/
 │    └── ordatabase_co.py    # Logique de connexion et requêtes Oracle
 ├── frontend/
 │    ├── logic/
 │    │    └── app.py         # Contrôleurs, Routes Flask
 │    └── template/
 │         └── index.html     # Vues HTML (Jinja2)
 ├── .venv/                   # Environnement virtuel isolé (packages PIP)
 └── requirements.txt         # Dépendances (flask, oracledb, python-dotenv)

Le module Base de données (ordatabase_co.py)

Ce fichier porte toute la responsabilité de l'interaction avec Oracle via la librairie logicielle python-oracledb (le driver natif Oracle pour Python).

• Le Pool de Connexions : Plutôt que de rouvrir une nouvelle connexion à chaque fois qu'un utilisateur arrive sur l'application web, l'application initialise un "Connection Pool" (bassin de connexions) au démarrage (min=1, max=5).
• Gestion des Sessions : À travers un "context manager" (with get_connection() as conn:), le code "emprunte" une connexion pour l'exécution d'une instruction (ex: UPDATE, INSERT, SELECT), puis redonne immédiatement la connexion disponible aux autres utilisateurs. Cela empêche l'apparition de l'erreur ORA-02391 (dépassement autorisé de sessions simultanées Oracle).
• Formatage des champs : Les entêtes de colonnes remontées par Oracle (qui sont nativement en majuscules comme SALAIRE) sont abaissées en minuscules (salaire) afin d'être manipulables de manière canonique côté Python / Frontend.

Le module Web (app.py et templates)

C'est le routeur principal et le point d'entrée du serveur qui associe les URL web à des processus de données.

• Route / (GET) : Fait un appel de requête SELECT, remonte les données, et charge un fichier template HTML. Le moteur de rendu Jinja2 injecte dynamiquement la variable employes dans index.html.
• API /api/employes (POST / DELETE / PUT) : Ce sont les points d'interactions pour modifier la donnée. Le backend capte si l'utilisateur est sur l'interface graphique (formulaire HTML requêtant une redirection) ou utilise un outil comme Postman (requêtant des retours de type JSON textuel).

Démarrage

# Activation de l'environnement virtuel et lancement de l'app Flask
.venv\Scripts\python.exe frontend/logic/app.py