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。

当前交换 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 导入工程端子时按下面顺序读取：

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(...)

但正式按钮调用顺序是：

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

装配视频复盘

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

用户装配视频提炼

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

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

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

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

甲方视频参考能力

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

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

后续装配优化方向

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

1. 面贴合可靠性

目标：

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

贴合计算原则：

移动面法向 -> 目标面反向法向
移动面参考点 -> 目标面参考点所在平面
最终位姿写入可移动父对象 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

入口位于：

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