Справочник схемы

Документ Factory MBOM версионируется строкой schema верхнего уровня. Текущая версия — scalarcut.factory_bom.v1.1. Относитесь к полю schema как к контракту: если меняется константа или смысл поля, версия повышается.

Эта схема описывает реальные MBOM проектов — документ, который скачивает кнопка Factory MBOM в планировщике и который возвращает API для собственных проектов предприятия. Публичный образец «гаража», используемый в документации и панели Try MBOM API, соответствует той же версии scalarcut.factory_bom.v1.1.

Двойные единицы, одна истина

Внутренняя решётка планировщика — в метрах, но экспортируемый документ — в миллиметрах:

• Размеры резов и поля экспорта — целые миллиметры (round(m × 1000)).
• Документ указывает unit_system: "metric" и lattice_unit: "mm".
• Канонические размеры деталей — всегда w_mm / h_mm.
• Отображение в дюймах/футах в планировщике конвертируется из миллиметровой решётки и никогда не записывается обратно в ключи резов. Этот экспорт не содержит колонок в дюймах.

Заголовок документа

Поле	Смысл
schema	scalarcut.factory_bom.v1.1
scene_id	Идентификатор сцены планировщика или null, если не сохранено
project_id	В этом цикле то же, что и scene_id (одна сцена раскладки = один ключ ERP)
title	Отображаемая подпись сцены
unit_system / lattice_unit / unit_policy	metric / mm / строка политики
rates	Зафиксированные константы расходных материалов (ниже)
totals	Сводка по помещению по всем поверхностям
surfaces / pieces / recipes	Ведомость по поверхности, карта резов и рецепты CRE

Детали

Деталь описывает группу реза — размер, повторённый qty раз. Ключевые поля:

Поле	Смысл
surface_id	wall-a … wall-d или floor
letter	Буква легенды, совпадающая с картой резов PDF (A, B, …)
group_id	Стабильный идентификатор группы, вычисленный из расположения + размера
sku	Артикул каталога или пусто в собственном планировщике
w_mm / h_mm	Канонический размер в миллиметрах
cut_type	Класс реза для этой детали
qty	Количество одинаковых деталей
fragile	True, когда рез ниже порога хрупкости 50 мм
cre_recycled	True, когда деталь переработана Cut Recycling Engine
cre_parent	Ключ размера исходной плитки (tileW×tileH мм) при переработке, иначе пусто
is_l_cut	True для L-образных резов

Типы резов

cut_type классифицирует, как производится деталь. Интегратор может завязать на него поведение раскроечного стола. Хрупкие детали помечаются отдельно, чтобы их можно было направить на особую обработку, а не отдать машине, которая их расколет.

L-резы

L-образные детали помечаются is_l_cut и несут размеры плеч в геометрии детали. Вложение CRE по-прежнему рассматривает каждую деталь как её ограничивающий прямоугольник w_mm × h_mm.

Дополнительный полигон остатка (geometry)

Деталь может содержать аддитивный объект geometry:

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

• frame — это миллиметры, выровненные по стене и сдвинутые так, чтобы минимум AABB номинальной необрезанной плитки был (0, 0).
• Присутствует, когда остаток — одно выпуклое/простое кольцо (фрагмент диагонали 45° или «ёлочки» либо прямоугольный остаток по осям).
• Опускается для L-резов, многофрагментных остатков и групп с количеством, члены которых не делят одно кольцо.
• Это не траектория ЧПУ и не вводит произвольные углы лезвия — CRE по-прежнему вкладывает прямоугольники w_mm × h_mm.
• Неизвестные поля аддитивны: ERP, игнорирующая geometry, сохраняет w_mm / h_mm / cut_type / is_l_cut.

Округление коробок и упаковки

Когда известно общее количество деталей (totalPieces):

1. orderPieces = ceil(totalPieces × (1 + wastage) − 1e-12)
2. При количестве в упаковке (pack_qty, плиток в коробке) от 1 и выше:
   • fullBoxes = floor(orderPieces / pack_qty)
   • looseTiles = orderPieces % pack_qty
   • boxes_to_order = fullBoxes — остатки плиток не округляются в лишнюю коробку.
   • pack_mode = "full_boxes_plus_loose"
3. Без количества в упаковке: pack_mode = "pack_unset", boxes_to_order = null; строка плитки всё равно равна orderPieces.

Когда totalPieces неизвестно: pack_mode = "area_ceil_boxes", boxes_to_order = ceil(grossTileAreaSqm / sqmPerBox − 1e-12).

Поля упаковки поверхности: pack_qty, pack_mode, order_pieces, full_boxes, loose_tiles, boxes_to_order и устаревший псевдоним boxes (равен boxes_to_order).

Расходные материалы (зафиксированные нормы)

Расходные материалы выдаются как версия формулы rates и как кг/л по поверхности и в totals. Эти константы зафиксированы вместе со схемой; если они меняются между сборками, контракт изменился и схема повышается.

Константа	Значение	Использование
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	масса затирки CAD
grout_compaction_factor	1.05	масса затирки CAD

Масса затирки вычисляется из геометрии узора с учётом плотности × уплотнения. Округление для отображения (шаги 0.1) — только для человекочитаемых листов; заводской JSON хранит значение движка до округления для отображения.

Сводка итогов

totals суммирует поля ведомости по поверхностям, плюс:

• cut_qty — сумма qty деталей (при сверке должна совпадать с заголовком карты резов чертежа).
• boxes_to_order (и устаревший boxes) — сумма количеств коробок по поверхностям, где задано.

Стабильные идентификаторы

• Поверхности: wall-a, wall-b, wall-c, wall-d, floor.
• Группы резов: group_id из ключа расположения + размера (мм w×h или ключ L-плеча).
• Буквы легенды: A, B, … в порядке массива групп, идентично карте резов PDF.

Одна и та же решётка всегда даёт те же group_id и буквы при повторном экспорте.

SKU

• Пустой sku допускается в собственном планировщике (демо, без каталога).
• Встраивание каталога/виджета обязано заполнять sku для живой заводской подачи.
• Пустой SKU не блокирует экспорт.

Список деталей CSV

CSV — это только список деталей (те же колонки, что и v1). Упаковка, идентификаторы, нормы, итоги и дополнительный geometry живут в JSON.

Колонки: surface_id, letter, group_id, sku, w_mm, h_mm, cut_type, qty, fragile, cre_recycled, cre_parent, is_l_cut.