fix(types): @import JSDoc et correction des JSDoc (#328)

CLAUDE.md

@@ -59,7 +59,7 @@ fait »). Combiner :
   avec `toBeCloseTo(valeur, 9)` en la **commentant** comme référence de régression.
 - Vérifier aussi la **logique métier propre au fichier** (ex. le _matcher_ construit et passé à
   `tv()`), pas seulement le résultat final.
-- Ajouter un commentaire `@see : Methode_de_calcul_3CL_DPE_2021-338.pdf - §X` quand pertinent.
+- Ajouter un commentaire `@see Methode_de_calcul_3CL_DPE_2021-338.pdf - §X` quand pertinent.
 
 ### Testabilité du code source
 

src/10_besoin_fr.spec.js

@@ -38,7 +38,7 @@ const { calc_sse_j } = await import('./6.2_surface_sud_equivalente.js');
 
 /**
  * 10. Calcul des besoins de froid (Bfr)
- * @see : Methode_de_calcul_3CL_DPE_2021-338.pdf - §10
+ * @see Methode_de_calcul_3CL_DPE_2021-338.pdf - §10
  */
 describe('calc_besoin_fr_j - besoin de froid journalier', () => {
   test('retourne 0 lorsque le nombre de jours de référence est nul', () => {

src/10_clim.spec.js

@@ -31,7 +31,7 @@ beforeEach(() => {
 
 /**
  * 10. Calcul de la consommation de climatisation (froid)
- * @see : Methode_de_calcul_3CL_DPE_2021-338.pdf - §10
+ * @see Methode_de_calcul_3CL_DPE_2021-338.pdf - §10
  */
 describe('calc_clim - consommation de climatisation', () => {
   test('prorate le besoin de froid au ratio surface_clim / Sh', () => {

src/11_besoin_ecs.spec.js

@@ -23,7 +23,7 @@ const { default: calc_besoin_ecs, calc_besoin_ecs_j } = await import('./11_besoi
 
 /**
  * 11. Calcul du besoin d'eau chaude sanitaire (Becs)
- * @see : Methode_de_calcul_3CL_DPE_2021-338.pdf - §11
+ * @see Methode_de_calcul_3CL_DPE_2021-338.pdf - §11
  */
 describe('calc_besoin_ecs_j - besoin ECS journalier', () => {
   test('valeur de référence en mode conventionnel (56 L/j/personne)', () => {

src/11_ecs.js

@@ -1,3 +1,4 @@
+/** @import { InstallationEcsDE } from './features/dpe/domain/models/installation-ecs.model.js' */
 import enums from './enums.js';
 import calc_gen_ecs from './14_generateur_ecs.js';
 import { tv, requestInput, mois_liste, Njj } from './utils.js';
@@ -196,7 +197,7 @@ const TYPES_INSTALLATION_ECS_COLLECTIVE = ['2', '3'];
  * @see Moteur_DPE.dll Calcul_batiment.cs l.583-592 (Becs / Rdim seulement pour une installation
  * individuelle en immeuble ; Becs × Sh_ecs / SH sans Rdim pour une installation collective)
  * @param th {string} type de bâtiment (maison, appartement, immeuble)
- * @param de {Donnee_entree} donnée d'entrée de l'installation ECS
+ * @param de {InstallationEcsDE} donnée d'entrée de l'installation ECS
  * @returns {boolean}
  */
 export function isRdimEcsNeutralise(th, de) {

src/11_ecs.spec.js

@@ -61,7 +61,7 @@ beforeEach(() => {
 
 /**
  * 11. Prise en compte de l'ECS (ratio de besoin + rendement de distribution)
- * @see : Methode_de_calcul_3CL_DPE_2021-338.pdf - §11 / §17.2.1
+ * @see Methode_de_calcul_3CL_DPE_2021-338.pdf - §11 / §17.2.1
  */
 describe('calc_ecs - ratio de besoin ECS', () => {
   test('virtualisation : le ratio est la clé de répartition ECS', () => {
@@ -87,7 +87,7 @@ describe('calc_ecs - ratio de besoin ECS', () => {
    * Immeuble à ECS individuelles de surfaces différentes (cas CSTB IC1-0-3 / IC1-0-5 : 4
    * appartements de 20, 30, 45 et 80 m² sur 175 m², rdim 1) : besoin au prorata de la surface
    * desservie, comme Tribu (Becs appartement 1 = Becs immeuble × 20 / 175).
-   * @see : Methode_de_calcul_3CL_DPE_2021-338.pdf - §11.4
+   * @see Methode_de_calcul_3CL_DPE_2021-338.pdf - §11.4
    */
   test('immeuble à ECS individuelles : ratio = surface desservie / surface de l’immeuble', () => {
     const des = [20, 30, 45, 80].map((surface) => ({

src/11_nadeq.js

@@ -1,3 +1,4 @@
+/** @import { Logement } from './features/dpe/domain/models/dpe.model.js' */
 export class Nadeq {
   /**
    * Return nadeq for maison or individual logement

src/11_nadeq.spec.js

@@ -3,7 +3,7 @@ import { describe, expect, test } from 'vitest';
 
 describe('Nadeq unit tests', () => {
   /**
-   * @see : Methode_de_calcul_3CL_DPE_2021-338.pdf Page 70
+   * @see Methode_de_calcul_3CL_DPE_2021-338.pdf Page 70
    */
   const nadeq = new Nadeq();
 

src/12.4_pac.js

@@ -1,9 +1,11 @@
+/** @import { GenerateurChauffageDE, GenerateurChauffageDI } from './features/dpe/domain/models/installation-chauffage.model.js' */
+/** @import { GenerateurEcsDE, GenerateurEcsDI } from './features/dpe/domain/models/installation-ecs.model.js' */
 import { requestInputID, tv } from './utils.js';
 
 /**
  * Calcul ou récupération des paramètres scop ou cop
- * @param di {Donnee_intermediaire}
- * @param de {Donnee_entree}
+ * @param di {GenerateurChauffageDI|GenerateurEcsDI}
+ * @param de {GenerateurChauffageDE|GenerateurEcsDE}
  * @param du {Object}
  * @param zc_id {string}
  * @param ed_id {string|null}

src/12.4_pac.spec.js

@@ -26,7 +26,7 @@ beforeEach(() => {
 
 /**
  * 12.4 - Détermination du SCOP / COP des pompes à chaleur.
- * @see : Methode_de_calcul_3CL_DPE_2021-338.pdf - §12.4
+ * @see Methode_de_calcul_3CL_DPE_2021-338.pdf - §12.4
  */
 describe('scopOrCop - méthode de saisie "caractéristiques saisies" (id 6)', () => {
   test('SCOP renseigné : rg et rg_dep prennent la valeur du SCOP sans accès à la table', () => {

src/13.2_generateur_combustion.js

@@ -1,3 +1,6 @@
+/** @import { FullDpe } from './features/dpe/domain/models/dpe.model.js' */
+/** @import { GenerateurChauffage, GenerateurChauffageDE, GenerateurChauffageDI, InstallationChauffage } from './features/dpe/domain/models/installation-chauffage.model.js' */
+/** @import { GenerateurEcsDE, GenerateurEcsDI } from './features/dpe/domain/models/installation-ecs.model.js' */
 import { bug_for_bug_compat, convertExpression, tv, tvColumnLines } from './utils.js';
 import enums from './enums.js';
 import { updateGenerateurBouilleurs } from './13.2_generateur_combustion_bouilleur.js';
@@ -63,7 +66,7 @@ export const PN_MAX_QP0_CHAUDIERE_GAZ = 400000;
  * (Tribu, `Calcul_generateur.cs` Rpn_chaudieregaz, `Math.Min(400.0, Pn)`) plafonne Pn à 400 kW :
  * au-delà, la formule n'est plus représentative (elle décroît et devient négative vers 1 500 kW).
  * Le plafond ne s'applique pas aux chaudières fioul (Rpn_chaudierefioul : Pn non plafonné).
- * @see : Methode_de_calcul_3CL_DPE_2021-338.pdf - §13.2.2
+ * @see Methode_de_calcul_3CL_DPE_2021-338.pdf - §13.2.2
  *
  * @param row {object} ligne de la table generateur_combustion
  * @param pnCollectif {number} puissance nominale du générateur (W)
@@ -154,7 +157,7 @@ export function pnEstimee(GV, tbase, ratioSurface = 1) {
  * pour le chauffage, 8 pour l'ECS) du générateur.
  *
  * @param dpe {FullDpe}
- * @param de {Donnee_entree}
+ * @param de {GenerateurChauffageDE|GenerateurEcsDE}
  * @param type {'ch' | 'ecs'}
  * @returns {boolean|undefined} undefined si non renseigné
  */
@@ -170,7 +173,7 @@ export function chaudiereMurale(dpe, de, type) {
  * générateur ECS mixte de même `reference_generateur_mixte`, sinon générateur ECS mixte unique.
  *
  * @param dpe {FullDpe}
- * @param de {Donnee_entree} données du générateur de chauffage
+ * @param de {GenerateurChauffageDE|GenerateurEcsDE} données du générateur de chauffage
  * @returns {number|undefined}
  */
 export function volumeStockageEcsMixte(dpe, de) {
@@ -200,7 +203,7 @@ export function volumeStockageEcsMixte(dpe, de) {
  * pour une installation collective, Pch est conservée (comportement historique).
  *
  * @param dpe {FullDpe}
- * @param de {Donnee_entree} données du générateur
+ * @param de {GenerateurChauffageDE|GenerateurEcsDE} données du générateur
  * @param type {'ch' | 'ecs'}
  * @param pch {number} Pch (W) proratisée à la surface desservie
  * @param optionsPn {{installationIndividuelle?: boolean, volumeStockage?: number}}
@@ -249,8 +252,8 @@ export function pnEstimeeGenerateur(dpe, de, type, pch, optionsPn = {}) {
  * 5 - caractéristiques saisies à partir de la plaque signalétique ou d'une documentation technique du système à combustion : pn, rpn,rpint,qp0,temp_fonc_30,temp_fonc_100
  *
  * @param dpe {FullDpe}
- * @param di {Donnee_intermediaire} données du générateur
- * @param de {Donnee_entree} données du générateur
+ * @param di {GenerateurChauffageDI|GenerateurEcsDI} données du générateur
+ * @param de {GenerateurChauffageDE|GenerateurEcsDE} données du générateur
  * @param type {'ecs'|'ch'}
  * @param GV {number} déperdition de l'enveloppe
  * @param tbase {number} température de fonctionnement du générateur
@@ -392,8 +395,8 @@ export function tv_generateur_combustion(
    * dans Cper). Le XML ne transporte pas cette donnée : elle est lue dans la fiche technique du
    * générateur. Sans fiche technique, la ventouse est conservée comme approximation (choix
    * Open3CL, la méthode ne prévoyant pas de valeur par défaut).
-   * @see : Methode_de_calcul_3CL_DPE_2021-338.pdf - §13.2.2
-   * @see : Tribu Calcul_generateur.cs (ventilateur_combustion)
+   * @see Methode_de_calcul_3CL_DPE_2021-338.pdf - §13.2.2
+   * @see Tribu Calcul_generateur.cs (ventilateur_combustion)
    */
   const indexEF = de.ventilateurCombustion ?? de.presence_ventouse;
   const E = E_tab[indexEF];
@@ -474,7 +477,7 @@ export function tv_generateur_combustion(
 /**
  * Mise à jour du type de générateur si besoin
  * @param dpe {FullDpe}
- * @param de {Donnee_entree}
+ * @param de {GenerateurChauffageDE|GenerateurEcsDE}
  * @param type {'ch' | 'ecs'}
  */
 export function updateGenerateurCombustion(dpe, de, type) {
@@ -515,7 +518,7 @@ export function valeurVeilleuse(valeur) {
  * @see Methode_de_calcul_3CL_DPE_2021-338.pdf - §13.2.4 / §14.1 (« Pveil : si veilleuse »)
  *
  * @param dpe {FullDpe}
- * @param de {Donnee_entree}
+ * @param de {GenerateurChauffageDE|GenerateurEcsDE}
  * @param type {'ch' | 'ecs'}
  * @returns {1 | 0 | undefined} 1 si veilleuse, 0 si pas de veilleuse, undefined si non renseigné
  */
@@ -558,7 +561,7 @@ export function presenceVeilleuse(dpe, de, type) {
  * Récupération d'informations complémentaires issues des fiches techniques pour les générateurs
  *
  * @param dpe {FullDpe}
- * @param de {Donnee_entree}
+ * @param de {GenerateurChauffageDE|GenerateurEcsDE}
  * @param type {'ch' | 'ecs'}
  */
 function addInfosFromFichesTechniques(dpe, de, type) {
@@ -590,7 +593,7 @@ function addInfosFromFichesTechniques(dpe, de, type) {
  * Vérifier que les informations du générateur ECS sont bien les mêmes que celles du générateur de chauffage
  * Dans le cas d'une génération mixte, le type du générateur doit être le même
  * @param dpe {FullDpe}
- * @param de {Donnee_entree}
+ * @param de {GenerateurChauffageDE|GenerateurEcsDE}
  * @param typeGenerateurKey {string}
  * @returns {string}
  */
@@ -612,7 +615,7 @@ function checkEcsVsChauffageForMixteGeneration(dpe, de, typeGenerateurKey) {
   }
 
   /**
-   * @type {InstallationChauffageItem[]}
+   * @type {InstallationChauffage[]}
    */
   const installationsCh = dpe.logement.installation_chauffage_collection.installation_chauffage;
 
@@ -668,9 +671,9 @@ function checkEcsVsChauffageForMixteGeneration(dpe, de, typeGenerateurKey) {
  * 3. même énergie (`enum_type_energie_id`), si un seul générateur de chauffage mixte correspond ;
  * 4. générateur de chauffage mixte unique du DPE, si son énergie n'est pas incompatible.
  *
- * @param generateursChMixtes {GenerateurChauffageItem[]} générateurs de chauffage d'usage 'chauffage + ecs'
- * @param de {Donnee_entree} données du générateur ECS
- * @returns {GenerateurChauffageItem|null} null si aucun jumeau ne peut être identifié sans ambiguïté
+ * @param generateursChMixtes {GenerateurChauffage[]} générateurs de chauffage d'usage 'chauffage + ecs'
+ * @param de {GenerateurEcsDE} données du générateur ECS
+ * @returns {GenerateurChauffage|null} null si aucun jumeau ne peut être identifié sans ambiguïté
  */
 export function findGenerateurChMixteJumeau(generateursChMixtes, de) {
   const sameValue = (a, b) =>

src/13.2_generateur_combustion.spec.js

@@ -121,7 +121,7 @@ const ROW_DEFAUT = {
 
 /**
  * 13.2 - Récupération des caractéristiques forfaitaires d'un générateur à combustion.
- * @see : Methode_de_calcul_3CL_DPE_2021-338.pdf - §13.2
+ * @see Methode_de_calcul_3CL_DPE_2021-338.pdf - §13.2
  */
 describe('tv_generateur_combustion - caractéristiques du générateur', () => {
   test('puissance nominale calculée à partir de GV et Tbase lorsqu’elle est absente', () => {
@@ -358,7 +358,7 @@ describe('tv_generateur_combustion - compatibilité bug_for_bug_compat', () => {
 
   /**
    * Système collectif par défaut : chaudière fioul standard datant de la construction du bâtiment.
-   * @see : Methode_de_calcul_3CL_DPE_2021-338.pdf - §17.2.1.1
+   * @see Methode_de_calcul_3CL_DPE_2021-338.pdf - §17.2.1.1
    */
   describe('système collectif par défaut : chaudière selon l’année de construction', () => {
     test('CH 119 + ligne compatible : type et ligne de la période de construction retenus', () => {
@@ -668,7 +668,7 @@ describe('tv_generateur_combustion - génération mixte (checkEcsVsChauffageForM
 /**
  * Issue #210 : l'ECS mixte doit être appariée avec SON générateur de chauffage mixte (même appareil),
  * et non avec le premier générateur de chauffage mixte du DPE.
- * @see : Methode_de_calcul_3CL_DPE_2021-338.pdf - §13.2 et §14
+ * @see Methode_de_calcul_3CL_DPE_2021-338.pdf - §13.2 et §14
  */
 describe('findGenerateurChMixteJumeau - appariement ECS / chauffage mixte (issue #210)', () => {
   const ch = (donnees) => ({ donnee_entree: { enum_usage_generateur_id: '3', ...donnees } });
@@ -876,7 +876,7 @@ const dpeFiches = (...fiches) => ({
 
 /**
  * 13.2 - Orchestration des substitutions de générateurs et enrichissement fiches techniques.
- * @see : Methode_de_calcul_3CL_DPE_2021-338.pdf - §13.2
+ * @see Methode_de_calcul_3CL_DPE_2021-338.pdf - §13.2
  */
 describe('updateGenerateurCombustion - orchestration des substitutions', () => {
   test('délègue aux trois routines de substitution avec les mêmes arguments', () => {
@@ -983,7 +983,7 @@ describe('updateGenerateurCombustion - orchestration des substitutions', () => {
 /**
  * Issue #35 : les coefficients (E, F) de la formule qp0 dépendent de la présence d'un ventilateur
  * dans le circuit de combustion (fiche technique), la ventouse n'étant qu'un repli.
- * @see : Methode_de_calcul_3CL_DPE_2021-338.pdf - §13.2.2
+ * @see Methode_de_calcul_3CL_DPE_2021-338.pdf - §13.2.2
  */
 describe('tv_generateur_combustion - coefficients (E, F) selon le ventilateur de combustion (#35)', () => {
   const ROW_EF = { ...ROW_DEFAUT, rpn: 'E*40', qp0_perc: 'Pn*(E+F*log10(Pn))/100' };
@@ -1032,7 +1032,7 @@ describe('tv_generateur_combustion - coefficients (E, F) selon le ventilateur de
  * Issue #39 : présence d'une veilleuse lue dans la sous-fiche technique du générateur.
  * Tribu : entrée `Is_veilleuse` (DPE.DataClasses/generateur.cs), Pveil1 = 0 si absente
  * (DPE.Core/Calcul_generateur.cs).
- * @see : Methode_de_calcul_3CL_DPE_2021-338.pdf - §13.2.4 / §14.1
+ * @see Methode_de_calcul_3CL_DPE_2021-338.pdf - §13.2.4 / §14.1
  */
 describe('presenceVeilleuse - fiche technique « Présence d’une veilleuse »', () => {
   const ficheGen = (desc, veilleuse) => [
@@ -1151,7 +1151,7 @@ describe('presenceVeilleuse - fiche technique « Présence d’une veilleuse »'
 /**
  * Issue #124 : générateur collectif virtualisé, puissance saisie collective (Pn) ou individualisée
  * (Pe = a × Pn) selon les logiciels.
- * @see : Methode_de_calcul_3CL_DPE_2021-338.pdf - §13.2 et §17.2.1
+ * @see Methode_de_calcul_3CL_DPE_2021-338.pdf - §13.2 et §17.2.1
  */
 describe('tv_generateur_combustion - convention de puissance d’un générateur virtualisé (#124)', () => {
   const ROW_PN = {
@@ -1418,7 +1418,7 @@ describe('caracteristiquesGenerateurCombustion - selon la méthode de saisie', (
 /**
  * Plafond de Pn à 400 kW dans Qp0 = Pn × (E + F × log Pn) / 100 des chaudières gaz après 2015
  * (moteur de référence Tribu : Calcul_generateur.cs, Rpn_chaudieregaz, Math.Min(400.0, Pn)).
- * @see : Methode_de_calcul_3CL_DPE_2021-338.pdf - §13.2.2
+ * @see Methode_de_calcul_3CL_DPE_2021-338.pdf - §13.2.2
  */
 describe('puissanceFormuleQp0 - plafond de Pn à 400 kW pour les chaudières gaz', () => {
   const ROW_GAZ = {
@@ -1486,7 +1486,7 @@ describe('puissanceFormuleQp0 - plafond de Pn à 400 kW pour les chaudières gaz
 
 /**
  * Estimation de la puissance nominale d'un générateur à combustion (pn absente).
- * @see : Methode_de_calcul_3CL_DPE_2021-338.pdf - §13.2.2.4
+ * @see Methode_de_calcul_3CL_DPE_2021-338.pdf - §13.2.2.4
  */
 describe('pnEstimee - puissance nominale estimée (issue #264)', () => {
   // 1,2 × 200 × (19 − (−9)) / 0,95³ -- valeur de référence de régression
@@ -1518,7 +1518,7 @@ describe('pnEstimee - puissance nominale estimée (issue #264)', () => {
 
 /**
  * Pn estimée par la puissance de dimensionnement (issue #271).
- * @see : Methode_de_calcul_3CL_DPE_2021-338.pdf - §13.2.2.4
+ * @see Methode_de_calcul_3CL_DPE_2021-338.pdf - §13.2.2.4
  */
 describe('pnEstimeeGenerateur - Pdim = max(Pch ; Pecs) et table Pdim → Pn (issue #271)', () => {
   const dpeAvecEcsMixte = (generateursEcs) => ({

src/13.2_generateur_combustion_bouilleur.js

@@ -1,9 +1,12 @@
+/** @import { FullDpe } from './features/dpe/domain/models/dpe.model.js' */
+/** @import { GenerateurChauffageDE } from './features/dpe/domain/models/installation-chauffage.model.js' */
+/** @import { GenerateurEcsDE } from './features/dpe/domain/models/installation-ecs.model.js' */
 import getFicheTechnique from './ficheTechnique.js';
 
 /**
  * Pour les générateurs "poêles à bois bouilleur", les calculs sont faits comme pour les chaudières bois
  * @param dpe {FullDpe}
- * @param de {Donnee_entree}
+ * @param de {GenerateurChauffageDE|GenerateurEcsDE}
  * @param type {'ch' | 'ecs'}
  */
 export function updateGenerateurBouilleurs(dpe, de, type) {
@@ -121,7 +124,7 @@ export function updateGenerateurBouilleurs(dpe, de, type) {
  *  - Pour un poêle à bois bouilleur bûche installé avant 1948, on prendra la chaudière bois bûche avant 1978
  * @param dpe {FullDpe}
  * @param ids
- * @param de {Donnee_entree}
+ * @param de {GenerateurChauffageDE|GenerateurEcsDE}
  * @param type {'ch' | 'ecs'}
  */
 function updateGenerateurBouilleur(dpe, ids, de, type) {

src/13.2_generateur_combustion_bouilleur.spec.js

@@ -18,7 +18,7 @@ beforeEach(() => {
 /**
  * 13.1 - Les poêles à bois bouilleur sont assimilés à des chaudières bois de la
  * période correspondante.
- * @see : Methode_de_calcul_3CL_DPE_2021-338.pdf - §13.1
+ * @see Methode_de_calcul_3CL_DPE_2021-338.pdf - §13.1
  */
 describe('updateGenerateurBouilleurs - substitution par une chaudière bois équivalente', () => {
   test('type non concerné : aucune substitution', () => {