主题
IoT 物联网 PRD
文档信息
| 项目 | 内容 |
|---|---|
| 产品名称 | PMForge - IoT 物联网 |
| 文档版本 | v2.0 |
| 创建日期 | 2026-09-24 |
| 最后更新 | 2026-09-24 |
| 文档状态 | 评审中 |
| 优先级 | P1 |
一、功能概述
1.1 功能定位
通俗理解：如果把各种智能设备（传感器、摄像头、控制器）比作"会说话的工具"，那 IoT 物联网模块就是"翻译官 + 管家"——它让不同品牌、不同语言的设备都能接入平台说同一种话，同时 24 小时盯着它们的状态，发现问题自动报警、自动处理。
IoT 物联网模块为 PMForge 提供设备接入与管理的完整能力。企业在智慧工厂、智慧楼宇、智慧农业等场景中，往往需要管理成百上千甚至数以万计的设备。这些设备来自不同厂商、使用不同通信协议、上报不同格式的数据。IoT 模块通过"产品 → 物模型 → 设备"三层抽象，将复杂的设备管理标准化：先用"产品"定义一类设备的通用特征，再用"物模型"描述这类设备能做什么（上报什么数据、能接收什么指令），最后批量注册具体设备实例。配合规则引擎实现"温度超标 → 自动启动排风扇 → 发短信给负责人"这样的场景联动，无需写代码就能完成业务编排。
1.2 功能范围与使用频率
| 功能模块 | 后台 | 前台 | 使用频率 | 说明 |
|---|---|---|---|---|
| 产品管理 | ✅ | ✅ | 每周数次 | 定义设备模板，新设备接入时操作 |
| 物模型管理 | ✅ | — | 每周数次 | 描述设备能力（属性/事件/服务） |
| 设备管理 | ✅ | ✅ | 每天 | 设备全生命周期管理、远程控制、OTA |
| 设备分组 | ✅ | — | 每周数次 | 按区域/楼栋/楼层层级管理设备 |
| 规则引擎 | ✅ | — | 配置后自动运行 | 场景联动、自动告警、数据转发 |
| 设备消息 | ✅ | — | 持续运行 | 属性上报、事件上报、服务下发的消息通道 |
| 设备监控 | ✅ | ✅ | 每天 | 实时数据、历史趋势、告警管理 |
1.3 业务价值
| 价值维度 | 具体收益 |
|---|---|
| 降低接入门槛 | 标准化物模型定义，新设备接入从数天缩短到数小时 |
| 提升运维效率 | 设备状态实时监控、故障自动告警、远程批量操控，减少现场巡检 |
| 释放数据价值 | 设备数据自动采集、存储和分析，为业务决策提供数据支撑 |
| 加速业务创新 | 可视化规则引擎，无需编码即可实现"如果…就…"的场景联动 |
| 统一管理标准 | 产品和物模型的抽象层设计，支持海量设备品类的统一管理 |
二、用户场景
2.1 用户角色
| 角色 | 描述 | 核心诉求 |
|---|---|---|
| IoT 平台管理员 | 负责产品定义和物模型设计 | 快速定义设备能力，灵活管理设备接入标准 |
| 运维工程师 | 负责设备日常监控和故障处理 | 实时掌握设备状态，快速定位和解决故障 |
| 业务开发者 | 负责规则引擎配置和场景联动 | 低代码实现业务联动，减少开发工作量 |
| 数据分析师 | 负责设备数据分析和报表 | 获取结构化设备数据，支持业务分析 |
| 企业高管 | 查看 IoT 运营看板 | 全面掌握设备运营状况，辅助决策 |
2.2 使用场景
场景1：IoT 管理员小王——新产品接入与批量注册设备
前置条件：企业新采购了 200 台工业温湿度传感器，需要在 IoT 平台完成产品定义和设备注册。
操作流程：
- 小王进入"产品管理"，点击"新建产品"
- 填写产品名称"工业温湿度传感器"，选择品类"传感器"，接入协议"MQTT"，数据格式"Alink JSON"
- 进入"物模型设计"，定义两个只读属性（温度、湿度）和一个可写属性（上报周期），再定义一个"温度超限"告警事件
- 产品发布后，进入"设备管理"，通过 Excel 模板批量导入 200 台设备
- 系统为每台设备自动生成 DeviceKey 和 DeviceSecret
- 设备出厂后，现场人员用这组密钥完成设备认证上线
期望结果：200 台设备全部注册成功，上线后自动出现在监控面板，数据正常上报。
验收标准（AC）：
- 产品创建后自动生成唯一的 ProductKey（16 位字母数字组合），不可手动修改
- 物模型属性支持 10 种数据类型（int32/float/bool/string/enum/struct 等），配置后可导出为 JSON
- Excel 批量导入 200 台设备在 30 秒内完成，导入结果展示成功/失败明细
- 设备首次连接平台时自动从未激活变为在线状态，延迟不超过 3 秒
- 已发布产品不允许修改接入协议和数据格式，编辑时给出明确提示
场景2：运维工程师小张——实时监控与告警处理
前置条件：某车间已部署温湿度传感器，规则引擎已配置高温告警规则。
操作流程：
- 小张打开"设备监控"面板，看到所有设备的实时温度/湿度数据
- 突然看到 3 号车间的传感器标红——温度 42.5℃，触发了"温度超限"告警
- 点击该设备进入详情，查看温度历史趋势曲线，确认是持续上升而非瞬间波动
- 通过"服务下发"向关联的排风扇发送"启动"指令（参数：风速=高）
- 在告警管理页面处理该告警，填写处理措施"已启动排风扇"
- 持续观察温度变化，10 分钟后温度回落到 28℃
期望结果：从发现告警到处理完毕全程在平台上完成，无需跑到现场。
验收标准（AC）：
- 实时监控面板每 5 秒自动刷新，WebSocket 推送延迟 < 1 秒
- 告警触发后 3 秒内在监控面板标红展示，同时推送通知给相关人员
- 服务下发指令从点击到设备收到 < 500ms（P99）
- 告警处理流程：待处理 → 处理中 → 已处理/已忽略，每步操作记录操作人和时间
- 历史趋势图支持选择时间范围（1 小时/24 小时/7 天/30 天），数据点超过 1 万时自动聚合
场景3：业务开发者小陈——规则引擎实现场景联动
前置条件：车间已部署温湿度传感器和排风扇，需要实现"温度超标自动启动排风扇并通知负责人"。
操作流程：
- 小陈进入"规则引擎"，点击"新建规则"
- 填写规则名称"车间高温联动控制"，关联"工业温湿度传感器"产品
- 配置触发条件：当"温度"属性值 > 35 时触发
- 配置三个执行动作：① 向设备下发"启动排风扇"服务（风速=高）；② 向负责人发短信（内容含设备名称和当前温度）；③ 将告警数据写入日志
- 启用规则，系统开始实时匹配设备上报数据
- 某设备温度达到 36℃ 时，排风扇自动启动，负责人收到短信
期望结果：无需写一行代码，通过可视化配置完成场景联动。
验收标准（AC）：
- 规则引擎从消息接收到规则匹配 < 100ms，动作执行 < 200ms
- 触发条件支持 AND/OR 逻辑组合，最多 10 个条件节点
- 执行动作最多 5 个，支持串行和并行两种模式
- 同一设备同一规则 1 分钟内最多触发 10 次（防规则风暴），超出后自动限流
- 规则日志保留 30 天，可查看每次触发的条件快照和动作执行结果
场景4：运维工程师小张——设备固件 OTA 批量升级
前置条件：某批次传感器存在固件缺陷，需要推送 OTA 升级。
操作流程：
- 小张进入"设备管理"→"固件升级"，上传新版本固件文件
- 填写固件版本号 v2.1.3 和变更说明
- 选择升级策略"定时升级"（当晚 23:00 执行），升级范围"A 栋所有传感器"分组
- 提交升级任务，系统向目标设备推送升级通知
- 在升级任务列表中监控进度：已推送 → 已下载 → 升级中 → 升级成功/失败
- 对 3 台升级失败的设备查看原因（网络中断），次日重试成功
期望结果：批量升级过程可视、可控、可重试。
验收标准（AC）：
- OTA 升级支持三种策略：立即升级、定时升级、确认升级（设备端确认后才执行）
- 升级范围支持按产品全量、按分组、按百分比（灰度）三种方式
- 10,000 台设备推送升级通知 < 30 秒
- 升级失败自动重试，重试次数可配置（默认 3 次，间隔 5 分钟）
- 升级任务可随时取消（未完成的设备不再推送），已升级的设备不支持回退
场景5：运维工程师小张——设备分组管理与批量操控
前置条件：某智慧楼宇项目有 A/B/C 三栋建筑，每栋 5 层，每层约 20 个设备。
操作流程：
- 小张创建多级分组：根分组"XX 智慧楼宇" → A 栋/B 栋/C 栋 → 每栋下按楼层建子分组
- 将设备分配到对应分组（支持拖拽或批量选择后移动）
- 下班时选择"A 栋"分组，通过"批量服务下发"向所有照明设备发送"关灯"指令
- 查看分组统计：设备总数 300、在线 285、离线 10、告警 5
期望结果：按建筑-楼层的层级管理设备，批量操作一键完成。
验收标准（AC）：
- 分组支持最多 5 级层级深度，分组名称在同一父级下不重复
- 一个设备只能属于一个分组，移动分组后自动继承新分组的规则
- 分组支持跨产品（同一分组下可有传感器、照明、空调等不同产品的设备）
- 批量服务下发时，逐一记录每台设备的执行结果，展示成功/失败明细
- 分组统计信息实时更新（设备总数、在线数、离线数、告警数）
三、功能需求
3.1 产品管理
3.1.1 产品管理页面（后台）
描述：产品是设备的"模板"——同一类产品（如"工业温湿度传感器"）共享相同的通信协议、数据格式和物模型定义。在一个产品下可以创建成百上千个具体的设备实例。
功能清单：
| 功能项 | 优先级 | 描述 |
|---|---|---|
| 产品列表查询 | P0 | 按名称、品类、状态、协议类型筛选，分页展示 |
| 创建产品 | P0 | 填写名称、选择品类/设备类型/接入协议/数据格式 |
| 编辑产品 | P0 | 修改基本信息；已关联设备的产品的关键字段锁定 |
| 删除产品 | P0 | 仅允许删除无关联设备的产品 |
| 发布/禁用产品 | P0 | 发布后不可修改协议和数据格式 |
| 产品品类管理 | P1 | 维护品类树（传感器/照明/安防/家电/工业设备），支持自定义 |
业务规则：
| 规则 | 说明 | 设计原因 |
|---|---|---|
| 产品名称租户内唯一 | 同一租户下不可创建同名产品 | 避免产品混淆，运维时能快速定位 |
| ProductKey 全局唯一 | 16 位字母数字，系统自动生成 | 作为设备通信的路由标识，必须全局不冲突 |
| 已发布产品锁定协议 | 发布后不可修改接入协议和数据格式 | 已有设备按此协议通信，修改会导致所有设备掉线 |
| 删除前检查关联设备 | 有关联设备时拒绝删除 | 防止误删导致设备失去模板定义 |
| 设备类型决定子设备 | 网关设备可挂载子设备，直连设备不可 | 区分网关场景和普通设备场景 |
接口列表：
| 接口名称 | 请求方式 | 路径 | 说明 |
|---|---|---|---|
| 产品分页查询 | GET | /admin-api/iot/product/page | 按条件分页查询 |
| 产品详情 | GET | /admin-api/iot/product/get | 获取产品详情 |
| 创建产品 | POST | /admin-api/iot/product/create | 新增产品 |
| 更新产品 | PUT | /admin-api/iot/product/update | 编辑产品 |
| 删除产品 | DELETE | /admin-api/iot/product/delete | 删除产品（无关联设备时） |
| 发布产品 | PUT | /admin-api/iot/product/publish | 发布产品 |
| 禁用产品 | PUT | /admin-api/iot/product/disable | 禁用产品 |
| 品类树查询 | GET | /admin-api/iot/product/category/list | 获取品类树 |
| 创建品类 | POST | /admin-api/iot/product/category/create | 新增品类 |
| 更新品类 | PUT | /admin-api/iot/product/category/update | 编辑品类 |
| 删除品类 | DELETE | /admin-api/iot/product/category/delete | 删除品类 |
3.2 物模型管理
3.2.1 物模型配置页面（后台）
描述：物模型是对设备能力的"说明书"——告诉平台这个设备能上报什么数据（属性）、会主动报告什么事件（事件）、能接收什么指令（服务）。
通俗理解：物模型就像员工的"岗位说明书"——属性是"需要定期汇报的工作指标"，事件是"遇到特殊情况要立即上报"，服务是"领导可以下达的工作指令"。
功能清单：
| 功能项 | 优先级 | 描述 |
|---|---|---|
| 物模型列表 | P0 | 按产品查看，分属性/事件/服务三个标签页 |
| 新增属性 | P0 | 定义标识符、名称、数据类型、访问模式、单位、取值范围 |
| 新增事件 | P0 | 定义标识符、名称、事件类型（信息/告警/故障）、输出参数 |
| 新增服务 | P0 | 定义标识符、名称、调用方式（同步/异步）、输入/输出参数 |
| 编辑/删除 | P0 | 修改或删除物模型定义 |
| 物模型导入导出 | P1 | JSON 文件批量导入/导出 |
| 物模型模板 | P2 | 常用品类的预置模板，一键导入 |
数据类型说明：
| 数据类型 | 说明 | 典型用途 |
|---|---|---|
| int32 / int64 | 整数 | 开关状态、计数器 |
| float / double | 浮点数 | 温度、湿度、GPS 经纬度 |
| bool | 布尔值 | 开关状态 |
| string | 文本 | 设备型号、版本号 |
| enum | 枚举 | 工作模式（手动/自动/定时） |
| struct | 结构体 | 坐标 |
| array | 数组 | 历史数据列表 |
| datetime | 时间戳 | 告警发生时间 |
业务规则：
| 规则 | 说明 | 设计原因 |
|---|---|---|
| 标识符产品内唯一 | 字母开头，由字母/数字/下划线组成 | 标识符是数据路由的 key，重复会导致数据错乱 |
| 已发布产品物模型不可删除 | 仅可修改描述等辅助信息 | 已有设备在按此物模型上报数据，删除会导致解析失败 |
| 枚举类型至少 2 项 | 每项包含枚举值和描述 | 单个枚举值没有意义 |
| 取值范围用于数据校验 | 超出范围的数据标记为异常 | 防止传感器故障产生的异常数据污染业务 |
接口列表：
| 接口名称 | 请求方式 | 路径 | 说明 |
|---|---|---|---|
| 属性列表 | GET | /admin-api/iot/thing-model/property/list | 查询产品属性 |
| 创建属性 | POST | /admin-api/iot/thing-model/property/create | 新增属性 |
| 更新属性 | PUT | /admin-api/iot/thing-model/property/update | 编辑属性 |
| 删除属性 | DELETE | /admin-api/iot/thing-model/property/delete | 删除属性 |
| 事件列表 | GET | /admin-api/iot/thing-model/event/list | 查询产品事件 |
| 创建事件 | POST | /admin-api/iot/thing-model/event/create | 新增事件 |
| 更新事件 | PUT | /admin-api/iot/thing-model/event/update | 编辑事件 |
| 删除事件 | DELETE | /admin-api/iot/thing-model/event/delete | 删除事件 |
| 服务列表 | GET | /admin-api/iot/thing-model/service/list | 查询产品服务 |
| 创建服务 | POST | /admin-api/iot/thing-model/service/create | 新增服务 |
| 更新服务 | PUT | /admin-api/iot/thing-model/service/update | 编辑服务 |
| 删除服务 | DELETE | /admin-api/iot/thing-model/service/delete | 删除服务 |
| 导入物模型 | POST | /admin-api/iot/thing-model/import | JSON 导入 |
| 导出物模型 | GET | /admin-api/iot/thing-model/export | JSON 导出 |
3.3 设备管理
3.3.1 设备管理页面（后台）
描述：设备管理覆盖设备从"出生"到"退役"的全生命周期：注册 → 激活 → 在线 → 离线 → 禁用/恢复。
设备详情页：
功能清单：
| 功能项 | 优先级 | 描述 |
|---|---|---|
| 设备列表查询 | P0 | 按名称、DeviceName、状态、产品、分组筛选 |
| 创建/批量创建设备 | P0 | 手动创建或 Excel 批量导入，自动分配 DeviceKey/Secret |
| 编辑/删除设备 | P0 | 修改基本信息；删除时清除关联的消息日志和物模型数据 |
| 设备详情 | P0 | 基本信息 + 物模型实时数据 + 告警 + 操作日志 |
| 启用/禁用设备 | P0 | 禁用后平台拒绝该设备的连接请求 |
| 远程控制 | P1 | 通过服务下发向设备发送指令 |
| 属性设置 | P1 | 向设备写入属性值（如修改上报周期） |
| 固件 OTA 升级 | P1 | 上传固件、创建升级任务、监控进度、处理失败 |
| 设备标签 | P1 | 自定义 Key-Value 标签，用于分类和检索 |
| 设备调试 | P2 | 模拟设备上报数据、测试服务下发 |
设备状态流转：
名词解释：
- 心跳：设备每隔固定时间向平台发一条"我还活着"的消息。如果平台连续 3 个心跳周期没收到消息，就认为设备离线了。就像值班室每隔 5 分钟打电话确认各岗位安全一样。
- OTA：Over-The-Air，通过无线网络远程升级设备固件，不用拆设备、不用插 U 盘。
业务规则：
| 规则 | 说明 | 设计原因 |
|---|---|---|
| DeviceName 产品内唯一 | 同一产品下设备名不重复 | 避免设备身份冲突 |
| 每台设备自动分配密钥 | DeviceKey + DeviceSecret 用于身份认证 | 确保只有合法设备能接入平台 |
| 心跳超时自动标记离线 | 默认 3 个心跳周期未收到消息则离线 | 自动感知设备异常，无需人工巡检 |
| 禁用设备拒绝连接 | 平台主动拒绝被禁用设备的连接请求 | 存在安全隐患的设备需要立即隔离 |
| 删除设备清除关联数据 | 同时清除消息日志和物模型数据 | 避免残留数据占用存储空间 |
| OTA 失败自动重试 | 默认重试 3 次，间隔 5 分钟 | 网络波动导致的失败不应放弃 |
接口列表：
| 接口名称 | 请求方式 | 路径 | 说明 |
|---|---|---|---|
| 设备分页查询 | GET | /admin-api/iot/device/page | 按条件分页查询 |
| 设备详情 | GET | /admin-api/iot/device/get | 获取设备详情 |
| 创建设备 | POST | /admin-api/iot/device/create | 新增设备 |
| 批量创建设备 | POST | /admin-api/iot/device/batch-create | 批量导入设备 |
| 更新设备 | PUT | /admin-api/iot/device/update | 编辑设备 |
| 删除设备 | DELETE | /admin-api/iot/device/delete | 删除设备 |
| 启用设备 | PUT | /admin-api/iot/device/enable | 启用设备 |
| 禁用设备 | PUT | /admin-api/iot/device/disable | 禁用设备 |
| 属性设置 | POST | /admin-api/iot/device/property/set | 设置设备属性值 |
| 服务调用 | POST | /admin-api/iot/device/service/invoke | 调用设备服务 |
| 设备标签列表 | GET | /admin-api/iot/device/tag/list | 查询设备标签 |
| 设置设备标签 | POST | /admin-api/iot/device/tag/set | 设置/更新标签 |
| 删除设备标签 | DELETE | /admin-api/iot/device/tag/delete | 删除指定标签 |
| OTA 创建升级任务 | POST | /admin-api/iot/device/ota/create | 创建固件升级任务 |
| OTA 任务列表 | GET | /admin-api/iot/device/ota/page | 查询升级任务 |
| OTA 任务详情 | GET | /admin-api/iot/device/ota/get | 查看升级进度 |
| OTA 取消任务 | PUT | /admin-api/iot/device/ota/cancel | 取消升级任务 |
3.4 设备分组管理
3.4.1 分组管理页面（后台）
描述：设备分组提供"文件夹"式的层级管理——就像电脑里的文件夹可以嵌套子文件夹一样，设备分组也可以按"公司 → 楼栋 → 楼层 → 区域"层层嵌套。
功能清单：
| 功能项 | 优先级 | 描述 |
|---|---|---|
| 分组树查询 | P0 | 树形结构展示所有分组 |
| 创建/编辑/删除分组 | P0 | 支持指定父分组形成层级；删除前需移出所有设备 |
| 设备分配分组 | P0 | 将一个或多个设备分配到指定分组 |
| 批量移动设备 | P1 | 设备从一个分组批量移动到另一个 |
| 分组统计 | P1 | 展示设备总数、在线数、离线数、告警数 |
| 分组批量操作 | P1 | 对分组内设备批量下发服务/禁用/启用 |
业务规则：
| 规则 | 说明 | 设计原因 |
|---|---|---|
| 最多 5 级层级 | 超过 5 级拒绝创建 | 层级过深影响查询性能和用户体验 |
| 一设备一分组 | 一个设备只能属于一个分组 | 避免批量操作时的歧义 |
| 分组可跨产品 | 同一分组下可有不同产品的设备 | 实际场景中按区域管理，不按产品类型 |
| 删除前清空设备 | 分组内有设备时不允许删除 | 防止设备变成"无家可归"的孤儿数据 |
接口列表：
| 接口名称 | 请求方式 | 路径 | 说明 |
|---|---|---|---|
| 分组树查询 | GET | /admin-api/iot/device-group/tree | 获取完整分组树 |
| 创建分组 | POST | /admin-api/iot/device-group/create | 新增分组 |
| 更新分组 | PUT | /admin-api/iot/device-group/update | 编辑分组 |
| 删除分组 | DELETE | /admin-api/iot/device-group/delete | 删除空分组 |
| 分组内设备列表 | GET | /admin-api/iot/device-group/device-list | 查询分组下设备 |
| 分配设备到分组 | POST | /admin-api/iot/device-group/assign | 分配设备 |
| 批量移动设备 | POST | /admin-api/iot/device-group/move | 批量移动 |
| 分组统计 | GET | /admin-api/iot/device-group/stats | 获取统计信息 |
| 分组批量服务下发 | POST | /admin-api/iot/device-group/batch-service | 批量下发服务 |
3.5 规则引擎
3.5.1 规则配置页面（后台）
描述：规则引擎是 IoT 平台的"自动化大脑"——当设备上报的数据满足某个条件时，自动执行预设的动作。
通俗理解：规则引擎就像家里的"智能音箱场景"——"当我到家（条件），就开灯 + 播放音乐（动作）"。区别是 IoT 的规则引擎面向工业场景，条件更复杂、动作更多样、可靠性要求更高。
功能清单：
| 功能项 | 优先级 | 描述 |
|---|---|---|
| 规则列表 | P0 | 展示所有规则，按名称/状态/产品筛选 |
| 创建规则 | P0 | 定义触发条件 + 执行动作 |
| 编辑/删除规则 | P0 | 修改条件动作配置 |
| 启用/禁用规则 | P0 | 控制规则是否生效 |
| 规则日志 | P1 | 查看触发历史、执行结果、失败原因 |
| 场景联动 | P1 | 多条件 AND/OR 组合，多动作串行/并行 |
| 数据流转 | P2 | 将设备数据转发到 Kafka/HTTP/数据库 |
| 规则模板 | P2 | 常用场景预置模板 |
| 规则调试 | P2 | 模拟数据触发规则，查看执行过程 |
触发条件类型：
| 条件类型 | 说明 | 配置方式 |
|---|---|---|
| 属性条件 | 设备属性值满足条件 | 选属性 → 运算符（>、<、=、between）→ 阈值 |
| 事件条件 | 设备上报特定事件 | 选事件标识符，可配参数条件 |
| 状态条件 | 设备状态变化 | 选变更类型（上线/离线/禁用） |
| 定时条件 | 按 cron 表达式定时 | 配置 cron 和时区 |
执行动作类型：
| 动作类型 | 说明 | 配置方式 |
|---|---|---|
| 服务下发 | 向设备发指令 | 选设备/分组 → 选服务 → 配参数 |
| 属性设置 | 写入设备属性 | 选设备/分组 → 选属性 → 设值 |
| 消息通知 | 短信/邮件/站内信/Webhook | 选渠道 → 配接收人 → 编写模板 |
| 数据流转 | 转发到外部系统 | 选目标（Kafka/HTTP/DB）→ 配连接信息 |
| 规则链 | 触发另一个规则 | 选目标规则 |
| 设备禁用 | 自动禁用异常设备 | 选目标设备 |
业务规则：
| 规则 | 说明 | 设计原因 |
|---|---|---|
| 规则名称租户内唯一 | 同一租户不可重名 | 避免规则管理混乱 |
| 最多 10 个条件节点 | AND/OR 组合 | 过多条件影响匹配性能 |
| 最多 5 个执行动作 | 支持串行/并行 | 过多动作增加执行失败风险 |
| 触发频率限制 | 同设备同规则 1 分钟最多 10 次 | 防止"规则风暴"——设备抖动导致规则被反复触发 |
| 失败自动重试 | 默认 3 次，间隔 5 秒 | 网络抖动不应导致动作丢失 |
| 日志保留 30 天 | 超期自动清理 | 平衡排查需求和存储成本 |
接口列表：
| 接口名称 | 请求方式 | 路径 | 说明 |
|---|---|---|---|
| 规则分页查询 | GET | /admin-api/iot/rule/page | 按条件分页查询 |
| 规则详情 | GET | /admin-api/iot/rule/get | 获取规则详情（含条件和动作） |
| 创建规则 | POST | /admin-api/iot/rule/create | 新增规则 |
| 更新规则 | PUT | /admin-api/iot/rule/update | 编辑规则 |
| 删除规则 | DELETE | /admin-api/iot/rule/delete | 删除规则 |
| 启用规则 | PUT | /admin-api/iot/rule/enable | 启用规则 |
| 禁用规则 | PUT | /admin-api/iot/rule/disable | 禁用规则 |
| 规则日志 | GET | /admin-api/iot/rule/log/list | 查询触发日志 |
| 规则模板列表 | GET | /admin-api/iot/rule/template/list | 获取模板 |
| 规则调试 | POST | /admin-api/iot/rule/debug | 模拟调试 |
3.6 设备消息
3.6.1 消息管理页面（后台）
描述：设备消息是所有设备与平台之间数据交互的"邮局"——设备上报的数据从这里进入平台，平台下发的指令从这里送达设备。
消息流向：
功能清单：
| 功能项 | 优先级 | 描述 |
|---|---|---|
| 消息日志列表 | P0 | 按设备、消息类型、时间范围查询 |
| 属性上报记录 | P0 | 查看设备上报的属性数据 |
| 事件上报记录 | P0 | 查看设备上报的事件数据 |
| 服务下发记录 | P0 | 查看服务调用记录和响应结果 |
| 消息详情 | P1 | 查看单条消息的完整报文和处理结果 |
| 消息统计 | P1 | 按类型/设备/产品维度统计消息量和成功率 |
| 数据解析配置 | P1 | 配置原始报文到物模型数据的解析脚本（JS/Python） |
| 消息模拟 | P2 | 模拟设备上报消息，测试解析和规则 |
业务规则：
| 规则 | 说明 | 设计原因 |
|---|---|---|
| 消息唯一 ID | 每条消息有唯一 MessageId | 用于消息追踪和去重 |
| 物模型强校验 | 不符合物模型定义的数据标记为解析失败 | 防止脏数据进入业务系统 |
| 服务下发超时 | 默认 5 秒，超时标记调用失败 | 避免无限等待占用资源 |
| 消息日志保留 7 天 | 可配置，超期自动归档 | 平衡排查需求和存储成本 |
| 解析脚本沙箱执行 | 限制执行时间和内存 | 防止恶意或错误脚本影响系统 |
接口列表：
| 接口名称 | 请求方式 | 路径 | 说明 |
|---|---|---|---|
| 消息日志分页 | GET | /admin-api/iot/message/log/page | 查询消息日志 |
| 属性上报记录 | GET | /admin-api/iot/message/property/list | 查询属性上报 |
| 事件上报记录 | GET | /admin-api/iot/message/event/list | 查询事件上报 |
| 服务下发记录 | GET | /admin-api/iot/message/service/list | 查询服务下发 |
| 消息详情 | GET | /admin-api/iot/message/log/get | 查看消息详情 |
| 消息统计 | GET | /admin-api/iot/message/statistics | 消息统计 |
| 数据解析脚本配置 | POST | /admin-api/iot/message/parser/configure | 配置解析脚本 |
| 数据解析测试 | POST | /admin-api/iot/message/parser/test | 测试解析脚本 |
3.7 设备监控
3.7.1 监控面板页面（后台）
描述：设备监控是运维人员的"主战场"——实时数据面板、历史趋势图表、告警管理都在这里。
功能清单：
| 功能项 | 优先级 | 描述 |
|---|---|---|
| 实时监控面板 | P0 | 展示设备实时属性数据，自动刷新 |
| 历史数据查询 | P0 | 按设备/属性/时间范围查询历史数据 |
| 历史趋势图表 | P0 | 折线图/柱状图展示属性趋势 |
| 告警记录管理 | P0 | 查看/处理/忽略告警 |
| 告警规则配置 | P1 | 配置阈值告警：运算符、阈值、等级、通知方式 |
| 数据导出 | P1 | 导出为 Excel/CSV，单次最大 100 万条 |
| 告警统计 | P1 | 按产品/设备/时间维度统计告警趋势 |
| 告警通知 | P1 | 短信/邮件/站内信/Webhook 多渠道通知 |
| 设备地图 | P2 | 在地图上展示设备分布（适用于含 GPS 的设备） |
| 数据聚合 | P2 | 按分钟/小时/天聚合（平均值/最大值/最小值/求和） |
告警状态流转：
业务规则：
| 规则 | 说明 | 设计原因 |
|---|---|---|
| 实时数据 5 秒刷新 | WebSocket 推送，频率可配置 | 平衡实时性和服务器负载 |
| 历史数据保留 90 天 | 可按产品配置 | 过短影响分析，过长增加存储成本 |
| 告警等级四级 | 提示/一般/严重/紧急 | 不同等级对应不同通知策略 |
| 告警触发自动通知 | 通知接收人可配置 | 确保关键告警不遗漏 |
| 数据超 1 万条自动聚合 | 降采样策略 | 前端渲染过多数据点会导致页面卡顿 |
接口列表：
| 接口名称 | 请求方式 | 路径 | 说明 |
|---|---|---|---|
| 实时数据查询 | GET | /admin-api/iot/monitor/realtime | 查询实时属性数据 |
| 实时数据订阅 | WebSocket | /ws/iot/monitor/realtime | WebSocket 实时推送 |
| 历史数据查询 | GET | /admin-api/iot/monitor/history | 查询历史数据 |
| 历史趋势查询 | GET | /admin-api/iot/monitor/trend | 趋势数据（支持聚合） |
| 数据导出 | POST | /admin-api/iot/monitor/export | 导出历史数据 |
| 告警规则列表 | GET | /admin-api/iot/monitor/alarm-rule/page | 查询告警规则 |
| 创建告警规则 | POST | /admin-api/iot/monitor/alarm-rule/create | 新增告警规则 |
| 更新告警规则 | PUT | /admin-api/iot/monitor/alarm-rule/update | 编辑告警规则 |
| 删除告警规则 | DELETE | /admin-api/iot/monitor/alarm-rule/delete | 删除告警规则 |
| 告警记录列表 | GET | /admin-api/iot/monitor/alarm/page | 查询告警记录 |
| 处理告警 | PUT | /admin-api/iot/monitor/alarm/handle | 标记已处理 |
| 忽略告警 | PUT | /admin-api/iot/monitor/alarm/ignore | 忽略告警 |
| 告警统计 | GET | /admin-api/iot/monitor/alarm/statistics | 告警统计 |
四、非功能需求
4.1 性能要求
| 指标 | 目标值 | 实现策略 |
|---|---|---|
| 消息处理吞吐 | 单节点 10,000 条/秒 | 基于 Kafka 消息队列异步处理，水平扩展 |
| 属性上报延迟 | 接收到入库 < 200ms（P99） | 内存缓冲 + 批量写入 |
| 服务下发延迟 | 发起到设备收到 < 500ms（P99） | MQTT QoS 1 保证送达 |
| 实时数据推送 | WebSocket 延迟 < 1 秒 | 基于 Redis Pub/Sub 分发 |
| 规则匹配延迟 | 消息接收到匹配 < 100ms | 规则预编译 + 内存缓存 |
| 历史数据查询 | 100 万条聚合查询 < 3 秒 | 时序数据库 + 预聚合 |
| 并发连接数 | 单节点 100,000 设备 | Netty 长连接 + 集群部署 |
| 设备上下线感知 | 状态变更到平台感知 < 3 秒 | 心跳检测定时任务 |
| OTA 推送 | 10,000 台设备 < 30 秒 | 批量异步推送 |
4.2 安全要求
| 安全项 | 实现方式 |
|---|---|
| 设备认证 | DeviceKey + DeviceSecret，支持一机一密和一型一密 |
| 传输加密 | TLS/DTLS 加密通信 |
| 数据加密 | 敏感数据 AES-256 存储加密 |
| 接口鉴权 | RBAC 权限模型，所有接口需对应权限标识 |
| 多租户隔离 | 所有数据表含 tenant_id |
| 消息签名 | 设备消息携带签名，平台校验合法性 |
| 操作审计 | 设备创建/删除/禁用、规则变更等记录审计日志 |
| 脚本沙箱 | 数据解析脚本在隔离环境执行，限制资源 |
4.3 错误码定义
| 错误码 | 说明 | 处理建议 |
|---|---|---|
| IOT_PRODUCT_001 | 产品名称已存在 | 更换产品名称 |
| IOT_PRODUCT_002 | 产品下存在设备，无法删除 | 先删除关联设备 |
| IOT_PRODUCT_003 | 产品已发布，不可修改协议 | 创建新产品 |
| IOT_DEVICE_001 | DeviceName 已存在 | 系统自动分配或更换名称 |
| IOT_DEVICE_002 | 设备认证失败 | 检查 DeviceKey/Secret 是否正确 |
| IOT_DEVICE_003 | 设备已禁用 | 联系管理员启用设备 |
| IOT_THING_MODEL_001 | 物模型标识符已存在 | 更换标识符 |
| IOT_THING_MODEL_002 | 物模型已被设备引用，不可删除 | 先解除设备关联 |
| IOT_RULE_001 | 规则名称已存在 | 更换规则名称 |
| IOT_RULE_002 | 规则触发频率超限 | 等待限流窗口过期 |
| IOT_GROUP_001 | 分组名称已存在 | 更换分组名称 |
| IOT_GROUP_002 | 分组下存在设备，无法删除 | 先移出设备 |
| IOT_ALARM_001 | 告警规则不存在 | 检查规则 ID |
五、数据设计
5.1 数据表总览
IoT 模块共涉及 16 张数据表，分为 6 个数据域：
| 数据域 | 表名 | 说明 |
|---|---|---|
| 产品域 | iot_product | 产品表 |
| 产品域 | iot_product_category | 产品品类表 |
| 物模型域 | iot_thing_model_property | 物模型属性表 |
| 物模型域 | iot_thing_model_event | 物模型事件表 |
| 物模型域 | iot_thing_model_service | 物模型服务表 |
| 设备域 | iot_device | 设备表 |
| 设备域 | iot_device_tag | 设备标签表 |
| 设备域 | iot_device_group | 设备分组表 |
| 设备域 | iot_device_ota_task | OTA 升级任务表 |
| 规则域 | iot_rule | 规则表 |
| 规则域 | iot_rule_log | 规则日志表 |
| 消息域 | iot_message_log | 消息日志表 |
| 消息域 | iot_message_parser | 数据解析脚本表 |
| 监控域 | iot_alarm_rule | 告警规则表 |
| 监控域 | iot_alarm_record | 告警记录表 |
| 监控域 | iot_device_property_data | 设备属性数据表（时序） |
5.2 数据关系图
5.3 缓存策略
| 缓存 Key | 数据内容 | 过期策略 | 更新时机 |
|---|---|---|---|
| iot:product: | 产品信息 | 不过期 | 产品创建/更新时刷新 |
| iot:thing-model: | 产品物模型 | 不过期 | 物模型变更时刷新 |
| iot:device:status: | 设备在线状态 | 心跳周期 ×3 | 设备上下线时更新 |
| iot:group:tree: | 分组树 | 1 小时 | 分组变更时主动刷新 |
| iot:rule:enabled: | 产品启用的规则列表 | 不过期 | 规则启用/禁用时刷新 |
5.4 核心数据表结构
iot_product 产品表：
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | bigint | 是 | 主键 |
| product_name | varchar(128) | 是 | 产品名称，租户内唯一 |
| product_key | varchar(32) | 是 | 产品标识，全局唯一 |
| product_secret | varchar(128) | 是 | 产品密钥 |
| category_id | bigint | 是 | 所属品类 ID |
| device_type | tinyint | 是 | 设备类型：0-直连 1-网关 2-网关子设备 |
| protocol_type | varchar(16) | 是 | 接入协议：MQTT/CoAP/HTTP/MODBUS |
| data_format | varchar(32) | 是 | 数据格式：ALINK_JSON/MODBUS_CUSTOM/RAW |
| status | tinyint | 是 | 状态：0-开发中 1-已发布 2-已禁用 |
| node_type | tinyint | 是 | 节点类型：0-设备 1-网关 |
| description | varchar(512) | 否 | 产品描述 |
| creator | varchar(64) | 否 | 创建者 |
| create_time | datetime | 是 | 创建时间 |
| updater | varchar(64) | 否 | 更新者 |
| update_time | datetime | 是 | 更新时间 |
| deleted | bit(1) | 是 | 逻辑删除 |
| tenant_id | bigint | 是 | 租户 ID |
iot_device 设备表：
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | bigint | 是 | 主键 |
| product_id | bigint | 是 | 所属产品 ID |
| device_name | varchar(128) | 是 | 设备名称，产品内唯一 |
| device_key | varchar(64) | 是 | 设备标识 |
| device_secret | varchar(128) | 是 | 设备密钥 |
| nickname | varchar(128) | 否 | 设备别名 |
| status | tinyint | 是 | 状态：0-未激活 1-在线 2-离线 3-已禁用 |
| firmware_version | varchar(32) | 否 | 当前固件版本 |
| group_id | bigint | 否 | 所属分组 ID |
| ip_address | varchar(64) | 否 | 最近连接 IP |
| last_online_time | datetime | 否 | 最后在线时间 |
| last_offline_time | datetime | 否 | 最后离线时间 |
| active_time | datetime | 否 | 首次激活时间 |
| description | varchar(512) | 否 | 设备描述 |
| creator | varchar(64) | 否 | 创建者 |
| create_time | datetime | 是 | 创建时间 |
| updater | varchar(64) | 否 | 更新者 |
| update_time | datetime | 是 | 更新时间 |
| deleted | bit(1) | 是 | 逻辑删除 |
| tenant_id | bigint | 是 | 租户 ID |
iot_device_group 设备分组表：
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | bigint | 是 | 主键 |
| parent_id | bigint | 否 | 父分组 ID，顶级为 null |
| group_name | varchar(128) | 是 | 分组名称 |
| group_path | varchar(512) | 是 | 分组路径（如 /root/A栋/1F） |
| level | int | 是 | 层级深度（1-5） |
| sort_order | int | 否 | 排序序号 |
| description | varchar(512) | 否 | 分组描述 |
| creator | varchar(64) | 否 | 创建者 |
| create_time | datetime | 是 | 创建时间 |
| updater | varchar(64) | 否 | 更新者 |
| update_time | datetime | 是 | 更新时间 |
| deleted | bit(1) | 是 | 逻辑删除 |
| tenant_id | bigint | 是 | 租户 ID |
iot_rule 规则表：
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | bigint | 是 | 主键 |
| rule_name | varchar(128) | 是 | 规则名称，租户内唯一 |
| description | varchar(512) | 否 | 规则描述 |
| product_id | bigint | 是 | 关联产品 ID |
| status | tinyint | 是 | 状态：0-禁用 1-启用 |
| trigger_type | varchar(16) | 是 | 触发类型：property/event/status/timer |
| trigger_config | text | 是 | 触发条件配置（JSON） |
| logic_type | varchar(8) | 是 | 条件逻辑：AND/OR |
| action_type | varchar(32) | 是 | 动作类型 |
| action_config | text | 是 | 动作配置（JSON） |
| action_mode | varchar(16) | 否 | 执行模式：serial/parallel |
| retry_count | int | 否 | 失败重试次数，默认 3 |
| rate_limit | int | 否 | 触发频率限制（次/分钟），默认 10 |
| trigger_count | bigint | 是 | 累计触发次数 |
| last_trigger_time | datetime | 否 | 最后触发时间 |
| creator | varchar(64) | 否 | 创建者 |
| create_time | datetime | 是 | 创建时间 |
| updater | varchar(64) | 否 | 更新者 |
| update_time | datetime | 是 | 更新时间 |
| deleted | bit(1) | 是 | 逻辑删除 |
| tenant_id | bigint | 是 | 租户 ID |
iot_alarm_record 告警记录表：
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | bigint | 是 | 主键 |
| alarm_rule_id | bigint | 是 | 触发的告警规则 ID |
| device_id | bigint | 是 | 告警设备 ID |
| product_id | bigint | 是 | 所属产品 ID |
| alarm_level | tinyint | 是 | 告警等级：0-提示 1-一般 2-严重 3-紧急 |
| alarm_content | varchar(512) | 是 | 告警内容 |
| trigger_value | varchar(64) | 否 | 触发时的属性值 |
| threshold_value | varchar(64) | 否 | 告警阈值 |
| status | tinyint | 是 | 状态：0-待处理 1-处理中 2-已处理 3-已忽略 |
| handler | varchar(64) | 否 | 处理人 |
| handle_time | datetime | 否 | 处理时间 |
| handle_remark | varchar(512) | 否 | 处理备注 |
| notify_status | tinyint | 否 | 通知状态：0-未发送 1-已发送 2-发送失败 |
| alarm_time | datetime | 是 | 告警发生时间 |
| create_time | datetime | 是 | 记录创建时间 |
| tenant_id | bigint | 是 | 租户 ID |
iot_device_property_data 设备属性数据表（时序）：
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | bigint | 是 | 主键 |
| device_id | bigint | 是 | 设备 ID |
| product_id | bigint | 是 | 产品 ID |
| property_identifier | varchar(64) | 是 | 属性标识符 |
| property_value | varchar(256) | 是 | 属性值 |
| report_time | datetime | 是 | 上报时间 |
| create_time | datetime | 是 | 入库时间 |
| tenant_id | bigint | 是 | 租户 ID |
索引设计：复合索引 idx_device_property_time (device_id, property_identifier, report_time)；普通索引 idx_product_id、idx_report_time、idx_tenant_id。建议数据量大时迁移至时序数据库（TDengine/InfluxDB）。
六、跨模块联动
6.1 联动关系
| 联动模块 | 联动方向 | 联动内容 |
|---|---|---|
| 消息通知（02-03） | IoT → 消息通知 | 告警触发时通过短信/邮件/站内信通知相关人员 |
| 认证授权（01-01） | 认证 → IoT | IoT 接口鉴权依赖系统认证体系 |
| 角色权限（01-03） | 权限 → IoT | IoT 功能权限配置依赖 RBAC 权限模型 |
| 定时任务（02-03） | 定时 → IoT | 心跳检测、日志清理、OTA 定时升级依赖定时任务调度 |
| 数据报表（09-02） | IoT → 数据报表 | IoT 设备数据分析和导出复用数据报表模块 |
| 监控运维（02-05） | IoT → 监控 | IoT 平台自身的健康监控接入系统监控体系 |
| MES 制造执行（08-04） | IoT ↔ MES | IoT 设备数据可为 MES 提供设备状态和产能数据 |
6.2 详细联动说明
6.2.1 IoT → 消息通知（02-03）
| 联动场景 | 触发条件 | 联动行为 | 数据流向 |
|---|---|---|---|
| 告警通知 | 设备属性触发告警规则 | 调用消息通知模块发送短信/邮件/站内信 | IoT 告警记录 → 消息通知模板 → 用户 |
| 设备离线通知 | 设备心跳超时变为离线 | 发送离线告警通知给运维人员 | IoT 设备状态变更 → 消息通知 → 运维人员 |
| OTA 升级结果 | 升级任务完成/失败 | 发送升级结果通知 | IoT OTA 任务状态 → 消息通知 → 管理员 |
6.2.2 IoT ↔ MES 制造执行（08-04）
| 联动场景 | 触发条件 | 联动行为 | 数据流向 |
|---|---|---|---|
| 设备状态同步 | IoT 设备状态变更 | MES 查询设备可用性用于排产 | IoT 设备状态 → MES 设备管理 |
| 环境数据关联 | IoT 传感器上报环境数据 | MES 关联生产工单的质量数据 | IoT 属性数据 → MES 质量追溯 |
七、附录
7.1 名词解释
| 术语 | 通俗理解 |
|---|---|
| 产品（Product） | 一类设备的"模板"，就像"iPhone 16"是一个产品，每个人手里的具体手机是"设备" |
| 设备（Device） | 能联网的具体物理实体，就像你手里那台具体的手机 |
| 物模型（Thing Model） | 设备的"岗位说明书"——定义它能汇报什么（属性）、遇到什么事要报告（事件）、能接什么指令（服务） |
| 属性（Property） | 设备定期汇报的数据，像体温计每隔几分钟报一次温度 |
| 事件（Event） | 设备主动报告的异常情况，像烟雾报警器检测到浓烟时自动报警 |
| 服务（Service） | 平台可以向设备下达的指令，像远程开机、调高风速 |
| DeviceKey/Secret | 设备的"身份证 + 密码"，用来证明"我是谁" |
| ProductKey/Secret | 产品的"统一社会信用代码"，标识产品身份 |
| 心跳（Heartbeat） | 设备定期向平台喊一声"我还活着"，平台听不到就认为设备掉线了 |
| OTA | 远程升级设备固件，就像手机推送系统更新，不用拆机器 |
| Topic | MQTT 协议中的"消息频道"，设备在特定频道上收发消息，像微信群聊 |
| 透传 | 数据不做任何格式转换直接传递，像原封不动转发别人的消息 |
| Alink JSON | 设备和平台之间的"标准普通话"——一种 JSON 格式的数据交换协议 |
| 规则引擎 | "如果…就…"的自动化引擎——温度超标就开排风扇，设备离线就发短信 |
| 场景联动 | 多个设备通过规则引擎自动协作，像"回家模式"自动开灯+开空调 |
| 设备分组 | 按区域/楼层等维度把设备分门别类管理，像电脑文件夹分类 |
| 数据解析 | 把设备说的"方言"翻译成平台能懂的"普通话"，支持 JS/Python 脚本 |
| 告警规则 | 给设备属性设"红线"——超过就报警，像体温超过 37.3℃ 就提示发烧 |
| 灰度升级 | 先给一小部分设备升级，没问题再全量推送，像软件内测→公测→正式版 |
| MQTT | 一种专门为物联网设计的通信协议，轻量、省电、适合设备长时间在线 |
| 时序数据 | 按时间顺序排列的数据，像每 5 秒记录一次的温度值，适合用专门的时序数据库存储 |
7.2 权限标识汇总
| 模块 | 权限标识 | 说明 |
|---|---|---|
| 产品管理 | iot:product:query / create / update / delete / publish / category | 产品 CRUD + 发布 + 品类管理 |
| 物模型管理 | iot:thing-model:query / create / update / delete / import / export | 物模型 CRUD + 导入导出 |
| 设备管理 | iot:device:query / create / update / delete / enable / disable / control / ota / debug | 设备全生命周期 + 控制 + OTA + 调试 |
| 设备分组 | iot:device-group:query / create / update / delete / assign | 分组 CRUD + 设备分配 |
| 规则引擎 | iot:rule:query / create / update / delete / enable / debug | 规则 CRUD + 启用禁用 + 调试 |
| 设备消息 | iot:message:query / parser | 消息查看 + 解析脚本管理 |
| 设备监控 | iot:monitor:query / export / alarm-rule / alarm | 监控数据 + 导出 + 告警规则 + 告警处理 |