上篇搞定了权限体系。这篇开始做第一个业务模块——设备管理。
设备是整个系统的第一环。没有设备注册进来，后面素材、节目、统计都无从谈起。
设备有哪些属性
回到之前画的表结构：
CREATETABLEt_device(idBIGINTPRIMARYKEY,device_noVARCHAR(50)NOTNULL,-- 设备编号（唯一）nameVARCHAR(100)NOTNULL,-- 设备名称modelVARCHAR(50),-- double_side/stand/wallgroup_idBIGINT,-- 所属分组resolutionVARCHAR(20)DEFAULT'1920x1080',layout_templateVARCHAR(50)DEFAULT'single',-- 分屏布局statusVARCHAR(20)DEFAULT'offline',-- online/offline/errorip_addressVARCHAR(50),last_heartbeatDATETIME,...);每个字段都有它的来由：
- device_no：设备唯一编号，相当于身份证。心跳上报和节目下发都靠它
- model：双面屏、立式屏、壁挂屏——不同型号播放器适配不同
- layout_template：单屏、左右分屏、上下分屏、三区——影响素材怎么排
- status：不在线的设备不发节目，避免浪费流量
- last_heartbeat：判断在线的依据——超过 5 分钟没心跳就算离线
设备分组的取舍
要不要做设备分组？我想了想——如果只有三五台设备，分组是多余的。但如果一个客户有 20 家门店，每家店 2 块屏，40 台设备不分组根本管不过来。
所以我做了分组，但做得极简：t_device_group就三个字段——名称、描述、创建更新时间。不搞嵌套分组，不搞继承关系，一级分组够用。
心跳机制
设备怎么上报心跳？一条 POST 请求：
POST /api/v1/devices/{deviceNo}/heartbeat后端更新last_heartbeat时间。前端列表页根据心跳判断在线状态：
- 5 分钟内有心跳 → 🟢 在线
- 超过 5 分钟 → ⚪ 离线
- 超过 30 分钟且之前在线 → 🔴 异常
这个接口是公开的——不需要登录。设备端播放器没有用户概念，它只管上报。
远程指令
有时候需要远程操作设备——重启、关机、调音量、调亮度。这些叫"指令"：
@PostMapping("/{id}/command")@RequirePermission("device:command")publicApiResult<Void>sendCommand(@PathVariableLongid,@RequestBodyCommandDTOdto){deviceService.sendCommand(id,dto);returnApiResult.success();}指令发出去后，状态流转是：
pending → sent → success/failed设备下次心跳时拉取待执行指令，执行完上报结果。不是实时的——但够用了。
Controller 全貌
50 个 Java 文件里，DeviceController 是最大的一个：
GET /api/v1/devices → 列表（分页 + 搜索） POST /api/v1/devices → 新增设备 GET /api/v1/devices/{id} → 设备详情 PUT /api/v1/devices/{id} → 编辑设备 DELETE /api/v1/devices/{id} → 删除设备 GET /api/v1/devices/{id}/commands → 指令历史 POST /api/v1/devices/{id}/command → 发送指令 GET /api/v1/devices/groups → 分组列表 POST /api/v1/devices/groups → 新建分组 DELETE /api/v1/devices/groups/{id} → 删除分组 GET /api/v1/devices/{deviceNo}/current-program → [公开] 拉取当前节目 POST /api/v1/devices/{deviceNo}/heartbeat → [公开] 心跳上报 POST /api/v1/devices/{deviceNo}/play-log → [公开] 播放日志认证接口 6 个，公开接口 3 个。每个认证接口都标了@RequirePermission——viewer 只能看列表，operator 能增能改，admin 能删。
到这里设备管理模块就完成了。设备能注册、有心跳、能分组、能远程发命令。下篇做素材管理——上传图片视频、分类管理。素材是整个系统里文件最多的模块。
关于作者：无羡，独立开发者，全栈工程师，专注 AI 应用与微服务架构。
📌 分类：技术复盘
🔗 个人博客 — 更多技术文章
✨ 开发者福利整理 — 云服务资源汇总
📂 软件工坊 — 我的技术分享
🌐 个人门户 — 独立开发作品全集
