第3章 建模前准备工作：设备信息采集表、云端接口文档清单、网络拓扑图

适用场景

本章适用于IoT系统架构师、设备开发工程师、云平台对接开发人员在开始进行云端交互流程建模之前，系统性地收集和整理必要的基础信息。典型场景包括：

• 新接入一批IoT设备到现有云平台时，需要明确每类设备的数据上报方式、控制指令格式和网络拓扑位置。
• 对已有系统进行建模重构或迁移时，需要盘点所有设备与云端之间的接口依赖和物理连接关系。
• 在团队协作建模前，统一信息采集标准和接口描述规范，避免因数据缺失导致后续建模返工。

前置条件

• 已明确建模范围：包括设备类型、云平台、网络环境。
• 具备访问设备配置工具（如串口调试、AT指令工具）和云端管理后台的权限。
• 已准备项目文档模板（设备信息采集表模板、接口文档模板、网络拓扑图模板）。
• 团队成员角色清晰：设备负责人、云平台负责人、建模工程师。

操作步骤

1. 创建设备信息采集表：按设备类型分别制作采集表，包含设备标识、通信协议、数据主题、上报频率、控制指令列表等字段。
2. 逐设备填写并验证：通过实际设备或设备文档获取真实参数，填入采集表；对不确定字段须通过实测确认。
3. 整理云端接口文档清单：收集云平台对外暴露的API、MQTT主题、Webhook回调等接口，按照“接口名称-方法/主题-入参-出参-说明”整理为清单。
4. 绘制网络拓扑图：识别所有设备节点、网关、交换机、云服务器及中间件，标注IP/域名、端口、协议，形成分层拓扑。
5. 交叉校验一致性：确保设备采集表中的通信参数与云端接口文档中对应的主题/API完全匹配；拓扑图中的网络路径与接口文档中的连接关系一致。
6. 归档并发布：将三个产出物提交至项目共享文档库，并邮件通知相关角色。

输入输出物

责任边界

• 设备负责人：保证设备信息采集表中的参数与实际设备一致；对采集表内容的真实性负责。
• 云平台负责人：提供最新的云端接口文档清单，确保接口版本与生产环境一致；对接口清单的准确性负责。
• 建模工程师：负责整合采集表和接口清单，绘制网络拓扑图；对三份材料的完整性、一致性负最终审核责任。

记录材料

以下为设备信息采集表的推荐格式（JSON示例）：

{
  "deviceType": "温湿度传感器_R12",
  "deviceId": "R12-AABBCCDD",
  "protocol": "MQTT 3.1.1",
  "broker": "mqtt.iot.example.com:8883",
  "publishTopic": "devices/r12/data",
  "subscribeTopic": "devices/r12/cmd",
  "dataFormat": "JSON",
  "payloadExample": "{\"temp\":25.3,\"hum\":68.1,\"ts\":1710000000}",
  "commandList": [
    {"cmd":"restart","payload":"{}","ackRequired":true},
    {"cmd":"setInterval","payload":"{\"interval\":60}","ackRequired":true}
  ],
  "firmwareVersion": "v2.1.0",
  "timezone": "UTC+8"
}

云端接口文档清单示例（表格形式归档）：

异常处理

• 设备信息采集表与实物不符：停止使用采集表，重新通过串口/AT指令读取设备实际参数，并更新文档；同时记录异常日志。
• 云端接口文档版本过期：立即联系云平台负责人确认最新版本，废弃旧文档，更新清单后重新发布。
• 网络拓扑图缺少关键节点：启动网络勘察流程，利用 traceroute、抓包等方式补全遗漏的网关或中间件，并更新拓扑。
• 交叉校验发现一致性冲突：召集设备负责人和云平台负责人现场会议，逐项核对冲突点，达成一致后修改对应文档。

验收标准

• 设备信息采集表覆盖所有建模范围内的设备类型，每个字段均有真实来源（文档截图或实测记录）。
• 云端接口文档清单包含至少10个核心接口/主题，且每个接口的入参出参描述完整。
• 网络拓扑图采用分层绘制（设备层-网关层-网络层-云平台层），节点之间连线有协议和端口标注。
• 三份材料之间至少完成一次交叉一致性校验，并保留校验记录（如共享文档中的注释或独立的校验报告）。
• 所有文档已上传至项目文档库，并通知相关干系人审阅。