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

## 目标

本功能用于 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`。

当前交换 JSON 中，正式端子优先来自 `devices[].terminals[]`。顶层 `terminals[]` 可以为空，不能因此判断 QET 没有传端子。导线任务的 `start_terminal_uuid / end_terminal_uuid` 也使用同一套真实端子 UUID。

FreeCAD 负责：

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

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

## 端子导入顺序

FreeCAD 导入工程端子时按下面顺序读取：

```text
1. 顶层 terminals[]
2. devices[].terminals[]
3. wires[] 中的起点/终点端子，仅作为缺失端子的兜底补齐
```

如果 `devices[].terminals[]` 已经包含某个导线端点，`wires[]` 不会重复生成同一个端子。正式工程中生成的工程端子必须保留 QET 传入的 `terminal_uuid`，包括 `element_uuid:terminal_uuid` 这种复合字符串，不允许转换为 `local:*`。

## 端子排批量排布

正式流程：

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 Terminals` 分组。工程端子和端子分组也会携带 `QetInstanceId / QetElementUuid`，不能只按这些字段判断为设备，否则 `QF1:1` 这类端子会被误当成断路器一起排布。

断路器端子号来自 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、端子片端挡、隔板、跨接片、短接片规则暂不纳入第一版。

## 装配视频复盘

本节作为后续 3D 装配优化的对比基准。装配相关需求、问题复盘和验收差异优先沉淀到本文档，再拆分为具体实现计划。

### 用户装配视频提炼

用户视频前半段体现的目标流程：

1. 先按真实设备和实物安装关系确认 3D 模型是否匹配。
2. 对设备补充可复用的装配脚点、连接点或接线点。
3. 设备脚点制作完成后，保存为可复用 `.FCStd` 模块。
4. 后续工程中再次插入该设备时，自动带出脚点、端子和装配语义。
5. 装配时可使用 FreeCAD 原生 `切换透明度`、`显示/隐藏所选`，便于选中柜板、导轨、线槽和设备背面。
6. 按步骤导入设备并完成贴合，避免只靠人工拖拽。

当前 FreeCAD 二开需要重点解决的问题：

- 面不容易选中，尤其是柜内导轨、线槽、设备背面被遮挡时。
- 旋转模型后再贴合，容易出现一部分贴合、一部分穿模或悬空。
- 贴合时如果只移动可视子对象，父对象 `Placement` 没同步，后续使用 `变换` 会回到旧位置。
- 多选多个设备面参与贴合不合理，约束语义不清，会导致算法不知道哪个面是移动面。
- 线槽、导轨贴合后仍需要能二次修改长度，并保持与柜板的贴合关系。
- FreeCAD 任务面板和原生 `变换` 任务框会冲突，普通用户需要一键关闭当前面板并进入原生变换。

### 甲方视频参考能力

甲方视频中可参考的装配体验：

- 柜体、导轨、线槽、安装板可透明显示，便于从柜内选择目标面；透明化优先复用 FreeCAD 原生右键菜单能力。
- 对象树、属性面板和三维操纵器联动，用户能明确看到当前选中的对象和坐标。
- 装配过程使用面、边、点作为参考，而不是单纯输入绝对坐标。
- 设备沿导轨或安装板成组排列，位置规则清晰，适合端子排、断路器、继电器等电气元件。
- 贴合后仍能继续微调距离、方向和局部偏移。
- 电气装配关注柜板、导轨、线槽、设备安装面，不需要第一阶段实现完整机械 CAD 装配约束。

## 后续装配优化方向

后续装配能力优先向 SolidWorks Electrical / EPLAN 的电气柜装配体验靠拢，但第一阶段只做电气常用能力，不做完整机械装配工作台。

### 1. 面贴合可靠性

目标：

- 目标面和移动面只允许一对一贴合。
- 如果用户已点击 `设为贴合目标面`，后续只能再选一个移动面。
- 如果用户一次选择两个面，按选择顺序解释为：第一个目标面，第二个移动面。
- 如果选择超过两个面，直接提示重新选择，不执行贴合。
- 贴合时同时更新父级可移动对象的 `Placement`，避免可视位置和对象坐标脱节。

贴合计算原则：

```text
移动面法向 -> 目标面反向法向
移动面参考点 -> 目标面参考点所在平面
最终位姿写入可移动父对象 Placement
```

### 2. 旋转模型后的贴合

目标：

- 用户为了选面临时旋转设备后，贴合仍能根据真实面法向计算旋转和位移。
- 不再只做单轴平移。
- 贴合完成后设备安装面应整体与目标面共面，不允许局部穿模。
- 用户可设置 `贴合间距`，0 mm 表示完全贴合，正值表示沿目标面法向预留距离。
- 已贴合对象保存 `QetMountHostNormalJson` 和 `QetMountOffsetMm`，后续选择对象后可点击 `应用贴合间距` 做二次调节。
- 如果模型法向与现场直觉相反，选择已贴合对象后点击 `反转贴合方向`，再应用贴合间距。

验收：

- 电流互感器、小型断路器、端子片旋转后，仍可贴到导轨或柜板。
- 贴合后使用 FreeCAD 原生 `变换`，对象从当前贴合位置继续移动，不跳回旧位置。
- 在 `3D手动布线` 面板中选择对象后点击 `关闭面板并变换`，系统先关闭当前任务面板，再调用 FreeCAD 原生 `Std_TransformManip`。

### 3. 导轨、线槽、柜板宿主语义

装配宿主分为：

- `cabinet`：柜板、安装板、门板等。
- `rail`：DIN 导轨。
- `wire_duct`：线槽。
- `device`：已经装配好的设备，可作为局部参考。

宿主对象应保存：

- `QetCarrierKind`
- `QetCarrierAxis`
- `QetCarrierBaseLength`
- `QetMountMode`
- `QetMountHostName`
- `QetMountHostKind`
- `QetMountContactSubElement`
- `QetMountHostSubElement`
- `QetMountLocalBaseJson`
- `QetMountHostBaseJson`

这些属性用于保存重开、刷新宿主装配和后续自动布线。

### 4. 长度二次调节

导轨和线槽长度调整规则：

- 导入时可设置初始长度。
- 贴合到柜板后仍可修改长度。
- 修改长度时保持宿主贴合面不变。
- 长度变化应优先沿 `QetCarrierAxis` 扩展。
- 如果对象是导入的 FCStd/STEP 组合体，优先修改带 `QetCarrierBaseLength` 的父级载体对象，不应误选内部子零件。

### 5. 设备模板化与复用

设备模板应包含：

- 真实几何模型。
- 安装接触面或装配脚点。
- 工程端子 LCS。
- 端子出线方向。
- 可选局部出线路径。

保存为 `.FCStd` 后，QET 再次导入同型号设备时，应复用这些模板语义。正式导线匹配仍以 QET 传入的 `terminal_uuid` 为准，不使用 `local:*` 作为正式端子身份。

### 6. 电气装配优先级

优先实现：

1. 导轨贴柜板。
2. 线槽贴柜板。
3. 端子排沿导轨排列。
4. 小型断路器沿导轨排列。
5. 电流互感器、继电器等设备贴导轨或柜板。
6. 贴合后的长度调节和刷新宿主装配。

暂不优先实现：

- 完整机械装配 Joint。
- 螺钉、孔、螺纹的精确机械配合。
- 复杂运动学约束。
- 完整 SW Mechanical 级别的 Mate 系统。

## 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`，包括 `element_uuid:terminal_uuid` 这种 QET -> FreeCAD 交换身份，不会变成 `local:*`。
6. 选中导轨，点击 `批量断路器`。
7. 输入 `QF`，确认后真实断路器沿导轨排布。
8. 保存后重新打开 `scene.FCStd`，设备位置保持。
9. 后续 `3D手动布线` 或 `3D布线连接` 能继续通过 `terminal_uuid` 匹配导线任务。

## 非目标

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