Référence de schéma

Le document Factory MBOM est versionné par une chaîne schema de premier niveau. La version actuelle est scalarcut.factory_bom.v1.1. Traitez le champ schema comme le contrat : si une constante ou la signification d'un champ change, la version est incrémentée.

Ce schéma décrit de vrais MBOM de projets — le document téléchargé par le bouton Factory MBOM du planificateur et renvoyé par l'API pour les projets propres d'une entreprise. L'échantillon public du garage utilisé dans la documentation et le panneau Try MBOM API respecte la même version scalarcut.factory_bom.v1.1.

Deux unités, une seule vérité

La grille interne du planificateur est en mètres, mais le document exporté est en millimètres :

• Les tailles de coupe et les champs d'export sont des millimètres entiers (round(m × 1000)).
• Le document indique unit_system: "metric" et lattice_unit: "mm".
• Les tailles canoniques de pièce sont toujours w_mm / h_mm.
• L'affichage en pouces/pieds du planificateur convertit depuis la grille millimétrique et n'est jamais réécrit dans les clés de coupe. Cet export n'émet aucune colonne en pouces.

En-tête du document

Champ	Signification
schema	scalarcut.factory_bom.v1.1
scene_id	Id de scène du planificateur, ou null si non enregistrée
project_id	Identique à scene_id pour l'instant (une scène de carrelage = une clé ERP)
title	Libellé d'affichage de la scène
unit_system / lattice_unit / unit_policy	metric / mm / chaîne de politique
rates	Constantes de consommables figées (ci-dessous)
totals	Cumul de la pièce sur toutes les surfaces
surfaces / pieces / recipes	Nomenclature par surface, liste de découpe et recettes CRE

Pièces

Une pièce décrit un groupe de coupe — une taille répétée qty fois. Champs clés :

Champ	Signification
surface_id	wall-a … wall-d, ou floor
letter	Lettre de légende correspondant à la liste de découpe du PDF (A, B, …)
group_id	Id de groupe stable dérivé de l'emplacement + la taille
sku	SKU du catalogue, ou vide sur le planificateur propre
w_mm / h_mm	Taille canonique en millimètres
cut_type	La classe de coupe de cette pièce
qty	Nombre de pièces identiques
fragile	True quand la coupe est sous le seuil de fragilité de 50 mm
cre_recycled	True quand la pièce est recyclée par le Cut Recycling Engine
cre_parent	Clé de taille du carreau d'origine (tileW×tileH mm) en cas de recyclage, sinon vide
is_l_cut	True pour les coupes en L

Types de coupe

cut_type classe la façon dont la pièce est produite. Un intégrateur peut y lier le comportement de la table de découpe. Les pièces fragiles sont marquées séparément afin de pouvoir être orientées vers un traitement spécial plutôt que d'être envoyées à une machine qui les briserait.

Coupes en L

Les pièces en forme de L sont marquées avec is_l_cut et portent les dimensions de leurs branches dans la géométrie de la pièce. L'imbrication CRE traite toujours chaque pièce comme son rectangle englobant w_mm × h_mm.

Polygone de chute optionnel (geometry)

Une pièce peut inclure un objet geometry additif :

"geometry": {
  "frame": "tile_local_mm",
  "vertices_mm": [[0, 0], [180, 0], [180, 600], [0, 600]]
}

• frame est en millimètres alignés au mur, décalés pour que le minimum de l'AABB du carreau nominal non rogné soit (0, 0).
• Présent quand la chute est un seul anneau convexe/simple (un fragment diagonal à 45° ou en chevrons, ou une chute rectangulaire alignée aux axes).
• Omis pour les coupes en L, les chutes multi-fragments et les groupes de quantité dont les membres ne partagent pas le même anneau.
• Ce n'est pas un parcours CNC et cela n'introduit pas d'angles de lame arbitraires — CRE imbrique toujours des rectangles w_mm × h_mm.
• Les champs inconnus sont additifs : un ERP qui ignore geometry conserve w_mm / h_mm / cut_type / is_l_cut.

Arrondi de cartons et d'emballage

Quand le nombre total de pièces (totalPieces) est connu :

1. orderPieces = ceil(totalPieces × (1 + wastage) − 1e-12)
2. Avec une quantité d'emballage (pack_qty, carreaux par carton) de 1 ou plus :
   • fullBoxes = floor(orderPieces / pack_qty)
   • looseTiles = orderPieces % pack_qty
   • boxes_to_order = fullBoxes — les carreaux restants ne sont pas arrondis en carton supplémentaire.
   • pack_mode = "full_boxes_plus_loose"
3. Sans quantité d'emballage : pack_mode = "pack_unset", boxes_to_order = null ; la ligne de carreaux reste orderPieces.

Quand totalPieces est inconnu : pack_mode = "area_ceil_boxes", boxes_to_order = ceil(grossTileAreaSqm / sqmPerBox − 1e-12).

Champs d'emballage de surface : pack_qty, pack_mode, order_pieces, full_boxes, loose_tiles, boxes_to_order et l'alias obsolète boxes (égal à boxes_to_order).

Consommables (tarifs figés)

Les consommables sont émis comme une version de formule rates et comme kg/L par surface et dans totals. Ces constantes sont figées avec le schéma ; si elles changent entre les builds, le contrat a changé et le schéma est incrémenté.

Constante	Valeur	Utilisation
adhesive_kg_per_sqm	4.5	adhesiveKg = grossTileAreaSqm × 4.5
adhesive_bag_kg	25	adhesiveBags = ceil(adhesiveKg / 25 − 1e-12)
primer_l_per_sqm	0.2	primerL = grossTileAreaSqm × 0.2
grout_density_kg_m3	1200	masse de joint CAD
grout_compaction_factor	1.05	masse de joint CAD

La masse de joint est calculée à partir de la géométrie du motif avec densité × compactage. L'arrondi d'affichage (pas de 0.1) ne concerne que les feuilles lisibles par l'humain ; le JSON d'usine stocke la valeur du moteur avant l'arrondi d'affichage.

Cumul des totaux

totals additionne les champs de nomenclature des surfaces, plus :

• cut_qty — somme des qty de pièces (doit correspondre à l'en-tête de la liste de découpe du plan lors de l'audit).
• boxes_to_order (et boxes obsolète) — somme des comptes de cartons par surface, là où définis.

Identifiants stables

• Surfaces : wall-a, wall-b, wall-c, wall-d, floor.
• Groupes de coupe : group_id à partir de la clé d'emplacement + taille (w×h mm ou clé de branche L).
• Lettres de légende : A, B, … selon l'ordre du tableau de groupes, identique à la liste de découpe du PDF.

La même grille produit toujours les mêmes group_id et lettres à la réexportation.

SKU

• Un sku vide est autorisé sur le planificateur propre (démo, sans catalogue).
• Un embed catalogue/widget doit renseigner sku pour un flux d'usine réel.
• Un SKU vide ne bloque pas l'export.

Liste de pièces CSV

Le CSV est uniquement la liste de pièces (mêmes colonnes que v1). L'emballage, les ids, les tarifs, les totaux et la geometry optionnelle vivent dans le JSON.

Colonnes : surface_id, letter, group_id, sku, w_mm, h_mm, cut_type, qty, fragile, cre_recycled, cre_parent, is_l_cut.