# FreeCAD FCStd 设备资产流转 A 方案设计

## 1. 设计目标

A 方案把 `.FCStd` 定义为正式的 3D 电气设备资产格式。

完整链路是：

```text
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 = true`
  - `QetTemplateSlotName`
  - `QetTerminalLabel`
  - `QetTerminalType`
- 保存为 `.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_JSON`
  - `QET_FREECAD_SCENE_FILE`

zwl 不解析 `.FCStd` 内部结构，不读取 LCS，不判断端子位置。`.FCStd` 内部端子语义由 FreeCADExchange 读取。

## 3. 模板与工程实例的区别

### 3.1 FCStd 设备模板保存通用槽位

模板中的端子表示“这个设备模型哪里可以接线”，例如：

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

模板端子保存：

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

模板端子不保存：

```text
QetProjectUuid
QetElementUuid
QetTerminalUuid
QetInstanceId
```

### 3.2 工程场景保存真实绑定

工程打开 3D 视图后，FreeCAD 根据 `2d_to_3d.json` 创建或更新工程端子对象。

工程端子保存：

```text
QetProjectUuid
QetElementUuid
QetTerminalUuid
QetInstanceId
Role = Terminal
CanWire = true
```

这样同一个 FCStd 模板可以被多个工程复用，而不会把某个工程的端子 UUID 写死在模板里。

## 4. zwl 侧需要支持的最小改动

### 4.1 设备 3D 资产选择

`D:\code\zwl\sources\DeviceManager\deviceeditor.cpp` 中的设备 3D 文件选择过滤器需要加入 `.fcstd`：

```text
3D 文件 (*.fcstd *.FCStd *.step *.stp *.iges *.igs *.stl *.obj)
```

提示文案从“STEP/IGES 文件”改成“3D 模型文件”，避免用户以为 FCStd 不是合法资产。

### 4.2 格式识别

`detect3dFormat(...)` / `normalize3dFormatFromPathInternal(...)` 需要把：

```text
.fcstd / .FCStd -> fcstd
```

写入 `device_3d_asset.format`。

### 4.3 资产复制

当前设备编辑器选择工程外文件时会复制到工程 3D 资产目录。该流程应继续适用于 `.FCStd`。

如果源文件旁边存在 sidecar JSON，可以继续复制；但对正式 A 方案来说，FCStd 内 LCS 是优先来源，sidecar 只作为过渡兼容。

### 4.4 导出给 FreeCAD

`FreeCADExchangeExportService.cpp` 已经导出：

```json
{
  "parts_3d": "...",
  "resolved_model_path": "..."
}
```

`.FCStd` 第一版不需要额外字段也能工作，因为 FreeCAD 可从 `resolved_model_path` 的扩展名判断格式。

后续可以把 `device_3d_asset.format` 作为可选调试字段导出：

```json
{
  "format": "fcstd"
}
```

但第一版不应让 FreeCAD 依赖这个字段，避免旧 JSON 失效。

### 4.5 旧 3D 空间对象入口

`qetdiagrameditor.cpp` 里旧的空间对象 STEP/IGES 选择入口属于旧 3D 场景功能。A 方案第一版不建议把它作为设备模板主入口。

如果后续仍要用它给机柜、导轨、安装板选择模型，可以单独扩展为：

```text
空间对象模型 (*.fcstd *.FCStd *.step *.stp *.iges *.igs)
```

但它不负责设备端子语义。

## 5. FreeCAD 侧需要保持的读取优先级

项目导入设备后，端子槽位解析顺序固定为：

1. FCStd 模板内已有的 `Role="Terminal"` LCS。
2. STEP 同目录 sidecar JSON。
3. bbox fallback 临时端子。

长期目标是让常用设备都进入第 1 类。第 3 类只用于没有模板时打通流程，不能作为正式端子位置。

## 6. 手动连线与保存回写

手动连线只允许从工程端子对象连到工程端子对象。

连线对象保存在 `scene.FCStd`，第一版不把导线几何路径写入数据库。

保存时 `3d_to_2d.json` 只回写最小绑定：

```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 制作设备模板

1. 打开 FreeCAD。
2. 导入厂家 STEP / STP / STE 模型。
3. 在真实接线位置添加端子，例如 `P1`、`P2`。
4. 执行模板端子校验。
5. 保存为 `设备名.FCStd`。

### 7.2 在 zwl/QET 中使用模板

1. 打开设备管理或设备属性。
2. 选择 3D 资产。
3. 选择刚制作好的 `.FCStd`。
4. 保存设备资产绑定。
5. 在工程中点击 `3D视图`。
6. zwl 导出 `2d_to_3d.json` 并启动 FreeCAD。
7. FreeCAD 导入 `.FCStd`，读取模板端子，生成工程端子对象。
8. 用户选择端子并创建手动连线。
9. 保存 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. 实施顺序

1. 在 zwl 侧补 `.FCStd` 文件过滤、格式识别和提示文案。
2. 确认 `.FCStd` 资产复制、哈希、保存流程不被阻断。
3. 确认 `2d_to_3d.json` 能输出 `.FCStd` 的 `resolved_model_path`。
4. 在 FreeCAD 中用现有 `TemplateAuthoring.py` 制作一个样板设备。
5. 用该 FCStd 样板设备跑通导入、端子显示、手动连线、保存回写。
6. 再补更友好的模板端子编辑 UI。

## 10. 风险和处理

`.FCStd` 无法被 zwl 预览尺寸：

- 不阻断资产绑定。
- 尺寸字段可以为空或由后续 FreeCAD 侧读取后回填。

模板端子槽位与 2D 端子数量不一致：

- 第一版按数量顺序匹配可用槽位。
- 后续再引入显式槽位映射 UI。

用户误选普通 STEP：

- 仍允许导入，但只能走 sidecar 或 bbox fallback。
- 文档和提示中明确“正式可复用资产推荐 FCStd”。

旧空间对象入口和新设备模板入口混淆：

- 第一版设备端子语义只走设备 3D 资产入口。
- 旧空间对象入口只作为柜体、导轨、安装板模型入口。