设备命令（命令注册表）
PlantPulse 在写入标签值（控制写入）之上，增加了一层“该设备可以执行哪些操作”。 这就是命令注册表。
操作员无需在 TAG_CNC01_SPEED_SP 中写入 1200，而是选择“速度设置 (SET_SPEED)”并仅输入速度。
向哪些标签按何种顺序写入、在何种条件为真时才允许执行，均由管理员预先定义。
在此处点击 [执行] 会向 PLC 实际写入值。测试务必在模拟器连接或停机的设备上进行。 没有自动回滚——即使序列中途失败，此前已写入的值也不会被恢复（这是为了保留审计记录而设计的）。
位置
在资产屏幕（/asset/tree/index）中选择设备 (EQUIPMENT) 节点，底部会打开选项卡。
| 选项卡 | 功能 |
|---|---|
| 命令 | 选择并执行已定义的命令 · 最近命令历史 |
| 注册表 | 定义命令（注册、编辑、删除） · 资产语句 |
定义位于注册表选项卡内的“命令注册表”面板。选项卡名称是“注册表”而非“命令”，因此一开始很容易找错选项卡。
谁可以查看 · 谁可以执行
访问权限分三层进行控制。
| 层 | 位置 | 过滤内容 |
|---|---|---|
| ① URL 过滤器 | security-rule.xml 中的 /asset/*/command* | 除 ADMIN · MANAGER 外，URL 本身即被阻止 |
| ② 屏幕·控制器 | “命令”选项卡的命令执行面板 | 仅对 ADMIN / MANAGER 可见。其他角色仅查看底部的历史记录。服务器对未认证返回 401 · 对非 ADMIN/MANAGER 返回 403 |
| ③ 按命令 | 定义中的允许角色 | 对每条命令分别指定“谁可以执行”。不允许时返回 REJECTED_FORBIDDEN |
即使通过②，也可能在③处被阻止——这意味着可以基于命令进一步缩小范围。
访问控制虽写为“ADMIN 或 MANAGER”，但**MANAGER 是在用户注册屏幕上无法授予的角色**（选项仅有 ADMIN、API、USER 三个）。若通过 API 强行添加，该账户登录后将无法进入——
请参阅用户管理。
因此，能使用此屏幕的人实际上只有 ADMIN。定义中的“允许角色”也仅对
ADMIN 和 API 有效。
定义命令 — 注册表选项卡
点击 [命令注册] 打开定义对话框。按照屏幕提示：“定义此资产的语义命令。配置参数、前置条件，以及按顺序执行的标签写入步骤。”
基本信息
| 字段 | 必填 | 说明 |
|---|---|---|
| 命令类型 | ✅ | 语义标识符 — 诸如 START、STOP、SET_SPEED 的值 |
| 命令名称 | ✅ | 在执行下拉框中显示的名称 |
| 允许角色 | ADMIN · MANAGER · API 复选框。“可以执行此命令的角色” | |
| 顺序 | 列表排序顺序（数字越小越靠前） | |
| 启用 | 关闭后，不会出现在执行下拉框中。定义保留 |
权限门为 fail-closed 模式——如果请求者的角色不在 허용 역할 列表中，则拒绝。
留空意味着列表为空，因此即使是 ADMIN 也会收到 REJECTED_FORBIDDEN。
参数
定义执行时操作员需要输入的值的表格。每行包含 名称 · 类型 · 最小值 · 最大值 · 选项 · 必填。
| 类型 | 校验 |
|---|---|
| Number | 解析为数值且必须是有限值（NaN、Infinity 无论范围如何均拒绝）。若存在 최소/최대，则须在其间（含边界） |
| Boolean | true / false（忽略大小写） |
| Enum | 必须是 옵션 中列出的值之一 |
| String | 不校验 |
- 标记为必填但为空则拒绝（
REJECTED_PARAM）。 - 可选参数留空则跳过类型校验；若填写则进行校验。
- 也允许没有任何参数的命令。
命令流程 — 步骤序列
定义对话框中的命令流程区域是一个可视化编辑器。 从左侧调色板放置节点（“点击=追加到末尾 · 拖拽=插入中间”），在右侧检查器中填写该节点的值。
[시작] → [쓰기] → [지연] → [읽기 확인] → [종료]
| 节点 | 检查器字段 | 功能 |
|---|---|---|
写入（write） | 标签 · 值表达式 · 前置条件（互锁门） | 向该标签写入值 |
读取确认（read_back） | 标签 · 运算符 · 期望值 · 稳定时间 · 轮询间隔 · 容差 | 回读确认写入的值是否实际生效 |
延时（delay） | 延时 (毫秒) | 等待到下一步骤 |
值表达式可以是字面量或参数引用——按屏幕帮助原文：“字面量值或表达式。{param} 将被替换为同名命令参数。”
{speed}、1、SET {speed} RPM 均适用。
读取确认的空白字段使用默认值——稳定 2000 毫秒 · 轮询 200 毫秒 · 容差 0.0。 由于 PLC 值稳定需要时间，写入后立即回读出现的偏差由该稳定窗口吸收。
写入节点的标签列表中，仅显示属于该设备的标签中 rw 为 W 或 RW 且 tag_type 为 SETPOINT 或 COMMAND 的项。读取确认和前置条件的标签列表无限制（因为是读取操作）。
如果列表中没有要修改的标签，请先在标签属性选项卡中修改读/写和标签类型。
前置条件与互锁
每个条件包含 标签 · 运算符 · 值 三个字段，另有一个互锁复选框。
运算符包括 eq、ne、gt、gte、lt、lte。
| 非互锁 | 互锁 | |
|---|---|---|
| 执行开始前 | 检查 ✅ | 检查 ✅ |
| 每个写入步骤之前 | 不检查 | 重新检查 ✅ |
如果序列中包含延时或读取确认，开始执行与实际写入之间会存在时间差。 在此期间安全门若已打开怎么办？只有设为互锁的条件会在写入前重新检查， 如果条件不符，则不发布该写入并中止。
诸如“门关闭 = TRUE”、“紧急停止 = FALSE”之类的条件，务必设为互锁。
条件定义即使无效也不会被放行。如果标签或运算符缺失，或解析失败，
不会静默跳过，而是通过 REJECTED_PRECONDITION 阻止——这是 fail-closed 设计，旨在不使安全门失效。
执行命令 — 命令选项卡
- 在命令选项卡的命令下拉框中选择——仅显示启用的定义，按顺序排列。 （若显示“没有已启用的命令”，请在注册表中启用。）
- 点击 [执行] — 如果定义了参数，则先弹出参数输入对话框 （自动生成类型匹配的控件 — Number 为 min/max，Enum 为下拉选择，Boolean 为真/假）。
- 确认对话框 — 显示“确定要对资产 ○○ 执行命令 ○○ 吗？”以及参数摘要。 此对话框用于防误操作，请务必在此处确认目标资产的名称。
- 结果将显示在面板中 — 按步骤显示标签 · 操作 · 请求值 · 实际值 · 成功 · 错误。
执行顺序（固定）
정의 로드 → 에셋 확인 → 자산락 → 권한 → 파라미터 → 태그 스코프 → 사전조건
↓
종결 판정 ← 스텝 시퀀스(쓰기 직전 인터록 재검증) ←
资产锁将对同一设备的命令进行完全串行化处理。不同设备的命令可以同时执行。
结果状态与应对措施
| 状态 | 含义 | 查看位置 |
|---|---|---|
SUCCESS | 所有步骤成功 | — |
FAILED | 在某个步骤失败并在此停止 | 结果表中的“错误”列。之前的写入已生效 |
REJECTED_NOT_FOUND | 定义不存在 · 或属于其他设备 · 或未启用 | 在注册表中检查启用状态 |
REJECTED_FORBIDDEN | 我的角色不在该命令的允许角色中 | 定义中的允许角色 |
REJECTED_PARAM | 参数不符合规格 | 必填缺失 · 范围 · 枚举值 |
REJECTED_TAG_SCOPE | 步骤指向的标签不属于该设备或不可写 | 修改定义后重新布线的标签，或更改了 rw 的情况 |
REJECTED_PRECONDITION | 前置条件不满足 — 或前置条件定义本身无效 | 条件标签的当前值 |
REJECTED_BUSY | 同一设备上正在执行其他命令 (HTTP 409) | 稍等片刻后重试 |
FAILED 不是“什么都没发生”REJECTED_* 是在写入开始之前被阻止，因此设备状态未改变。
反之，FAILED 是进入序列之后停止，因此失败步骤之前的写入已生效。
请查看结果表确认执行进度，如有必要请手动恢复。
仅 REJECTED_BUSY 和 REJECTED_NOT_FOUND 不会发布到历史记录（传输前竞争 · 路由错误）。
序列上限
| 项目 | 上限 |
|---|---|
| 整个序列 | 30,000 毫秒 — 超出则执行该步骤不执行并返回 FAILED（操作码 deadline） |
| 读取确认 | 稳定时间（默认 2,000 毫秒） |
| 写入 | 边缘 HTTP 超时 |
读取确认会通过轮询多次读取，但写入仅发送一次。重新发布有部分应用风险， 因此有意禁止——失败时请由人员判断后重新执行。
历史记录保存在何处
已结束的执行会作为标准 asset_command 发布，进入历史表（tm_asset_command） · UNS ·
时间线 · 缓存。失败、拒绝也会记录在诊断日志中
（诊断）。
“命令”选项卡底部的“最近命令列表”会一并显示由语句发布的命令 — 时间戳 · 语句名称 · 键 · 值（JSON）。
常见问题
Q. 命令执行面板不可见。
A. 角色不是 ADMIN（或不可授予的 MANAGER）。USER、API 仅能查看底部历史记录。
Q. 下拉框中显示“没有已启用的命令”。 A. 要么没有定义，要么全部未启用。请在注册表选项卡中启用。
Q. 写入步骤的标签列表为空。
A. 该设备上没有 rw 为 W/RW 且 tag_type 为 SETPOINT/COMMAND 的标签。
请在标签属性选项卡中修改。
Q. 一直出现 REJECTED_BUSY。
A. 同一设备的其他命令尚未执行完毕。请在最近命令列表中检查是否有包含长延时或读取确认的命令正在运行。
Q. 执行后似乎值未改变。 A. 请查看结果表中的实际值列。如果有读取确认步骤，该列即为实际回读的值。 如果没有读取确认步骤，则只能知道写入已发送，无法知道是否生效——对于重要命令，请加入读取确认。