3. 项目文档体系与交付物标准

在三菱iQ-R项目验收与工程交付中，文档不是“程序写完后的附属品”，而是与程序、参数、硬件同等重要的交付对象。验收方通常无法逐行阅读梯形图，却一定会翻阅硬件配置图、I/O分配表、网络拓扑和测试记录。文档体系是否完整、规范、可追溯，直接决定项目能否顺利通过验收，也决定后期维护时能否快速定位问题。本节围绕六类核心交付物，说明其编制规范、相互引用关系以及完整性检查方法。

一、交付物体系的整体结构

iQ-R项目的文档体系可以按“硬件—接口—网络—程序—参数—验证”六个维度组织。硬件配置图回答“系统由哪些模块组成、装在哪个机架槽位”；I/O分配表回答“每个信号对应哪个模块的哪个点、地址是什么”；网络拓扑回答“各站点、交换机、上位机如何连接、走什么协议”；程序注释回答“程序里每个标签、每个程序块做什么”；参数文件回答“模块参数、网络参数、伺服参数的实际设定值”；测试记录回答“上述内容是否经过验证、结果如何”。六者不是并列关系，而是层层引用：I/O分配表引用硬件配置图的模块与槽位，程序注释引用I/O分配表的地址，测试记录引用前三者的对象与参数。任何一处不一致，都会在验收或排障时暴露出来。

二、硬件配置图的编制规范

硬件配置图不是简单的模块照片拼贴，而应是一张可核对、可追溯的系统结构图。图中至少应包含：机架编号与槽位编号、每个槽位安装的模块型号（如R04CPU、RJ71EN71、RX42C4、RY42NT）、模块的起始I/O地址、电源模块型号与容量、扩展机架连接关系。对于多机架系统，应标明主基板与扩展基板的连接电缆型号和长度。编制时建议采用“从左到右、从上到下”的槽位顺序，与GX Works3中“系统配置”窗口的显示顺序保持一致，便于验收时逐项核对。一个常见的完整性缺陷是只画了主基板而遗漏了扩展基板上的远程I/O模块，导致I/O分配表与实物不符。

三、I/O分配表的编制规范

I/O分配表是程序与现场设备之间的“字典”，其规范程度直接影响调试效率。一张合格的I/O分配表应包含以下字段：信号名称（中文描述）、软元件地址（如X0、Y10、D100）、模块型号与槽位、点号/通道号、信号类型（DI/DO/AI/AO）、正常状态（常开/常闭）、对应现场设备编号、备注。对于特殊模块，还应标注缓冲存储器（BFM）地址或工程值换算关系。例如，模拟量输入模块RJ71AD4的通道1对应地址U0\G1，量程0～10V对应0～4000数字量，这些信息应直接写入I/O分配表，而不是留到调试时临时查找。编制时建议按“输入区—输出区—模拟量区—特殊模块区”分段排列，并在表头注明程序版本号和日期。

四、网络拓扑与程序注释的规范

网络拓扑图应标明每个站点的站号、IP地址、子网掩码、通信协议（CC-Link IE Field、CC-Link IE Control、以太网、Modbus TCP等）、交换机端口连接关系、线缆类型与长度。对于CC-Link IE Field网络，还应标注网络刷新周期和站间同步设置。程序注释方面，iQ-R项目应做到“三层注释”：软元件注释（标签名）、程序块注释（功能说明）、网络注释（每段逻辑的作用）。标签命名建议采用“设备类型_功能_序号”的格式，如“MTR_Conveyor_Start”，避免使用X0、Y10这类无意义地址作为唯一标识。程序块注释应说明该块的输入条件、输出结果和关键中间变量，使维护人员无需逐行阅读即可理解逻辑意图。

五、参数文件与测试记录的规范

参数文件应导出为可读格式（如CSV或PDF），并注明参数来源（默认值/调整值/计算值）。对于伺服参数、定位参数、安全参数等关键设定，应记录调整前后的数值和调整原因。测试记录则应覆盖“单点测试—联锁测试—网络通信测试—异常测试”四个层次，每条记录包含测试项、测试条件、预期结果、实际结果、判定（合格/不合格）、测试人和日期。测试记录不是简单打勾，而应记录可复现的测试方法和观察到的现象。例如，网络通信测试应记录“断开站号3的网线，观察主站是否在设定时间内报出通信错误，错误代码是什么”，而不是只写“通信正常”。

六、交付物版本管理与完整性检查表

文档交付最容易被忽视的是版本一致性。程序修改后，I/O分配表和程序注释往往没有同步更新，导致验收时出现“程序里有这个地址，表里查不到”的情况。建议在项目根目录下建立“文档版本记录表”，记录每份文档的版本号、修改日期、修改内容和修改人。交付前使用以下检查表逐项确认：硬件配置图是否包含所有机架和模块；I/O分配表是否覆盖所有输入输出点和特殊模块通道；网络拓扑是否标明所有站点和协议参数；程序注释是否覆盖所有程序块和关键标签；参数文件是否导出且注明调整记录；测试记录是否覆盖单点、联锁、通信和异常测试。六项全部通过后，方可进行最终交付。

文档体系的最终目标不是“凑齐六份文件”，而是让任何一个具备iQ-R基础知识的工程师，仅凭这套文档就能理解系统结构、找到信号地址、复现测试过程、判断参数是否被改动。验收方检查文档时，本质上是在检查工程交付的完整性和可维护性。因此，编制文档时应始终以“他人能否独立使用”为标准，而不是以“自己能否看懂”为标准。在项目实践中，建议将文档编制与程序开发同步进行，每完成一个功能块就更新对应的I/O分配和注释，避免最后集中补文档时出现遗漏和错误。