LightWork3D/docs/superpowers/plans/2026-06-17-freecad-terminal-access-routing.md

FreeCAD Terminal Access Routing Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 参考 SOLIDWORKS Electrical 3D 的 CPoint/RPoint 思路，把 FreeCAD 自动布线的端子出线方向、出线长度和 TerminalAccess 接入路径做成可诊断、可测试、可手动验收的工程规则。

Architecture: 第一阶段保留现有 RoutingNetwork.py 作为路径网络核心，但把端子出线规则集中到少量函数：显式出线方向优先，其次 LCS 方向，再通过设备包围盒和候选方向做校正。AutoRouting.py 继续消费 terminal_access_path_points_with_network_access()，诊断数据写入 route/report，面板和文档读取这些字段。

Tech Stack: FreeCAD Python API, src/Mod/FreeCADExchange, unittest, FreeCADCmd.exe

---

Task 1: 出线长度上限和方向诊断

Files:

• Modify: src/Mod/FreeCADExchange/RoutingNetwork.py

• Modify: src/Mod/FreeCADExchange/AutoRouting.py

• Test: tests/python/freecad_exchange_auto_routing_test.py

• Step 1: Write failing tests

Add tests that create a terminal inside a large device box and assert that the default access path does not extend indefinitely through the full box. Add a second test that verifies the access diagnostics include the selected direction, requested exit length, actual exit length, and whether the length was capped.

• Step 2: Run focused tests

Run:

python -B -m unittest tests.python.freecad_exchange_auto_routing_test.AutoRoutingTest

Expected before implementation: the new tests fail because current bbox fallback can return a long exit segment and route diagnostics do not expose capped length metadata.

• Step 3: Implement minimal routing rule

Add terminal_exit_max_length option with a conservative default. The device-aware exit point should cap bbox-derived length and record diagnostics when the cap is reached. Keep Chinese comments near non-obvious engineering rules.

• Step 4: Verify

Run the same focused tests. Expected: PASS.

Task 2: 显式端子出线方向

Files:

• Modify: src/Mod/FreeCADExchange/TerminalObjects.py

• Modify: src/Mod/FreeCADExchange/RoutingNetwork.py

• Test: tests/python/freecad_exchange_auto_routing_test.py

• Step 1: Write failing tests

Add tests that set a terminal property such as QetTerminalExitDirectionJson={"x":1,"y":0,"z":0} and verify the access path uses that vector instead of LCS +Z.

• Step 2: Implement explicit direction reader

Add a small helper that reads explicit direction JSON or comma-separated text, normalizes it, and falls back to current LCS direction when missing or invalid.

• Step 3: Verify

Run the focused tests and full auto-routing test module.

Task 3: TerminalAccess 接入主路径质量

Files:

• Modify: src/Mod/FreeCADExchange/RoutingNetwork.py

• Modify: src/Mod/FreeCADExchange/AutoRouting.py

• Test: tests/python/freecad_exchange_auto_routing_test.py

• Step 1: Write failing tests

Add tests where both a main UserPath/WireDuct and a fallback RoutingRange exist. Assert TerminalAccess prefers the main path unless outside max distance.

• Step 2: Improve target selection diagnostics

Expose target kind, target label, distance, primary segment count, and fallback reason in route diagnostics.

• Step 3: Verify

Run focused and full routing tests.

Task 4: 文档和运行目录同步

Files:

• Modify: docs/FreeCAD 机柜装配操作文档.md

• Modify: docs/FreeCAD 端子显示连线保存回写开发文档.md

• Runtime copy: D:\fc\run-FreeCAD-1.1.1\Mod\FreeCADExchange

• Step 1: Update Chinese docs

Document terminal exit direction, explicit direction property, exit length cap, TerminalAccess target metadata, and manual testing steps.

• Step 2: Sync runtime plugin

Run:

robocopy D:\LightWork3D\src\Mod\FreeCADExchange D:\fc\run-FreeCAD-1.1.1\Mod\FreeCADExchange /E /NFL /NDL /NJH /NJS /NP

Robocopy return code 0 or 1 is acceptable.

• Step 3: FreeCADCmd verification

Run:

D:\fc\run-FreeCAD-1.1.1\bin\FreeCADCmd.exe -c "import sys; sys.path.insert(0, r'D:\fc\run-FreeCAD-1.1.1\Mod\FreeCADExchange'); import AutoRouting, RoutingNetwork, TerminalObjects; print('freecad_exchange_import_ok')"

Expected: freecad_exchange_import_ok.

Task 5: TerminalAccess 端点设备避让

Files:

• Modify: src/Mod/FreeCADExchange/RoutingNetwork.py

• Test: tests/python/freecad_exchange_auto_routing_test.py

• Docs: docs/FreeCAD 机柜装配操作文档.md

• Step 1: Write failing test

Add a local-route terminal case where the short TerminalAccess segment from the local route exit to a UserPath would re-enter the terminal parent device bbox.

• Step 2: Implement endpoint-device avoidance

When generating TerminalAccess carriers, test only the short access-to-target segment against the terminal parent bbox. If the direct orthogonal path crosses that bbox, choose the shortest dogleg candidate outside the bbox and mark QetTerminalAccessAvoidedEndpointDevice=1.

• Step 3: Verify and document

Run the focused TerminalAccess tests and document the manual-test property.