doc: document configuration and application routes

Co-authored-by: OpenAI/GPT-5.6-Terra <vibecoder@antoineve.me>
Co-authored-by: Google/Gemini-3.5-Flash <vibecoder@antoineve.me>
Co-authored-by: DeepSeek/DeepSeek-v4-Flash <vibecoder@antoineve.me>

app/config_loader.py

@@ -1,21 +1,76 @@
+"""Module de chargement et d'accès à la configuration TOML de l'application.
+
+Ce module sert d'interface entre l'application Flask et le fichier `config.toml`.
+Toute la configuration des véhicules, des trajets et du barème kilométrique y est stockée
+et chargée au démarrage dans `app.config["TOML"]`.
+
+Contrat TOML :
+1. Véhicules (`[vehicles]`) :
+   - Chaque véhicule possède un identifiant unique (clé).
+   - Attributs : `name` (nom d'affichage), `type` ("moteur" ou "velo"), `fuel` ("electric", "essence", etc.),
+     et optionnellement `cv` (puissance fiscale pour le barème kilométrique).
+2. Trajets (`[journeys]`) :
+   - Profils de trajets prédéfinis (ex: "domicile-travail").
+   - Attributs : `name` (nom d'affichage), `distances` (dictionnaire associant un type de véhicule à une distance en km).
+3. Barème kilométrique (`[bareme_kilometrique.YYYY]`) :
+   - Organisé par année (ex: "2026") puis par puissance fiscale (`cv_3`, `cv_4`, `cv_5`, `cv_6`, `cv_7plus`).
+   - Chaque catégorie contient une liste de `tranches` définissant les formules de calcul des frais réels.
+   - Une tranche possède : `km_max` (limite supérieure de la tranche, `km_max = 0` signifie "pas de limite supérieure"),
+     `coeff` (coefficient multiplicateur par km) et `fixe` (montant forfaitaire à ajouter).
+4. Types de jours sans trajet :
+   - Certains types de journées (Télétravail, Maladie, Congé, RTT, Férié) n'impliquent aucun déplacement physique.
+"""
+
 from flask import current_app
 
 
 def get_vehicles():
+    """Récupère l'ensemble des véhicules configurés dans le fichier TOML.
+
+    Retourne:
+        dict: Un dictionnaire des véhicules où la clé est l'identifiant du véhicule
+              et la valeur est un dictionnaire contenant ses propriétés (name, type, fuel, cv).
+              Retourne un dictionnaire vide si aucune configuration n'est chargée.
+    """
     return current_app.config.get("TOML", {}).get("vehicles", {})
 
 
 def get_motor_vehicles():
-    """Retourne uniquement les véhicules de type 'moteur'."""
+    """Filtre et retourne uniquement les véhicules de type 'moteur'.
+
+    Cette fonction exclut les véhicules alternatifs (comme les vélos) pour ne conserver
+    que ceux qui possèdent une puissance fiscale (CV) et sont éligibles au barème kilométrique.
+
+    Retourne:
+        dict: Un dictionnaire contenant uniquement les véhicules dont le type est 'moteur'.
+    """
     return {k: v for k, v in get_vehicles().items() if v.get("type") == "moteur"}
 
 
 def get_journeys():
+    """Récupère l'ensemble des profils de trajets configurés dans le fichier TOML.
+
+    Retourne:
+        dict: Un dictionnaire des trajets où la clé est l'identifiant du trajet
+              et la valeur est un dictionnaire contenant ses propriétés (name, distances).
+              Retourne un dictionnaire vide si aucune configuration n'est chargée.
+    """
     return current_app.config.get("TOML", {}).get("journeys", {})
 
 
 def journey_has_motor(journey_profile_id: str | None) -> bool:
-    """Retourne True si le profil de trajet inclut un véhicule à moteur."""
+    """Vérifie si un profil de trajet donné inclut une distance pour véhicule à moteur.
+
+    Cette validation permet de déterminer si l'utilisateur doit sélectionner un véhicule
+    à moteur lors de la saisie d'une journée de travail avec ce trajet.
+
+    Paramètres:
+        journey_profile_id (str | None): L'identifiant du profil de trajet à vérifier.
+
+    Retourne:
+        bool: True si le trajet existe et définit une distance pour la clé 'moteur',
+              False sinon ou si l'identifiant est nul.
+    """
     if not journey_profile_id:
         return False
     journeys = get_journeys()
@@ -24,6 +79,24 @@ def journey_has_motor(journey_profile_id: str | None) -> bool:
 
 
 def get_bareme(year: int, cv: int) -> list[dict]:
+    """Récupère les tranches du barème kilométrique pour une année et une puissance fiscale données.
+
+    Le barème kilométrique officiel est structuré en tranches de distances annuelles.
+    Cette fonction sélectionne la bonne catégorie de puissance fiscale (CV) :
+    - cv <= 3 -> 'cv_3'
+    - cv == 4 -> 'cv_4'
+    - cv == 5 -> 'cv_5'
+    - cv == 6 -> 'cv_6'
+    - cv >= 7 -> 'cv_7plus'
+
+    Paramètres:
+        year (int): L'année civile concernée par le calcul.
+        cv (int): La puissance fiscale du véhicule en chevaux fiscaux.
+
+    Retourne:
+        list[dict]: Une liste de dictionnaires représentant les tranches applicables.
+                    Chaque tranche contient 'km_max' (0 si pas de limite), 'coeff' et 'fixe'.
+    """
     bareme = current_app.config.get("TOML", {}).get("bareme_kilometrique", {})
     year_data = bareme.get(str(year), {})
     if cv <= 3:
@@ -40,4 +113,12 @@ def get_bareme(year: int, cv: int) -> list[dict]:
 
 
 def day_types_without_journey():
+    """Retourne l'ensemble des types de jours qui n'impliquent aucun trajet physique.
+
+    Ces types de jours (Télétravail, Maladie, Congé, RTT, Férié) sont exemptés de la saisie
+    de trajets ou de véhicules, car le travail s'effectue à distance ou l'employé est absent.
+
+    Retourne:
+        set[str]: Un ensemble de codes de types de jours (ex: {"TT", "MALADE", ...}).
+    """
     return {"TT", "MALADE", "CONGE", "RTT", "FERIE"}