SchotzIAD/.kiro/specs/precision-distances-km/requirements.md

Requirements Document

Introduction

Cette fonctionnalité introduit un paramètre global de précision d'affichage des distances (nombre de décimales : 0, 1 ou 2) dans l'application SchotzIAD KM Tracker, ainsi qu'une règle d'arrondi supérieur systématique appliquée à cette précision pour toute distance affichée ou agrégée (trajet, totaux journaliers/mensuels/annuels, carte, export PDF, barème kilométrique). Elle modifie également le mode de calcul de l'indication de versement mensuelle (Montant_Previsionnel), qui passe d'un calcul basé sur le cumul annuel partiel à un calcul basé uniquement sur le mois affiché, et introduit une nouvelle ligne d'affichage « Montant prévisionnel annuel » (100% du barème, projection sur le cumul annuel partiel).

Note

: Cette spec complète la spec existante schotziad-km-tracker (requirements.md, design-requirements.md, design.md). Elle réutilise et étend les termes déjà définis dans le glossaire de schotziad-km-tracker (notamment Trajet, Distance, Aller_Retour, Distance_Effective, Résumé_Mensuel, Résumé_Annuel, Total_Annuel_Partiel, Panneau_Totaux, Bareme_Kilometrique, Montant_Previsionnel, Montant_Reel, Regularisation, Frais_Reel_Mensuel, Page_Parametrage, Export_PDF, Carte). Les exigences ci-dessous priment sur celles de schotziad-km-tracker en cas de divergence portant sur le calcul du Montant_Previsionnel et sur la précision d'affichage des distances ; toutes les autres exigences de schotziad-km-tracker restent applicables sans changement.

---

Glossary

• Precision_Distance : Le paramètre global de l'Application déterminant le nombre de décimales (0, 1 ou 2) utilisé pour l'arrondi supérieur des distances à l'affichage et dans les agrégats. Ce paramètre est unique pour toute l'Application (pas de déclinaison par Véhicule ni par Utilisateur).
• Distance_Arrondie : La valeur d'une Distance simple (non doublée) après application de l'arrondi supérieur mathématique (ceiling) à la précision définie par Precision_Distance. Exemple avec Precision_Distance = 0 : 12,3 km devient 13 km. Exemple avec Precision_Distance = 1 : 12,34 km devient 12,4 km. Exemple avec Precision_Distance = 2 : 12,347 km devient 12,35 km.
• Distance_Effective_Arrondie : La distance comptée d'un Trajet dans tous les agrégats et affichages une fois la règle d'arrondi appliquée : égale à la Distance_Arrondie, ou à son double lorsque le Trajet est un Aller_Retour (la Distance simple est arrondie AVANT d'être doublée, jamais après).
• Sous_Menu_Application : L'entrée « Application » du menu latéral de la Page_Parametrage, positionnée entre « Compte » et « Véhicules », permettant de configurer Precision_Distance.
• Montant_Previsionnel_Mensuel : L'indication de versement mensuelle (80%) redéfinie par la présente spec : elle correspond à 80% du Bareme_Kilometrique appliqué à la Distance_Effective_Arrondie totale du seul mois affiché (et non plus au Total_Annuel_Partiel).
• Montant_Previsionnel_Annuel : La nouvelle ligne d'affichage introduite par la présente spec, calculée comme 100% (sans minoration) du Bareme_Kilometrique appliqué au Total_Annuel_Partiel arrondi (cumul de l'année sélectionnée jusqu'au mois affiché inclus), affichée sous le Montant_Previsionnel_Mensuel.

---

Requirements

Requirement 1: Paramètre global de précision des distances

User Story: En tant qu'utilisateur, je veux choisir le nombre de décimales utilisé pour l'affichage des distances en kilomètres, afin d'adapter la précision affichée à mes besoins (ex. arrondi à l'unité pour une lecture rapide, ou deux décimales pour une précision fine).

Acceptance Criteria

1. THE Backend SHALL persister une valeur unique de Precision_Distance pour l'ensemble de l'Application, parmi exactement trois valeurs possibles : 0, 1 ou 2.
2. WHERE aucune valeur de Precision_Distance n'a encore été enregistrée, THE Backend SHALL considérer la valeur par défaut de Precision_Distance comme égale à 2.
3. THE Backend SHALL exposer une API protégée par authentification permettant de lire la valeur courante de Precision_Distance.
4. THE Backend SHALL exposer une API protégée par authentification permettant de modifier la valeur de Precision_Distance.
5. WHEN l'utilisateur soumet une nouvelle valeur de Precision_Distance égale à 0, 1 ou 2, THE Backend SHALL persister cette valeur et SHALL l'appliquer immédiatement à tous les calculs et affichages ultérieurs de distances, pour les Trajets passés comme futurs, sans migration ni recalcul des données stockées.
6. IF le Backend reçoit une valeur de Precision_Distance différente de 0, 1 ou 2, THEN THE Backend SHALL rejeter la modification et retourner un message d'erreur indiquant que seules les valeurs 0, 1 et 2 sont autorisées.
7. IF le Backend reçoit une requête de lecture ou de modification de Precision_Distance sans Session authentifiée valide, THEN THE Backend SHALL rejeter la requête.
8. THE Backend SHALL ne jamais modifier la valeur brute stockée de la Distance d'un Trajet (colonne Distance existante) ni les calculs de Calculateur_Distance (routier ou Haversine) suite à un changement de Precision_Distance ; seuls l'affichage et les agrégats calculés à la volée sont affectés.

---

Requirement 2: Sous-menu « Application » dans le paramétrage

User Story: En tant qu'utilisateur, je veux accéder à un sous-menu « Application » dans la page de paramétrage, afin de configurer la précision d'affichage des distances au même endroit que mes autres réglages.

Acceptance Criteria

1. THE Page_Parametrage SHALL présenter, dans son menu latéral, l'entrée Sous_Menu_Application positionnée entre l'entrée « Compte » et l'entrée « Véhicules » (ordre : Compte, Application, Véhicules, Barème).
2. WHEN l'utilisateur sélectionne Sous_Menu_Application dans le menu latéral de la Page_Parametrage, THE Frontend SHALL afficher à droite du menu un contrôle de sélection « Nombre de décimales des distances (km) » proposant exactement trois choix : 0, 1 et 2, sans rechargement complet de la page.
3. WHEN la page Sous_Menu_Application est affichée, THE Frontend SHALL présélectionner le choix correspondant à la valeur courante de Precision_Distance renvoyée par le Backend.
4. WHILE la page Sous_Menu_Application est affichée, WHEN l'utilisateur sélectionne une valeur différente pour Precision_Distance, THE Frontend SHALL envoyer la nouvelle valeur au Backend et afficher un message de confirmation lorsque l'enregistrement réussit.
5. IF l'enregistrement d'une nouvelle valeur de Precision_Distance échoue au niveau du Backend, THEN THE Frontend SHALL afficher un message d'erreur indiquant que la modification n'a pas pu être enregistrée et SHALL conserver l'affichage de la valeur précédemment active.
6. THE Backend SHALL autoriser l'accès à Sous_Menu_Application indépendamment de l'état de configuration du Profil (Profil_Configure ou non), de la même manière que les entrées « Compte » et « Véhicules » de la Page_Parametrage.

---

Requirement 3: Arrondi supérieur d'un trajet simple

User Story: En tant qu'utilisateur, je veux que la distance affichée d'un trajet simple soit arrondie au supérieur selon la précision choisie, afin d'obtenir un affichage cohérent et jamais sous-évalué.

Acceptance Criteria

1. WHEN le Frontend affiche la distance d'un Trajet qui n'est pas un Aller_Retour, THE Frontend SHALL afficher la Distance_Arrondie de ce Trajet, calculée par arrondi supérieur mathématique de la Distance brute à la précision définie par Precision_Distance.
2. WHILE Precision_Distance est égal à 0, THE Distance_Arrondie SHALL être égale à la Distance brute arrondie au kilomètre entier supérieur (ex. 12,3 km devient 13 km ; 12,0 km reste 12 km).
3. WHILE Precision_Distance est égal à 1, THE Distance_Arrondie SHALL être égale à la Distance brute arrondie au dixième de kilomètre supérieur (ex. 12,34 km devient 12,4 km).
4. WHILE Precision_Distance est égal à 2, THE Distance_Arrondie SHALL être égale à la Distance brute arrondie au centième de kilomètre supérieur (ex. 12,347 km devient 12,35 km).
5. THE Distance_Arrondie d'un Trajet SHALL toujours être supérieure ou égale à la Distance brute correspondante, quelle que soit la valeur de Precision_Distance.

---

Requirement 4: Arrondi supérieur d'un trajet aller-retour

User Story: En tant qu'utilisateur, je veux que la distance affichée d'un trajet aller-retour soit le double de la distance simple déjà arrondie, afin que l'ordre des opérations (arrondi puis doublement) soit cohérent et prévisible.

Acceptance Criteria

1. WHEN le Frontend affiche la distance d'un Trajet dont Aller_Retour est vrai, THE Frontend SHALL afficher la Distance_Effective_Arrondie égale au double de la Distance_Arrondie de la distance simple mesurée entre le départ et l'arrivée.
2. THE Backend SHALL calculer la Distance_Effective_Arrondie d'un Trajet Aller_Retour en appliquant l'arrondi supérieur à la distance simple AVANT de la multiplier par deux, et jamais en doublant d'abord la distance brute puis en arrondissant le résultat.
3. THE Distance_Effective_Arrondie d'un Trajet non-Aller_Retour SHALL être égale à sa Distance_Arrondie (sans doublement).

---

Requirement 5: Agrégation des totaux à partir des distances arrondies

User Story: En tant qu'utilisateur, je veux que les totaux du jour, du mois et de l'année soient calculés en additionnant des distances déjà arrondies, afin que la somme affichée soit cohérente avec la somme visuelle des lignes de détail.

Acceptance Criteria

1. WHEN le Backend ou le Frontend calcule le total kilométrique d'une journée, THE Backend ou THE Frontend SHALL additionner la Distance_Effective_Arrondie de chaque Trajet de cette journée, sans appliquer d'arrondi supplémentaire après la somme.
2. WHEN le Backend calcule le total kilométrique d'un Résumé_Mensuel, THE Backend SHALL additionner la Distance_Effective_Arrondie de chaque Trajet du mois concerné, sans appliquer d'arrondi supplémentaire après la somme.
3. WHEN le Backend calcule le total kilométrique d'un Résumé_Annuel ou le Total_Annuel_Partiel, THE Backend SHALL additionner la Distance_Effective_Arrondie de chaque Trajet des mois concernés, sans appliquer d'arrondi supplémentaire après la somme.
4. THE Panneau_Totaux SHALL afficher le total du jour, le total du mois sélectionné et le Total_Annuel_Partiel de l'année sélectionnée en appliquant la règle de sommation des distances déjà arrondies définie par la présente exigence.
5. WHEN Precision_Distance est modifié, THE Frontend SHALL recalculer et afficher immédiatement les totaux du jour, du mois et de l'année selon la nouvelle valeur de Precision_Distance, sans rechargement complet de la page.

---

Requirement 6: Application de l'arrondi au barème kilométrique

User Story: En tant qu'utilisateur, je veux que les calculs de barème kilométrique (indication de versement, montant réel, régularisation) utilisent les distances arrondies affichées, afin que les montants calculés correspondent aux kilomètres que je vois à l'écran.

Acceptance Criteria

1. WHEN le Backend calcule le Montant_Previsionnel_Mensuel, THE Backend SHALL appliquer le Bareme_Kilometrique à la somme des Distance_Effective_Arrondie des Trajets du mois affiché, et non à la Distance brute.
2. WHEN le Backend calcule le Montant_Previsionnel_Annuel, THE Backend SHALL appliquer le Bareme_Kilometrique à la valeur arrondie du Total_Annuel_Partiel telle que définie par l'Exigence 5.
3. WHEN le Backend calcule le Montant_Reel annuel d'un Véhicule, THE Backend SHALL appliquer le Bareme_Kilometrique plein (100%) au total kilométrique annuel obtenu par sommation des Distance_Effective_Arrondie de tous les Trajets de l'année, et non des Distances brutes.
4. WHEN le Backend calcule le Frais_Reel_Mensuel de chaque mois, THE Backend SHALL multiplier la somme des Distance_Effective_Arrondie des Trajets du mois par le coefficient de la tranche annuelle applicable.
5. WHEN le Backend calcule la Regularisation d'un Véhicule pour une année, THE Backend SHALL utiliser le Montant_Reel annuel calculé à partir des distances arrondies conformément à la présente exigence.
6. THE Backend SHALL déterminer la Tranche_Bareme applicable (mensuelle ou annuelle) à partir du total kilométrique arrondi correspondant, et non à partir du total kilométrique brut.

---

Requirement 7: Indication de versement mensuelle recentrée sur le mois affiché

User Story: En tant qu'utilisateur, je veux que l'indication de versement (80%) corresponde uniquement au mois que je consulte, afin de mieux estimer le montant à verser pour ce mois précis plutôt que pour tout le cumul annuel.

Acceptance Criteria

1. WHEN l'utilisateur consulte les données d'un mois, THE Frontend SHALL afficher le Montant_Previsionnel_Mensuel calculé comme 80% du Bareme_Kilometrique appliqué à la Distance_Effective_Arrondie totale du seul mois affiché, sans y inclure les distances des mois précédents de l'année.
2. THE Backend SHALL déterminer la Tranche_Bareme utilisée pour le Montant_Previsionnel_Mensuel à partir du total kilométrique annuel arrondi cumulé (Total_Annuel_Partiel), conformément à la règle de sélection de tranche du Bareme_Kilometrique définie dans schotziad-km-tracker (Requirement 13), tout en appliquant le coefficient ainsi déterminé au seul kilométrage arrondi du mois affiché.
3. THE Frontend SHALL continuer à indiquer explicitement que le Montant_Previsionnel_Mensuel est une simple indication de versement et que le montant réellement versé est celui saisi par l'utilisateur (Montant_Regle).
4. THE présente exigence SHALL remplacer, pour le calcul du Montant_Previsionnel mensuel, la règle de calcul antérieure basée sur le Total_Annuel_Partiel définie dans schotziad-km-tracker (Requirement 13, critère 5).

---

Requirement 8: Montant prévisionnel annuel

User Story: En tant qu'utilisateur, je veux voir, en dessous de l'indication de versement mensuelle, une projection du montant prévisionnel annuel sans minoration, afin d'avoir une vision du montant total attendu sur l'année en cours.

Acceptance Criteria

1. WHEN l'utilisateur consulte les données d'un mois, THE Frontend SHALL afficher, immédiatement sous le Montant_Previsionnel_Mensuel, une ligne « Montant prévisionnel annuel » présentant le Montant_Previsionnel_Annuel.
2. THE Backend SHALL calculer le Montant_Previsionnel_Annuel en appliquant le Bareme_Kilometrique sans minoration (100%) au Total_Annuel_Partiel arrondi de l'année sélectionnée, cumulé jusqu'au mois affiché inclus.
3. THE Frontend SHALL indiquer explicitement que le Montant_Previsionnel_Annuel est une projection indicative sans minoration (100% du barème) et qu'il ne se substitue pas au Montant_Reel calculé en fin d'année sur la base du kilométrage annuel complet.
4. THE Frontend SHALL afficher le Montant_Previsionnel_Annuel avec une précision de deux décimales, selon les mêmes conventions d'affichage monétaire que le Montant_Previsionnel_Mensuel.
5. THE Backend SHALL déterminer la Tranche_Bareme utilisée pour le Montant_Previsionnel_Annuel à partir du même total kilométrique arrondi (Total_Annuel_Partiel) auquel le barème est appliqué.

---

Requirement 9: Cohérence de l'arrondi sur la carte et dans l'export PDF

User Story: En tant qu'utilisateur, je veux que la carte et les exports PDF affichent la même distance arrondie que la liste des trajets et les totaux, afin de ne jamais voir de chiffres contradictoires selon l'endroit de l'application consulté.

Acceptance Criteria

1. WHEN l'utilisateur survole ou clique sur un tracé de Trajet sur la Carte, THE Frontend SHALL afficher dans l'infobulle la Distance_Effective_Arrondie de ce Trajet, calculée selon la valeur courante de Precision_Distance.
2. WHEN le Backend génère un Export_PDF (mensuel ou annuel), THE Backend SHALL utiliser la Distance_Effective_Arrondie de chaque Trajet, ainsi que les totaux calculés à partir de ces distances arrondies conformément à l'Exigence 5, pour toutes les valeurs kilométriques figurant dans le document.
3. WHEN le Backend génère un Export_PDF, THE Backend SHALL appliquer la valeur de Precision_Distance en vigueur au moment de la génération du document pour arrondir les distances affichées dans le PDF.
4. THE Backend SHALL garantir que la Distance_Effective_Arrondie utilisée pour un même Trajet est strictement identique, à valeur de Precision_Distance égale, dans la liste des Trajets, le Panneau_Totaux, la Carte, l'Export_PDF et les calculs de Bareme_Kilometrique.

---