硬體接線圖工作流程
將數據手冊和連接器圖面視為電氣真相的唯一來源。除非零組件照片上的焊盤標籤清晰可讀且方向明確，否則僅將其視為位置參考。
1. 建立連線合約
- 盤點所有零組件、連接器、接腳、訊號、電壓域、方向及要求的輸出格式。
- 記錄每個接腳定義的權威來源及修訂版本。若存在數據手冊或原理圖，請勿從產品照片推斷接腳分配。
- 在繪製前，將所有連線標準化為機器可讀的網表。同時使用物理接腳編號與訊號名稱。
- 明確標記未知、可選、保留、不連接及電源來源接腳。若安全關鍵的接腳定義或電壓未能解決，請在佈線前停止。
- 區分安裝/接線圖與原理示意圖。即使只向使用者顯示其中一種，也應透過相同的網表使其保持同步。
在解釋旋轉的電路板、鏡像視圖、底部照片或連接器對接面之前，請先閱讀source-truth-and-orientation.md。有關訊號和電源檢查，請閱讀electrical-rules.md。
2. 在佈線前規劃圖面
- 選擇 A4 或 A3 紙張，並預留標題、零組件、接腳說明、註解和圖例的區域。
- 將主控制器放置於視覺中心附近。將週邊設備放置在與其連接的控制器側附近。
- 將零組件圖像及其說明一起旋轉。將每個說明保持靠近對應的物理連接器。
- 當板端接頭過於密集時，使用緊湊的接腳說明。在旋轉或鏡像後保留確切的物理順序。
- 在佈線前將標籤移至空側。切勿穿過照片、標籤、接腳編號或相鄰的接觸符號進行佈線。
有關 A3 構圖、GPIO 說明和零組件卡片樣式，請閱讀layout-and-callouts.md。
3. 確定性佈線
- 除非專案明確要求其他風格，否則以正交方式佈線。
- 從標記端子或焊盤的邊界連接到其目的地的邊界。不要中途停止、消失在卡片下方或穿過接觸中心。
- 每條線路保留一個通道。切勿將兩個連接段放在同一個幾何線段上。
- 避免交叉。若無法避免交叉，請保持 90 度，使用可見的分隔約定，且絕不暗示連接點。
- 在端子符號下方繪製路徑，然後在路徑上方重新繪製端子填充、編號和標籤。在接觸邊緣保留可見的端點。
- 平行路徑之間至少保持設定的通道間距（含其光暈）。
- 套用visual-language.md中的穩定顏色對應；始終將顏色與訊號標籤配對。
每次進行實質性的佈線變更後，請使用 scripts/validate_wiring.py。將任何重疊、意外交叉、懸空端點、被遮蓋的標籤或無效的電氣連接視為失敗的候選方案。
4. 從可重複使用的 SVG 基元構建
- 當沒有專案原生模板時，從 wiring-a3-template.svg 開始。
- 將零組件照片保留在
assets/或專案資產目錄中，並透過相對路徑引用它們。 - 為路徑、端子、標籤、零組件和禁止佈線區域賦予穩定的 ID 和語義化的
data-*屬性。遵循svg-annotation-contract.md。 - 將路徑放置在端子與文字下方的專用圖層中。僅使用光暈將路徑與背景分離；請勿用它來隱藏另一條路徑。
- 保留可編輯的 SVG 作為原始檔。僅將 PNG/PDF 產生為用於審查的派生工件。
5. 分層驗證
- 執行結構性 SVG 解析與佈線驗證器。
- 驗證每個網表端點僅存在一次，且每條路徑終止於其宣告的兩個端點。
- 驗證電源方向、電壓相容性、共地、UART 交叉及匯流排特定要求。
- 根據實際顯示的方向驗證物理編號，包括 Pin 1 指示器和奇/偶數行。
- 渲染完整的圖面以及每個修改過連接器的特寫裁切。
- 以預期的列印尺寸檢查。接腳編號、訊號名稱、線路標識、端點接觸和警告必須保持清晰可讀。
- 每次 SVG 編輯後重新渲染；切勿僅憑原始檔檢查就報告成功。
使用 scripts/render_svg.py。在 Codex Desktop 中，當工作區依賴項可用時載入它們；渲染器也會自動檢測捆綁的 Node.js 和 Sharp 執行時期以產生 PNG 輸出。
在宣告完成前，請閱讀validation-gates.md。在修復現有圖面時，請閱讀failure-patterns.md。
6. 如實交付
- 交付可編輯的 SVG、渲染後的 PNG，並根據要求提供 PDF。
- 明確說明新增或變更連線的精確接腳到接腳對應。
- 說明哪些接腳定義已通過來源驗證，以及哪些假設仍存在。
- 僅當結構、電氣、佈線和視覺檢查全部通過時，才報告
completed。 - 當無法確定權威的接腳定義、電壓額定值、連接器方向或對接面解讀時，報告
blocked。 - 切勿聲稱視覺上看似合理的路徑能證明電氣正確性。