# FreeCAD 端子模板语义设计

> 目标：把端子位置、端子命名、端子朝向和接线资格从几何模型里分离出来，放进可维护的模板语义层。

**Goal:** 让 FreeCAD 的端子显示、手动连线和最小保存回写依赖真实模板语义，而不是长期依赖包围盒猜位。

**Architecture:** 以 `FreeCADExchange` 的 Python 层为主体。`DeviceImport.py` 负责把设备模型导入到设备组，`TemplateSemantics.py` 负责把模板输入统一成端子槽位，`TerminalImport.py` 负责创建或更新端子 LCS，`ManualWiring.py` 负责端子到端子的人工连线，`ExchangeWriteBack.py` 负责生成 `3d_to_2d.json`。FreeCAD 文档 `scene.FCStd` 是 3D 状态真相源，数据库只保留第一版最小绑定表。

**Tech Stack:** FreeCAD Python API, `App::DocumentObjectGroup`, `Part::LocalCoordinateSystem` / `PartDesign::CoordinateSystem`, JSON sidecar files, FreeCAD document observer.

---

## 1. 设计目标

1. 端子必须有稳定的语义来源。
2. 端子必须能被看见、选中、更新。
3. 手动连线只能从端子连到端子。
4. 保存时只回写第一版最小结果，不把 3D 位姿塞回数据库。
5. 常用设备最终要补成真实模板，不能长期靠 `bbox fallback`。

## 2. 设计边界

本设计只覆盖以下内容：

- 端子模板语义解析
- 端子对象创建 / 更新
- 手动连线对象创建
- 保存时生成 `3d_to_2d.json`

本设计不覆盖：

- 自动布线
- FreeCAD C/C++ 核心修改
- `D:\code\zwl\sources\ThreeD` 旧 3D 引擎
- 新增 3D 场景数据库表
- 将完整线几何回写到 QET

## 3. 模板语义优先级

端子位置来源按下面优先级解析：

1. `FCStd` 模板里已有的 `LCS`
2. 同目录 sidecar JSON
3. `bbox fallback`

解释：

- `FCStd` 模板是正式答案，适合已经整理过的常用设备。
- sidecar JSON 是过渡方案，适合 STEP 几何已经有了，但还没整理成 FCStd 模板的设备。
- `bbox fallback` 只用于打通流程，不代表真实端子位置。

## 4. 模板资产约定

### 4.1 FCStd 模板

FCStd 模板里，端子用 LCS 表达，建议对象满足：

- 类型是 `Part::LocalCoordinateSystem` 或 `PartDesign::CoordinateSystem`
- `Role = "Terminal"`
- `CanWire = true`

这些属性的作用是：

- `Role` 让 FreeCADExchange 识别它是端子
- `CanWire` 让连线命令只接受有效端子
- 端子对象的 `QetTerminalUuid` 由导入流程补齐，不依赖模板文件本身已有的 2D 绑定字段

### 4.2 sidecar JSON

sidecar JSON 与模型同目录，当前支持的文件名后缀约定：

- `.terminals.json`
- `.qet_terminals.json`
- `.terminal_slots.json`
- `.qet_template.json`

sidecar 中可接受的槽位字段：

- `name`
- `label`
- `position`
- `base`
- `origin`
- `point`
- `x / y / z`

如果某个槽位已经有明确位置，就直接作为端子坐标。名称和标签只用于显示和调试，不作为业务主键。

### 4.3 bbox fallback

当模板里没有 LCS，也没有 sidecar JSON 时，才用包围盒生成临时端子位置。

这个 fallback 只做三件事：

- 让导入链路跑通
- 让用户能先看到端子对象
- 给后续补模板留出验证空间

它不能作为最终模板方案。

## 5. 端子对象模型

每个端子对象都必须挂在对应设备实例下的 `QETTerminals_<element_uuid>` 组内。

端子对象必须保存这些语义属性：

- `QetProjectUuid`
- `QetElementUuid`
- `QetTerminalUuid`
- `QetInstanceId`
- `Role = "Terminal"`
- `CanWire = true`

补充属性：

- `QetTemplateSlotName`

识别规则只认 `terminal_uuid`，不依赖 `terminal_key`、`connection_point_key` 这类旧字段。

## 6. 连线对象模型

手动连线只允许连接两个端子。

连线对象保存：

- `QetProjectUuid`
- `QetStartTerminalUuid`
- `QetEndTerminalUuid`
- `QetStartInstanceId`
- `QetEndInstanceId`
- `RouteType = "Manual"`

连线几何保存在 `scene.FCStd`，第一版不把完整路径几何写回数据库。

## 7. 数据流

1. QET 导出 `2d_to_3d.json`。
2. FreeCAD 读取 `devices / terminals / device_models`。
3. `DeviceImport.py` 导入设备模型并形成 `QETExchangeDevices` 树。
4. `TemplateSemantics.py` 为每个设备解析端子槽位。
5. `TerminalImport.py` 创建或更新端子对象。
6. 用户通过命令手动连线。
7. 保存文档时 `ExchangeWriteBack.py` 输出 `3d_to_2d.json`。

## 8. 实现约束

1. 第一版只改 `FreeCADExchange` Python 层。
2. 第一版不改 FreeCAD C/C++。
3. 第一版不依赖旧 3D 场景表。
4. 第一版 3D 状态以 FreeCAD 文档为准。
5. 第一版绑定只认：
   - `project_uuid`
   - `element_uuid`
   - `terminal_uuid`
   - `instance_id`

## 9. 模板建设顺序

建议先补这几类常用设备：

1. 机柜 / 安装板
2. DIN 导轨
3. 断路器或继电器
4. 端子排

先把这些设备补成 FCStd LCS 或 sidecar JSON，可以最快验证“端子显示 + 手动连线 + 保存回写”这条链路。

## 10. 失败处理

1. 模型文件不存在，跳过设备并记录警告。
2. 没有端子模板，退回 sidecar。
3. 没有 sidecar，退回 bbox fallback。
4. 端子 `terminal_uuid` 缺失，直接跳过该条。
5. 同一个 `terminal_uuid` 已存在时，更新旧端子而不是重复创建。
6. 保存回写失败时，保留 FreeCAD 文档状态，错误写入调试日志。

## 11. 验收标准

满足下面结果，就说明这套设计可用：

- 设备模型导入后，树里能看到 `QETDevice_<element_uuid>`
- 每个设备下有对应的 `QETTerminals_<element_uuid>`
- 端子对象带 `QetTerminalUuid` 和 `Role="Terminal"`
- 用户只能从端子连到端子
- 保存后生成 `3d_to_2d.json`
- `3d_to_2d.json` 里只保留设备实例和端子实例的最小回写结果

## 12. 结论

这条路线的核心不是“先把所有模型做完”，而是先把模板语义建立起来。只要常用设备的端子位置从 fallback 升级到 FCStd LCS 或 sidecar JSON，FreeCAD 这条 3D 线就能从临时验证变成可持续开发。