Analyse approfondie : Standardisation des Masses & Rendement

Gram est profondément ancré dans la réalité physique. Contrairement aux parseurs Markdown basiques qui se contentent de mettre du texte en gras, le @gram/analyzer comprend qu'une "tasse de farine" et une "tasse d'eau" ont des poids complètement différents.

Cette page explique le moteur physique derrière les calculs de masse et de rendement de Gram.

Les Trois Piliers de la Physique

Gram sépare les propriétés physiques des ingrédients en trois concepts distincts au sein de votre base de données. Cette séparation stricte garantit que les mathématiques sont toujours exactes, que vous écriviez en volumes, en nombres, ou en poids.

1. Densité (density) : Utilisée strictement pour convertir les Volumes en Masse.
   • Exemple : 1 tasse de lait -> 240 g (en utilisant une densité de 1,03 g/ml).
2. Poids Unitaire (unit_weight) : Utilisé strictement pour convertir les Nombres en Masse.
   • Exemple : 1 avocat -> 150 g (le poids moyen d'un avocat entier).
3. Rendement (yield) : Le Facteur de Déchet. Utilisé strictement pour calculer le rapport entre la Masse Nette comestible et la Masse Brute à l'achat (à cause des pelures, graines, os).
   • Exemple : Un avocat a un rendement de 0.70 (30 % correspond au noyau et à la peau).

---

Le But de la Standardisation des Masses

Le but principal de l'Analyseur est de calculer la Masse Totale d'une recette. C'est essentiel pour l'estimation nutritionnelle, le calcul du coût, et les ratios de pâtisserie.

Pour ce faire, l'Analyseur doit convertir chaque quantité d'ingrédient en une base de référence unifiée : les grammes (g).

L'Algorithme de Conversion

Lorsque l'Analyseur rencontre un ingrédient, il le passe par un algorithme de priorité stricte pour trouver sa masse :

1. Masse Précise : Si vous avez écrit @farine{200 g} ou @boeuf{1 kg}, l'Analyseur n'a rien à faire. Il convertit simplement cela en grammes.
2. Surcharge Utilisateur : Si vous avez fourni une surcharge de densité spécifique dans le frontmatter YAML de la recette (ex : densities: { farine: 0.55 }), il utilise cette valeur explicite pour convertir le volume demandé en masse.
3. Densité de la Base de Données : Si vous avez demandé un volume connu (ml, tasse, c.à.s, c.à.c) et que votre ingredients.yaml contient un champ density pour cet ingrédient, il calcule Volume * Densité = Masse.
4. Poids Unitaire de la Base de Données : Si vous avez demandé un nombre (@oeuf{3} ou @ail{2 gousses}) et que votre base de données contient un champ unit_weight, il calcule Nombre * Poids Unitaire = Masse.
5. Incomplet : Si un volume n'a aucune densité disponible (pas de surcharge, pas d'entrée en BDD) ou qu'un nombre n'a pas de unit_weight, l'Analyseur refuse de deviner. Il ne va pas supposer une densité par défaut (ex : traiter n'importe quoi comme de l'eau) — cela fausserait silencieusement les totaux de la liste de courses. Le calcul de la masse échoue, l'ingrédient est marqué comme "incomplet", et il est listé dans son unité brute non convertie.

Calcul du Rendement (Le Facteur de Déchet)

Dans les cuisines professionnelles, il y a une différence fondamentale entre ce qui va dans la casserole et ce que vous achetez au magasin.

• Masse Nette (Portion Comestible) : Le poids de l'ingrédient après épluchage, évidage ou parage.
• Masse Brute (Poids d'Achat) : Le poids de l'ingrédient tel qu'il est acheté.

Le rapport entre ces deux éléments est le Facteur de Rendement.

Comment Gram gère le Rendement

Par défaut, Gram suppose que tout ingrédient écrit dans votre recette fait référence à la Masse Nette. Le générateur de liste de courses travaille ensuite à l'envers en utilisant le rendement (yield) et le poids unitaire (unit_weight) pour vous dire exactement quelle quantité acheter.

Regardons deux scénarios pour un avocat (unit_weight: 150g, yield: 0.70) :

Scénario A : Écrire en Nombres (@avocat{1})

1. L'Analyseur lit "1 unité".
2. Il applique le unit_weight : 1 * 150 g = 150 g. C'est la Masse Brute (l'avocat entier acheté) — stockée en tant que purchasingMass de l'ingrédient.
3. Il applique le yield (rendement) vers l'avant pour trouver ce qui entre réellement dans la recette : 150 g * 0.70 = 105 g. C'est la Masse Nette — la valeur utilisée pour la masse totale de la recette et les calculs de nutrition.

Scénario B : Écrire en Masse (@avocat{200 g})

1. L'Analyseur lit "200 g". Il suppose qu'il s'agit de la Masse Nette dont vous avez besoin dans le bol.
2. Il applique le yield à l'envers pour trouver le poids de la liste de courses : 200 g / 0.70 = 285 g. C'est la Masse Brute.
3. Il peut utiliser le unit_weight pour vous dire combien en acheter : 285 g / 150 g = 1,9 avocats (donc, en acheter 2).

Cela garantit que vous ne vous retrouverez jamais à court d'ingrédients après les avoir préparés.