LightWork3D/docs/FreeCAD 3D模型端子设计方案.md

FreeCAD 3D 模型端子设计方案

1. 目标

本文档定义电气设备 3D 模型上的“端子”如何设计、保存、生成和参与布线。

当前正式路线固定为：

STEP / STP / STE 原始几何
  -> FreeCAD 添加模板端子
  -> 保存为 FCStd 设备模板
  -> QET 绑定该 FCStd 作为设备 3D 资产
  -> 3D 视图打开 FreeCAD
  -> FreeCAD 从模板端子生成工程端子
  -> 工程端子参与 3D 手动布线

STEP / STP / STE 只作为几何输入。正式可复用的电气 3D 设备资产是 .FCStd。

2. 名词约定

2.1 端子

本文档统一使用“端子”作为电气设备上可接线位置的名称。

在不同软件或资料中，它也可能被称为：

• 接线端子
• 接线点
• 连接点
• terminal
• connection terminal

后续代码和文档尽量使用“端子”，避免继续使用泛化的 connectionPoint 作为正式设计依据。

2.2 模板端子

模板端子存在于设备模板 .FCStd 中，表示“这个设备模型上哪里可以接线”。

模板端子是跨工程复用的槽位，不属于某一个具体项目。

例如电流互感器模板可以有：

电流互感器.FCStd
  Body / imported geometry
  Terminal_P1
  Terminal_P2

Terminal_P1 和 Terminal_P2 是 FreeCAD LCS 对象。它们的位置表示真实接线位置，方向表示后续出线方向。

2.3 工程端子

工程端子存在于具体项目的 scene.FCStd 中，表示“当前工程中某个设备实例上的可布线端子”。

工程端子从模板端子生成。它继承模板端子的位置、方向和槽位语义，同时补上当前工程的设备实例信息。

如果 QET 已传入真实 terminal_uuid，工程端子可以和 2D 端子准确绑定。如果 QET 没有传入 terminal_uuid，FreeCAD 只能生成本地 3D 工程端子，用于 3D 手动布线验证，不能可靠回写到 QET 2D 端子。

3. 模板端子设计

模板端子使用 FreeCAD LCS 表示，推荐类型：

Part::LocalCoordinateSystem
PartDesign::CoordinateSystem

模板端子至少保存：

属性	说明
Role = "Terminal"	标识该 LCS 是端子
CanWire = true	表示该端子允许接线
QetTemplateSlotName	模板内稳定槽位名，例如 P1、P2、A1
QetTerminalLabel	显示名称，可与槽位名一致
QetTerminalType	端子类型，例如 generic、primary、power、control
Placement.Base	端子在设备模板局部坐标系中的位置
Placement.Rotation	端子方向，默认把 LCS 本地 +Z 作为出线方向

模板端子禁止保存：

QetProjectUuid
QetElementUuid
QetTerminalUuid
QetInstanceId

原因是这些字段属于某个具体工程。如果写进模板，同一个设备模板传给别人或放到另一个工程里就会污染绑定关系。

4. 工程端子设计

工程端子同样使用 LCS 表示，但它属于当前工程。

工程端子至少保存：

属性	说明
QetProjectUuid	当前项目 UUID
QetElementUuid	2D 设备实例 UUID
QetInstanceId	3D 设备实例 ID
QetTerminalUuid	QET 2D 端子 UUID；没有 QET 绑定时可使用 local:* 本地 UUID
Role = "Terminal"	标识为端子
CanWire = true	允许被手动布线命令选择
QetTemplateSlotName	来源模板槽位名

工程端子创建后放在设备组下面：

QETExchangeDevices
  QETDevice_<element_uuid>
    imported model objects
    QETTerminals_<element_uuid>
      P1
      P2

手动布线命令只允许选择工程端子，不应该直接连接模板端子。

5. 端子方向

端子方向对后续手动布线和自动布线都很重要。

当前约定：

LCS 本地 +Z 方向 = 端子出线方向

例如模板端子 P1 的 LCS 放在接线孔中心，LCS 的 +Z 指向电线离开设备的方向。后续手动布线或自动布线可以先沿该方向生成一小段出线段，再进入线槽或自由走线路径。

如果第一版模板制作界面暂时只能准确放置位置，方向可以先用默认方向；但正式设备模板最终应补齐方向，否则后续布线容易出现电线穿过设备或从错误方向出线。

6. 自动生成工程端子规则

QET 点击 3D视图 打开 FreeCAD 后，FreeCAD 可以自动创建工程端子，但必须满足条件：

1. 2d_to_3d.json 中存在端子数据。
2. 端子数据至少有 terminal_uuid 和 instance_id。
3. FreeCAD 能通过 instance_id 找到对应设备实例。
4. 该设备实例导入的 .FCStd 内有模板端子。

如果设备没有模板端子，FreeCAD 不自动凭空生成工程端子。

这样做是为了避免把端子生成在错误位置。没有模板端子的设备，应先补模板端子，或者由用户在 FreeCAD 中手动建立模板端子后再保存成新的 .FCStd。

7. 手动生成工程端子规则

当 QET 没有传端子数据，或者某些设备没有自动生成工程端子时，用户可以在 FreeCAD 中手动生成工程端子。

推荐操作：

1. 在树目录中选中 QETDevice_xxx 设备组。
2. 点击 QET模板 -> 生成工程端子。
3. FreeCAD 扫描该设备里的模板端子。
4. 按模板端子的位置、方向和槽位名生成工程端子。
5. 工程端子放入该设备下的 QETTerminals_xxx 分组。

如果不选设备，命令可以尝试处理当前工程中所有 QETDevice_xxx。

手动生成工程端子时必须优先以模板端子为准，不能再用设备包围盒猜测端子位置。

如果没有 QET 真实 terminal_uuid，手动生成的工程端子使用本地 UUID：

local:<instance_id>:<slot_name>

这种端子可以用于 3D 手动布线，但不能当作 QET 2D 端子的可靠回写依据。

8. QET 数据传输责任边界

QET/zh 侧负责把 2D 端子和 3D 设备实例的绑定关系传给 FreeCAD。

第一版必须传：

{
  "terminal_uuid": "2d-terminal-uuid",
  "instance_id": "3d-device-instance-id",
  "element_uuid": "2d-device-element-uuid"
}

其中：

• terminal_uuid 是 2D 端子主键，也是第一版端子绑定唯一依据。
• instance_id 表示该 2D 端子属于哪个 3D 设备实例。
• element_uuid 可帮助 FreeCAD 定位父设备，但第一版端子绑定仍以 terminal_uuid 为核心。

QET 不需要解析 .FCStd 内部 LCS，也不需要计算端子坐标。端子空间位置由 FreeCAD 模板负责。

后续如果需要更准确地把 2D 端子匹配到模板槽位，可以在交换 JSON 里增加非主键提示字段，例如：

{
  "terminal_uuid": "2d-terminal-uuid",
  "instance_id": "3d-device-instance-id",
  "slot_name_hint": "P1",
  "terminal_label": "P1"
}

这些字段只能作为匹配提示，不能替代 terminal_uuid。

当前 FreeCAD 侧已经支持用 slot_name_hint 或 terminal_label 优先匹配模板槽位，再退回顺序匹配。也就是说，zh 侧后续只要把端子提示名补上，FreeCAD 就能更稳定地把 2D 端子落到正确的模板端子上。

9. 与布线的关系

手动布线连接的是工程端子，不是模板端子。

完整关系是：

模板端子
  -> 定义设备上哪里能接线
  -> 提供局部坐标和出线方向

工程端子
  -> 从模板端子生成
  -> 绑定当前工程设备实例
  -> 带 QET terminal_uuid 或 local UUID
  -> 被手动布线命令选择

导线
  -> 连接两个工程端子
  -> 起点和终点记录端子 UUID
  -> 路径几何保存在 scene.FCStd

工程端子位置应跟随设备移动。实现上，工程端子挂在设备组下，并使用模板端子的局部坐标；计算布线路径时再取端子的全局坐标。

10. 当前不采用的方案

10.1 不把 STEP 当成最终电气资产

STEP 可以稳定保存几何，但不能可靠保存 FreeCAD LCS、动态属性、端子角色和接线资格。因此 STEP 只作为制作模板的输入。

10.2 不依赖 connectionPoint

已有代码或旧文档中的 connectionPoint 可以作为历史参考，但当前正式端子方案不以它为核心。正式方案统一使用 FreeCAD 模板端子和工程端子。

10.3 不再用 bbox fallback 作为正式端子

包围盒猜点容易把端子放到错误位置。当前正式方案中，设备没有模板端子时不自动创建工程端子。需要先补模板端子，或者由用户明确手动创建。

11. 当前开发下一步

下一步优先做“工程端子生成和可验证流程”，不是继续扩大模板工具范围。

建议顺序：

1. 保持模板端子默认隐藏，只显示工程端子。
2. 生成工程端子 命令只从模板端子生成工程端子。
3. 没有模板端子的设备不自动生成工程端子，并给出清晰提示。
4. 有 QET terminal_uuid 的端子生成真实工程端子。
5. 没有 QET terminal_uuid 但用户手动生成时，生成 local:* 本地工程端子。
6. 手动布线只允许连接工程端子。
7. 3d_to_2d.json 回写时区分真实 QET 端子和本地端子，本地端子不作为 2D 绑定结果。

12. 验收标准

第一版验收以电流互感器为例：

1. 从 STEP 制作 电流互感器.FCStd。
2. 模板中有 P1、P2 模板端子。
3. QET 绑定该 .FCStd。
4. QET 点击 3D视图 打开 FreeCAD。
5. FreeCAD 能导入设备模型。
6. 选中设备执行 生成工程端子 后，工程端子落在模板端子位置。
7. 移动设备后，工程端子跟随设备移动或能正确计算全局位置。
8. 选择两个设备上的工程端子可以创建手动导线。
9. 保存后重新打开，设备、工程端子和导线仍存在。
10. 如果 QET 提供真实 terminal_uuid，3d_to_2d.json 中能回写端子绑定；如果是 local:* 端子，则只用于 3D 本地布线。