硬件接线图工作流程
将数据手册和连接器图纸视为电气真理源。将组件照片仅视为放置证据，除非其焊盘标签清晰可辨且方向明确。
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 交叉以及特定总线要求。
- 根据实际显示的方向验证物理编号，包括引脚 1 指示符和奇/偶行。
- 渲染完整图纸以及每个修改过的连接器的特写裁剪图。
- 以预期的打印尺寸检查。引脚编号、信号名称、导线标识、端点接触和警告必须保持清晰可读。
- 每次 SVG 编辑后重新渲染；切勿仅凭源文件检查就报告成功。
使用 scripts/render_svg.py。在 Codex Desktop 中，当可用时加载工作区依赖项；渲染器也会自动检测捆绑的 Node.js 和 Sharp 运行时以输出 PNG。
在宣布完成之前，请阅读 validation-gates.md。在修复现有图表时，请阅读 failure-patterns.md。
6. 如实交付
- 交付可编辑的 SVG、渲染的 PNG，以及根据请求交付 PDF。
- 陈述新添加或更改连接的精确引脚到引脚映射。
- 说明哪些引脚排列已通过源验证，以及哪些假设仍然存在。
- 仅当结构、电气、布线和视觉关卡全部通过时，报告
completed。 - 当无法建立权威的引脚排列、额定电压、连接器方向或配合面解释时，报告
blocked。 - 切勿声称视觉上合理的路线证明了电气正确性。