设备管理系统开发流程

面向物联网/工业互联网场景下的设备全生命周期管理（注册、接入、监控、控制、运维、报废），说明从立项到上线的可执行流程、技术要点与交付物，便于研发与项目经理直接落地。

1. 文档范围与读者

读者使用方式项目经理拆 WBS、排期、验收标准架构/后端接口、数据模型、消息与任务设计前端页面流、权限、大屏与表单测试用例维度、边界与压测指标运维环境、监控、发布与回滚

不纳入本文：具体品牌 PLC/模组 AT 指令细节（以项目选型手册为准）。

2. 系统目标（可验收）

建议立项时写成 SMART 指标，示例：

维度示例指标规模首期接入 ≥ N 台设备，支持水平扩展至 10N可用性核心 API 月可用性 ≥ 99.5%（或按合同）实时性关键遥测端到端 P95 ≤ T 秒（定义链路：设备→云端→前端）控制远程指令成功率 ≥ 99%，超时与重试策略可配置安全全链路 TLS、设备证书/密钥轮换、操作审计 100% 留痕

3. 总体开发阶段（瀑布+迭代混合）

plaintext

阶段0 可行性 / 立项
   ↓
阶段1 需求基线（BRD/PRD + 数据字典）
   ↓
阶段2 架构与原型（接口契约、物模型、非功能）
   ↓
阶段3 迭代开发（2～4 周一个 Sprint）
   ↓
阶段4 联调与试点（真实设备/网关）
   ↓
阶段5 测试与加固（安全、性能、灾备）
   ↓
阶段6 上线与移交（运维文档、培训）

落地建议：阶段 1～2 尽量「冻结」物模型与核心 API 版本；迭代中新增字段走 版本化扩展，避免线上大面积改表。

4. 阶段 1：需求与范围

4.1 必备需求清单

• 设备类型：网关、传感器、执行器、摄像头、第三方子系统等。

• 生命周期状态机：未激活 → 已注册 → 在线/离线 → 故障 → 维修中 → 停用 → 报废（按业务裁剪）。

• 数据类型：遥测（时序）、属性（慢变）、事件（告警）、指令（下行）、文件（OTA/日志）。

• 角色与权限：租户、站点、运维、只读访客；数据权限到设备/分组级。

• 合规：等保、关基、日志留存年限、个人信息（若有移动端账号）。

4.2 交付物

交付物说明PRD用户故事 + 验收标准（Given/When/Then）数据字典测点编码、单位、精度、读写权限、告警阈值接口清单对内/对外开放范围、速率限制、认证方式

4.3 用户故事示例（可贴进 Jira）

text

作为 运维人员，
我希望 按「产品型号 + 固件版本」批量查看设备在线率，
以便 快速定位某批次是否存在批量离线问题。

验收：筛选后列表展示在线/离线数与占比；导出 CSV；P95 查询 < 3s（1 万台规模下可接受索引方案）。

5. 阶段 2：架构设计

5.1 逻辑架构（参考）

plaintext

设备/网关 ──(MQTT/HTTP/Modbus 等)── 接入层 ── 消息总线/规则引擎
                                      │
                    ┌─────────────────┼─────────────────┐
                    ▼                 ▼                 ▼
                 时序存储          关系库/元数据      缓存/会话
                    │                 │                 │
                    └──────── 业务服务（设备、告警、OTA、租户） ────┘
                                      │
                              API 网关 / BFF ── Web / App / 开放 API

5.2 关键技术选型（决策表）

能力常见选项选型要点设备接入MQTT Broker、HTTP 长轮询弱网选 MQTT QoS1+离线缓存；高吞吐评估分片时序数据InfluxDB、TDengine、Timescale压缩率、SQL 熟练度、运维成本元数据MySQL / PostgreSQL事务、JSON 字段、审计表消息队列Kafka、RabbitMQ、MQTT 共享订阅指令下发顺序、死信队列OTA对象存储 + 任务表 + 分片下载断点续传、签名、灰度

5.3 物模型（Thing Model）示例

设备类型 SmartValve_V2：

标识符类型读写说明tempfloatR温度，℃，0.1valve_openboolR/W阀门开度到位反馈 / 控制signalintRRSSI 或信号质量err_codeenumR故障码

事件 alarm_high_temp： 载荷 { "value": 85.2, "threshold": 80 }。

物模型应 版本化（如 modelVersion: 2），老设备兼容读旧版本字段。

5.4 交付物

• C4 图（上下文/容器/组件）或等效说明

• OpenAPI 3.0 初稿（设备 CRUD、影子、指令、OTA）

• 威胁建模简要（STRIDE 或数据流图）

6. 阶段 3：迭代开发（按域拆分）

6.1 推荐迭代顺序（MVP → 增强）

Sprint 主题功能包技术要点M1 设备台账注册、分组、导入、基础查询幂等注册（deviceId+租户）；软删M2 接入与心跳认证、上线/离线、最后上报时间JWT/证书；心跳超时判离线M3 遥测上报、查询、聚合批量写入；降采样任务M4 告警规则、通知、确认规则 DSL 或脚本沙箱；防抖M5 指令下发、状态机、超时消息 ID 去重；异步结果回调M6 OTA（可选）包管理、任务、进度分片；失败重试与黑名单

6.2 核心 API 示例（REST）

注册或幂等创建：

http

POST /api/v1/devices
Authorization: Bearer <token>
Content-Type: application/json

{
  "deviceId": "HW-VALVE-000918",
  "productKey": "smart_valve_v2",
  "name": "1 号楼水阀",
  "siteId": "site-sh-01",
  "tags": { "building": "A", "floor": "3" }
}

下行控制（异步）：

http

POST /api/v1/devices/HW-VALVE-000918/commands
Content-Type: application/json

{
  "commandId": "cmd-20260328-001",
  "action": "set_valve",
  "params": { "openPercent": 60 },
  "timeoutSec": 30
}

响应 202 Accepted，客户端轮询或通过 WebSocket/MQTT 订阅 .../commands/{commandId}/result。

6.3 数据库表设计要点（元数据侧）

• 设备主表：id, device_id(业务唯一), tenant_id, product_key, status, secret/cert_sn, last_seen_at, metadata(JSON)。

• 审计表：谁在何时对哪台设备做了什么（指令、配置变更）。

• 指令表：command_id, device_id, status(pending/sent/ack/timeout/fail), payload, result。

索引：(tenant_id, device_id) 唯一；(tenant_id, last_seen_at) 列表筛选；告警可按 (device_id, rule_id, fired_at)。

6.4 代码与分支策略（落地）

• main 保护分支；develop 集成；feature/* 开发；hotfix/* 紧急修复。

• 接口契约：前后端共用 OpenAPI 生成类型或 Mock。

• 配置：十二因子；密钥不进库，用 KMS/环境变量。

7. 阶段 4：联调与试点

7.1 联调环境矩阵

环境用途数据Dev日常开发伪造设备脚本Staging与真实网关/样机脱敏或专用测试租户Prod生产仅发布窗口变更

7.2 设备模拟器清单（可自动化）

• MQTT 客户端脚本：定时发 telemetry，订阅 commands。

• 负载工具：模拟 1k/10k 连接（注意 Broker max_inflight、单客户端吞吐）。

7.3 试点检查表（节选）

• 注册 10～50 台真实设备，连续运行 72h 无内存泄漏

• 断网 5min 后自动重连，上行不丢（或明确可丢策略）

• 指令超时与重试符合 PRD

• 告警到钉钉/邮件/短信链路打通

8. 阶段 5：测试

8.1 测试类型与最低要求

类型关注点单元规则引擎、状态机、鉴权中间件集成接入层→DB→API 全链路接口契约测试（Pact 或 Postman CI）性能上报 TPS、指令延迟、列表查询 P95安全OWASP API Top10、越权访问（跨租户设备 ID）

8.2 性能基线示例

• 单分区 10k msg/s 遥测入库（需说明单条大小）；

• 设备列表 分页 20 条 P95 < 200ms（带索引）。

8.3 必测越权场景

text

租户 A 的 Token 请求 GET /devices/{租户B的deviceId} → 必须 404 或 403，且日志记审计。

9. 阶段 6：上线与运维

9.1 发布检查表

• 数据库迁移可回滚（或蓝绿+只增不改）

• 配置中心与密钥已更新

• 监控大盘：连接数、消息堆积、API 5xx、DB 慢查询

• 值班与 escalation 联系人

9.2 可观测性

• 日志：结构化 JSON，traceId 贯穿网关→服务。

• 指标：Prometheus：MQTT 连接数、消费 lag、指令成功率。

• 追踪：关键路径（可选 OpenTelemetry）。

9.3 移交包

• 部署手册（含端口、依赖版本）

• 备份与恢复演练记录（RTO/RPO）

• 管理员操作手册（禁用设备、重置密钥、OTA 紧急中止）

10. 风险与对策（常见）

风险对策需求蔓延每期冻结范围；变更走 CCB协议不统一网关适配层；物模型映射表时序数据爆炸TTL、降采样、冷热分层OTA 变砖双分区、签名校验、灰度 + 回滚包多租户串数据行级 tenant_id + 中间件强制注入

11. 附录 A：里程碑与工时粗算（示例）

里程碑周期（人天级参考）说明PRD+原型5～15视设备类型数量MVP 可演示20～40不含复杂 OTA试点上线+15～30含联调与安全基线

（实际需按团队规模与历史速率估算。）

12. 附录 B：术语

术语说明物模型设备能力与数据结构的抽象定义设备影子云端期望状态与设备上报状态的合并视图数字孪生（轻量）以实时数据驱动的设备状态镜像，非必须 3D

修订记录

版本日期说明1.02026-03-28初版：阶段、架构、API/表设计要点与检查表

使用说明：实施时将文中 N、T、超时等占位符替换为合同或内部 SLA；物模型与 API 路径请与真实代码仓库中的 OpenAPI 保持一致，避免文档与实现漂移。