CAD 图块
调用指南

接口入口

先声明进出口数量，再返回匹配图形

调用方先从 Aspen 设备拓扑统计实际入口数和出口数，在同一次请求中提供 inlet_count 与 outlet_count。接口不会根据设备名称、外形或默认值猜数量；它只按 connection_configuration 的端口优先级和 geometry_binding.entity_handles 生成匹配实例。

1. 从 Aspen 上下游流股统计目标设备实际进、出口数量。
2. 读取目录或母模板，确认存在 connection_configuration 并检查数量约束。
3. 调用 symbol、ports 或推荐的 placement 接口，同时传入两个数量。
4. 服务端选择对应端口，保留其关联图元并移除未启用端口的独占图元。
5. 调用方只使用响应中的实例实体、启用端口和重算后的占位框。

GET /api/v1/cad-blocks/Mixer_01/placement
  ?inlet_count=2&outlet_count=1
  &insertion_x=200&insertion_y=100

• 不传数量：返回完整母模板，只适合发现、审阅和维护，不代表实际 PFD 实例。
• 两个数量必须同时提供；越界或对固定端口图块使用会返回 422。
• 没有 connection_configuration 的固定图块不传数量，直接使用其固定图形和端口。
• 空关联端口被禁用时只移除端口；共享图元在任一引用端口启用时保留。
• instance_configuration 明确列出请求数量、启用端口和移除端口；不得把实例覆盖回母模板。
• 当前 Mixer_01 支持 2–5 个入口、固定 1 个出口。

完整块 JSON

/api/v1/cad-blocks/{template_id} 是图块重建的主数据源，不是预览摘要。设备块应同时提供以下结构：

{
  "catalog": { "template_id": "Pump_01", "block_role": "equipment_symbol" },
  "bounds_local": [min_x, min_y, max_x, max_y],
  "insertion_base_local": [x, y, z],
  "reference_insertion_point": { "local": [x, y, z] },
  "entities": [ ... ],
  "layer_styles": { ... },
  "linetype_styles": { ... },
  "nested_block_dependencies": [ ... ],
  "equipment_occupancy_frame": { ... },
  "connection_ports": { ... },
  "api_resolution": { "fallback": false }
}

• entities 保存真实局部几何；样式联合读取实体属性、layer_styles 和 linetype_styles。
• bounds_local 是全部图元边界，可能包含文字或辅助结构；设备排布应使用 equipment_occupancy_frame。
• reference_insertion_point.local 与 insertion_base_local 应一致，前者补充来源和网页标记信息。
• 存在 nested_block_dependencies 时必须递归读取，不得用截图替代子块。

设备矩形与面积

equipment_occupancy_frame.limits_from_insertion_base 的 left、bottom、right、top 是相对插入基点的有符号极限。size.width = right-left，size.height = top-bottom；接口返回的面积是这个矩形的面积，不是设备实体真实投影面积。

GET /api/v1/cad-blocks/Pump_01/placement
  ?insertion_x=200&insertion_y=100
  &scale_x=1&scale_y=1&rotation_deg=90

• occupancy.world_corners：旋转后的四角，依次为左下、右下、右上、左上。
• occupancy.world_aabb：从四角重新求得，自动排布和碰撞检查使用它。
• area_local_square_drawing_units：未缩放局部矩形面积。
• area_scaled_square_drawing_units：缩放后旋转矩形面积；旋转不改变此值。
• 设备净距、位号空间和管线通道应在紧致框外另加项目级 padding，不回写模板。

进出口点与接线

只有 ports.connectable=true 且端口数组非空时才允许自动接线。local 是模板局部坐标，不是已扣除基点的偏移；调用时计算 local - insertion_base_local。normal 是首段方向，不是第二个点。

{
  "id": "in1",
  "flow": "in",
  "local": [-24.0, 18.0, 0.0],
  "normal": [-1.0, 0.0, 0.0],
  "world": [176.0, 118.0, 0.0],
  "world_normal": [-1.0, 0.0, 0.0]
}

• id 是当前显示顺序；存在 port_uid 时，用它保存跨重排绑定。
• flow=in/out 表示相对设备的流入或流出。
• 从源设备的 world 沿 world_normal 引出短直段，再做正交寻路。
• needs_manual_definition、草案或 review_required=true 不得直接用于最终 CAD。

坐标公式

world = insertion
      + R(rotation_deg)
      × diag(scale_x, scale_y)
      × (local - insertion_base_local)

局部坐标遵循 AutoCAD：X 向右，Y 向上，旋转角为逆时针。调用端不得假定基点恒为零，也不得把网页 Canvas 的向下 Y 轴写回 CAD。

最短可靠调用

const placed = await fetch(
  "/api/v1/cad-blocks/Pump_01/placement" +
  "?insertion_x=200&insertion_y=100&rotation_deg=0"
).then(r => r.json());

if (placed.fallback) flagForReview();
const collisionBox = placed.occupancy.world_aabb;
if (placed.ports.connectable && !placed.ports.review_required) {
  routeFrom(placed.ports.items[0].world,
            placed.ports.items[0].world_normal);
}

碰撞检测固定读取 placement.occupancy.world_aabb；接线点固定读取 placement.ports.items[].world。这两个字段已经完成插入、缩放和旋转变换。

未知类型回退

未知 template_id 返回 GenericEquipmentBlock_01，HTTP 仍为 200。务必检查 api_resolution.fallback 或组合接口顶层 fallback。万能块为 48 × 48 正方形，左侧 6 个输入、右侧 6 个输出，只保证拓扑可视化，不代表真实设备选型。