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

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

目标

第一版只做当前项目可演示、可操作的批量装配能力：用户在 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。放置公式：

第 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。
• 不做完整端子排电气跨接片、跳线、短接片规则。