反馈与预览

操作反馈

CadFlow 使用不可变记录保存机器可读的操作证据：

类型	关键字段	作用
Diagnostic	severity、code、message、hint、data	一个可操作问题
OperationReport	operation、status、output、diagnostics、parameters	完整操作证据
OperationResult	shape、report	返回值与证据组合

OperationResult.value 是 shape 的别名，因此同一容器也可返回标量、映射或几何。控制流使用 report.ok，进入 JSON 边界时使用 report.to_dict()。

result = model.apply("box", 10.0, 20.0, 3.0)
payload = result.report.to_dict()
if result.report.ok:
    body = result.value

Diagnostic 有明确顺序。报告失败时应保留完整元组；即使没有异常，某条 Warning 也可能解释后续证据为何发生降级。

预览网格缓冲区

Shape.preview_mesh_buffer() 向原生运行时请求紧凑二进制缓冲区。parse_preview_mesh_buffer 验证 Header，并返回 PreviewMeshBuffer，其中包含数量、边界和 positions、normals、indices 的零复制 MemoryView。

from cadflow.preview import parse_preview_mesh_buffer, preview_mesh_buffer_to_glb

raw = body.preview_mesh_buffer(deflection=0.25)
mesh = parse_preview_mesh_buffer(raw)
assert len(mesh.indices) > 0
glb = preview_mesh_buffer_to_glb(raw)

解析器会拒绝缓冲区截断、Magic/Version 无效、索引格式不支持和长度不一致。使用 MemoryView 期间必须保持原始 data 字节存活。

GLB 转换

preview_mesh_buffer_to_glb 把经过验证的数组封装为单个二进制 glTF 产物。它只转换格式，不改变底层三角网格精度；精度应在生成原生缓冲区时通过 deflection 选择。

预览输出用于浏览器显示和审阅，不是精确几何交换格式。精确交换使用 Shape.export_step()；展示生成预览前应验证三角形数量与边界。