Lot 1, séquence A2 — Produits, attributs, recettes et packs

1er octobre 2026. Mise en œuvre de la séquence A2 du plan du Lot 1. Décisions : EC-054 (recettes complètes), EC-063 à EC-065.

En bref

• Les facteurs, leurs valeurs et les unités sont des données globales, en lecture seule pour l’API, chargées par le noyau et par les packs.
• Les produits, leurs attributs et les recettes appartiennent à chaque organisation : ils sont créés depuis un pack publié, puis modifiables.
• Un pack est un fichier JSON versionné (packs/fruits/1.0.0.json). Il est publié par un script, refusé s’il est incohérent, puis chargé dans une organisation.
• Le stock reste en grammes ; l’unité (g, kg, t) ne sert qu’à la saisie et à l’affichage (EC-030).

Données

Table	Portée	Contenu
app.facteur	Globale	Les huit facteurs de PC-02, avec leur nature (liste, classes) et leur source (noyau, pack, dynamique)
app.facteur_valeur	Globale, ajout seul	Valeurs permises : pluvial et irrigue (noyau), puis celles des packs (pays, type de sol, opération)
app.unite	Globale	g, kg, t avec leur nombre de grammes
app.produit	Organisation	Code (segment du numéro officiel, EC-063), noms fr et en, unité, matière première liée, modèle et version de pack d’origine
app.attribut	Organisation	Attribut typé d’un produit : JSON Schema de la valeur, obligatoire ou non
app.recette, app.recette_ligne	Organisation	Opération, entrées, une sortie principale, coproduits (RG-055)

app.mouvement_ligne.produit_id référence désormais app.produit : un mouvement ne porte que sur un produit connu de son organisation.

Le rendement de référence n’est pas dans la base : la recette porte cle_rendement (par défaut rendement.reference), et la valeur se résout avec le contexte de l’opération (PC-04, resoudre de packages/domain).

Format d’un pack

Clé	Contenu
code, version, libelle	Identité, version x.y.z, libellé fr et en (EX-074)
facteurs	Valeurs ajoutées aux facteurs de source pack : pays, region, type_sol, operation
produits	Code, noms, unité, matière première liée, attributs (code, libellés, schema JSON Schema, obligatoire, ordre)
recettes	Code, libellés, operation, entrees, sortie, coproduits
parametres	Jeux de règles (rendement de référence, tolérances) : format de la page « Paramètres contextuels » §3. Une valeur nulle dit « pas de référence » (EC-007)
classes	Classes des facteurs numériques (PC-03)

Schéma : ContenuPack dans packages/schemas/src/pack.ts.

Publication

pnpm --filter @biotrace/api packs:publier ../../packs/fruits/1.0.0.json, avec la connexion du rôle des migrations (DATABASE_URL) : l’API n’a aucun droit d’écriture sur les packs.

Refus (pack_invalide, avec le détail), dans cet ordre, sans rien écrire :

1. forme du JSON (Ajv) ;
2. JSON Schema d’un attribut non compilable (mode strict) ;
3. unité inconnue ;
4. cohérence, par packs.validerPack de packages/domain : facteur absent du catalogue (PC-02), valeur de facteur hors catalogue, facteur qu’un pack n’a pas le droit d’étendre, code en double, produit inconnu, matière première invalide, recette sans entrée ou qui consomme ce qu’elle produit, classes qui ne se suivent pas, règles ambiguës (PC-06).

Republier le même contenu ne change rien (deja_publiee). Un contenu différent pour une version déjà publiée est refusé (version_existante) : une version publiée est figée (SB-10).

Chargement dans une organisation

chargerPack(db, organisation_id, pack_version_id) crée les produits, les attributs et les recettes de l’organisation, avec le rôle de l’API (RLS). Il est rejouable : un modèle déjà chargé n’est ni recréé ni écrasé. Il refuse une version inconnue ou en brouillon, et un code de produit déjà pris par un produit créé à la main : dans ce cas rien n’est chargé. Son branchement sur la création d’une organisation (page « Keycloak multi-clients » §8.1, étape 5) reste à faire.

Attributs : une seule fonction, deux usages

validerAttributs(definitions, valeurs) (packages/schemas, Ajv) contrôle les valeurs saisies pour un produit : chaque valeur son schéma, les attributs obligatoires présents, aucun attribut inconnu. Le formulaire généré l’appelle côté client ; le serveur l’appelle à la réception, avec les app.attribut du produit (validerAttributsDuProduit).

Pack fruits 1.0.0

Produits ANA (ananas frais) et ANS (ananas séché), attributs calibre et brix_dixiemes (bornes à valider, EC-064), recette de séchage, pays TG et BJ, types de sol de PC, et un jeu rendement.reference réduit à sa règle par défaut nulle : aucun rendement n’est calibré (EC-007). Vecteurs : testdata/packs/fruits/resolution/.

Hors séance

Routes REST des référentiels (écrans B3), règles PowerSync et publication des nouvelles tables (A9), branchement du chargement sur la création d’organisation.