一、前置准备（必须先完成）
- 必要资料（向设备方/平台方索取）
  - 接入模式：设备直连 / 网关代理 / 平台采集（本平台去消费对方MQTT/HTTP）
  - 协议与地址：MQTT/HTTP服务地址与端口
  - 认证信息：账号/密码或密钥/签名算法、ClientId要求（若有）
  - Topic清单：含层级规范与变量段说明（设备编码所在层级）
  - 数据样例：真实上报JSON（至少包含设备编码、事件类型、事件时间、示例字段）
  - 物模型草案：关键字段清单、字段类型、枚举值、时间戳格式
- 平台账号与权限
  - 建议按项目或服务商使用独立账号；确认账号具备网络组件、产品、设备的增改权限

二、总体流程总览
1) 配置网络组件（MQTT/HTTP）
2) 创建产品与物模型
   - 网关产品（如用网关或平台采集方案）
   - 设备产品（真实设备）
   - 发布产品（自动建表）
3) 创建设备实例
   - 网关设备（如有）
   - 子设备（N台）
4) 绑定网络与Topic
5) 启用与验证（数据入库校验）
说明：
- 直连设备：可不建网关产品/设备，设备产品直连绑定网络并上报
- 网关/平台采集：需先建网关产品/网关设备，再建子设备并绑定到网关

三、步骤详解（以“网关代理/平台采集”通用流程为例）
步骤1：配置网络组件
- 入口：平台-网络管理-新增网络组件
- 填写项
  - 类型：MQTT（常用）或HTTP
  - 地址/端口：对方提供
  - 认证：账号/密码或密钥/签名（按文档要求）
  - ClientId/连接参数：若对方有格式要求需按要求填写
  - 备注：建议标注项目/厂商名称，便于后续识别
- 校验要点
  - 先用MQTT客户端连通测试（能订阅到任意公开主题最佳）
  - 认证失败优先检查账号状态、白名单、TLS/证书要求

步骤2：创建网关产品（如使用网关或平台采集）
- 入口：平台-产品管理-新增产品（类型：网关）
- 物模型设计建议
  - 必含设备标识字段：如 deviceId 或 sip（用于路由到子设备）
  - 事件类字段：type（枚举）、subType/desc（可选）、eventTime（long时间戳）
  - 其它业务字段：按对方数据样例补充
- 发布产品
  - 发布后平台自动在时序库创建超级表；未发布将导致后续入库失败
- 检查
  - 确认字段名与对方数据一致，时间字段勾选为时间列

步骤3：创建设备产品（真实设备）
- 入口：平台-产品管理-新增产品（类型：设备）
- 物模型设计建议
  - 不重复设备标识字段（已由网关路由确定）
  - 保留设备侧关注的业务字段，如 type、alertSubType、eventTime 等
  - 将 eventTime 设为时间列；枚举值与对方对齐
- 发布产品
  - 发布后生成对应设备超级表

步骤4：创建设备实例-网关设备
- 入口：平台-设备管理-新增设备（选择网关产品）
- 关键配置
  - 接入方式：网关记录 或 平台记录
    - 网关记录：数据由“网关代理”上报至平台
    - 平台记录：平台主动去对方平台消费（安全帽MQTT消费属此类）
  - 协议：MQTT（并备注厂商/平台名称）
  - 绑定网络组件：选择步骤1创建的网络组件
  - 订阅Topic：填写对方提供的Topic；中间层级不确定用“+”通配
    - 示例：/vendor/helmet/+/alarm
  - 启用：保存后先不启用，待子设备创建完一起启用
- 校验要点
  - 用MQTT客户端实测该Topic能收到与样例一致的数据
  - Topic变量段确定设备编码位置，便于后续路由

步骤5：创建设备实例-子设备（N台）
- 入口：平台-设备管理-新增设备（选择步骤3的设备产品）
- 关键配置
  - 设备编码：与上报数据中的设备标识一致，平台全局唯一
  - 接入方式：网关记录（通过网关代理）
  - 所属网关：选择步骤4的网关设备
  - 其它信息：名称、位置、单位、行业分类等
- 批量建议
  - 若数量大，先准备模板CSV后批量导入（如平台支持批量）
- 注意
  - 子设备不绑定网络组件与Topic，由网关设备统一订阅与路由

步骤6：启用与联调
- 入口：设备列表/网关设备详情
- 操作
  - 启用网关设备
  - 启用子设备
  - 观察监控页/日志：确认网关连接成功、订阅成功、消息接收正常
- 入库校验
  - 在平台查询实时/历史数据或直连时序库查询对应表
  - 核对字段映射是否正确、eventTime是否生效排序

四、直连设备（无网关）的差异化步骤
- 产品：仅需设备产品（可将设备编码作为辅助字段或不存储，视平台实现）
- 设备实例：接入方式选“直连”，直接绑定网络组件
- Topic：在设备实例上配置其专属Topic（若每台设备一个Topic），或采用平台方提供的统一Topic+设备编码路由
- 其余校验同上

五、平台推送（第三方向本平台推送HTTP/MQTT）
- 网络组件：配置为“平台接收”端点（若平台提供专属接入地址与认证）
- 安全策略：为对方创建独立账号与密钥，限制可见与写入范围
- 物模型与设备：与网关模式的设备侧一致
- 验证：让对方用真实报文调用接入地址，平台查收并入库

六、字段与物模型设计清单（避免入库失败）
- 必备
  - 路由字段：deviceId/sip（在网关模型中必需）
  - 时间字段：eventTime（long，设为时间列）
  - 类型字段：type（枚举或字符串，保持与对方一致）
- 不建议
  - 在设备模型中重复定义设备ID（已由路由确定）
  - 使用平台保留关键字作为字段名
- 变更
  - 发布后字段调整需评估对历史数据表结构影响，慎重变更；必要时新建版本产品

七、Topic与通配符配置指引
- 常见差异：文档与现场Topic中间多一层（如项目号/渠道号）
- 处理方法
  - 优先使用“+”单层通配匹配中间层
  - 样例：/v1/device/+/alarm 或 /org/+/helmet/+/event
- 验证
  - 使用MQTT客户端先订阅通配符Topic，确认能收到期望设备的数据

八、启用后的自检与排障
- 收不到数据
  - 网络组件未连通或认证失败：检查账号/密码/证书/白名单
  - Topic错误：客户端验证；核对通配层级数量
  - 未启用：确认网关与子设备均为启用状态
- 入库异常
  - 物模型字段名不一致/类型不匹配：对照样例修正
  - 未发布产品/表未生成：检查发布动作是否成功
  - 时间列未设置：导致排序/查询异常
- 路由失败
  - 网关模型中未正确解析设备编码
  - 子设备未创建或设备编码不一致（唯一索引冲突或找不到匹配）
- 性能问题
  - 平台主动采集负载高：优先引导改为对方推送
  - 大批量设备：提前估算队列/缓存资源，必要时分批启用

九、最佳实践与建议
- 先证后配：先用客户端验证MQTT/HTTP链路与Topic，再在平台录入配置
- N+1建模：网关产品+网关设备（1）+子设备（N），清晰解耦
- 简化字段：设备模型只保留必要业务字段；网关模型承载路由与原始结构
- 命名一致：字段名与对方对齐；枚举提前对表
- 批量导入：产品发布后，再批量导入设备，减少重复劳动
- 审计与隔离：项目/厂商独立账号与密钥；便于问题定位与权限控制

十、快速清单（实施现场可打印）
- 我是否拿到：地址/端口、认证、Topic、真实样例、设备编码列表？
- 我是否：创建了网络组件、创建并发布了网关/设备产品？
- 我是否：创建了网关设备并配置了Topic与网络组件？
- 我是否：为每台设备创建了子设备并与网关绑定，设备编码一致？
- 我是否：启用设备与网关、用监控与日志确认已接收到消息？
- 我是否：在平台或库中查到实时/历史数据，字段与时间正确？