# 外设执行管理

本页说明 Web 管理操作；字段与动作见[外设执行配置](https://www.fastbee.cn/doc/device/v2/periph-exec/periph-exec-configuration-guide.md)，各触发器及场景见[自动化目录](https://www.fastbee.cn/doc/device/v2/periph-exec.md)。

## 查看与准备

登录后进入“外设执行”，查看规则 ID、名称、启用状态、触发器、动作和执行结果。修改、启停、删除、导入及手动运行要求开发环境功能开启；该功能默认关闭，按需通过密码确认开启，旧设备已有选择保留。

确认当前设备身份、外设和协议配置，不用公开样例替换现场内容。规则能显示为启用，不代表所有功能、资源和目标都已经初始化成功；保护暂停应查看原因和恢复条件。

## 新建和编辑

1. 先保存需要的外设、协议和功能配置，确认类型及资源。
2. 新增停用规则，最多 3 个触发器、4 个动作，多触发器为 OR。
3. 选择实际事件、数据源或平台下发 ID，填写动作参数与执行前延时。
4. 预检失败、通信失败或响应无效时不继续保存；风险提示与翻转操作须阅读后确认。
5. 保存成功再重新读取核对；发生冲突或失败时保留有效配置，刷新后重试。

普通编辑事务保存成功后更新运行态；重配规则会退休旧来源/版本。整包文件导入则先持久化，重启后生效，不能根据旧列表推断已经应用。

平台触发操作符 1 是接收任意值的设置模式；本地采样告警用 `ds:<实际缓存键>` 事件。轮询规则到期会执行整条规则，不能把“读取→报警”误认为只在阈值满足时报警。温控使用[专用持续控制规则](https://www.fastbee.cn/doc/device/v2/periph-exec/thermostat-control.md)，不使用缺少失鲜关闭和最小开停时间的旧双阈值方案。

## 启停、删除和执行一次

启停通过完整配置/图和资源检查，保存失败不当作运行态已改变。删除前导出备份并核对其他规则的目标与完成事件引用；停用草稿也须在启用时重新检查。

“执行一次”会进行真实动作准入，不是预览。点击后只提交一次，再查询执行记录；结果未确认、网络失败或记录暂未出现时不自动再次执行。电平翻转、继电器和电机可能已经产生输出，不能靠重试猜测结果。页面离开后不显示旧请求的晚到结果。

已受理、排队、完成记录、协议应答与实物反馈分开判断。具体语义见[动作检查](https://www.fastbee.cn/doc/device/v2/periph-exec/action-contracts.md)和[Modbus 控制结果](https://www.fastbee.cn/doc/device/v2/periph-exec/modbus-control-results.md)。

## 屏幕与历史

`allowPanelControl` 默认 false，规则需要显式授权后才能绑定设备屏幕保存卡片；数值控件及规则版本再做白名单检查，Web 预览不执行动作。详情见[设备屏幕](https://www.fastbee.cn/doc/device/v2/system/screen-panel.md)。

`recordHistory` 默认 false，只对允许的数值读取生效；目标固件须编译并启用 `pointHistory`，非空历史来源白名单也须包含目标。缓存、历史与平台字段用途不同，不用重绘延长原采样时间。

## 事件链与当前能力

规则完成监听填写源规则的真实 ID，完成数据可能为 `success/failed/cancelled`。`periph_exec_completed` 不是任意完成通配符；动作 21 的目标须为支持的固定事件或已保存 DEVICE\_EVENT，不能凭空创建事件。

启用规则间的完成和固定事件链不得形成环；拒绝返回 `CONFIG_RULE_EVENT_CYCLE`，有界图容量不足返回 `CONFIG_RULE_EVENT_GRAPH_LIMIT`，原配置和运行态保留。比较条件不豁免潜在联动环。

系统恢复出厂动作 7 被拒绝，OTA 动作 9 当前保留但不执行。旧远程通道动作 33 已退休，绑定旧数据源会暂停整条规则；天气动作 34 只用于当前单一心知天气来源。不要按早期动作表继续创建远程开关或自动恢复出厂。

## 常用接口

| 路径 | 用途 |
| --- | --- |
| `/api/periph-exec` | GET 列表、POST 新增 |
| `/api/periph-exec/update` | POST 更新 |
| `/api/periph-exec/preflight` | POST 配置预检，不执行输出 |
| `/api/periph-exec/enable`、`/disable` | POST 启停 |
| `/api/periph-exec/run`、`/results` | POST 手动运行、GET 结果 |
| `/api/periph-exec/events/static`、`/events/dynamic` | 查询当前事件 |
| `/api/periph-exec/import-chunk` | 有界分块导入，确认提交后须重启 |

短路径表内 `/disable`、`/results` 和事件路径都使用 `/api/periph-exec` 前缀。请求格式及状态字段见[API 参考](https://www.fastbee.cn/doc/device/v2/dev/api-reference.md)。接口成功不表示设备已经通过现场或长期稳定验收。
