# 批量端子排与小型断路器装配设计

## 目标

本功能用于 QET 与 FreeCAD 协同工程中的快速 3D 装配。正式工程里，QET 已经传入真实设备、真实端子和 3D 模型，FreeCAD 不再把 `批量端子排`、`批量断路器` 理解为重新生成一批假设备，而是把 QET 已导入的真实实例沿导轨批量排布。

第一版目标：

- 选择一根 DIN 导轨后，批量排布 QET 已导入的端子排实例，例如 `UD`、`ID`。
- 选择一根 DIN 导轨后，批量排布 QET 已导入的小型断路器或同类设备，例如 `QF1`、`QF2`。
- 保留 QET 身份字段，尤其是 `QetTerminalUuid`、`QetInstanceId`、`QetElementUuid`。
- 不破坏现有工程端子、导线任务和后续布线匹配。
- 旧的本地占位生成逻辑只作为没有 QET 数据时的演示兜底。

## 数据职责

QET 负责：

- 2D 原理图中的设备、符号、端子、端子排和导线任务。
- 设备型号、端子号、端子排名称，例如 `UD`、`ID`。
- 设备与 3D 模型资产绑定。
- 端子的真实 `terminal_uuid`。

FreeCAD 负责：

- 真实 3D 设备实例的空间位姿。
- 导轨、线槽、柜面等装配宿主。
- 工程端子的 3D 坐标和出线方向。
- 设备与导轨的批量排布状态。
- 3D 布线路径和保存回写。

第一版仍遵守 2D/3D 协同约束：3D 端子绑定唯一依据是 `terminal_uuid`，3D 位姿以 `scene.FCStd` 为准，不从数据库反推 3D 位姿。

## 端子排批量排布

正式流程：

1. 用户在 FreeCAD 中选中一根已识别或已标记的导轨。
2. 点击 `3D手动布线` 面板中的 `批量端子排`。
3. 输入 QET 端子排名称或前缀，例如 `UD`、`ID`。
4. 输入端子片间距和起始偏移。
5. 系统扫描当前 `scene.FCStd` 中 QET 已导入的端子片设备。
6. 匹配端子排名称，例如 `UD:1`、`UD-2`、`ID_006`。
7. 按 QET 顺序字段或名称中的自然序号排序。
8. 沿导轨轴向排布这些真实端子片。
9. 写入轻量装配属性，不改变端子的 QET 绑定。

端子排匹配优先读取这些属性：

- `QetTerminalStripName`
- `QetTerminalBlockName`
- `QetTerminalGroupName`
- `QetStripName`
- `QetParentTerminalBlockName`

如果没有上述属性，则从对象 `Label` / `Name` 解析 `UD:1`、`ID-2` 这类名称。

端子排排序优先读取这些属性：

- `QetTerminalStripIndex`
- `QetTerminalIndex`
- `QetTerminalSequence`
- `QetTerminalOrder`
- `QetTerminalNo`
- `QetTerminalDisplay`

如果没有上述属性，则从对象名称中提取最后一个数字做自然排序。

## 小型断路器批量排布

正式流程：

1. 用户在 FreeCAD 中选中一根导轨。
2. 点击 `3D手动布线` 面板中的 `批量断路器`。
3. 输入 QET 设备前缀，例如 `QF`。
4. 输入设备间距和起始偏移。
5. 系统扫描当前 `scene.FCStd` 中 QET 已导入的真实设备实例。
6. 排除端子排端子片和旧的本地批量生成对象。
7. 按设备 `Label`、`Name`、`QetInstanceId` 等字段匹配前缀。
8. 按自然顺序排布，例如 `QF1`、`QF2`、`QF10`。
9. 保留设备下的工程端子和 QET 绑定关系。

断路器端子号来自 QET 传入的真实端子数据。参数窗口中的“兜底端子号”只在当前工程没有匹配 QET 设备、需要演示生成占位对象时使用。

## 旧兜底逻辑

为了保留开发调试和无 QET 数据演示能力，旧接口仍保留：

- `create_terminal_block(...)`
- `create_breakers(...)`

但正式按钮调用顺序是：

```text
先 layout_existing_terminal_block / layout_existing_devices
如果 updated_devices > 0，说明已排布 QET 真实对象
如果没有匹配对象，才回退 create_terminal_block / create_breakers
```

兜底生成对象可能产生 `local:*` 端子，只能用于 3D 演示和开发测试，不作为正式 QET 布线匹配的主流程。

## 装配属性

排布真实 QET 对象时，系统只写入轻量属性：

- `QetBatchAssemblyKind`
- `QetBatchAssemblyName`
- `QetBatchAssemblyMode = layout_existing`
- `QetBatchAssemblyOrder`
- `QetBatchAssemblyOffsetMm`
- `QetMountKind = rail`
- `QetMountHostName`
- `QetMountHostKind`

这些属性保存在 FreeCAD 文档里，用于后续刷新、诊断和显示，不扩展第一版数据库绑定表。

## 导轨定位规则

第一版使用导轨对象的 `QetCarrierAxis` 作为排列轴，默认 `x`。如果导轨带旋转，排列轴经过导轨 `Placement.Rotation` 转换。

放置公式：

```text
第 N 个对象位置 = 导轨 Placement.Base + 导轨轴向单位向量 * (起始偏移 + N * 间距)
```

当前实现重点保证批量排布稳定、身份不丢失。复杂 Assembly Joint、端子片端挡、隔板、跨接片、短接片规则暂不纳入第一版。

## UI

入口位于：

```text
QET模板 -> 3D手动布线
```

按钮：

- `批量端子排`
- `批量断路器`

参数窗口说明：

- `QET端子排名称/前缀`：正式工程用于匹配 QET 端子排，例如 `UD`、`ID`。
- `QET断路器前缀`：正式工程用于匹配 QET 已导入设备，例如 `QF`。
- `端子间距 / 断路器间距`：沿导轨方向的排布间距。
- `起始偏移`：从导轨基点开始的偏移。
- `兜底数量 / 兜底端子号`：只有找不到匹配 QET 对象时才用于生成演示对象。

执行成功后状态栏会区分：

- `已排布 QET 端子排`
- `已排布 QET 断路器`
- `未找到匹配的 QET ...，已兜底生成`

## 验收

1. 从 QET 点击 `3D视图` 打开 FreeCAD。
2. 树目录中已经存在 QET 导入的端子片或设备实例。
3. 选中导轨，点击 `批量端子排`。
4. 输入 `UD` 或 `ID`，确认后真实端子片沿导轨排布。
5. 排布后端子对象仍保留真实 `QetTerminalUuid`，不会变成 `local:*`。
6. 选中导轨，点击 `批量断路器`。
7. 输入 `QF`，确认后真实断路器沿导轨排布。
8. 保存后重新打开 `scene.FCStd`，设备位置保持。
9. 后续 `3D手动布线` 或 `3D布线连接` 能继续通过 `terminal_uuid` 匹配导线任务。

## 非目标

- 不做完整 SolidWorks Electrical / EPLAN 设备库。
- 不在 FreeCAD 中重新创建 QET 已经传入的正式设备。
- 不伪造 QET `terminal_uuid`。
- 不删除旧兜底生成函数，但普通工程主流程不依赖它。
- 不实现完整端子排电气跨接片、跳线、端挡和标记条规则。