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

## 目标

第一版只做当前项目可演示、可操作的批量装配能力：用户在 FreeCAD 中选中一根已标记的导轨后，可以批量插入端子片形成端子排，也可以批量插入小型断路器。系统按导轨方向等距放置对象，并为每个对象生成可布线工程端子。

本功能不做完整设备库、不扩展数据库绑定表、不替代 QET 现有 2D 设备/符号关联。2D 仍负责设备型号、端子号和导线任务；3D 只负责模型、位姿、端子空间点和装配状态。

## 范围

### 端子排

用户选择导轨后，输入端子排名称、端子数量、端子片宽度/间距和起始偏移。系统沿导轨方向生成：

- 一个端子排分组，例如 `XT1`
- 多个端子片实例，例如 `XT1_001`、`XT1_002`。这些实例同时写入标准 QET 设备语义，便于后续端子绑定和布线索引识别。
- 每片端子对应的工程端子，例如 `XT1:1`、`XT1:2`

正式主流程中，端子片模型资源应来自 QET 传入的设备/资产绑定。后端保留 `model_path` 参数，用于 QET 自动传入模型路径或开发调试兜底；普通用户参数窗口不要求手动选择模型文件。未传入模型路径时回退为脚本生成的简化几何。关键是位置整齐、命名清楚、可被布线模块发现。

### 小型断路器

用户选择导轨后，输入起始设备名、数量、单个宽度/间距和端子号模板。系统沿导轨方向生成：

- 多个设备实例，例如 `QF1`、`QF2`。对象名称使用 `QETDevice_QF1` 这类标准前缀，树目录 Label 仍显示 `QF1`。
- 每个设备的工程端子，例如 `QF1:1`、`QF1:2`、`QF1:3`、`QF1:4`、`QF1:5`、`QF1:6`

如果 2D 已经提供真实设备名和端子号，后续导入/绑定逻辑优先使用 QET 的 `terminal_uuid`；本功能生成的是第一版本地 3D 辅助对象，用于快速摆放和演示。

## 数据语义

- 不新增数据库字段。
- 3D 对象保存在 FreeCAD 文档中。
- 工程端子仍使用 `TerminalObjects.set_terminal_semantics(...)`。
- 批量生成的本地槽位端子使用 `local:<instance_id>:<terminal_no>`，避免伪造 QET terminal_uuid。
- 批量设备组写入 `QetProjectUuid`、`QetElementUuid`、`QetInstanceId` 和 `QetGroupKind=Device`，使它们能被现有端子导入/布线绑定逻辑找到。
- 当 QET 的 `2d_to_3d.json` 后续提供真实 `terminal_uuid + terminal_display` 时，布线/端子绑定逻辑按端子号匹配本地槽位，并把 `local:*` 提升为真实 QET `terminal_uuid`。
- 树目录显示名使用 `设备名:端子号`，方便设计人员辨认。
- 批量对象额外写入本地属性：
- `QetBatchAssemblyKind`
- `QetBatchAssemblyName`
- `QetMountHostName`
- `QetMountKind`
- `QetBatchSourceModelPath`，仅导入本地模型文件时写入可见几何对象

## 导轨定位规则

第一版使用导轨对象的 `QetCarrierAxis` 作为排列轴，默认 `x`。放置公式：

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

如果导轨对象带有旋转，排列轴会经过导轨 `Placement.Rotation` 转换。第一版先保证当前工程和内置导轨的稳定演示。

## UI

挂在 `QET模板 -> 3D手动布线` 面板，新增两个按钮：

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

点击按钮后弹出参数窗口，窗口内带默认参数：

- 端子排：`XT1`，10 片，5.2 mm 间距
- 小型断路器：`QF`，3 个，18 mm 间距，端子号 `1,2,3,4,5,6`

端子号支持用空格、英文逗号、中文逗号、分号分隔；重复端子号会被拒绝，避免生成两个同名接线点。
普通用户窗口不提供模型文件选择；模型文件由 QET 侧传入或由开发调试入口传入。不传入时使用脚本简化几何。

## 验收

1. 选中导轨后点击 `批量端子排`，生成 `XT1` 分组和端子片。
2. 在参数窗口中可调整端子排名称、数量、间距和起始偏移。
3. 每个端子片都有一个工程端子，Label 为 `XT1:n`。
4. 选中导轨后点击 `批量断路器`，生成 `QF1`、`QF2`、`QF3`。
5. 在参数窗口中可调整断路器前缀、数量、间距、起始偏移和端子号模板。
6. 每个断路器生成指定端子号。
7. 生成对象位于导轨方向上，间距正确。
8. 端子默认隐藏，但可被手动/自动布线模块按端子对象收集。
9. 如果 QET 已传入同一设备实例和端子号，`local:*` 槽位能被提升为真实 `terminal_uuid`，从而参与导线任务匹配。

## 非目标

- 不做完整 SolidWorks Electrical 设备库。
- 不自动读取所有 2D 设备属性批量生成真实设备。
- 不伪造 QET terminal_uuid；只有 QET 输入中存在真实端子 UUID 时才提升绑定。
- 不做复杂 Assembly Joint。
- 不做完整端子排电气跨接片、跳线、短接片规则。