3. 参数配置文档规范

参数配置文档是SOP与系统联机验收的核心交付物,其规范性直接决定后续运维、排故与变更的可追溯性。本节从文档结构标准、参数命名规则、版本控制要求与变更记录模板四个维度建立统一规范。

规范前置原则:所有参数文档必须在系统联调前完成初版评审,避免“边调边写”导致的遗漏与不一致。

3.1 文档结构标准

每份参数配置文档应遵循固定的章节树结构,确保跨项目、跨系统的文档具有一致的查找路径。推荐采用三级标题结构:

层级 章节编号 章节名称 内容说明
一级 1 概述 文档目的、适用范围、参考标准
一级 2 系统环境 硬件/软件版本、网络拓扑、依赖服务
一级 3 参数配置清单 按子系统/模块分节,每节包含参数表
二级 3.1 通信参数 IP、端口、协议、超时时间
二级 3.2 业务参数 阈值、开关、策略标识
二级 3.3 安全参数 认证方式、密钥、访问控制列表
一级 4 参数依赖关系 参数间耦合说明、启动顺序约束
一级 5 验证用例 每个关键参数的验收测试步骤
一级 6 变更历史 版本号、日期、变更人、变更说明
结构检查清单:
  • 每个参数条目必须包含:参数全名、数据类型、默认值、当前值、取值范围、生效方式(重启/热加载)。
  • 文档末尾必须附《参数索引表》,按字母顺序列出所有参数及其所在章节。
参数配置文档标准结构树 参数配置文档 1. 概述 2. 系统环境 3. 参数配置清单 4. 依赖关系 3.1 通信参数 3.2 业务参数 3.3 安全参数 说明:每个一级章节可继续展开,但深度不超过4级。参数表必须使用统一模板。 变更历史(第6章)为必选章节,即使首次发布也需写入“V1.0 初始版本”。

3.2 参数命名规则

参数名称是文档与系统之间的唯一标识符。命名必须遵循以下规则,避免歧义与冲突:

  • 全局唯一性:同一系统内不允许出现两个同名参数,即使属于不同模块。
  • 层级前缀法:格式为 系统_子系统_模块_参数名,例如 MES_WH_RCV_TIMEOUT。
  • 禁止使用特殊字符:仅允许字母(A-Z, a-z)、数字(0-9)和下划线(_),不允许空格、连字符、中文。
  • 大小写敏感:统一使用大写字母,单词间用下划线分隔。
  • 语义自解释:参数名应能直接反映其用途,避免缩写歧义。
示例(正确) 示例(错误) 错误原因
SCADA_ALM_HIGH_TEMP scada-alarm-1 使用连字符、小写、无意义数字
PLC_CONV_SPEED_SET plc速度设定 包含中文、大小写混用
WMS_STORE_ZONE_ID WMS_Zone 大小写混用,未体现层级
命名冲突风险:当两个子系统使用相同参数名但含义不同时,必须在参数名前增加子系统缩写。例如 OEE_TARGET_RATE 与 QC_TARGET_RATE 不可简化为 TARGET_RATE。
参数命名规则层级结构 系统 子系统 模块 参数名 MES_WH_RCV_TIMEOUT MES WH RCV TIMEOUT 完整参数名:MES_WH_RCV_TIMEOUT → 制造执行系统_仓库_收货_超时时间(单位:秒)

3.3 版本控制要求

参数配置文档必须纳入版本管理,与系统代码版本解耦但保持关联。核心要求如下:

  • 版本号格式:采用 V主版本.次版本.修订号,例如 V2.1.3。
  • 主版本递增:参数结构变更、参数删除或新增模块时递增。
  • 次版本递增:参数默认值变更、取值范围调整时递增。
  • 修订号递增:仅文档描述修正、格式调整、注释补充时递增。
  • 版本关联:文档头部必须注明对应的系统软件版本号与SOP版本号。
变更类型 版本号变化 示例 是否需要重新验收
新增参数模块 主版本+1 V1.2.0 → V2.0.0 是
修改参数默认值 次版本+1 V1.2.0 → V1.3.0 是
修正文档描述 修订号+1 V1.2.0 → V1.2.1 否
删除已废弃参数 主版本+1 V1.2.0 → V2.0.0 是
版本存储规范:文档应存储在Git或SVN等版本控制系统中,文件名格式为 参数配置文档_系统名_V版本号.pdf。禁止使用“最终版”“修改版”等非版本化命名。
参数文档版本控制流程 V1.0.0 初始发布 V1.1.0 修改默认值 V1.1.1 修正描述 V2.0.0 结构变更 版本控制要点:每次变更必须更新版本号并填写变更记录。V1.1.1 到 V2.0.0 的跳变 表示中间可能经历了多次修订号递增,但主版本仅在结构变更时递增。

3.4 变更记录模板

每份参数配置文档必须包含《变更历史》章节,使用统一表格模板记录所有版本变更。模板字段与填写规范如下:

版本号 日期 变更人 变更类型 变更说明 受影响参数 验收状态
V1.0.0 2025-01-15 张三 初始发布 首次创建参数配置文档 全部 已验收
V1.1.0 2025-02-10 李四 参数修改 调整SCADA报警阈值:高温从85℃改为80℃ SCADA_ALM_HIGH_TEMP 待验收
V1.1.1 2025-02-12 王五 文档修正 修正3.2节参数取值范围描述错误 无 无需验收
V2.0.0 2025-03-01 张三 结构变更 新增PLC通信参数模块,删除已废弃的串口参数 PLC_COM_* 系列 已验收
变更记录填写规范:
  • “变更说明”必须描述变更原因与具体数值变化,禁止写“优化参数”“调整配置”等模糊描述。
  • “受影响参数”列填写具体参数名,多个参数用逗号分隔;若影响全部参数则写“全部”。
  • “验收状态”分为:无需验收、待验收、已验收、验收不通过。验收不通过时需在备注中说明原因。
变更记录模板字段结构 版本号 日期 变更人 变更类型 变更说明 验收状态 V1.0.0 2025-01-15 张三 初始发布 首次创建参数配置文档 已验收 V1.1.0 2025-02-10 李四 参数修改 高温阈值85→80℃ 待验收 变更记录填写示例说明 1. 初始发布时“验收状态”为“已验收”,表示文档发布前已完成内部审核。 2. 参数修改后“验收状态”为“待验收”,需在系统联机验收通过后更新为“已验收”。 3. 文档修正(如V1.1.1)无需验收,但必须记录在案。

3.5 文档规范检查清单

在提交参数配置文档前,请逐项确认以下检查点:

检查项 标准要求 通过标准
结构完整性 包含概述、系统环境、参数清单、依赖关系、验证用例、变更历史 6个一级章节齐全
参数命名合规 大写字母+数字+下划线,无中文/特殊字符 随机抽查20个参数,0违规
版本号正确 格式Vx.x.x,与变更记录一致 文档封面与变更历史版本号匹配
变更记录完整 每次变更均有记录,字段填写完整 无空字段,变更说明可追溯
参数表格式统一 每行包含参数名、类型、默认值、当前值、范围、生效方式 所有参数表列数一致
常见文档规范违规案例:
  • 参数名使用中文拼音缩写(如 wd_sz 代替 TEMP_SETPOINT)。
  • 变更记录中“变更说明”写“优化配置”,未描述具体数值变化。
  • 文档版本号与系统实际部署版本号不一致,导致验收时参数比对失败。

通过严格执行上述文档规范,可确保参数配置文档在SOP标准作业与系统联机验收全生命周期中具备可读