物联网卡

一、卡平台

1、概述

背景：物联网卡有三大运营商，分别是中国移动、中国电信、中国联通。有很多公司会和三大运营商直签售卖物联网卡，这些公司一般会有自己的卡平台管理，因此做一个卡平台管理功能，方便和各平台对接；

目前已经对接了中国移动、中国电信5GCMP、中国联通、有人云物联卡、握手物联卡、智宇物联卡平台，每个平台可以创建多条对接信息；

2、各平台参数

2.1、中国移动

• apiBaseUrl：接口访问地址，目前是 http://111.10.45.200:7000
• appid和password：自行去中国移动物联卡能力开放平台-账户信息-客户信息-接入信息下查看
• transid：中国移动物联卡集团客户按照相应规则自主生成

2.2、中国电信5GCMP

• apiBaseUrl：接口访问地址，目前是 https://cmp-api.ctwing.cn:20164
• appKey和secretKey：自行去中国电信5G连接管理平台-能力开发-API网关账号管理下查看

2.3、中国联通

• apiBaseUrl：接口访问地址，目前是 https://gwapi.10646.cn/api
• appid和appSecret：鉴权参数，申请开通API功能时发放
• version：接口版本号，目前是 1.0
• openId：登录用户的openId

2.4、有人云物联卡

• apiBaseUrl：接口访问地址，目前是 https://sim-api.usr.cn
• appKey和appSecret：自行去有人云控制台-SIM管理-开发者中心-开发者信息下配置

  提示

  注意：需要配置接口白名单，填写自己物联网平台部署的IP地址即可

2.5、智宇物联卡

• apiBaseUrl：接口访问地址，目前是 https://api.wl1688.net/iotc/getway
• appid和appSecret：自行去智宇物联卡接口管理-接口信息下配置查看

2.6、握手物联卡

• apiBaseUrl：接口访问地址，目前是 http://tools.wosoiot.com:8080
• account和password：对应握手物联卡平台登录的账号和密码

二、卡概览

展示物联网卡各平台、卡状态、本月流量最多统计数据；

• 顶部：展示物联网卡各状态卡片数量；
• 运营商分布：展示各运营商物联网卡数量；
• 卡平台分布：展示各卡平台物联网卡数量；
• 本月流量最多：展示本月流量使用最多的10张物联网卡，还可查看是否报警；

三、SIM卡

1、卡列表

展示所有物联网卡分页列表信息；

• 搜索条件：ICCID号、IMSI号、卡号是模糊搜索；卡状态、卡平台（数据来源是卡平台列表）、运营商是精确匹配；

• 新增：选择对应的卡平台，然后输入ICCID号，能正确获取到卡信息则新增成功；

• 同步：点击同步按钮，会同步当前卡的信息；

• 查看：查看物联网卡详细信息；

2、卡详情

• 卡状态：点击右边的刷新按钮即可同步当前卡的状态；
• 已用流量：点击右边的刷新按钮即可同步当前卡的流量使用情况；
• 告警配置：流量告警阈值（已用流量占总流量的比例），通知用户配置-当已用流量超过告警阈值时会发邮箱通知配置的用户；
• 绑定设备信息：设备可通过 /info/post 主题上报物联网卡ICCID号，即可自动绑定该设备；也可以选择对应的设备绑定；同时设备详情也会展示物联网卡ICCID号；

3、设备上报ICCID号

发布设备信息，对应主题：/{productId}/{deviceNum}/info/post，具体参考Mqtt协议设备接入

• iccid：物联网卡的ICCID号，设备上传后，如果平台已经存在该SIM卡，则SIM卡会绑定该设备；如果平台不存在SIM卡，则先同步卡信息，并新增SIM卡，然后绑定该设备；

• cardPlatformId：卡平台编号，设备如果上传，则根据对应的卡平台查询SIM卡信息，如果不上传，则默认遍历所有卡平台查询；

  # 描述：1.设备上电后发布设备信息； 2.设备接收到设备信息指令后发布设备信息
  # iccid            可选，物联网卡的ICCID号，设备使用物联网卡时上传
  # cardPlatformId   可选，对应物联网卡管理-卡平台编号，设备上传ICCID号时上传，如果不上传则默认遍历所有卡平台查询
  
  {
       "rssi": -43,
       "firmwareVersion": 1.2,
       "status": 3,
       "userId": 2, 
       "longitude": 0,
       "latitude": 0,
       "iccid": 898604293620C0000970,
       "cardPlatformId": 0,
       "summary": {
   	    "name": "FastBee",
   	    "chip": "ESP8266",
   	    "author": "fastbee",
   	    "deliveryTime": "2023-06-06",
   	    "activeTime": "2022-10-01"
       }
   }

4、定时同步

配置了一个系统定时任务，每隔10分钟会同步所有物联网卡流量信息；

四、二次开发

1、卡平台对接

• 新增卡平台：字典类型是 iot_card_platform，在此字典类型下新增卡平台；

• 卡平台信息：在字典备注里编写卡平台对应的认证参数，采用key-value的形式；然后在后端Java代码里找到这个类com.fastbee.common.extend.core.card.CardPlatformConfigContent，如果没有对应的认证参数，则自己添加；

• 根据新平台新建一个服务类，实现ICardPlatformFactoryService类，在实现方法里编写对应的业务

• 找到CardPlatformFactory类，添加新平台的服务类，然后在getService里面添加返回该服务类

五、后续优化

1、接入一些其它物联卡经销商的平台；
2、考虑接入NB卡管理；

六、配置验收

验收项	正常表现
卡平台	API 地址、账号、密钥配置正确
新增 SIM 卡	输入 ICCID 后能同步卡基础信息
卡状态	状态、流量、套餐等信息可刷新
设备绑定	设备上报 ICCID 后自动绑定卡
流量告警	超过阈值后能触发通知
定时同步	定时任务能周期同步卡信息

七、常见问题

新增卡失败

检查卡平台 API 白名单、账号密钥、ICCID 是否存在、运营商平台是否开放接口。

设备上报 ICCID 后没有绑定

检查 /info/post 报文中的 iccid 和 cardPlatformId，以及平台是否能同步到该卡。

流量不同步

检查定时任务状态、卡平台接口可用性、服务器 IP 白名单和接口限流。

告警没有发送

检查告警阈值、通知用户、邮箱或通知渠道配置。

八、二次开发入口

类型	路径或接口	说明
前端页面	vue3/src/views/iot/card	卡平台、卡概览、SIM 卡列表
后端接口	卡管理相关接口	卡平台和 SIM 卡管理
后端扩展	ICardPlatformFactoryService	新卡平台接入
配置类	CardPlatformConfigContent	卡平台认证参数
数据表	iot_card、iot_card_platform	SIM 卡和平台配置