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/routes/reports.py

@@ -1,3 +1,10 @@
+"""Blueprint des routes de génération des rapports et statistiques.
+
+Ce module gère l'affichage des rapports annuels et mensuels. Il calcule les distances cumulées,
+les émissions de CO2, les frais réels selon le barème kilométrique officiel, et compile les statistiques
+de temps de travail (médianes quotidiennes et hebdomadaires) pour chaque mois de l'année sélectionnée.
+"""
+
 from collections import defaultdict
 from datetime import date
 
@@ -30,6 +37,35 @@ MONTHS_FR = {
 
 @bp.route("/")
 def index():
+    """Génère et affiche le rapport d'activité annuel et mensuel.
+
+    Cette route effectue les opérations suivantes :
+    1. Récupère l'année cible depuis les paramètres de requête HTTP GET (`year`). Par défaut, utilise l'année en cours.
+    2. Récupère toutes les entrées de temps (`WorkEntry`) de cette année civile.
+    3. Récupère la configuration des véhicules et des trajets depuis le fichier TOML.
+    4. Calcule les statistiques annuelles cumulées :
+       - Distances parcourues par véhicule (`total_km`).
+       - Émissions de CO2 totales en grammes (`total_co2`), converties ensuite en kilogrammes.
+       - Frais réels remboursables par véhicule (`frais_reels`) en appliquant le barème kilométrique officiel
+         de l'année correspondante (avec une majoration de +20% pour les véhicules électriques).
+       - Nombre de jours par type de journée (`day_type_counts`).
+    5. Regroupe les entrées par mois pour calculer les statistiques mensuelles :
+       - Nom du mois en français.
+       - Nombre de jours saisis.
+       - Distances parcourues par véhicule et distance totale du mois.
+       - Durée quotidienne médiane de travail et durée hebdomadaire médiane de travail (formatées en chaînes "HHhMM").
+    6. Rend le template `reports.html` avec l'ensemble de ces données de contexte.
+
+    Méthode HTTP :
+        GET
+
+    Paramètres de requête (Query Params) :
+        year (int, optionnel) : L'année civile pour laquelle générer le rapport (ex: `?year=2026`).
+                                Par défaut, l'année courante.
+
+    Retourne:
+        str: Le rendu HTML de la page des rapports (`reports.html`).
+    """
     year = request.args.get("year", date.today().year, type=int)
     start = date(year, 1, 1)
     end = date(year, 12, 31)