# 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. 模板文件结构

以电流互感器为例：

```text
电流互感器.FCStd
  ModelGeometry
  Terminal_P1
  Terminal_P2
```

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

## 5. 模板端子属性

模板端子至少写入：

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

模板端子不写入：

```text
QetProjectUuid
QetElementUuid
QetTerminalUuid
QetInstanceId
```

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

## 6. 新模块

新增模块：

```text
src/Mod/FreeCADExchange/TemplateAuthoring.py
```

职责：

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

不负责：

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

## 7. 第一版命令

第一版先做两个命令：

```text
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. 与现有导入流程的关系

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

```text
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. 用电流互感器模型手工验证一次完整流程。