LightWork3D/docs/superpowers/specs/2026-05-29-face-contact-snap-design.md

面贴合装配辅助设计

背景

CAD 用户在 FreeCAD 中摆放导轨、线槽和设备时，需要让两个接触面刚好贴合，避免穿模或悬空。FreeCAD 原生 变换 可以移动旋转对象，但不会自动判断面接触；Assembly 工作台可以做装配约束，但对当前 QET 演示流程偏重。

目标

在 QET模板 -> 3D手动布线 面板增加一个轻量装配辅助按钮：贴合到选中面。

用户先选择目标承载面，再选择要移动对象的接触面，点击按钮后：

• 沿第一个目标面的法向移动第二个对象，使第二个选择面落到目标面的同一平面上。
• 尽量让第二个选择面的法向与第一个选择面的反向对齐。
• 保持第二个对象原来的切向位置，不把对象横向拉到目标面的拾取点。
• 操作完成后恢复当前 QET 工程为活动文档。
• 不写数据库，不改 2D/3D 绑定表，不影响导线任务。

适用场景

• 导轨背面贴合机柜安装板。
• 线槽背面或底面贴合机柜安装板。
• 设备背面或卡扣接触面贴合导轨安装面。

交互

推荐流程：

1. 在 3D 视图中选择机柜、导轨或线槽上的目标安装面。
2. 点击 设为贴合目标面。
3. 选择要移动对象上的接触面。
4. 点击 贴合到选中面。
5. 对同一个目标面连续摆放多个设备时，只重复第 3、4 步。

兼容流程：

1. 同时选择两个面，第一个是目标面，第二个是要移动对象的接触面。
2. 点击 贴合到选中面。

如果用户只选中了一个对象而没有选中具体面，系统会尝试使用该对象面积最大的平面作为贴合面。这是为了降低机柜板、导轨、线槽这类规则模型的选面难度；复杂设备仍建议精确选择真实安装面。

如果方向不理想，用户可以先用 FreeCAD 旋转视图、隐藏遮挡物或透明化对象来选面。不要为了选面而旋转模型本体。

第一版只接受两个面。多选多个设备、多个面时，系统不能唯一判断哪个对象应该移动、哪个面是目标、是否要同时满足多个约束，因此会直接提示错误。多面贴合属于完整 Assembly 约束求解范围，不放进这个轻量按钮。

第一版不做多约束求解，不自动识别“哪个面是背面”，也不保存永久装配约束。它只执行一次几何位姿调整。

错误处理

• 少于两个面：提示用户先选目标面，再选移动对象接触面。
• 多于两个面：提示只能选择两个面。
• 第二个选择对象没有可移动 Placement：提示对象不能移动。
• 无法读取面中心或法向：提示请选择有效模型面。
• 已设置目标面后又选中多个移动面：提示只选择一个接触面。

测试

• 选择两个面后，移动对象应只沿目标面法向平移，消除法向间距。
• 多选三个或更多面时应报错。
• 已设置目标面后，只选择一个接触面即可贴合。
• 选择内部子零件面时，应移动 QET 设备或载体根对象，而不是只移动内部 Shape。
• 贴合后应重新选中被移动的根对象，保证后续 FreeCAD 变换 从新坐标开始。
• 只选对象时，可用最大平面作为辅助贴合面。
• 导入类操作或贴合操作后，App.ActiveDocument 仍应是当前 QET 工程。