Referência de esquema

O documento Factory MBOM é versionado por uma string schema de nível superior. A versão atual é scalarcut.factory_bom.v1.1. Trate o campo schema como o contrato: se uma constante ou o significado de um campo mudar, a versão é incrementada.

Este esquema descreve MBOMs reais de projetos — o documento baixado pelo botão Factory MBOM do planejador e retornado pela API para os projetos próprios de uma empresa. A amostra pública da garagem usada na documentação e no painel Try MBOM API está em conformidade com a mesma versão scalarcut.factory_bom.v1.1.

Duas unidades, uma verdade

A grade interna do planejador está em metros, mas o documento exportado está em milímetros:

• Os tamanhos de corte e os campos de exportação são milímetros inteiros (round(m × 1000)).
• O documento declara unit_system: "metric" e lattice_unit: "mm".
• Os tamanhos canônicos das peças são sempre w_mm / h_mm.
• A exibição em polegadas/pés no planejador converte a partir da grade em milímetros e nunca é gravada de volta nas chaves de corte. Esta exportação não emite colunas em polegadas.

Cabeçalho do documento

Campo	Significado
schema	scalarcut.factory_bom.v1.1
scene_id	Id da cena do planejador, ou null se não salva
project_id	Igual a scene_id nesta rodada (uma cena de azulejos = uma chave ERP)
title	Rótulo de exibição da cena
unit_system / lattice_unit / unit_policy	metric / mm / string de política
rates	Constantes de consumíveis congeladas (abaixo)
totals	Resumo do ambiente entre superfícies
surfaces / pieces / recipes	BOM por superfície, lista de cortes e receitas CRE

Peças

Uma peça descreve um grupo de corte — um tamanho repetido qty vezes. Campos principais:

Campo	Significado
surface_id	wall-a … wall-d, ou floor
letter	Letra de legenda que corresponde à lista de cortes do PDF (A, B, …)
group_id	Id de grupo estável derivado de localização + tamanho
sku	SKU do catálogo, ou vazio no planejador próprio
w_mm / h_mm	Tamanho canônico em milímetros
cut_type	A classe de corte desta peça
qty	Número de peças idênticas
fragile	True quando o corte está abaixo do limite de fragilidade de 50 mm
cre_recycled	True quando a peça é reciclada pelo Cut Recycling Engine
cre_parent	Chave do tamanho da placa de origem (tileW×tileH mm) quando reciclada, senão vazio
is_l_cut	True para cortes em L

Tipos de corte

cut_type classifica como a peça é produzida. Um integrador pode condicionar o comportamento da mesa de corte a isso. Peças frágeis são marcadas separadamente para poderem ser encaminhadas a um manuseio especial em vez de caírem em uma máquina que as quebraria.

Cortes em L

Peças em forma de L são marcadas com is_l_cut e carregam as dimensões de seus braços na geometria da peça. O aninhamento CRE ainda trata cada peça como seu retângulo delimitador w_mm × h_mm.

Polígono de sobra opcional (geometry)

Uma peça pode incluir um objeto geometry aditivo:

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

• O frame são milímetros alinhados à parede, deslocados para que o mínimo do AABB do azulejo nominal sem cortes seja (0, 0).
• Presente quando a sobra é um único anel convexo/simples (um fragmento diagonal de 45° ou espinha de peixe, ou uma sobra retangular alinhada aos eixos).
• Omitido para cortes em L, sobras multifragmento e grupos de quantidade cujos membros não compartilham o mesmo anel.
• Não é um percurso CNC e não introduz ângulos de lâmina arbitrários — o CRE ainda aninha retângulos w_mm × h_mm.
• Campos desconhecidos são aditivos: um ERP que ignore geometry mantém w_mm / h_mm / cut_type / is_l_cut.

Arredondamento de caixas e embalagem

Quando o total de peças (totalPieces) é conhecido:

1. orderPieces = ceil(totalPieces × (1 + wastage) − 1e-12)
2. Com uma quantidade de embalagem (pack_qty, azulejos por caixa) de 1 ou mais:
   • fullBoxes = floor(orderPieces / pack_qty)
   • looseTiles = orderPieces % pack_qty
   • boxes_to_order = fullBoxes — azulejos restantes não são arredondados para uma caixa extra.
   • pack_mode = "full_boxes_plus_loose"
3. Sem quantidade de embalagem: pack_mode = "pack_unset", boxes_to_order = null; a linha de azulejos continua orderPieces.

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

Campos de embalagem da superfície: pack_qty, pack_mode, order_pieces, full_boxes, loose_tiles, boxes_to_order e o alias obsoleto boxes (igual a boxes_to_order).

Consumíveis (taxas congeladas)

Os consumíveis são emitidos como uma versão de fórmula rates e como kg/L por superfície e em totals. Essas constantes são congeladas com o esquema; se mudarem entre builds, o contrato mudou e o esquema é incrementado.

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	massa de rejunte CAD
grout_compaction_factor	1.05	massa de rejunte CAD

A massa de rejunte é calculada a partir da geometria do padrão com densidade × compactação. O arredondamento de exibição (passos 0.1) é apenas para as folhas legíveis por humanos; o JSON de fábrica armazena o valor do motor antes do arredondamento de exibição.

Resumo de totais

totals soma os campos do BOM das superfícies, mais:

• cut_qty — soma do qty das peças (deve corresponder ao cabeçalho da lista de cortes da planta ao auditar).
• boxes_to_order (e o obsoleto boxes) — soma das contagens de caixas por superfície, onde definidas.

IDs estáveis

• Superfícies: wall-a, wall-b, wall-c, wall-d, floor.
• Grupos de corte: group_id a partir da chave de localização + tamanho (w×h mm ou chave de braço L).
• Letras de legenda: A, B, … na ordem do array de grupos, idêntico à lista de cortes do PDF.

A mesma grade sempre produz os mesmos group_id e letras na reexportação.

SKU

• Um sku vazio é permitido no planejador próprio (demo, sem catálogo).
• Um embed de catálogo/widget deve preencher sku para um feed de fábrica real.
• Um SKU vazio não bloqueia a exportação.

Lista de peças CSV

O CSV é apenas a lista de peças (mesmas colunas da v1). Embalagem, ids, taxas, totais e a geometry opcional vivem no JSON.

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