feat: add the residual value + some file refactoring

doc/specs.md

@@ -315,6 +315,14 @@ Avec ce choix, des questions peuvent se poser :
 > neuve et pour l'occasion ne pas la décompter ? Comment faire pour reporter
 > cette _dette d'empreinte_ lors d'un futur achat ?
 
+#### Durée de détention
+
+Ayant choisit un amortissement linéaire du prix d'achat sur la durée de
+détention, il est nécessaire de déterminer cette durée de détention.
+Or, trouver la bonne formulation afin de signifier que **cette durée
+comprend à la fois le temps écoulé depuis l'achat mais également
+le temps restant avant la revente n'est pas évident**.
+
 ### Estimation du prix d'achat
 
 Pour le calcul des coûts de la voiture actuelle, il n'est pas nécessaire d'être
@@ -433,3 +441,4 @@ Le type de trajet à pour but d'affiner l'estimation des coûts de la catégorie
 etc... (Voir [futur.eco/cout-voiture](https://futur.eco/cout-voiture).
 
 <details>
+```

rules/commun.publicodes

@@ -12,3 +12,10 @@ commun . voiture:
 commun . voiture . parc français 2022:
   titre: Nombre de voiture en circulation en France au 1er janvier 2022
   valeur: 38.7 millions de voiture
+
+# NOTE: cette règle ne devrait-elle pas être déplacée dans le modèle
+# publicodes-commun avec une github action pour mettre à jour la valeur chaque
+# année ?
+commun . année courante:
+  titre: Année courante
+  valeur: 2024

rules/cout.publicodes → rules/couts/couts.publicodes

@@ -148,7 +148,7 @@ coûts . voiture . coûts de possession . assurance estimée:
 
 coûts . voiture . coûts de possession . achat amorti:
   titre: Coût annuel de l'achat de votre voiture
-  formule: voiture . prix d'achat / voiture . durée de détention
+  formule: (voiture . prix d'achat - valeur résiduelle) / voiture . durée de détention totale
   note: |
     Le prix d'achat d'une voiture qu'elle soit neuve ou d'occasion représente
     un facteur important du coût total du véhicule. Le choix de la fonction
@@ -163,7 +163,7 @@ coûts . voiture . coûts de possession . achat amorti:
     Nous avons donc du faire un choix et avons décidé de choisir un
     **amortissement linéaire sur la durée de détention**.
 
-    ### Historique de ce choix
+    #### Historique de ce choix
 
     La première version du modèle pour le calcul des coûts d'une voiture était
     basée sur le modèle de [futur.eco](https://futur.eco/cout-voiture) qui
@@ -186,10 +186,20 @@ coûts . voiture . coûts de possession . achat amorti:
     durée de détention du véhicule. Or, dans le contexte d'un questionnement
     sur le remplacement d'un véhicule, il est plus probable que la durée de
     détention soit connue.
-
+  avec:
+    valeur résiduelle:
+      titre: Valeur résiduelle du véhicule à la revente
+      description: |
+        Prix estimé de revente de votre voiture à la fin de son utilisation,
+        permettant ainsi d'amortir uniquement la différence entre le prix
+        d'achat et la valeur résiduelle.
+      valeur: voiture . prix d'achat * décote
+      contexte:
+        décote . durée décote: voiture . durée de détention totale
+
 coûts . voiture . coûts de possession . certificat d'immatriculation amorti:
   titre: Coût annuel du certificat d'immatriculation
-  formule: certificat d'immatriculation / voiture . durée de détention
+  formule: certificat d'immatriculation / voiture . durée de détention totale
 
 # TODO: a compléter
 coûts . voiture . coûts de possession . certificat d'immatriculation:

rules/electricite.publicodes → rules/couts/prix-electricite.publicodes

@@ -1,22 +1,25 @@
-électricité:
+prix électricité:
+  description: |
+    Prix de l'électricité en France en août 2024 selon le tarif réglementé de
+    vente (TRV) d'EDF.
 
-électricité . TRV base:
+prix électricité . TRV base:
   titre: Tarif réglementé de vente (TRV) (Tarif Bleu d'EDF - Base)
   valeur: 0.2516 €/kWh
   note : |
     Tarif réglementé de vente (TRV) de l'électricité au 14 août 2024 selon la
     grille tarifaire renseignée sur [hello
     watt](https://www.hellowatt.fr/contrat-electricit%C3%A9/prix-trv-electricite).
 
-électricité . TRV HC:
+prix électricité . TRV HC:
   titre: Tarif réglementé de vente (TRV) (Tarif Bleu d'EDF - Heures Creuses)
   valeur: 0.2068 €/kWh
   note: |
     Tarif réglementé de vente (TRV) de l'électricité au 14 août 2024 selon la
     grille tarifaire renseignée sur [hello
     watt](https://www.hellowatt.fr/contrat-electricit%C3%A9/prix-trv-electricite).
 
-électricité . TRV HP:
+prix électricité . TRV HP:
   titre: Tarif réglementé de vente (TRV) (Tarif Bleu d'EDF - Heures Pleines)
   valeur: 0.27 €/kWh
   note: |

rules/couts/voiture-decote.publicodes

@@ -0,0 +1,57 @@
+# NOTE: on pourrait vouloir extraire le prix d'achat comme paramètre pour
+# rendre le modèle plus générique. Cependant, pour l'instant il est possible
+# d'écraser la règle `voiture . prix d'achat` dans un `contexte`. Pour
+# l'instant, par soucis de performance, nous privilégions cette solution pour
+# éviter les les recaculs inutiles.
+décote:
+  titre: Calcul de la décote d'une voiture
+  description: |
+    Ce modèle permet de calculer la décote moyenne d'une voiture en fonction de
+    son âge.
+
+    La décote est une estimation de la perte de valeur d'un bien, ici d'une
+    voiture, au fil du temps. Elle s'explique par l'usure du véhicule, son
+    obsolescence, l'évolution des normes environnementales, etc...
+
+    A noter que le prix d'une voiture peut grandement varier en fonction du
+    modèle, de l'état du véhicule et que seul une comparaison avec les prix du
+    marché à un instant donné permettra de déterminer le prix de vente réel.
+    Par conséquent, **la décote calculée ici est une estimation moyenne**.
+  formule:
+    variations:
+      - si: durée décote <= 1
+        alors: 20%
+      - si: durée décote <= 2
+        alors: 35%
+      - si: durée décote <= 3
+        alors: 45%
+      - si: durée décote <= 4
+        alors: 55%
+      - sinon: 60%
+  note: |
+    ### Sources
+
+    Selon cet
+    [article](https://www.carizy.com/blog/article/decote-voiture-impacts) ou
+    [celui-ci](https://www.fiches-auto.fr/articles-auto/argent-economie/s-2952-decote-d-une-voiture-variables-et-estimation.php),
+    on peut estimer une valeur moyenne de décote dégressive au fur et à mesure
+    de sa mise en circulation : 
+
+    | Temps écoulé depuis la mise en circulation  | Décote moyenne |
+    |---------------------------------------------|----------------|
+    | 1 an                                        | 20-25%         |
+    | 2 ans                                       | 15%            |
+    | 3 ans                                       | 10-12%         |
+    | 4 ans                                       | 10%            |
+    | 5 ans et plus                               | 5-7%           |
+
+    ### Pistes d'amélioration
+
+    Le taux de décote varie d'un type de motorisation à un autre. Il serait
+    pertinent de prendre en compte ce critère pour affiner le calcul.
+    Cependant, il n'existe pas réellement de sources pour le faire.
+  avec: 
+    durée décote:
+      description: Durée sur laquelle la décote est appliquée.
+      par défaut: voiture . âge
+      unité: an