3. 版本标识与命名规范

在Sysmac Studio项目中，版本治理的第一道防线不是Git，也不是备份策略，而是命名与标识本身。如果项目文件叫“新建项目_最终版_改2.smc2”，程序块叫“P_1”“P_2”，注释只写“修改”，那么无论后续使用多么完善的版本管理工具，都无法建立可靠的追溯链。本节要解决的核心问题是：如何用一套可执行的规则，让每个项目文件、每个程序块、每条关键注释都能自解释、可排序、可检索、可追溯。

一、版本号规则：让版本可比较、可排序

Sysmac项目建议采用四段式版本号：主版本.次版本.修订号.构建号，例如 V2.3.1.045。四段含义如下：

• 主版本：设备整体功能架构发生不兼容变更时递增，如新增EtherCAT从站拓扑、改变安全逻辑架构、更换NJ/NX控制器型号。
• 次版本：新增功能或程序块，但接口保持兼容时递增，如新增一段配方管理逻辑、增加HMI交互变量。
• 修订号：缺陷修复、参数调整、注释完善等小范围变更时递增。
• 构建号：每次在Sysmac Studio中执行“生成”或下载到控制器时递增，用于区分同一修订号下的多次编译产物。

需要特别强调的是，构建号必须与Sysmac Studio的编译事件绑定，而不是与人工保存绑定。建议在项目属性或版本记录表中记录每次构建对应的日期、操作者和变更摘要。例如：

V1.0.0.001  2025-03-01  初始导入，NJ501-1300，EtherCAT 12从站
V1.0.0.002  2025-03-02  修正X轴原点回归参数
V1.1.0.003  2025-03-05  新增配方切换程序块 FB_Recipe
V1.1.1.004  2025-03-07  修复配方切换时HMI变量未刷新问题

这样，当现场反馈“V1.1.0.003版本配方切换异常”时，可以立即定位到具体构建，并对比V1.1.1.004的修复内容。

二、项目文件命名：从文件名读出项目身份

Sysmac Studio项目文件扩展名为.smc2，默认文件名往往缺乏信息。建议采用以下命名结构：

项目代号_设备名称_控制器型号_版本号_日期.smc2

例如：PKG01_封箱机_NJ501-1300_V1.1.1.004_20250307.smc2

其中项目代号用于区分产线或客户，设备名称用于区分同一产线内的不同工位，控制器型号用于避免下载时选错目标，版本号与日期用于排序和追溯。对于需要交付给客户的版本，可在文件名末尾追加_REL表示发布版，_DBG表示调试版，_BAK表示备份版。注意不要使用“最终”“最新”“确认”等无法排序的词汇。

三、程序块命名：按功能分层，按类型加前缀

Sysmac Studio支持程序（Program）、功能块（FB）、功能（FUN）、结构体（DUT）等多种POO（POU）。命名应体现类型前缀+功能域+具体对象三层结构。推荐前缀如下：

功能域建议使用统一缩写，如Axis表示轴控、Recipe表示配方、Alarm表示报警、HMI表示人机交互。具体对象名应使用英文或拼音，避免中文和特殊符号。例如FB_AxisControl_X1表示X1轴控制功能块，FB_Recipe_ProductA表示产品A配方功能块。

对于安全程序，建议额外增加SF_前缀，如SF_EStop，以便在交叉引用和权限管理中快速筛选。对于库文件中的通用功能块，建议增加LIB_前缀，如LIB_FB_PID，避免与项目内自定义块混淆。

四、注释规范：让注释成为可追溯的证据

Sysmac Studio中注释分为变量注释、程序块注释和网络注释。变量注释应说明物理含义、单位、有效范围，例如：

g_Axis1_Position  REAL  单位:mm  范围:0~500.0  X1轴当前位置
g_Recipe_Index    INT   范围:0~9      当前配方编号
g_Alarm_Code      WORD  位定义见ST_Alarm  当前报警字

程序块注释应包含功能描述、输入输出说明、版本变更记录。例如在FB_AxisControl头部注释中写明：

功能：X1轴使能、回零、点动、定位控制
输入：bEnable, bHome, bJogFwd, bJogRev, rTargetPos
输出：bReady, bBusy, bError, rActPos
版本：V1.1.1.004  2025-03-07  修复回零完成信号抖动

网络注释应说明该段逻辑的判断条件与预期结果，而不是重复指令名称。例如不要写“比较”，而应写“当配方编号变化且轴未运行时，触发配方切换”。

五、版本标识与命名规范的整体关系

下图展示了从项目文件到程序块、变量、注释的标识层级关系，以及版本号如何贯穿其中，形成可追溯的标识链。

这张图的核心含义是：版本号不是孤立地写在文件名里，而是从项目文件层向下贯穿到程序块、变量和注释。当现场出现问题时，可以沿着“文件名→版本号→程序块→变量→注释”的路径逐层定位，而不是在大量无命名规则的POO中盲目搜索。

六、落地检查清单

在项目启动阶段，建议将以下检查项纳入Sysmac Studio项目模板或团队规范：

• 项目文件名是否包含项目代号、设备名称、控制器型号、版本号和日期？
• 版本号是否采用四段式，且构建号是否与编译事件对应？
• 所有程序块是否按PRG_、FB_、FUN_、ST_前缀命名？
• 全局变量是否以g_开头，局部变量是否以l_开头？
• 关键变量注释是否包含物理含义、单位和有效范围？
• 功能块头部是否包含功能描述、输入输出说明和版本变更记录？
• 网络注释是否说明了判断条件和预期结果，而非重复指令名称？

命名规范的价值不在于“好看”，而在于降低沟通成本和排障时间。一个现场工程师看到FB_AxisControl_X1，就能立即知道这是X1轴控制功能块；看到V2.3.1.045，就能判断这是主版本2下的第3次功能新增、第1次修订、第45次构建。这种可识别性，正是版本治理能够持续运转的基础。