feat: 增强自动布线路由错误提示

src/Mod/FreeCADExchange/AutoRouting.py

@@ -1373,7 +1373,14 @@ def route_eplan_connections_from_payload(doc, payload, options=None, prepared_la
                         "wire_uuid": _wire_item_value(item, "wire_id", "wire_uuid", "id"),
                         "wire_label": _wire_item_value(item, "wire_label", "wire_mark"),
                         "start_terminal_uuid": start_uuid,
+                        "start_element_uuid": _wire_item_value(item, "start_element_uuid"),
+                        "start_terminal_display": _wire_item_value(item, "start_terminal_display"),
+                        "start_device_label": _wire_item_value(item, "start_device_label"),
                         "end_terminal_uuid": end_uuid,
+                        "end_element_uuid": _wire_item_value(item, "end_element_uuid"),
+                        "end_terminal_display": _wire_item_value(item, "end_terminal_display"),
+                        "end_device_label": _wire_item_value(item, "end_device_label"),
+                        "endpoint_label": _wire_item_value(item, "endpoint_label"),
                         "error": error_text,
                     }
                 )
@@ -1458,6 +1465,24 @@ def _missing_endpoint_side_summary(sample):
     return "（缺失：{0}）".format(missing_sides[0])
 
 
+def _wire_sample_text(sample):
+    return (
+        str(sample.get("wire_label", "") or "").strip()
+        or str(sample.get("wire_uuid", "") or "").strip()
+        or "未知导线"
+    )
+
+
+def _endpoint_pair_text(sample):
+    endpoint_label = str(sample.get("endpoint_label", "") or "").strip()
+    if endpoint_label:
+        return endpoint_label
+    return "{0} -> {1}".format(
+        _missing_endpoint_label(sample, "start"),
+        _missing_endpoint_label(sample, "end"),
+    )
+
+
 def format_eplan_connection_route_report(report):
     message = "批量生成布线连接完成：routed={0}, collision_warnings={1}, missing_terminals={2}".format(
         report.get("routed", 0),
@@ -1503,6 +1528,13 @@ def format_eplan_connection_route_report(report):
     errors = report.get("errors", []) or []
     if errors:
         message += "\n首个错误：{0}".format(str(errors[0]))
+    error_sample = (report.get("error_samples") or [None])[0]
+    if error_sample:
+        message += "\n错误示例：导线 {0}，{1}：{2}".format(
+            _wire_sample_text(error_sample),
+            _endpoint_pair_text(error_sample),
+            error_sample.get("error", ""),
+        )
     collision_sample = (report.get("collision_samples") or [None])[0]
     if collision_sample:
         obstacle_text = (

tests/python/freecad_exchange_auto_routing_test.py

@@ -1688,6 +1688,42 @@ class AutoRoutingTest(unittest.TestCase):
         self.assertEqual("terminal-start", report["error_samples"][0]["end_terminal_uuid"])
         self.assertIn("different", report["error_samples"][0]["error"])
 
+    def test_route_eplan_connections_report_includes_readable_error_sample(self):
+        _install_fake_freecad()
+        terminal_objects, _wiring_objects, routing_network, auto_routing = _reload_modules()
+        app = sys.modules["FreeCAD"]
+        doc = FakeDocument()
+        terminal_objects.ensure_root_group(doc, "project-1")
+        _terminal(doc, terminal_objects, "TerminalStart", "terminal-start", app.Vector(0, 0, 0))
+        routing_network.create_route_carrier(
+            doc,
+            [app.Vector(0, 0, 20), app.Vector(100, 0, 20)],
+            project_uuid="project-1",
+            kind="WireDuct",
+        )
+        payload = {
+            "project_uuid": "project-1",
+            "wires": [
+                {
+                    "wire_id": "wire-bad",
+                    "wire_label": "N500",
+                    "start_element_uuid": "device-a",
+                    "start_terminal_uuid": "terminal-start",
+                    "start_terminal_display": "A1",
+                    "end_element_uuid": "device-a",
+                    "end_terminal_uuid": "terminal-start",
+                    "end_terminal_display": "A1",
+                }
+            ],
+        }
+
+        report = auto_routing.route_eplan_connections_from_payload(doc, payload)
+        message = auto_routing.format_eplan_connection_route_report(report)
+
+        self.assertEqual("device-a", report["error_samples"][0]["start_element_uuid"])
+        self.assertIn("错误示例：导线 N500", message)
+        self.assertIn("device-a/A1 (terminal-start) -> device-a/A1 (terminal-start)", message)
+
     def test_route_eplan_connections_counts_route_statuses_for_summary(self):
         _install_fake_freecad()
         terminal_objects, _wiring_objects, routing_network, auto_routing = _reload_modules()