3. 参数配置文档规范
参数配置文档是SOP与系统联机验收的核心交付物,其规范性直接决定后续运维、排故与变更的可追溯性。本节从文档结构标准、参数命名规则、版本控制要求与变更记录模板四个维度建立统一规范。
规范前置原则:所有参数文档必须在系统联调前完成初版评审,避免“边调边写”导致的遗漏与不一致。
3.1 文档结构标准
每份参数配置文档应遵循固定的章节树结构,确保跨项目、跨系统的文档具有一致的查找路径。推荐采用三级标题结构:
| 层级 | 章节编号 | 章节名称 | 内容说明 |
|---|---|---|---|
| 一级 | 1 | 概述 | 文档目的、适用范围、参考标准 |
| 一级 | 2 | 系统环境 | 硬件/软件版本、网络拓扑、依赖服务 |
| 一级 | 3 | 参数配置清单 | 按子系统/模块分节,每节包含参数表 |
| 二级 | 3.1 | 通信参数 | IP、端口、协议、超时时间 |
| 二级 | 3.2 | 业务参数 | 阈值、开关、策略标识 |
| 二级 | 3.3 | 安全参数 | 认证方式、密钥、访问控制列表 |
| 一级 | 4 | 参数依赖关系 | 参数间耦合说明、启动顺序约束 |
| 一级 | 5 | 验证用例 | 每个关键参数的验收测试步骤 |
| 一级 | 6 | 变更历史 | 版本号、日期、变更人、变更说明 |
结构检查清单:
- 每个参数条目必须包含:参数全名、数据类型、默认值、当前值、取值范围、生效方式(重启/热加载)。
- 文档末尾必须附《参数索引表》,按字母顺序列出所有参数及其所在章节。
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。
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。禁止使用“最终版”“修改版”等非版本化命名。
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_* 系列 | 已验收 |
变更记录填写规范:
- “变更说明”必须描述变更原因与具体数值变化,禁止写“优化参数”“调整配置”等模糊描述。
- “受影响参数”列填写具体参数名,多个参数用逗号分隔;若影响全部参数则写“全部”。
- “验收状态”分为:无需验收、待验收、已验收、验收不通过。验收不通过时需在备注中说明原因。
3.5 文档规范检查清单
在提交参数配置文档前,请逐项确认以下检查点:
| 检查项 | 标准要求 | 通过标准 |
|---|---|---|
| 结构完整性 | 包含概述、系统环境、参数清单、依赖关系、验证用例、变更历史 | 6个一级章节齐全 |
| 参数命名合规 | 大写字母+数字+下划线,无中文/特殊字符 | 随机抽查20个参数,0违规 |
| 版本号正确 | 格式Vx.x.x,与变更记录一致 | 文档封面与变更历史版本号匹配 |
| 变更记录完整 | 每次变更均有记录,字段填写完整 | 无空字段,变更说明可追溯 |
| 参数表格式统一 | 每行包含参数名、类型、默认值、当前值、范围、生效方式 | 所有参数表列数一致 |
常见文档规范违规案例:
- 参数名使用中文拼音缩写(如
wd_sz代替TEMP_SETPOINT)。 - 变更记录中“变更说明”写“优化配置”,未描述具体数值变化。
- 文档版本号与系统实际部署版本号不一致,导致验收时参数比对失败。
通过严格执行上述文档规范,可确保参数配置文档在SOP标准作业与系统联机验收全生命周期中具备可读