LightWork3D/docs/superpowers/specs/2026-06-02-batch-din-device-placement-design.md

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

目标

本功能用于 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(...)

但正式按钮调用顺序是：

先 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 转换。

放置公式：

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

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

UI

入口位于：

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。
• 不删除旧兜底生成函数，但普通工程主流程不依赖它。
• 不实现完整端子排电气跨接片、跳线、端挡和标记条规则。