Riferimento schema

Il documento Factory MBOM è versionato da una stringa schema di primo livello. La versione corrente è scalarcut.factory_bom.v1.1. Tratta il campo schema come il contratto: se cambia una costante o il significato di un campo, la versione viene incrementata.

Questo schema descrive MBOM reali di progetto — il documento scaricato dal pulsante Factory MBOM del pianificatore e restituito dall'API per i progetti propri di un'azienda. Il campione pubblico del garage usato nella documentazione e nel pannello Try MBOM API è conforme alla stessa versione scalarcut.factory_bom.v1.1.

Due unità, una verità

La griglia interna del pianificatore è in metri, ma il documento esportato è in millimetri:

• Le dimensioni di taglio e i campi di export sono millimetri interi (round(m × 1000)).
• Il documento indica unit_system: "metric" e lattice_unit: "mm".
• Le dimensioni canoniche dei pezzi sono sempre w_mm / h_mm.
• La visualizzazione in pollici/piedi del pianificatore converte dalla griglia millimetrica e non viene mai riscritta nelle chiavi di taglio. Questo export non emette colonne in pollici.

Intestazione del documento

Campo	Significato
schema	scalarcut.factory_bom.v1.1
scene_id	Id scena del pianificatore, o null se non salvata
project_id	Uguale a scene_id in questo giro (una scena di piastrellatura = una chiave ERP)
title	Etichetta visualizzata della scena
unit_system / lattice_unit / unit_policy	metric / mm / stringa di policy
rates	Costanti dei consumabili congelate (sotto)
totals	Riepilogo della stanza tra le superfici
surfaces / pieces / recipes	Distinta per superficie, lista di taglio e ricette CRE

Pezzi

Un pezzo descrive un gruppo di taglio — una dimensione ripetuta qty volte. Campi chiave:

Campo	Significato
surface_id	wall-a … wall-d, oppure floor
letter	Lettera di legenda corrispondente alla lista di taglio del PDF (A, B, …)
group_id	Id gruppo stabile derivato da posizione + dimensione
sku	SKU di catalogo, o vuoto sul pianificatore proprietario
w_mm / h_mm	Dimensione canonica in millimetri
cut_type	La classe di taglio di questo pezzo
qty	Numero di pezzi identici
fragile	True quando il taglio è sotto la soglia di fragilità di 50 mm
cre_recycled	True quando il pezzo è riciclato dal Cut Recycling Engine
cre_parent	Chiave dimensione della piastrella di origine (tileW×tileH mm) in caso di riciclo, altrimenti vuota
is_l_cut	True per i tagli a L

Tipi di taglio

cut_type classifica come viene prodotto il pezzo. Un integratore può agganciarvi il comportamento del banco di taglio. I pezzi fragili sono marcati separatamente per poter essere instradati a una lavorazione speciale anziché essere inviati a una macchina che li frantumerebbe.

Tagli a L

I pezzi a forma di L sono marcati con is_l_cut e portano le dimensioni dei bracci nella geometria del pezzo. L'annidamento CRE tratta comunque ogni pezzo come il suo rettangolo di delimitazione w_mm × h_mm.

Poligono di sfrido opzionale (geometry)

Un pezzo può includere un oggetto geometry additivo:

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

• frame è in millimetri allineati alla parete, traslati così che il minimo dell'AABB della piastrella nominale non ritagliata sia (0, 0).
• Presente quando lo sfrido è un singolo anello convesso/semplice (un frammento diagonale a 45° o a spina di pesce, oppure uno sfrido rettangolare allineato agli assi).
• Omesso per tagli a L, sfridi multi-frammento e gruppi di quantità i cui membri non condividono lo stesso anello.
• Non è un percorso utensile CNC e non introduce angoli di lama arbitrari — CRE annida comunque rettangoli w_mm × h_mm.
• I campi sconosciuti sono additivi: un ERP che ignora geometry conserva w_mm / h_mm / cut_type / is_l_cut.

Arrotondamento di scatole e imballo

Quando il totale dei pezzi (totalPieces) è noto:

1. orderPieces = ceil(totalPieces × (1 + wastage) − 1e-12)
2. Con una quantità di imballo (pack_qty, piastrelle per scatola) pari a 1 o più:
   • fullBoxes = floor(orderPieces / pack_qty)
   • looseTiles = orderPieces % pack_qty
   • boxes_to_order = fullBoxes — le piastrelle residue non vengono arrotondate in una scatola extra.
   • pack_mode = "full_boxes_plus_loose"
3. Senza quantità di imballo: pack_mode = "pack_unset", boxes_to_order = null; la riga piastrelle resta orderPieces.

Quando totalPieces è sconosciuto: pack_mode = "area_ceil_boxes", boxes_to_order = ceil(grossTileAreaSqm / sqmPerBox − 1e-12).

Campi di imballo della superficie: pack_qty, pack_mode, order_pieces, full_boxes, loose_tiles, boxes_to_order e l'alias deprecato boxes (uguale a boxes_to_order).

Consumabili (tariffe congelate)

I consumabili sono emessi come versione di formula rates e come kg/L per superficie e nei totals. Queste costanti sono congelate con lo schema; se cambiano tra le build, il contratto è cambiato e lo schema viene incrementato.

Costante	Valore	Uso
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	massa stucco CAD
grout_compaction_factor	1.05	massa stucco CAD

La massa dello stucco è calcolata dalla geometria del motivo con densità × compattazione. L'arrotondamento di visualizzazione (passi 0.1) è solo per i fogli leggibili dall'uomo; il JSON di fabbrica memorizza il valore del motore prima dell'arrotondamento di visualizzazione.

Riepilogo totali

totals somma i campi della distinta delle superfici, più:

• cut_qty — somma delle qty dei pezzi (deve corrispondere all'intestazione della lista di taglio del blueprint al controllo).
• boxes_to_order (e il deprecato boxes) — somma dei conteggi scatole per superficie, dove impostati.

ID stabili

• Superfici: wall-a, wall-b, wall-c, wall-d, floor.
• Gruppi di taglio: group_id da chiave posizione + dimensione (w×h mm o chiave braccio L).
• Lettere di legenda: A, B, … dall'ordine dell'array dei gruppi, identico alla lista di taglio del PDF.

La stessa griglia produce sempre gli stessi group_id e lettere alla riesportazione.

SKU

• Un sku vuoto è consentito sul pianificatore proprietario (demo, senza catalogo).
• Un embed catalogo/widget deve valorizzare sku per un feed di fabbrica reale.
• Una SKU vuota non blocca l'export.

Elenco pezzi CSV

Il CSV è solo l'elenco dei pezzi (stesse colonne della v1). Imballo, id, tariffe, totali e la geometry opzionale vivono nel JSON.

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