Referencia de esquema

El documento Factory MBOM está versionado mediante una cadena schema de nivel superior. La versión actual es scalarcut.factory_bom.v1.1. Trata el campo schema como el contrato: si cambia una constante o el significado de un campo, la versión se incrementa.

Este esquema describe MBOMs reales de proyectos: el documento que descarga el botón Factory MBOM del planificador y que devuelve la API para los proyectos propios de una empresa. La muestra pública del garaje usada en la documentación y en el panel Try MBOM API se ajusta a la misma versión scalarcut.factory_bom.v1.1.

Dos unidades, una verdad

La rejilla interna del planificador está en metros, pero el documento exportado está en milímetros:

• Los tamaños de corte y los campos de exportación son milímetros enteros (round(m × 1000)).
• El documento indica unit_system: "metric" y lattice_unit: "mm".
• Los tamaños canónicos de pieza son siempre w_mm / h_mm.
• La visualización en pulgadas/pies del planificador convierte desde la rejilla en milímetros y nunca se vuelve a escribir en las claves de corte. Esta exportación no emite columnas en pulgadas.

Cabecera del documento

Campo	Significado
schema	scalarcut.factory_bom.v1.1
scene_id	Id de escena del planificador, o null si no se ha guardado
project_id	Igual que scene_id en esta ronda (una escena de alicatado = una clave ERP)
title	Etiqueta visible de la escena
unit_system / lattice_unit / unit_policy	metric / mm / cadena de política
rates	Constantes de consumibles congeladas (abajo)
totals	Resumen de la habitación entre superficies
surfaces / pieces / recipes	BOM por superficie, lista de cortes y recetas CRE

Piezas

Una pieza describe un grupo de corte: un tamaño repetido qty veces. Campos clave:

Campo	Significado
surface_id	wall-a … wall-d, o floor
letter	Letra de leyenda que coincide con la lista de cortes del PDF (A, B, …)
group_id	Id de grupo estable derivado de ubicación + tamaño
sku	SKU del catálogo, o vacío en el planificador propio
w_mm / h_mm	Tamaño canónico en milímetros
cut_type	La clase de corte de esta pieza
qty	Número de piezas idénticas
fragile	True cuando el corte está por debajo del umbral de fragilidad de 50 mm
cre_recycled	True cuando la pieza es reciclada por el Cut Recycling Engine
cre_parent	Clave del tamaño de baldosa de origen (tileW×tileH mm) al reciclar, si no vacío
is_l_cut	True para cortes en forma de L

Tipos de corte

cut_type clasifica cómo se produce la pieza. Un integrador puede condicionar el comportamiento de la mesa de corte a este campo. Las piezas frágiles se marcan por separado para poder enviarlas a manipulación especial en lugar de dejarlas caer en una máquina que las rompería.

Cortes en L

Las piezas en forma de L se marcan con is_l_cut y llevan las dimensiones de sus brazos en la geometría de la pieza. El anidado CRE sigue tratando cada pieza como su rectángulo delimitador w_mm × h_mm.

Polígono de sobrante opcional (geometry)

Una pieza puede incluir un objeto geometry aditivo:

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

• frame son milímetros alineados a la pared, desplazados de modo que el mínimo del AABB de la baldosa nominal sin recortar sea (0, 0).
• Presente cuando el sobrante es un único anillo convexo/simple (un fragmento diagonal a 45° o de espiga, o un sobrante rectangular alineado a los ejes).
• Omitido para cortes en L, sobrantes multifragmento y grupos de cantidad cuyos miembros no comparten el mismo anillo.
• No es una trayectoria CNC y no introduce ángulos de hoja arbitrarios: CRE sigue anidando rectángulos w_mm × h_mm.
• Los campos desconocidos son aditivos: un ERP que ignore geometry conserva w_mm / h_mm / cut_type / is_l_cut.

Redondeo de cajas y embalaje

Cuando se conoce el total de piezas (totalPieces):

1. orderPieces = ceil(totalPieces × (1 + wastage) − 1e-12)
2. Con una cantidad de embalaje (pack_qty, baldosas por caja) de 1 o más:
   • fullBoxes = floor(orderPieces / pack_qty)
   • looseTiles = orderPieces % pack_qty
   • boxes_to_order = fullBoxes: las baldosas sobrantes no se redondean a una caja extra.
   • pack_mode = "full_boxes_plus_loose"
3. Sin cantidad de embalaje: pack_mode = "pack_unset", boxes_to_order = null; la línea de baldosas sigue siendo orderPieces.

Cuando totalPieces es desconocido: pack_mode = "area_ceil_boxes", boxes_to_order = ceil(grossTileAreaSqm / sqmPerBox − 1e-12).

Campos de embalaje de superficie: pack_qty, pack_mode, order_pieces, full_boxes, loose_tiles, boxes_to_order y el alias obsoleto boxes (igual a boxes_to_order).

Consumibles (tarifas congeladas)

Los consumibles se emiten como una versión de fórmula rates y como kg/L por superficie y en totals. Estas constantes están congeladas con el esquema; si cambian entre compilaciones, el contrato ha cambiado y el esquema se incrementa.

Constante	Valor	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	masa de lechada CAD
grout_compaction_factor	1.05	masa de lechada CAD

La masa de lechada se calcula a partir de la geometría del patrón con densidad × compactación. El redondeo de visualización (pasos 0.1) es solo para las hojas legibles por humanos; el JSON de fábrica guarda el valor del motor antes del redondeo de visualización.

Resumen de totales

totals suma los campos del BOM de las superficies, más:

• cut_qty: suma de qty de las piezas (debe coincidir con la cabecera de la lista de cortes del plano al auditar).
• boxes_to_order (y el obsoleto boxes): suma de los conteos de cajas por superficie donde estén establecidos.

Identificadores estables

• Superficies: wall-a, wall-b, wall-c, wall-d, floor.
• Grupos de corte: group_id a partir de la clave de ubicación + tamaño (w×h mm o clave de brazo L).
• Letras de leyenda: A, B, … según el orden del array de grupos, idéntico a la lista de cortes del PDF.

La misma rejilla siempre produce los mismos group_id y letras al reexportar.

SKU

• Se permite un sku vacío en el planificador propio (demo, sin catálogo).
• Un embed de catálogo/widget debe rellenar sku para una alimentación de fábrica real.
• Un SKU vacío no bloquea la exportación.

Lista de piezas CSV

El CSV es solo la lista de piezas (mismas columnas que v1). Embalaje, ids, tarifas, totales y la geometry opcional viven en el JSON.

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