From 8b01a4504b44f8148a7505e1a2fcb48fbae9e4f0 Mon Sep 17 00:00:00 2001
From: Zhaowenlong <zhaowenlong@gdngsk.com>
Date: Thu, 28 May 2026 11:34:23 +0800
Subject: [PATCH] fix: prefer terminal element uuid during import

---
 src/Mod/FreeCADExchange/TerminalImport.py     |  6 +-
 ...nge_terminal_import_template_slots_test.py | 79 +++++++++++++++++++
 2 files changed, 82 insertions(+), 3 deletions(-)

diff --git a/src/Mod/FreeCADExchange/TerminalImport.py b/src/Mod/FreeCADExchange/TerminalImport.py
index 8cf91aa..fc297d4 100644
--- a/src/Mod/FreeCADExchange/TerminalImport.py
+++ b/src/Mod/FreeCADExchange/TerminalImport.py
@@ -207,10 +207,10 @@ def _locate_device_group(doc, entry):
     element_uuid = entry["element_uuid"]
 
     device_group = None
-    if instance_id:
-        device_group = TerminalObjects.find_device_group_by_instance_id(doc, instance_id)
-    if device_group is None and element_uuid:
+    if element_uuid:
         device_group = DeviceImport._find_device_group(doc, element_uuid)
+    if device_group is None and instance_id:
+        device_group = TerminalObjects.find_device_group_by_instance_id(doc, instance_id)
 
     return device_group
 
diff --git a/tests/python/freecad_exchange_terminal_import_template_slots_test.py b/tests/python/freecad_exchange_terminal_import_template_slots_test.py
index 5fb8446..3cc5e51 100644
--- a/tests/python/freecad_exchange_terminal_import_template_slots_test.py
+++ b/tests/python/freecad_exchange_terminal_import_template_slots_test.py
@@ -348,6 +348,85 @@ class TerminalImportTemplateSlotPolicyTest(unittest.TestCase):
         self.assertEqual("terminal-b", end_terminals[0].QetTerminalUuid)
         self.assertEqual("device-b", end_terminals[0].QetElementUuid)
 
+    def test_import_prefers_terminal_element_uuid_over_conflicting_instance_id(self):
+        _install_fake_freecad()
+        terminal_import, terminal_objects, device_import = _reload_modules()
+
+        doc = FakeDocument()
+        device_import._ensure_document = lambda scene_path: doc
+        root = device_import._ensure_root_group(doc, project_uuid="project-1")
+
+        def add_device(element_uuid, instance_id):
+            device = doc.addObject("App::Part", "QETDevice_" + element_uuid)
+            root.addObject(device)
+            terminal_objects.ensure_string_property(
+                device,
+                "QetProjectUuid",
+                "QET Exchange",
+                "Project UUID",
+                "project-1",
+            )
+            terminal_objects.ensure_string_property(
+                device,
+                "QetElementUuid",
+                "QET Exchange",
+                "Element UUID",
+                element_uuid,
+            )
+            terminal_objects.ensure_string_property(
+                device,
+                "QetInstanceId",
+                "QET Exchange",
+                "Instance ID",
+                instance_id,
+            )
+            return device
+
+        correct_device = add_device("device-a", "instance-a")
+        wrong_instance_device = add_device("device-b", "instance-b")
+
+        report = terminal_import.import_terminals_from_payload(
+            {
+                "project_uuid": "project-1",
+                "devices": [
+                    {"element_uuid": "device-a", "instance_id": "instance-a"},
+                    {"element_uuid": "device-b", "instance_id": "instance-b"},
+                ],
+                "terminals": [
+                    {
+                        "terminal_uuid": "terminal-a",
+                        "element_uuid": "device-a",
+                        "instance_id": "instance-b",
+                        "terminal_display": "12",
+                    }
+                ],
+            }
+        )
+
+        correct_terminals = terminal_objects.collect_terminal_objects(
+            terminal_objects.ensure_terminal_group(
+                doc,
+                correct_device,
+                project_uuid="project-1",
+                instance_id="instance-a",
+            )
+        )
+        wrong_terminals = terminal_objects.collect_terminal_objects(
+            terminal_objects.ensure_terminal_group(
+                doc,
+                wrong_instance_device,
+                project_uuid="project-1",
+                instance_id="instance-b",
+            )
+        )
+
+        self.assertEqual(1, report["imported_terminals"])
+        self.assertEqual(1, len(correct_terminals))
+        self.assertEqual([], wrong_terminals)
+        self.assertEqual("terminal-a", correct_terminals[0].QetTerminalUuid)
+        self.assertEqual("device-a", correct_terminals[0].QetElementUuid)
+        self.assertEqual("instance-a", correct_terminals[0].QetInstanceId)
+
     def test_import_uses_slot_name_hint_to_match_template_slots(self):
         _install_fake_freecad()
         terminal_import, terminal_objects, device_import = _reload_modules()