feat: 展示布线路径源对象示例

docs/FreeCAD 3D自动布线设计方案.md

@@ -348,6 +348,8 @@ QetWiringCutOutBridgeExtensionMm = 20.0
 
 生成导线的 `QetRouteTrackJson` 会记录实际经过的 carrier。carrier 如果来自线槽、过线孔、支撑面或端子接入源对象，route track 中还会保留 `source_name`、`source_label`、`source_kind`，用于手动测试时追踪“这段线实际走过哪个 3D 源对象”。
 
+批量生成布线连接后，面板/控制台报告会从第一条可追踪路径中提取一条“路径示例”，显示导线经过的源对象标签，便于快速确认线路是否进入了预期线槽、过线孔和支撑面。
+
 ### 5.3 布线连接功能
 
 已完成：
@@ -422,6 +424,7 @@ tests/python/freecad_exchange_auto_routing_test.py
 24. 自动生成的线槽、过线孔和支撑面 carrier 会在源对象移动、缩放、删除或失效后刷新/清理。
 25. `WiringCutOut` 会在穿孔方向外扩虚拟路径，用于桥接开孔两侧附近的线槽或支撑面网络，并支持通过 `QetWiringCutOutBridgeExtensionMm` 按对象调整外扩距离。
 26. `QetRouteTrackJson` 会在 carrier 有源对象元数据时保存 `source_name`、`source_label`、`source_kind`，方便核对导线实际走过的线槽、过线孔或支撑面。
+27. 批量布线报告会显示一条路径示例，列出首条可追踪导线经过的源对象标签。
 
 已完成 FreeCAD smoke：
 

src/Mod/FreeCADExchange/AutoRouting.py

@@ -1689,6 +1689,42 @@ def _endpoint_pair_text(sample):
     )
 
 
+def _route_source_labels(route_track, limit=5):
+    labels = []
+    seen = set()
+    if not isinstance(route_track, dict):
+        return labels
+    for segment in route_track.get("segments", []) or []:
+        carrier = segment.get("carrier", {}) if isinstance(segment, dict) else {}
+        if not isinstance(carrier, dict):
+            continue
+        label = (
+            str(carrier.get("source_label", "") or "").strip()
+            or str(carrier.get("source_name", "") or "").strip()
+        )
+        if not label or label in seen:
+            continue
+        seen.add(label)
+        labels.append(label)
+        if len(labels) >= int(limit or 0):
+            break
+    return labels
+
+
+def _route_source_sample_text(report):
+    for route in report.get("routes", []) or []:
+        if not isinstance(route, dict):
+            continue
+        labels = _route_source_labels(route.get("route_track", {}))
+        if not labels:
+            continue
+        return "路径示例：导线 {0} 经过 {1}。".format(
+            _wire_sample_text(route),
+            "、".join(labels),
+        )
+    return ""
+
+
 def format_eplan_connection_route_report(report):
     message = "批量生成布线连接完成：routed={0}, collision_warnings={1}, missing_terminals={2}".format(
         report.get("routed", 0),
@@ -1731,6 +1767,9 @@ def format_eplan_connection_route_report(report):
     total_length_mm = float(report.get("total_length_mm", 0.0) or 0.0)
     if total_length_mm > 0.0:
         message += "\n布线连接总长度：{0:.1f} mm。".format(total_length_mm)
+    route_source_sample = _route_source_sample_text(report)
+    if route_source_sample:
+        message += "\n{0}".format(route_source_sample)
     errors = report.get("errors", []) or []
     if errors:
         message += "\n首个错误：{0}".format(str(errors[0]))

tests/python/freecad_exchange_auto_routing_test.py

@@ -1941,6 +1941,32 @@ class AutoRoutingTest(unittest.TestCase):
         self.assertEqual(report["total_length_mm"], report["routes"][0]["length_mm"])
         self.assertIn("总长度", message)
 
+    def test_route_report_includes_route_source_sample_when_available(self):
+        _install_fake_freecad()
+        _terminal_objects, _wiring_objects, _routing_network, auto_routing = _reload_modules()
+        report = {
+            "routed": 1,
+            "collision_warnings": 0,
+            "skipped_missing_terminal": 0,
+            "routes": [
+                {
+                    "wire_label": "N4111",
+                    "route_track": {
+                        "segments": [
+                            {"carrier": {"kind": "TerminalAccess", "source_label": "QF1:A1"}},
+                            {"carrier": {"kind": "WireDuct", "source_label": "线槽A"}},
+                            {"carrier": {"kind": "WiringCutOut", "source_label": "过线孔A"}},
+                            {"carrier": {"kind": "WireDuct", "source_label": "线槽A"}},
+                        ]
+                    },
+                }
+            ],
+        }
+
+        message = auto_routing.format_eplan_connection_route_report(report)
+
+        self.assertIn("路径示例：导线 N4111 经过 QF1:A1、线槽A、过线孔A。", message)
+
     def test_route_eplan_connections_report_keeps_route_identity_and_diagnostics(self):
         _install_fake_freecad()
         terminal_objects, _wiring_objects, routing_network, auto_routing = _reload_modules()