LightWork3D/docs/superpowers/specs/2026-05-20-freecad-fcstd-template-authoring-design.md

FreeCAD FCStd 电气设备模板制作设计

1. 目标

把普通 STEP / STP / STE 几何模型加工成可复用的 .FCStd 电气设备模板。

模板保存设备几何和端子槽位语义。后续不同工程、不同人员导入这个 FCStd 时，FreeCADExchange 能识别其中的端子 LCS，并把工程里的真实 terminal_uuid 绑定到这些槽位上。

2. 非目标

• 不修改 FreeCAD C/C++ 内核。
• 不在模板文件里保存工程级 terminal_uuid、project_uuid、instance_id。
• 不做自动布线。
• 不把完整接线路径写入数据库。
• 不要求第一版做完整 UI 面板。

3. 核心原则

STEP / STP / STE 是几何输入，FCStd 是正式设备模板输出。

模板端子描述“这个设备模型哪里可以接线”。工程端子描述“当前工程的哪个 2D 端子绑定到哪个 3D 端子对象”。两者不能混用。

4. 模板文件结构

以电流互感器为例：

电流互感器.FCStd
  ModelGeometry
  Terminal_P1
  Terminal_P2

Terminal_P1 和 Terminal_P2 是 LCS 对象。它们的位置就是模型上真实接线位置，方向就是后续出线方向参考。

5. 模板端子属性

模板端子至少写入：

Role = Terminal
CanWire = true
QetTemplateSlotName = P1
QetTerminalLabel = P1
QetTerminalType = primary

模板端子不写入：

QetProjectUuid
QetElementUuid
QetTerminalUuid
QetInstanceId

这些字段只属于具体工程场景。

6. 新模块

新增模块：

src/Mod/FreeCADExchange/TemplateAuthoring.py

职责：

• 创建模板端子 LCS。
• 给 LCS 写入模板语义属性。
• 校验当前文档中的模板端子。
• 保存或辅助保存 .FCStd 模板。

不负责：

• 工程 2d_to_3d.json 导入。
• 工程端子 UUID 绑定。
• 手动连线。
• 3d_to_2d.json 回写。

7. 第一版命令

第一版先做两个命令：

QET_Template_AddTerminal
QET_Template_ValidateTerminals

QET_Template_AddTerminal：

1. 用户选择一个模型对象或模型上的点位。
2. 执行命令。
3. 输入端子槽位名，例如 P1。
4. 在选择位置创建 LCS。
5. 自动写入模板端子属性。

QET_Template_ValidateTerminals：

1. 扫描当前文档中的端子 LCS。
2. 检查是否有 Role="Terminal"。
3. 检查是否有 QetTemplateSlotName。
4. 输出端子列表和问题。

保存动作第一版直接使用 FreeCAD 自带保存为 .FCStd。后续再补 QET_Template_SaveAsFCStd。

8. 第一版点位策略

第一版按简单稳定策略实现：

1. 如果用户选择对象的子元素，并且能取到选择点，就使用该点。
2. 如果只能选到对象，则使用对象包围盒中心。
3. 如果没有选择，则拒绝创建端子。

端子方向第一版使用默认旋转。后续再增加方向编辑，例如沿面法向、沿用户选择边方向或手动输入轴角。

9. 与现有导入流程的关系

现有项目导入流程保持不变：

ExchangeBootstrap
  -> DeviceImport
  -> TerminalImport
  -> ExchangeWriteBack

TerminalImport 已经支持读取 FCStd 模板中的 Role="Terminal" LCS。模板制作工具只负责把这些 LCS 方便、规范地放进 FCStd。

项目导入时的优先级仍是：

1. FCStd 模板 LCS。
2. sidecar JSON。
3. bbox fallback。

10. 用户流程

以电流互感器为例：

1. 打开 FreeCAD。
2. 导入 电流互感器.step。
3. 选择 P1 接线位置。
4. 执行 QET_Template_AddTerminal，输入 P1。
5. 选择 P2 接线位置。
6. 执行 QET_Template_AddTerminal，输入 P2。
7. 执行 QET_Template_ValidateTerminals。
8. 保存为 电流互感器.FCStd。
9. 在 LightWork3D 设备 3D 资源中使用该 FCStd。

11. 验收标准

• 能从普通 STEP 模型创建 Terminal_P1 和 Terminal_P2。
• 端子对象是 LCS。
• 端子对象带 Role="Terminal" 和 CanWire=true。
• 端子对象带 QetTemplateSlotName。
• 保存为 FCStd 后重新打开，端子和属性仍存在。
• 使用该 FCStd 作为工程模型时，端子位置来自模板 LCS，不再使用 bbox fallback。

12. 风险和处理

选择点不可用：

• 第一版退回对象包围盒中心。
• 如果连对象也没有选择，则直接提示错误。

端子重名：

• 第一版自动使用唯一对象名，例如 Terminal_P1_1。
• QetTemplateSlotName 保持用户输入，用于槽位语义。

模板里混入工程端子属性：

• 校验命令提示警告。
• 第一版不自动删除，避免误删用户数据。

方向不准确：

• 第一版只保证位置和语义。
• 后续补方向编辑命令。

13. 实施顺序

1. 新增 TemplateAuthoring.py。
2. 在 CMakeLists.txt 加入该模块。
3. 在 InitGui.py 注册模板命令。
4. 实现添加端子命令。
5. 实现校验命令。
6. 增加 Python 单元测试，覆盖属性写入和校验逻辑。
7. 用电流互感器模型手工验证一次完整流程。