跳到主要内容

约定与契约

公共导入​

常用操作优先从顶层命名空间导入：

import cadflow as cad

with cad.Model() as model:
    body = model.box(40.0, 25.0, 6.0)

需要强调领域归属时使用公共子模块：

from cadflow.flexible import FlexibleMaterial, FlexiblePanel
from cadflow.inspect import brep
from cadflow.scene import SceneCompileOptions, compile_scene

出现在本参考或模块显式导出列表中的路径属于公共 API。cadflow._engine 下的路径是实现细节，可能在没有迁移别名的情况下调整。

所有权与生命周期​

除非构造时传入现有 Session，否则 Model 会持有自己的 NativeSession。每个原生 Shape 同时保存所属 Session 与不透明 Handle。因此：

  • 只在 Session 存活期间使用 Shape；
  • 布尔、距离和接触查询中的多个 Shape 必须来自同一 Session；
  • 不要把 ShapeHandle 当作可持久化的外部标识符；
  • 关闭 Session 前完成几何或结构化元数据导出。

使用外部 Session 构造的 Model 不会在关闭时销毁该 Session，最终关闭责任仍属于调用方。

值与更新语义​

核心 Shape 操作返回新 Handle，不会修改输入几何。多数产品与工程领域记录是不可变 dataclass；更新辅助函数会返回替代值：

assembly = cad.make_assembly_rassembly("fixture")
assembly = cad.add_component_rassembly(assembly, part, component_id="base")

不接收返回值会造成“修改没有生效”的常见问题。Model、Graph、GraphSession 与 Builder 等运行时对象可能维护显式内部状态，具体以各自页面为准。

数值、坐标与单位​

紧凑原生几何 API 接受普通 float。长度遵循当前模型约定；名称包含 degrees 的角度使用度。三维向量和点的顺序为 (x, y, z)。

表达式与工程 API 使用显式量纲或单位标签。当对象提供 length_unit、force_unit、time_unit、temperature_unit 或量纲值时，不要从字段名推断单位。应在子系统边界显式转换，并在导出产物中记录单位制。

预期为正的几何尺寸必须有限。公差不得为负，通常与输入几何使用相同长度单位。

索引与引用​

原生面和边集合在同一 Shape、同一运行版本内使用确定性的零基索引。索引适合紧接着作用于未改变拓扑的操作，但拓扑修改后不能作为稳定产品标识。需要跨重建保留意图时，应使用语义标签、Connector ID、Component ID 或显式 GeometryRef。

Graph 节点同样使用零基整数，并且只能引用之前的节点。Model JSON 使用字符串节点 ID，并验证 Graph 所有权。

路径与外部副作用​

名称以 export_*、write_*、save_* 开头的函数以及部分 render_* 函数会写文件。导入和加载函数会读取外部数据，并可能拒绝缺失、格式错误或不受支持的内容。使用应用控制的明确路径，并在交付前验证产物存在且非空。

JSON 与确定性数据​

除非另有说明，公共 to_dict() 与序列化函数返回 JSON-safe 值。Scene 与重放 API 在需要字节级确定性时提供规范化和严格解析函数。来自不可信来源的数据必须限制大小、严格解析，并在执行前通过领域 Schema 验证。

可选依赖​

部分领域需要额外 Python 包、原生库或外部 CAD 应用。模块可以导入不代表所有操作均可用；动态派发前应检查 capabilities() 或对应领域的能力记录。

稳定性​

CadFlow 0.1.0 处于 Alpha。公共名称已有文档与测试，但签名和序列化 Schema 在稳定版前仍可能演进。生产环境应固定精确版本、检查生成签名漂移，并在升级时验证几何或产物等价性。