616 lines
20 KiB
Markdown
616 lines
20 KiB
Markdown
**物联网集抄及营收平台关于水表数据交互需求及接口规范**
|
||
|
||
版本号：V1.2
|
||
|
||
**福建省水投数字科技有限公司**
|
||
|
||
**2022年9月21日**
|
||
|
||
**\
|
||
**
|
||
|
||
文档修订记录
|
||
|
||
--------------- -------------------- ------------------------ -----------
|
||
**版本** **日期** **说明** **作者**
|
||
|
||
V0.1 2022/05/20 初稿 蔡贵城
|
||
|
||
V0.2 2022/05/30 补充流程及原型图 蔡贵城
|
||
|
||
V0.3 2022/06/06 补充接口、字段优化 蔡贵城
|
||
|
||
V1.0 2022/06/09 补充需求说明、调整格式 张旭
|
||
|
||
V1.1 2022/06/13 细节调整 蔡贵城
|
||
|
||
V1.2 2022/09/21 细节调整，明确对应关系 蔡贵城
|
||
--------------- -------------------- ------------------------ -----------
|
||
|
||
**\
|
||
**
|
||
|
||
目录
|
||
|
||
[1 需求说明 [4](#需求说明)](#需求说明)
|
||
|
||
[1.1 需求概述 [4](#需求概述)](#需求概述)
|
||
|
||
[1.2 已上线营收系统流程 [4](#已上线营收系统流程)](#已上线营收系统流程)
|
||
|
||
[1.3 未上线营收系统流程 [5](#未上线营收系统流程)](#未上线营收系统流程)
|
||
|
||
[2 页面功能及接口 [6](#页面功能及接口)](#页面功能及接口)
|
||
|
||
[2.1 物联网平台 [6](#物联网平台)](#物联网平台)
|
||
|
||
[2.1.1 厂家信息接口 [6](#厂家信息接口)](#厂家信息接口)
|
||
|
||
[2.1.2 厂家设备信息管理模块功能开发
|
||
[7](#厂家设备信息管理模块功能开发)](#厂家设备信息管理模块功能开发)
|
||
|
||
[2.1.3 表务对接日志 [9](#表务对接日志)](#表务对接日志)
|
||
|
||
[2.2 集抄平台 [9](#集抄平台)](#集抄平台)
|
||
|
||
[2.2.1 厂家设备信息管理（感觉对用户无意义建议去掉）
|
||
[9](#厂家设备信息管理)](#厂家设备信息管理)
|
||
|
||
[2.2.2 厂家供货设备管理 [11](#厂家供货设备管理)](#厂家供货设备管理)
|
||
|
||
[2.2.3 水司批量导入水表数据（无营收系统时-不含用户信息）
|
||
[12](#水司批量导入水表数据无营收系统时-不含用户信息)](#水司批量导入水表数据无营收系统时-不含用户信息)
|
||
|
||
[2.2.4 水表数据推送接口 [13](#水表数据推送接口)](#水表数据推送接口)
|
||
|
||
[2.2.5 水表用户信息同步接口
|
||
[16](#水表用户信息同步接口)](#水表用户信息同步接口)
|
||
|
||
[2.3 营收平台 [18](#营收平台)](#营收平台)
|
||
|
||
[2.3.1 需求 [18](#需求)](#需求)
|
||
|
||
[2.3.2 日志报表 [19](#_Toc21252)](#_Toc21252)
|
||
|
||
[3 附录 [19](#附录)](#附录)
|
||
|
||
[3.1 导入模板 [19](#导入模板)](#导入模板)
|
||
|
||
[3.1.1 厂家设备信息模板（水投找厂商）V1.0
|
||
[19](#厂家设备信息模板水投找厂商v1.0)](#厂家设备信息模板水投找厂商v1.0)
|
||
|
||
[3.1.2 厂家水表信息模板（厂家提供）V1.0
|
||
[19](#厂家水表信息模板厂家提供v1.0)](#厂家水表信息模板厂家提供v1.0)
|
||
|
||
[3.1.3 工程安装水表信息模板V1.3
|
||
[20](#工程安装水表信息模板v1.0)](#工程安装水表信息模板v1.0)
|
||
|
||
# 需求说明
|
||
|
||
## 需求概述
|
||
|
||
随着各水司营收平台及物联网和集抄平台的上线投产，在实际操作中发现多平台之间水表数据维护和自动抄表多有不便，本文档将明确厂家、水司用户、数科公司多角色与物联网平台、集抄平台、营收平台多方之间关于远传水表的维护及抄表数据交互需求。
|
||
|
||
物联网平台：维护各类物联感知设备，接收设备的数据，为各类设备进行维护管理。
|
||
|
||
集抄平台：物联网平台收到的水表数据后，会传到集抄平台，集抄平台管理水表。
|
||
|
||
## 已上线营收系统流程
|
||
|
||
营收平台：
|
||
|
||
1) 营收平台定时调用【厂家信息接口】获取水表厂家信息。
|
||
|
||
2) 水表厂家填写水表信息模板后，由水司用户导入营收平台的表务管理模块，营收平台调用【水表数据推送接口】将水表信息推送至集抄平台，集抄平台即可完成水表注册并接收水表上传数据。
|
||
|
||
3) 水司完成水表安装并完善营收平台立户/换表信息后，营收平台调用【水表用户信息同步接口】将水表用户信息推送至集抄平台。
|
||
|
||
4) 营收平台根据各水司需求定时调用【物联网平台通用接口-实时数据接口】获取抄表数据。（改为根据用户号+水表编号同时匹配获取）
|
||
|
||
{width="5.768055555555556in"
|
||
height="3.5972222222222223in"}
|
||
|
||
注：图片上的供应商改为厂家
|
||
|
||
## 未上线营收系统流程
|
||
|
||
{width="5.759722222222222in"
|
||
height="2.707638888888889in"}
|
||
|
||
注：图片上的供应商改为厂家
|
||
|
||
# 页面功能及接口
|
||
|
||
## 物联网平台
|
||
|
||
### 厂家信息接口
|
||
|
||
功能：营收需获取厂家列表信息，用于后续用户信息同步的标志字段
|
||
|
||
接口：
|
||
|
||
{width="2.8097222222222222in"
|
||
height="3.7041666666666666in"}
|
||
|
||
注：图片上的供应商改为厂家
|
||
|
||
接口url：[http://IP:端口/read](http://IP:端口/read)Meter
|
||
|
||
Headers属性：\"orderType\"：getFactory
|
||
|
||
加密方式同通用接口：使用appId取密钥进行加解密
|
||
|
||
营收端发送报文的参考样式：
|
||
|
||
{
|
||
|
||
\"encrypt\": \"AJbu0rLxmcJYmbohIz78XVJRhh6m0zMi\",
|
||
|
||
\"appId\": \"营收系统的APPID\",
|
||
|
||
\"uptime\": 1637627700039 //发送时间
|
||
|
||
}
|
||
|
||
返回结果：
|
||
|
||
{
|
||
|
||
\"retCode\": 0,
|
||
|
||
\"retVal\": \[
|
||
|
||
{
|
||
|
||
\"factoryCode\": \"001\",
|
||
|
||
\"factoryName\": \"宁波水表厂\"
|
||
|
||
},
|
||
|
||
{
|
||
|
||
\"factoryCode\": \"002\",
|
||
|
||
\"factoryName\": \"智恒水表\"
|
||
|
||
}
|
||
|
||
\]
|
||
|
||
}
|
||
|
||
### 厂家设备信息管理模块功能开发
|
||
|
||
描述说明：科技公司物联网管理员统一管理接入的水表型号及协议，可按水司、厂家、型号等信息进行条目添加与修改；
|
||
|
||
查询条件：水司名称（模糊搜索）、厂家编号、厂家名称（模糊搜索）、水表型号、设备口径（范围）、连接方式（下拉框选择）、IWaterGateway（模糊搜索）、IWaterGatewayPort
|
||
|
||
显示的列：水司名称、厂家编号、厂家名称、水表型号、协议名称、IWaterGateway、IWaterGatewayPort、最近修改人、最近修改时间
|
||
|
||
支持功能：查询、显示列表、下载模板（参考附录模板1）、上传数据（相同的做修改）、新增、编辑、查看详情、导出（选中导出、全部导出）
|
||
|
||
原型图例：（具体页面元素以上述描述为准）
|
||
|
||
{width="4.3694444444444445in"
|
||
height="2.567361111111111in"}
|
||
|
||
{width="5.759027777777778in"
|
||
height="0.8381944444444445in"}
|
||
|
||
新增、编辑界面：
|
||
|
||
{width="5.759722222222222in"
|
||
height="3.736111111111111in"}
|
||
|
||
### 表务对接日志
|
||
|
||
描述说明：用于物联网管理员查看营收系统推送到集抄的水表及用户信息的同步日志。
|
||
|
||
查询条件：水司、同步类型（设备信息、用户信息）、请求内容（模糊搜索）、响应内容（模糊搜索）、日志时间（范围）
|
||
|
||
显示的列：水司、同步类型、请求时间、请求内容、响应内容
|
||
|
||
支持功能：查询、显示列表、查看详情、导出（选中导出、全部导出）
|
||
|
||
{width="5.760416666666667in"
|
||
height="2.1798611111111112in"}
|
||
|
||
## 集抄平台
|
||
|
||
### 厂家设备信息管理
|
||
|
||
描述说明：用于水司管理员查看本水司已对接的水表协议信息，水表设备参数。
|
||
|
||
查询条件：厂家编号、厂家名称（模糊搜索）、水表型号、设备口径（范围）、连接方式（下拉框选择）、IWaterGateway（模糊搜索）、IWaterGatewayPort
|
||
|
||
显示的列：水司名称、厂家编号、厂家名称、水表型号、协议名称、IWaterGateway、IWaterGatewayPort
|
||
|
||
支持功能：查询、显示列表、查看详情、水表设备参数修改（除协议信息外）
|
||
|
||
原型图例：（具体页面元素以上述描述为准）
|
||
|
||
{width="5.7625in"
|
||
height="3.120833333333333in"}
|
||
|
||
{width="5.759027777777778in"
|
||
height="0.8381944444444445in"}
|
||
|
||
{width="5.754166666666666in"
|
||
height="0.8951388888888889in"}
|
||
|
||
详情：
|
||
|
||
{width="5.759722222222222in"
|
||
height="3.736111111111111in"}
|
||
|
||
### 厂家供货设备管理
|
||
|
||
描述说明：用于水司管理本水司水表设备信息（各厂家提供的水表导入、修改等）。
|
||
|
||
查询条件：厂家编号、厂家名称（模糊搜索）、水表型号、厂家水表编号、表身码、IMEI号、IMSI号、状态、最近修改时间（范围）
|
||
|
||
显示的列：厂家编号、厂家名称（模糊搜索）、水表型号、厂家水表编号、表身码、IMEI号、IMSI号、状态、最近修改人、最近修改时间
|
||
|
||
支持功能：查询、显示列表、查看详情、下载模板（参考附录模板2）、上传数据、新增、编辑、导出（选中导出、全部导出）
|
||
|
||
原型图例：（具体页面元素以上述描述为准）
|
||
|
||
{width="5.767361111111111in"
|
||
height="3.147222222222222in"}
|
||
|
||
{width="5.756944444444445in"
|
||
height="0.6833333333333333in"}
|
||
|
||
新增、编辑界面：
|
||
|
||
{width="5.763194444444444in"
|
||
height="3.6645833333333333in"}
|
||
|
||
### 水司批量导入水表数据（无营收系统时-不含用户信息）
|
||
|
||
无营收系统的情况下，可以由水司集抄管理员根据厂家提供的水表发货清单（按模板《厂家水表信息模板（厂家提供）V1.0》）导入集抄系统，同时生成物联网水表记录（状态为：未启用)
|
||
|
||
处理逻辑：新增、换表统一使用此接口；
|
||
|
||
新增根据水司编号，厂家编号，厂家名称，厂家水表编号，同步绑定到集抄对应的水表上，如果为找到匹配的返回失败；
|
||
|
||
换表：已绑定水表用户号的，根据水表用户号判断厂家水表编号出现变更，原水表变为注销状态，新水表绑定到此用户信息上。
|
||
|
||
处理结果都要保存处理日志，并提供展示
|
||
|
||
### 水表数据推送接口
|
||
|
||
处理逻辑：当有营收系统时，收到的水表清单《厂家水表信息模板（厂家提供）V1.0》先导入营收的表务仓库中，由营收推送新表数据到集抄的厂家水表信息中。水表数据过多则分批传，营收可点击按钮进行立即传输操作。
|
||
|
||
需求：
|
||
|
||
同步时间点：每天凌晨1点
|
||
|
||
每个请求同步最大水表数量：100条
|
||
|
||
{width="1.825in"
|
||
height="2.501388888888889in"}
|
||
|
||
接口url：[http://IP:端口/](http://IP:端口/read)meterSynchronization
|
||
|
||
Headers属性：\"orderType\"：waterMeterSynchronization
|
||
|
||
营收推送水表数据到物联网的水表管理表中
|
||
|
||
营收加字段IMEI、IMSI、表身码
|
||
|
||
集抄系统根据厂家编号对厂家水表编号、通讯模块号、IMEI（如有）、IMSI（如有）做重复值校验
|
||
|
||
提供字段：
|
||
|
||
----------------- ----------------- ----------------- -----------------
|
||
参数项 参数名称： 类型 是否必填
|
||
|
||
companyCode 水司编号 String 是
|
||
|
||
factoryId 厂家编号 String 是
|
||
|
||
factoryName 厂家名称 String 是
|
||
|
||
factoryCode 厂家水表编号 String 是
|
||
|
||
model 水表型号 String 是
|
||
|
||
sn 通讯模块号 String 是
|
||
|
||
imei IMEI号 String 是
|
||
|
||
imsi IMSI号 String 是
|
||
|
||
meterStatus 水表状态 String 是
|
||
----------------- ----------------- ----------------- -----------------
|
||
|
||
{
|
||
|
||
\"encrypt\": \"INRzRgCmvt20f1ia+H30IeDZ6Op/KJaDokup3ft9VqffW/hrixAU1TCgOB6HKSu6\",
|
||
|
||
\"appType\": \"jc\",
|
||
|
||
\"appId\": \"营收系统的appId\",
|
||
|
||
\"companyCode\": \"C021039\",
|
||
|
||
\"datas\": \[
|
||
|
||
{
|
||
|
||
\"companyCode\": \"C021039\",
|
||
|
||
\"factoryId\": \"001\",
|
||
|
||
\"factoryName\": \"宁波水表厂\",
|
||
|
||
\"factoryCode\": \"1111111115\",
|
||
|
||
\"model\": \"LXSY-15F\",
|
||
|
||
\"sn\": \"1111111115\",
|
||
|
||
\"imei\": \"1111111115\",
|
||
|
||
\"imsi\": \"1111111115\",
|
||
|
||
\"meterStatus\":\"启用\"
|
||
|
||
}
|
||
|
||
\],
|
||
|
||
\"uptime\": \"1660206753790\"
|
||
|
||
}
|
||
|
||
返回结果：
|
||
|
||
返回添加成功的数量、失败列表（包含失败原因）
|
||
|
||
{
|
||
|
||
\"success\": \"95\",
|
||
|
||
\"appId\": \"营收系统的APPID\",
|
||
|
||
\"datas\": \[
|
||
|
||
{
|
||
|
||
\"message\": \"已有\",
|
||
|
||
\"factoryCode\": \"11111111\",
|
||
|
||
> \...
|
||
|
||
},
|
||
|
||
{
|
||
|
||
\"message\": \"已有\",
|
||
|
||
\"factoryCode\": \"11111112\",
|
||
|
||
> \...
|
||
|
||
},
|
||
|
||
> \...
|
||
|
||
\],
|
||
|
||
\"uptime\": 1637627700039 //发送时间
|
||
|
||
}
|
||
|
||
### 水表用户信息同步接口
|
||
|
||
处理逻辑：营收系统在每日固定时间将更新的用户信息通过接口传输到物联网平台进行用户信息的更新。信息更新是根据厂家水表编号进行关联，营收可点击按钮进行立即传输操作。
|
||
|
||
需求：
|
||
|
||
同步时间点：凌晨1点
|
||
|
||
每个请求同步最大水表用户数量：100条
|
||
|
||
提供营收同步用户信息的接口
|
||
|
||
{width="2.3194444444444446in"
|
||
height="3.178472222222222in"}
|
||
|
||
接口url：[http://IP:端口/](http://IP:端口/read)meterSynchronization
|
||
|
||
Headers属性：\"orderType\"：userDataSynchronization
|
||
|
||
约定：
|
||
|
||
提供字段：
|
||
|
||
----------------- --------------------- ----------------- -----------------
|
||
参数项 参数名称： 类型 是否必填
|
||
|
||
companyCode 水司编号 String 是
|
||
|
||
factoryId 厂家编号 String 是
|
||
|
||
factoryName 厂家名称 String 是
|
||
|
||
factoryCode 厂家水表编号 String 是
|
||
|
||
sn 通讯模块号 String 是
|
||
|
||
userCode 水表用户号 String 是
|
||
|
||
name 用户名称(水表名称) String 是
|
||
|
||
area 区域名称(小区名称) String 是
|
||
|
||
position 经纬度 (x,y) String
|
||
|
||
meterType 用户类型(大表/小表) String 是
|
||
|
||
installAddr 安装地点 String 是
|
||
|
||
installPosition 安装位置 String
|
||
|
||
installTime 安装时间 String
|
||
|
||
installMan 安装人员 String
|
||
|
||
meterReader 抄表员 String
|
||
|
||
formCode 表册号 String
|
||
----------------- --------------------- ----------------- -----------------
|
||
|
||
加密方式同通用接口：使用appId取密钥进行加解密
|
||
|
||
规则为：根据水司编号、厂商编号和厂家水表编号修改水表信息
|
||
|
||
营收端发送报文的参考样式：
|
||
|
||
{
|
||
|
||
\"encrypt\": \"LmiSjZHIgFK6mZNDsItCd+DZ6Op/KJaDokup3ft9VqffW/hrixAU1TCgOB6HKSu6\",
|
||
|
||
\"appType\": \"jc\",
|
||
|
||
\"appId\": \"营收的appId\",
|
||
|
||
\"companyCode\": \"C021039\",
|
||
|
||
\"datas\": \[
|
||
|
||
{
|
||
|
||
\"companyCode\": \"水司编号\",
|
||
|
||
\"factoryId\": \"厂家编号\",
|
||
|
||
\"factoryName\": \"厂家名称\",
|
||
|
||
\"factoryCode\": \"厂家水表编号\",
|
||
|
||
\"sn\": \"通讯模块号\",
|
||
|
||
\"userCode\": \"用户号\",
|
||
|
||
\"name\": \"用户名称\",
|
||
|
||
\"area\": **区域**,
|
||
|
||
\"position\": **经纬度**,
|
||
|
||
\"meterType\": \"水表类型\",
|
||
|
||
\"installAddr\": \"安装地点\",
|
||
|
||
\"installPosition\": \"安装位置\",
|
||
|
||
\"installTime\": \"安装时间\",
|
||
|
||
\"installMan\": **安装人员**,
|
||
|
||
\"meterReader\": \"抄表员\",
|
||
|
||
\"formCode\": \"表册号\"
|
||
|
||
},
|
||
|
||
\"uptime\": 1637627700039 //发送时间
|
||
|
||
}
|
||
|
||
返回结果：
|
||
|
||
返回成功修改的用户数，失败列表（水表用户号）
|
||
|
||
{
|
||
|
||
\"success\": \"95\",
|
||
|
||
\"appId\": \"营收系统的APPID\",
|
||
|
||
\"datas\": \[
|
||
|
||
> {
|
||
>
|
||
> \"userCode\": \"42800000001\"，
|
||
>
|
||
> \"errMsg\": \"\"
|
||
>
|
||
> },
|
||
>
|
||
> {
|
||
>
|
||
> \"userCode\": \"42800000002\"，
|
||
>
|
||
> \"errMsg\": \"\"
|
||
>
|
||
> }
|
||
>
|
||
> \...
|
||
|
||
\],
|
||
|
||
\"uptime\": 1637627700039 //发送时间
|
||
|
||
}
|
||
|
||
## 营收平台
|
||
|
||
### 需求
|
||
|
||
1) 营收平台定时调用【厂家信息接口】获取水表厂家信息。
|
||
|
||
2) 水表厂家填写水表信息模板后，由水司用户导入营收平台的表务管理模块，营收平台调用【水表数据推送接口】将水表信息推送至集抄平台，集抄平台即可完成水表注册并接收水表上传数据。
|
||
|
||
3) 水司完成水表安装并完善营收平台立户/换表信息后，营收平台调用【水表用户信息同步接口】将水表用户信息推送至集抄平台。
|
||
|
||
4) []{#_Toc21252
|
||
.anchor}营收平台根据各水司需求定时调用【物联网平台通用接口-实时数据接口】获取抄表数据。（改为根据用户号+厂家水表编号同时匹配获取）
|
||
|
||
### 日志报表
|
||
|
||
报表查询模块增加水表数据和用户信息两个接口推送情况统计报表，格式营收平台自行确定，两个原则，成功可看数量，失败可看明细。
|
||
|
||
### 获取集抄抄表数据
|
||
|
||
用户编号： userCode（用户编号）
|
||
|
||
水表编号：factoryCode（厂家水表编号）
|
||
|
||
{width="5.7625in"
|
||
height="6.610416666666667in"}
|
||
|
||
# 附录
|
||
|
||
## 导入模板
|
||
|
||
### 厂家设备信息模板（水投找厂商）V1.0
|
||
|
||
{width="5.750694444444444in"
|
||
height="0.8131944444444444in"}
|
||
|
||
注：图片上的供应商改为厂家
|
||
|
||
### 厂家水表信息模板（厂家提供）V1.0
|
||
|
||
{width="5.761111111111111in"
|
||
height="2.1902777777777778in"}
|
||
|
||
注：图片上的供应商改为厂家
|
||
|
||
### 工程安装水表信息模板V1.0
|
||
|
||
{width="5.764583333333333in"
|
||
height="0.88125in"}
|
||
|
||
注：图片上的供应商改为厂家
|
||
|
||
模板：
|
||
|
||
|