7.5 KiB
FreeCAD FCStd 设备资产流转 A 方案设计
1. 设计目标
A 方案把 .FCStd 定义为正式的 3D 电气设备资产格式。
完整链路是：
STEP / STP / STE 原始几何
-> FreeCAD 模板制作
-> 添加端子 LCS 和电气语义
-> 保存为 FCStd 设备模板
-> zwl/QET 选择该 FCStd 作为设备 3D 资产
-> 3D 视图导出 2d_to_3d.json
-> FreeCAD 导入 FCStd 并绑定工程端子
-> 手动连线并保存 scene.FCStd
-> 生成 3d_to_2d.json
这个设计解决的问题是：模型文件交给别人、换工程使用、重新打开工程时，端子位置和接线语义仍然跟着模型走。
2. 职责边界
2.1 LightWork3D / FreeCAD 负责
- 导入 STEP / STP / STE 原始几何。
- 在模型真实接线位置创建模板端子 LCS。
- 给模板端子写入：
Role = "Terminal"CanWire = trueQetTemplateSlotNameQetTerminalLabelQetTerminalType
- 保存为
.FCStd设备模板。 - 项目导入时读取 FCStd 模板里的端子 LCS。
- 根据
2d_to_3d.json把工程级terminal_uuid绑定到 3D 端子对象。 - 在 FreeCAD 文档里保存设备位姿、装配状态、端子位置和手动连线。
2.2 D:\code\zwl / QET 负责
- 支持选择
.FCStd作为设备 3D 资产。 - 将
.FCStd保存到device_3d_asset，格式识别为fcstd。 - 继续通过
device_3d_asset.uri优先提供 3D 资源路径。 - 导出
2d_to_3d.json时保持parts_3d和resolved_model_path。 - 启动 FreeCAD 并传递：
QET_2D_TO_3D_JSONQET_FREECAD_SCENE_FILE
zwl 不解析 .FCStd 内部结构，不读取 LCS，不判断端子位置。.FCStd 内部端子语义由 FreeCADExchange 读取。
3. 模板与工程实例的区别
3.1 FCStd 设备模板保存通用槽位
模板中的端子表示“这个设备模型哪里可以接线”，例如：
电流互感器.FCStd
ModelGeometry
Terminal_P1
Terminal_P2
模板端子保存：
QetTemplateSlotName = P1
QetTerminalLabel = P1
Role = Terminal
CanWire = true
模板端子不保存：
QetProjectUuid
QetElementUuid
QetTerminalUuid
QetInstanceId
3.2 工程场景保存真实绑定
工程打开 3D 视图后，FreeCAD 根据 2d_to_3d.json 创建或更新工程端子对象。
工程端子保存：
QetProjectUuid
QetElementUuid
QetTerminalUuid
QetInstanceId
Role = Terminal
CanWire = true
这样同一个 FCStd 模板可以被多个工程复用，而不会把某个工程的端子 UUID 写死在模板里。
4. zwl 侧需要支持的最小改动
4.1 设备 3D 资产选择
D:\code\zwl\sources\DeviceManager\deviceeditor.cpp 中的设备 3D 文件选择过滤器需要加入 .fcstd：
3D 文件 (*.fcstd *.FCStd *.step *.stp *.iges *.igs *.stl *.obj)
提示文案从“STEP/IGES 文件”改成“3D 模型文件”，避免用户以为 FCStd 不是合法资产。
4.2 格式识别
detect3dFormat(...) / normalize3dFormatFromPathInternal(...) 需要把：
.fcstd / .FCStd -> fcstd
写入 device_3d_asset.format。
4.3 资产复制
当前设备编辑器选择工程外文件时会复制到工程 3D 资产目录。该流程应继续适用于 .FCStd。
如果源文件旁边存在 sidecar JSON，可以继续复制；但对正式 A 方案来说，FCStd 内 LCS 是优先来源，sidecar 只作为过渡兼容。
4.4 导出给 FreeCAD
FreeCADExchangeExportService.cpp 已经导出：
{
"parts_3d": "...",
"resolved_model_path": "..."
}
.FCStd 第一版不需要额外字段也能工作，因为 FreeCAD 可从 resolved_model_path 的扩展名判断格式。
后续可以把 device_3d_asset.format 作为可选调试字段导出：
{
"format": "fcstd"
}
但第一版不应让 FreeCAD 依赖这个字段，避免旧 JSON 失效。
4.5 旧 3D 空间对象入口
qetdiagrameditor.cpp 里旧的空间对象 STEP/IGES 选择入口属于旧 3D 场景功能。A 方案第一版不建议把它作为设备模板主入口。
如果后续仍要用它给机柜、导轨、安装板选择模型，可以单独扩展为：
空间对象模型 (*.fcstd *.FCStd *.step *.stp *.iges *.igs)
但它不负责设备端子语义。
5. FreeCAD 侧需要保持的读取优先级
项目导入设备后，端子槽位解析顺序固定为：
- FCStd 模板内已有的
Role="Terminal"LCS。 - STEP 同目录 sidecar JSON。
- bbox fallback 临时端子。
长期目标是让常用设备都进入第 1 类。第 3 类只用于没有模板时打通流程，不能作为正式端子位置。
6. 手动连线与保存回写
手动连线只允许从工程端子对象连到工程端子对象。
连线对象保存在 scene.FCStd，第一版不把导线几何路径写入数据库。
保存时 3d_to_2d.json 只回写最小绑定：
{
"schema_version": "1.0",
"project_uuid": "string",
"instances": [
{
"element_uuid": "string",
"instance_id": "string"
}
],
"terminals": [
{
"terminal_uuid": "string",
"instance_id": "string"
}
]
}
这符合当前数据库约束：第一版只依赖 project_2d3d_symbol_binding 和 project_2d3d_terminal_binding，不依赖旧 3D 场景表。
7. 用户流程
7.1 制作设备模板
- 打开 FreeCAD。
- 导入厂家 STEP / STP / STE 模型。
- 在真实接线位置添加端子，例如
P1、P2。 - 执行模板端子校验。
- 保存为
设备名.FCStd。
7.2 在 zwl/QET 中使用模板
- 打开设备管理或设备属性。
- 选择 3D 资产。
- 选择刚制作好的
.FCStd。 - 保存设备资产绑定。
- 在工程中点击
3D视图。 - zwl 导出
2d_to_3d.json并启动 FreeCAD。 - FreeCAD 导入
.FCStd，读取模板端子，生成工程端子对象。 - 用户选择端子并创建手动连线。
- 保存 FreeCAD 工程，生成
3d_to_2d.json。
8. 第一版验收标准
- zwl 设备 3D 资产选择框能选择
.FCStd。 .FCStd能写入device_3d_asset，格式为fcstd。2d_to_3d.json中resolved_model_path指向.FCStd。- FreeCAD 能导入该
.FCStd。 - 模板中的 LCS 端子优先用于工程端子创建。
- 工程端子对象带真实
terminal_uuid。 - 用户能选择两个端子生成手动连线。
- 保存 FreeCAD 后生成
3d_to_2d.json。 - 不依赖
project_3d_scene_instance、project_3d_space_object、project_2d3d_link、start_end_terminal_matches。
9. 实施顺序
- 在 zwl 侧补
.FCStd文件过滤、格式识别和提示文案。 - 确认
.FCStd资产复制、哈希、保存流程不被阻断。 - 确认
2d_to_3d.json能输出.FCStd的resolved_model_path。 - 在 FreeCAD 中用现有
TemplateAuthoring.py制作一个样板设备。 - 用该 FCStd 样板设备跑通导入、端子显示、手动连线、保存回写。
- 再补更友好的模板端子编辑 UI。
10. 风险和处理
.FCStd 无法被 zwl 预览尺寸：
- 不阻断资产绑定。
- 尺寸字段可以为空或由后续 FreeCAD 侧读取后回填。
模板端子槽位与 2D 端子数量不一致：
- 第一版按数量顺序匹配可用槽位。
- 后续再引入显式槽位映射 UI。
用户误选普通 STEP：
- 仍允许导入，但只能走 sidecar 或 bbox fallback。
- 文档和提示中明确“正式可复用资产推荐 FCStd”。
旧空间对象入口和新设备模板入口混淆：
- 第一版设备端子语义只走设备 3D 资产入口。
- 旧空间对象入口只作为柜体、导轨、安装板模型入口。