forge-joniko/ldc-arcadia-api
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ldc-arcadia-api/documentation/Arcadia/IncoStuffIntelligence.md
Jérémy Munsch 0d2b0124ee docs(architecture): add global architecture documentation for Arcadia API 
docs(architecture): add request lifecycle documentation for Arcadia API

docs(architecture): add execution, transactions, and domain events documentation for Arcadia API

docs(architecture): add guide for creating a new use case in Arcadia API

docs(exceptions): summarize exception handling and HTTP status codes in Arcadia API

docs(tests): outline testing strategy and conventions for Arcadia API

style(openapi): correct description formatting in OpenAPI documentation

chore: remove outdated exceptions documentation

test: remove obsolete tests documentation
2026-08-21 10:41:07 +02:00

279 lines
19 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Classification Inco demandée a TOTO GPT
Voici une classification des champs en catégories sémantiques cohérentes pour des données nutritionnelles INCO :
---
## 🏷️ Classification des champs nutritionnels
### 1. **Identification / Métadonnées**
| Champ PHP | Constante | Description |
| --------- | --------- | -------------------- |
| `nom` | `NOM` | Nom du produit/fiche |
| `numero` | `NUMERO` | Numéro de la fiche |
| `source` | `SOURCE` | Source des données |
---
### 2. **Valeurs énergétiques - par 100g/100ml (référence `_R`)**
| Champ PHP | Constante | Description |
| ----------------------- | ------------------ | --------------------------------- |
| `tailleReference` | `TAILLE_REF` | Taille de la portion de référence |
| `valEnergKjReference` | `VAL_ENERG_KJ_R` | Énergie en kJ / 100g |
| `valEnergKcalReference` | `VAL_ENERG_KCAL_R` | Énergie en kcal / 100g |
---
### 3. **Macronutriments - par 100g/100ml (`_R`) + précisions (`_PREC`)**
| Champ PHP | Constante | Description |
| ----------------------------------------------------------- | ------------- | -------------------------- |
| `matGrassReference` / `matGrassReferencePrec` | `MAT_GRASS_R` | Matières grasses / 100g |
| `acideGrasSatureReference` / `acideGrasSatureReferencePrec` | `AGS_R` | Acides gras saturés / 100g |
| `glucidesReference` / `glucidesReferencePrec` | `GLUCIDES_R` | Glucides / 100g |
| `sucreReference` / `sucreReferencePrec` | `SUCRE_R` | Sucres / 100g |
| `fibAlimReference` / `fibAlimReferencePrec` | `FIB_ALIM_R` | Fibres alimentaires / 100g |
| `proteineReference` / `proteineReferencePrec` | `PROTEINE_R` | Protéines / 100g |
| `selReference` / `selReferencePrec` | `SEL_R` | Sel / 100g |
| `sodiumReference` | `SODIUM_R` | Sodium / 100g |
---
### 4. **Fruits, légumes, noix - par 100g/100ml (`_R`)**
| Champ PHP | Constante | Description |
| -------------------------- | --------------------- | ------------------------------- |
| `fruitsReference` | `FRUITS_R` | Teneur en fruits / 100g |
| `fruitsCoqueSechReference` | `FRUITS_COQUE_SECH_R` | Fruits à coque et séchés / 100g |
| `pourcentFruits` | `POURCENT_FRUITS` | % fruits (global) |
---
### 5. **Valeurs nutritionnelles - par portion (`_P`) + précisions (`_PREC`)**
| Champ PHP | Constante | Description |
| ------------------------------------------------------- | --------------------- | ---------------------------------- |
| `taillePortion` | `TAILLE_PORT` | Taille de la portion |
| `valEnergKjPortion` | `VAL_ENERG_KJ_P` | Énergie kJ / portion |
| `valEnergKcalPortion` | `VAL_ENERG_KCAL_P` | Énergie kcal / portion |
| `matGrassPortion` / `matGrassPortionPrec` | `MAT_GRASS_P` | Matières grasses / portion |
| `acideGrasSaturePortion` / `acideGrasSaturePortionPrec` | `AGS_P` | Acides gras saturés / portion |
| `glucidesPortion` / `glucidesPortionPrec` | `GLUCIDES_P` | Glucides / portion |
| `sucrePortion` / `sucrePortionPrec` | `SUCRE_P` | Sucres / portion |
| `fibAlimPortion` / `fibAlimPortionPrec` | `FIB_ALIM_P` | Fibres / portion |
| `proteinePortion` / `proteinePortionPrec` | `PROTEINE_P` | Protéines / portion |
| `sodiumPortion` | `SODIUM_P` | Sodium / portion |
| `selPortion` / `selPortionPrec` | `SEL_P` | Sel / portion |
| `fruitsPortion` | `FRUITS_P` | Fruits / portion |
| `fruitsCoqueSechPortion` | `FRUITS_COQUE_SECH_P` | Fruits à coque et séchés / portion |
---
### 6. **Pourcentages des apports de référence (`POURCENT_APPORT_REF_*`)**
| Champ PHP | Constante | Description |
| -------------------------- | ------------------------------ | -------------------------------- |
| `pourcentApportRefE14P` | `POURCENT_APPORT_REF_E14_P` | % AR énergie E14 / portion |
| `pourcentApportRefKjoP` | `POURCENT_APPORT_REF_KJO_P` | % AR énergie kJ / portion |
| `pourcentApportRefFatP` | `POURCENT_APPORT_REF_FAT_P` | % AR matières grasses / portion |
| `pourcentApportRefFatsatP` | `POURCENT_APPORT_REF_FATSAT_P` | % AR graisses saturées / portion |
| `pourcentApportRefChovalP` | `POURCENT_APPORT_REF_CHOVAL_P` | % AR glucides / portion |
| `pourcentApportRefSugarP` | `POURCENT_APPORT_REF_SUGAR_P` | % AR sucres / portion |
| `pourcentApportRefProP` | `POURCENT_APPORT_REF_PRO_P` | % AR protéines / portion |
| `pourcentApportRefSalteqP` | `POURCENT_APPORT_REF_SALTEQ_P` | % AR sel / portion |
---
### 7. **Nutri-Score**
| Champ PHP | Constante | Description |
| ----------------- | ------------------- | ---------------------------------------------------- |
| `composanteN` | `COMPOSANTE_N` | Composante négative (énergie, graisses, sucres, sel) |
| `composanteN2022` | `COMPOSANTE_N_2022` | Composante négative - algorithme 2022 |
| `composanteP` | `COMPOSANTE_P` | Composante positive (fibres, protéines, fruits) |
| `composanteP2022` | `COMPOSANTE_P_2022` | Composante positive - algorithme 2022 |
| `scoreNutri` | `SCORE_NUTRI` | Score Nutri-Score brut |
| `scoreNutri2022` | `SCORE_NUTRI_2022` | Score Nutri-Score 2022 |
| `classement` | `CLASSEMENT` | Lettre Nutri-Score (A–E) |
| `nutriScore2022` | `NUTRI_SCORE_2022` | Nutri-Score lettre - algorithme 2022 |
| `nutriAArt` | `NUTRI_A_ART` | Flag article Nutri-Score A |
---
### 8. **Points de calcul du Nutri-Score**
| Champ PHP | Constante | Description |
| ------------------------------ | ------------------ | -------------------------------- |
| `pointsEnergie` | `POINTS_ENERGIE` | Points énergie |
| `pointsAcideGrasSature` | `POINTS_AGS` | Points acides gras saturés |
| `pointsSucres` | `POINTS_SUCRES` | Points sucres |
| `pointsSel` | `POINTS_SEL` | Points sel |
| `pointsFibres` | `POINTS_FIBRES` | Points fibres |
| `pointsProteines` | `POINTS_PROTEINES` | Points protéines |
| `pointsFruitsLegumesNoixFrais` | `POINTS_FNL_FRAIS` | Points fruits/noix/légumes frais |
---
### 9. **FNL (Fruits, Noix, Légumes)**
| Champ PHP | Constante | Description |
| -------------------------------- | -------------------- | -------------------------- |
| `fruitLegumeNoixFrais` | `FNL_FRAIS` | Teneur FNL frais / 100g |
| `fruitLegumeNoixFraisPortion` | `FNL_FRAIS_PORTION` | Teneur FNL frais / portion |
| `pourcentFruitsLegumesNoixFrais` | `POURCENT_FNL_FRAIS` | % FNL frais |
---
### 10. **Ratio / Indicateurs complémentaires**
| Champ PHP | Constante | Description |
| ------------- | -------------- | ------------------------------------------- |
| `pSurL` | `P_SUR_L` | Ratio P/L (protéines sur lipides) |
| `viandeRouge` | `VIANDE_ROUGE` | Flag viande rouge (impact Nutri-Score 2022) |
---
### 11. **Micronutriments détaillés (`NUT_*`)**
Cette famille regroupe les vitamines, minéraux, acides aminés et acides gras détaillés - typiquement issus de bases comme **Ciqual** ou **FoodData Central**.
#### 11a. Minéraux & Oligo-éléments
| Champ PHP | Constante |
| ---------- | ---------------------- |
| `nutCa` | `NUT_CA` - Calcium |
| `nutMg` | `NUT_MG` - Magnésium |
| `nutK` | `NUT_K` - Potassium |
| `nutP` | `NUT_P` - Phosphore |
| `nutCld` | `NUT_CLD` - Chlorure |
| `nutFe` | `NUT_FE` - Fer |
| `nutZn` | `NUT_ZN` - Zinc |
| `nutCu` | `NUT_CU` - Cuivre |
| `nutMn` | `NUT_MN` - Manganèse |
| `nutSe` | `NUT_SE` - Sélénium |
| `nutId` | `NUT_ID` - Iode |
| `nutCr` | `NUT_CR` - Chrome |
| `nutMo` | `NUT_MO` - Molybdène |
| `nutS6` | `NUT_S6` - Soufre |
| `nutNitra` | `NUT_NITRA` - Nitrates |
#### 11b. Vitamines
| Champ PHP | Constante |
| ----------- | ---------------------------------------- |
| `nutVita` | `NUT_VITA` - Vitamine A |
| `nutVitb6` | `NUT_VITB6` - Vitamine B6 |
| `nutVitb12` | `NUT_VITB12` - Vitamine B12 |
| `nutVitc` | `NUT_VITC` - Vitamine C |
| `nutVitd` | `NUT_VITD` - Vitamine D |
| `nutVite` | `NUT_VITE` - Vitamine E |
| `nutVitk` | `NUT_VITK` - Vitamine K |
| `nutChocal` | `NUT_CHOCAL` - Cholécalciférol (vit. D3) |
| `nutNia` | `NUT_NIA` - Niacine (B3) |
| `nutRibf` | `NUT_RIBF` - Riboflavine (B2) |
| `nutThia` | `NUT_THIA` - Thiamine (B1) |
| `nutPantac` | `NUT_PANTAC` - Acide pantothénique (B5) |
| `nutBiot` | `NUT_BIOT` - Biotine (B8) |
| `nutFoldfe` | `NUT_FOLDFE` - Folates équivalents (B9) |
#### 11c. Glucides détaillés
| Champ PHP | Constante |
| ------------ | ----------------------------------------- |
| `nutStarch` | `NUT_STARCH` - Amidon |
| `nutMaltdex` | `NUT_MALTDEX` - Maltodextrines |
| `nutSucs` | `NUT_SUCS` - Saccharose |
| `nutGlus` | `NUT_GLUS` - Glucose |
| `nutLacs` | `NUT_LACS` - Lactose |
| `nutMals` | `NUT_MALS` - Maltose |
| `nutGalfb` | `NUT_GALFB` - Galactose |
| `nutGHc` | `NUT_G_HC` - Glucides hydrates de carbone |
| `nutFrufb` | `NUT_FRUFB` - Fructose lié (fibre) |
| `nutFrus` | `NUT_FRUS` - Fructose libre |
| `nutOlsac` | `NUT_OLSAC` - Oligosaccharides |
| `nutPolyl` | `NUT_POLYL` - Polyols |
| `nutFibsol` | `NUT_FIBSOL` - Fibres solubles |
| `nutInotl` | `NUT_INOTL` - Inositol |
#### 11d. Lipides / Acides gras détaillés
> Nomenclature lipidique standard (IUPAC / Ciqual) - `FXXdY` = chaîne carbonée XX, Y insaturations
| Champ PHP | Constante | Nom usuel |
| ----------------------- | ------------------------ | ----------------------------------- |
| `nutAgt` | `NUT_AGT` | Acides gras trans |
| `nutChol` | `NUT_CHOL` | Cholestérol |
| `nutFd` | `NUT_FD` | Lipides totaux |
| `nutFpalm` | `NUT_FPALM` | Palmitoleïque (C16:1) |
| `nutF16d0` | `NUT_F16D0` | Acide palmitique (C16:0) |
| `nutFsteariq` | `NUT_FSTEARIQ` | Acide stéarique (C18:0) |
| `nutFoleiq` | `NUT_FOLEIQ` | Acide oléique (C18:1, ω-9) |
| `nutF18d` | `NUT_F18D` | C18 insaturé (générique) |
| `nutF18d2cn6` | `NUT_F18D2CN6` | Acide linoléique (C18:2, ω-6) |
| `nutF18d3n3` | `NUT_F18D3N3` | Acide α-linolénique (C18:3, ω-3) |
| `nutF20d4` | `NUT_F20D4` | Acide arachidonique (C20:4) |
| `nutF20d5n3` | `NUT_F20D5N3` | EPA (C20:5, ω-3) |
| `nutF22d6n3` | `NUT_F22D6N3` | DHA (C22:6, ω-3) |
| `nutF11eico` | `NUT_F11EICO` | Acide gondoïque (C20:1) |
| `nutFarachidiq` | `NUT_FARACHIDIQ` | Acide arachidique (C20:0) |
| `nutFeruciq` | `NUT_FERUCIQ` | Acide érucique (C22:1) |
| `nutFlauriq` | `NUT_FLAURIQ` | Acide laurique (C12:0) |
| `nutFmyristiq` | `NUT_FMYRISTIQ` | Acide myristique (C14:0) |
| `nutFbutyriq` | `NUT_FBUTYRIQ` | Acide butyrique (C4:0) |
| `nutFcaproiq` | `NUT_FCAPROIQ` | Acide caproïque (C6:0) |
| `nutFcapryliq` | `NUT_FCAPRYLIQ` | Acide caprylique (C8:0) |
| `nutFcapriq` | `NUT_FCAPRIQ` | Acide caprique (C10:0) |
| `nutFapun3` | `NUT_FAPUN3` | AG polyinsaturés ω-3 |
| `nutFapun6` | `NUT_FAPUN6` | AG polyinsaturés ω-6 |
| `nutFapun9` | `NUT_FAPUN9` | AG polyinsaturés ω-9 |
| `nutFapucis` | `NUT_FAPUCIS` | AG polyinsaturés cis |
| `nutFapulc` | `NUT_FAPULC` | AG polyinsaturés longue chaîne |
| `nutFamscis` | `NUT_FAMSCIS` | AG monoinsaturés cis |
| `nutFacetiq` | `NUT_FACETIQ` | Acide acétique (C2:0) |
| `nutFpropioniq` | `NUT_FPROPIONIQ` | Acide propionique (C3:0) |
| `nutFvaleriq` | `NUT_FVALERIQ` | Acide valérique (C5:0) |
| `nutFcarboceriq` | `NUT_FCARBOCERIQ` | Acide carbocérique (C26:0) |
| `nutFbeheniq` | `NUT_FBEHENIQ` | Acide béhénique (C22:0) |
| `nutFlignoceriq` | `NUT_FLIGNOCERIQ` | Acide lignocérique (C24:0) |
| `nutFnervoniq` | `NUT_FNERVONIQ` | Acide nervonique (C24:1) |
| `nutFlaceroiq` | `NUT_FLACEROIQ` | Acide lacéroïque (C32:0) |
| `nutFmelissiq` | `NUT_FMELISSIQ` | Acide mélissique (C30:0) |
| `nutFmontaniq` | `NUT_FMONTANIQ` | Acide montanique (C28:0) |
| `nutFcerotiq` | `NUT_FCEROTIQ` | Acide cérotique (C26:0 alt.) |
| `nutFpsylliq` | `NUT_FPSYLLIQ` | Acide psyllique |
| `nutFgeddiq` | `NUT_FGEDDIQ` | Acide geddique (C20:1) |
| `nutFmargariq` | `NUT_FMARGARIQ` | Acide margarique (C17:0) |
| `nutFenatiq` | `NUT_FENATIQ` | Acide énanthique (C7:0) |
| `nutFformiq` | `NUT_FFORMIQ` | Acide formique (C1:0) |
| `nutFhyeniq` | `NUT_FHYENIQ` | Acide hyénique |
| `nutFrufb` | `NUT_FRUFB` | *(déjà classé glucides)* |
| `nutFrus` | `NUT_FRUS` | *(déjà classé glucides)* |
| `nutFpelargoniq` | `NUT_FPELARGONIQ` | Acide pélargonique (C9:0) |
| `nutFundecyliq` | `NUT_FUNDECYLIQ` | Acide undécylique (C11:0) |
| `nutFpentadecyliq` | `NUT_FPENTADECYLIQ` | Acide pentadécylique (C15:0) |
| `nutFtridecyliq` | `NUT_FTRIDECYLIQ` | Acide tridécylique (C13:0) |
| `nutFtricosiliq` | `NUT_FTRICOSILIQ` | Acide tétracosanoïque (C23:0) |
| `nutFnonacosyliq` | `NUT_FNONACOSYLIQ` | Acide nonacosylique (C29:0) |
| `nutFnonadylique` | `NUT_FNONADYLIQUE` | Acide nonadylique |
| `nutFheneicosyliq` | `NUT_FHENEICOSYLIQ` | Acide héneicosylique (C21:0) |
| `nutFhentriacontyliq` | `NUT_FHENTRIACONTYLIQ` | C31:0 |
| `nutFheptatriacontyliq` | `NUT_FHEPTATRIACONTYLIQ` | C37:0 |
| `nutFhextriacontyliq` | `NUT_FHEXTRIACONTYLIQ` | C36:0 |
| `nutFoctatriacontyliq` | `NUT_FOCTATRIACONTYLIQ` | C38:0 |
| `nutF19d` | `NUT_F19D` | C19 insaturé |
| `nutFoldfe` | `NUT_FOLDFE` | *(déjà classé vitamines - folates)* |
#### 11e. Acides aminés & protéines spécifiques
| Champ PHP | Constante | Description |
| --------- | ---------- | -------------------------------- |
| `nutAae` | `NUT_AAE` | Acides aminés essentiels (total) |
| `nutCasn` | `NUT_CASN` | Caséines |
| `nutWhey` | `NUT_WHEY` | Protéines de lactosérum |
#### 11f. Autres composés bioactifs / spéciaux
| Champ PHP | Constante | Description |
| --------------- | ---------------- | ----------- |
| `nutCholn` | `NUT_CHOLN` | Choline |
| `nutCarnitine` | `NUT_CARNITINE` | Carnitine |
| `nutTau` | `NUT_TAU` | Taurine |
| `nutNucleotide` | `NUT_NUCLEOTIDE` | Nucléotides |
---
## ⚠️ Points d'attention
1. **Doublon détecté** : `'acideGrasSaturePortion' => 'AGS_P'` est déclaré **deux fois** - l'une des deux entrées sera silencieusement ignorée par PHP.
2. **Champs `_PREC`** : Les suffixes `_PREC` semblent indiquer la **précision de mesure** (ex. `<`, `~`, tracé) - à documenter explicitement.
3. **Champs MISSING** : Nombreux champs présents dans le référentiel INCO mais absents du mapping - notamment toute la série `POURCENT_APPORT_REF_*_R` (apports de référence pour 100g) et certains AG comme `FATSAT_R`, `CHOVAL_R`, `SUGAR_R`.
4. **`classement` / `nutriscore`** : Vous notez vous-même que `CLASSEMENT` ne devrait pas être dans `INCO_COMPO` - à externaliser dans un objet Nutri-Score dédié.
Reference in a new issue View git blame Copy permalink