设备维护平台接口技术规范说明书[2013-05-13]...doc

设备维护平台
接口技术规范说明书
（版本号 V1.0）

杭州天梦科技有限公司
二〇一〇年五月

更改履历
版本号
修改编号
更改时间
更改的
图表和章节
更改简要描述
更改人
批准人
V1.0

2013-05-13

创建，形成初稿
叶庆国

V1.1

2014-06-09

维修业务操作接口调整，仅开放维保单位相关操作接口
叶庆国

注：更改人除形成初稿，以后每次修改在未批准确认前均需采用修订的方式进行修改。

设备维护平台接口技术规范说明书
目 录
1 概述 2
1.1 编写目的 2
1.2 预期读者 2
1.3 参考文献 2
2 接口平台设计 2
2.1 技术架构 2
2.1.1 接口架构图 2
2.1.2 业务流图 3
2.2 部署方式 4
2.3 接口标准 4
2.3.1 技术标准 4
2.3.2 数据规约 5
2.3.3 示例 6
3 WEBSERVICE服务 7
3.1 设备维护平台提供的服务 7
3.1.1 接口服务清单 7
3.1.2 接口服务设计 8

I

设备维护平台接口技术规范说明书
1 概述
1.1 编写目的
为设备维护平台的信息同步和共享，制定了统一的接口规范，用来指导各系统的接口设计、开发、联调及迁移工作。
范围：本文档主要是对设备维护平台与外围业务系统的数据交互需求进行说明。
1.2 调试要求
强烈要求第三方调用者，先做测试库的接口调试，确保接口及参数调用正确，否则将对正式库可能出现的系统故障承担主要责任。

1.3 预期读者
项目组人员、各交互系统涉及到的开发厂家。
1.4 参考文献
《智能交通设备维护管理系统设备接入标准》 杭州天梦科技有限公司

2 接口平台设计
2.1 技术架构
2.1.1 接口架构图
（暂缺）

2.1.2 业务流图
说明：用户通过接口。

2.2 部署方式
接口服务层包括Webservice服务、展现集成服务。
1、 Webservice服务
各系统提供的接口服务统一部署在设备维护平台接口服务层上，各系统客户端和接口服务层用SOAP协议通过HTTP来交互，客户端根据WSDL描述文档生成SOAP请求消息发送到服务端，服务端解析收到的SOAP请求，调用Web service，然后再生成相应的SOAP应答送回到客户端。
2、 展现集成服务
展现集成服务主要是应用界面集成服务，由服务提供方提供详细的URL及相关参数说明，调用方传入参数，调用服务方提供的页面进行展现。
3、 平台Service组件服务
平台Service组件服务统一部署在设备维护平台接口服务层上，通过平台接口服务层进行查询操作。
2.3 接口标准
2.3.1 技术标准
2.3.1.1 简述
客户端和服务器用SOAP协议通过HTTP来交互，客户端根据WSDL描述文档生成SOAP请求消息发送到服务端，服务端解析收到的SOAP请求，调用Web service，然后再生成相应的SOAP应答送回到客户端。
2.3.1.2 认证机制
设备维护平台提供的所有WebService服务均需要认证授权才能被调用，Webservice服务接收到请求后从传入参数中获取用户名和密码，进行认证，认证通过后再调用具体服务。
2.3.2 数据规约
2.3.2.1 简述
客户端和服务端采用XML格式的字符串来交互业务数据，客户端将业务数据组织成XML格式的字符串作为最后一个入参调用服务端接口，服务端解析XML格式的字符串得到业务数据处理业务并把结果组织成XML格式的字符串返回给客户端。
接口调用的结果，自动序列化后，以XML格式的字符串返回，其中包含了接口调用中出现的错误描述。
2.3.2.2 格式约定
若是业务接口调用，将以DataItem_Rsp类实例序列化，表示单一数据项，内容包括操作结果、错误描述，无数据集。
若是查询接口调用，将以EntSetSerialize_Rsp类实例序列化，表示查询结果，其中包括错误描述，有数据集。
XML字符串中，若是节点取值为null，则是<BANK_CODE xsi:nil="true"></BANK_CODE>，在节点中存在属性xsi:nil="true"；若是节点取值为空字符串，则是<BANK_NAME/>。
XML编码格式为“UTF-8”；
字段为日期的遵循以下约定：
1. 年月日格式统一为“YYYY-MM-DD”，如“2006-06-22”。
2. 年月格式为“YYYYMM”，如“200606”。
3. 包含时间的日期格式统一为“YYYY-MM-DDTHH:MI:SS”，如“2006-06-22T14:00:00”。
4. 如果未约定日期格式，则DATE类型的默认为“YYYY-MM-DD”，如“2006-06-22”。
2.3.2.3 格式DTD
暂缺
2.3.3 示例
2.3.3.1 示例：查询接口，包含数据集
<?xml version="1.0" encoding="utf-8" ?>
<EntSetSerialize_RspOfMNG_DATA_DICTIONARY xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://tempuri.org/">
<IsError>0</IsError>
<ErrorNo>0</ErrorNo>
<ErrorDesc>操作成功</ErrorDesc>
<TotalCount>3</TotalCount>
<RspCount>3</RspCount>
<RspPageSize>10</RspPageSize>
<RspPageIndex>0</RspPageIndex>
<RspPageTotal>1</RspPageTotal>
<EntList>
<MNG_DATA_DICTIONARY>
<IsCreated>true</IsCreated>
<NODE_GUID>e4fb99cf-108b-4688-b124-43ae8a2b5787</NODE_GUID>
<NODE_NAME>可控的故障维修</NODE_NAME>
<NODE_CODE>900308010</NODE_CODE>
<NODE_PARENT>ead3b6fb-0c5e-482c-892d-d629f57b75ef</NODE_PARENT>
<NODE_VALUE />
<NODE_LEVEL xsi:nil="true" />
<NODE_CATEGORY>900501010</NODE_CATEGORY>
<NODE_TYPE>900308010</NODE_TYPE>
<NODE_SORT>10</NODE_SORT>
<ENABLE_STATE>1</ENABLE_STATE>
<NODE_MEMO>可控的故障维修</NODE_MEMO>
<ADD_TIME>2011-09-26T17:20:17</ADD_TIME>
<UPDATE_TIME xsi:nil="true" />
</MNG_DATA_DICTIONARY>
<MNG_DATA_DICTIONARY>
<IsCreated>true</IsCreated>
<NODE_GUID>195a341c-35dc-43ab-a2fc-b050be12ea0c</NODE_GUID>
<NODE_NAME>不可控的故障维修</NODE_NAME>
<NODE_CODE>900308020</NODE_CODE>
<NODE_PARENT>ead3b6fb-0c5e-482c-892d-d629f57b75ef</NODE_PARENT>
<NODE_VALUE />
<NODE_LEVEL xsi:nil="true" />
<NODE_CATEGORY>900501010</NODE_CATEGORY>
<NODE_TYPE>900308020</NODE_TYPE>
<NODE_SORT>20</NODE_SORT>
<ENABLE_STATE>1</ENABLE_STATE>
<NODE_MEMO>不可控的故障维修</NODE_MEMO>
<ADD_TIME>2011-09-26T17:20:32.187</ADD_TIME>
<UPDATE_TIME xsi:nil="true" />
</MNG_DATA_DICTIONARY>
<MNG_DATA_DICTIONARY>
<IsCreated>true</IsCreated>
<NODE_GUID>c648d4d3-9a7e-4f3f-8a2f-96f94cb9d978</NODE_GUID>
<NODE_NAME>频繁上下线</NODE_NAME>
<NODE_CODE>900308030</NODE_CODE>
<NODE_PARENT>ead3b6fb-0c5e-482c-892d-d629f57b75ef</NODE_PARENT>
<NODE_VALUE />
<NODE_LEVEL xsi:nil="true" />
<NODE_CATEGORY>900501010</NODE_CATEGORY>
<NODE_TYPE>900308030</NODE_TYPE>
<NODE_SORT>22</NODE_SORT>
<ENABLE_STATE>1</ENABLE_STATE>
<NODE_MEMO>频繁上下线</NODE_MEMO>
<ADD_TIME>2011-11-24T23:28:17.953</ADD_TIME>
<UPDATE_TIME xsi:nil="true" />
</MNG_DATA_DICTIONARY>
</EntList>
</EntSetSerialize_RspOfMNG_DATA_DICTIONARY>

2.3.3.2 示例：业务接口，只有返回标识
<?xml version="1.0" encoding="utf-8" ?>
<DataItem_Rsp xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://tempuri.org/">
  <IsError>0</IsError>
  <ErrorNo>0</ErrorNo>
  <ErrorDesc>授权帐号验证失败</ErrorDesc>
  <ItemType>System.Boolean</ItemType>
  <ItemValue>False</ItemValue>
</DataItem_Rsp>

3 Webservice服务
3.1 设备维护平台提供的服务
由于各用户单独安装部署，故对于WebService服务地址，另外单独提供。
3.1.1 接口服务清单
序号
服务名称
接口名称
说明
调用方
频率
1
ClientUserCheck
客户端信息验证

第三方
实时
2
BaseData_DevList
基础数据.设备清单查询

第三方
实时
3
BaseData_OrgList
基础数据.组织机构及设备分组清单查询

第三方
实时
4
BaseData_DictionaryList
基础数据.数据字典代码项查询

第三方
实时
5
DevRep_FaultSearch
业务流程.故障上报查询

第三方
半小时
6
DevRep_FaultReport
故障上报

第三方
半小时
7
DevRep_RepairSearch
业务流程.报修查询

第三方
半小时
8
DevRep_RepFeeApp
维修报价申请

第三方
半小时
9
DevRep_FaultRsp
维修响应

第三方
半小时
10
DevRep_FaultFeedback
维修反馈

第三方
半小时
11
DevRep_RepairAudit
维修审核

第三方
半小时
12

3.1.2 接口服务设计
3.1.2.1 客户端信息验证
服务名称
ClientUserCheck
接口声明
public DataItem_Rsp ClientUserCheck(string clientUser, string clientPwd, string clientIp)
描述
客户端信息验证

中文名
字段名
长度类型
非空
说明及数据要求
入参
登录帐号
clientUser
string
Y

登录密码
clientPwd
string
Y

用户IP
clientIp
string
Y

出参
IsError
0：有错误；
1：无错误
ItemType
数据项类型
ItemValue
数据项取值
ErrorDesc
错误描述
部署情况
设备维护平台

3.1.2.2 基础数据，设备清单查询
服务名称
BaseData_DevList
接口声明
public EntSetSerialize_Rsp<View_DEVICE_PURCHASE> BaseData_DevList(string devType, string devIp, string devGuid, string devCodeSdk, string devChannel
, string unitRepGuid, Int32 pageIndex, string clientUser, string clientPwd, string clientIp)
描述
基础数据.设备清单查询

中文名
字段名
长度类型
非空
说明及数据要求
入参
设备类型
devType
string
N

设备IP
devIp
string
N

设备GUID
devGuid
string
N

设备接口编号
devCodeSdk
string
N
来自第三方设备平台
设备通道号
devChannel
string
N

维保单位GUID
unitRepGuid
string
N
作为维保方，其登录帐号所属单位GUID，可作为维保单位GUID
页索引
pageIndex
Int32
Y

登录帐号
clientUser
string
Y

登录密码
clientPwd
string
Y

用户IP
clientIp
string
Y

出参
IsError
0：有错误；
1：无错误
ErrorDesc
错误描述
TotalCount
数据查询结果的总记录数
RspCount
实际返回的记录数
RspPageSize
分页查询的页大小
RspPageIndex
分页查询的页索引
RspPageTotal
分页查询的页总数
EntList
数据查询结果列表,采用泛型集合List<T>，自动序列化产生，根据查询接口不同，其中嵌套的对象及其字段名称也不同，以实际返回结果为准
部署情况
设备维护平台

3.1.2.3 基础数据，组织机构及设备分组查询
服务名称
BaseData_OrgList
接口声明
public EntSetSerialize_Rsp<BASIC_ORG_DOMAIN> BaseData_OrgList(Int32 pageIndex, string clientUser, string clientPwd, string clientIp)
描述
基础数据.组织机构及设备分组清单查询

中文名
字段名
长度类型
非空
说明及数据要求

页索引
pageIndex
Int32
Y

登录帐号
clientUser
string
Y

登录密码
clientPwd
string
Y

用户IP
clientIp
string
Y

出参
IsError
0：有错误；
1：无错误
ErrorDesc
错误描述
TotalCount
数据查询结果的总记录数
RspCount
实际返回的记录数
RspPageSize
分页查询的页大小
RspPageIndex
分页查询的页索引
RspPageTotal
分页查询的页总数
EntList
数据查询结果列表,采用泛型集合List<T>，自动序列化产生，根据查询接口不同，其中嵌套的对象及其字段名称也不同，以实际返回结果为准
部署情况
设备维护平台

3.1.2.4 基础数据，数据项查询
服务名称
BaseData_DictionaryList
接口声明
public EntSetSerialize_Rsp<MNG_DATA_DICTIONARY> BaseData_DictionaryList(Int32 pageIndex, string nodeCategory, string nodeType
, string clientUser, string clientPwd, string clientIp)
描述
基础数据.数据字典代码项查询

中文名
字段名
长度类型
非空
说明及数据要求

页索引
pageIndex
Int32
Y

节点大类
nodeCategory
string
Y
故障原因大类-900501010
故障原因细类-900501020
节点细类
nodeType
string
N

登录帐号
clientUser
string
Y

登录密码
clientPwd
string
Y

用户IP
clientIp
string
Y

出参
IsError
0：有错误；
1：无错误
ErrorDesc
错误描述
TotalCount
数据查询结果的总记录数
RspCount
实际返回的记录数
RspPageSize
分页查询的页大小
RspPageIndex
分页查询的页索引
RspPageTotal
分页查询的页总数
EntList
数据查询结果列表,采用泛型集合List<T>，自动序列化产生，根据查询接口不同，其中嵌套的对象及其字段名称也不同，以实际返回结果为准
部署情况
设备维护平台

3.1.2.5 业务流程，故障上报查询
服务名称
DevRep_FaultSearch
接口声明
public EntSetSerialize_Rsp<View_RECORD_FAULT_REPAIR> DevRep_FaultSearch(string reportUnitGuid, string faultAuditStatus, string devType, string faultType
, string faultTimeStart, string faultTimeEnd, string repStatus, string jobNo, string deviceGuid, int pageIndex
, string clientUser, string clientPwd, string clientIp)
描述
业务流程.故障上报查询

中文名
字段名
长度类型
非空
说明及数据要求
入参
上报单位GUID
reportUnitGuid
string
N
作为维保方，其登录帐号所属单位GUID，可作为上报单位GUID
故障审核状态
faultAuditStatus
string
N

设备类型
devType
string
N

故障类型
faultType
string
N

开始时间
faultTimeStart
string
N
故障时间
结束时间
faultTimeEnd
string
N
故障时间
维修状态
repStatus
string
N

工单号
jobNo
string
N

设备GUID
deviceGuid
string
N

页索引
pageIndex
Int32
Y

登录帐号
clientUser
string
Y

登录密码
clientPwd
string
Y

用户IP
clientIp
string
Y

出参
IsError
0：有错误；
1：无错误
ErrorDesc
错误描述
TotalCount
数据查询结果的总记录数
RspCount
实际返回的记录数
RspPageSize
分页查询的页大小
RspPageIndex
分页查询的页索引
RspPageTotal
分页查询的页总数
EntList
数据查询结果列表,采用泛型集合List<T>，自动序列化产生，根据查询接口不同，其中嵌套的对象及其字段名称也不同，以实际返回结果为准
部署情况
设备维护平台

3.1.2.6 业务流程，故障上报
服务名称
DevRep_FaultReport
接口声明
public DataItem_Rsp DevRep_FaultReport(string deviceGuid, string fault_Time, string fault_Type
, string fault_Remark, string clientUser, string clientPwd, string clientIp)
描述
故障上报

中文名
字段名
长度类型
非空
说明及数据要求

设备GUID
deviceGuid
string
Y

故障时间
fault_Time
string
Y

故障类型
fault_Type
string
Y
故障类型编号，可在数据项中查询，参考参数如下
节点大类，900501005
节点细类，900504050
故障描述
fault_Remark
string
Y

登录帐号
clientUser
string
Y

登录密码
clientPwd
string
Y

用户IP
clientIp
string
Y

出参
IsError
0：有错误；
1：无错误
ItemType
数据项类型
ItemValue
数据项取值
ErrorDesc
错误描述
部署情况
设备维护平台

3.1.2.7 业务流程，报修查询
服务名称
DevRep_RepairSearch
接口声明
public EntSetSerialize_Rsp<View_RECORD_FAULT_REPAIR_UNIT> DevRep_RepairSearch(string reportUnitGuid, string repTransferStatus, string devType, string faultType
, string faultTimeStart, string faultTimeEnd, string repStatus, string jobNo, string deviceGuid, int pageIndex
, string clientUser, string clientPwd, string clientIp)
描述
业务流程.报修查询

中文名
字段名
长度类型
非空
说明及数据要求
入参
上报单位GUID
reportUnitGuid
string
N
作为维保方，其登录帐号所属单位GUID，可作为上报单位GUID
维修移交状态
repTransferStatus
string
N

设备类型
devType
string
N

故障类型
faultType
string
N

开始时间
faultTimeStart
string
N
故障时间
结束时间
faultTimeEnd
string
N
故障时间
维修状态
repStatus
string
N

工单号
jobNo
string
N

设备GUID
deviceGuid
string
N

页索引
pageIndex
Int32
Y

登录帐号
clientUser
string
Y

登录密码
clientPwd
string
Y

用户IP
clientIp
string
Y

出参
IsError
0：有错误；
1：无错误
ErrorDesc
错误描述
TotalCount
数据查询结果的总记录数
RspCount
实际返回的记录数
RspPageSize
分页查询的页大小
RspPageIndex
分页查询的页索引
RspPageTotal
分页查询的页总数
EntList
数据查询结果列表,采用泛型集合List<T>，自动序列化产生，根据查询接口不同，其中嵌套的对象及其字段名称也不同，以实际返回结果为准
部署情况
设备维护平台

3.1.2.8 业务流程，维修报价申请
服务名称
DevRep_RepFeeApp
接口声明
public DataItem_Rsp DevRep_RepFeeApp(string fault_Repair_Unit_Guid, string repFeeMemo, decimal repFee
, string clientUser, string clientPwd, string clientIp)
描述
维修报价申请

中文名
字段名
长度类型
非空
说明及数据要求

维修记录GUID
fault_Repair_Unit_Guid
string
Y

申请描述
repFeeMemo
string
Y

申请费用
repFee
decimal
Y

登录帐号
clientUser
string
Y

登录密码
clientPwd
string
Y

用户IP
clientIp
string
Y

出参
IsError
0：有错误；
1：无错误
ItemType
数据项类型
ItemValue
数据项取值
ErrorDesc
错误描述
部署情况
设备维护平台

3.1.2.9 业务流程，维修响应
服务名称
DevRep_FaultRsp
接口声明
public DataItem_Rsp DevRep_FaultRsp(string fault_Repair_Unit_Guid, string fault_Reason_Memo
, string clientUser, string clientPwd, string clientIp)
描述
维修响应

中文名
字段名
长度类型
非空
说明及数据要求

维修记录GUID
fault_Repair_Unit_Guid
string
Y

维修响应说明
fault_Reason_Memo
string
Y

登录帐号
clientUser
string
Y

登录密码
clientPwd
string
Y

用户IP
clientIp
string
Y

出参
IsError
0：有错误；
1：无错误
ItemType
数据项类型
ItemValue
数据项取值
ErrorDesc
错误描述
部署情况
设备维护平台

3.1.2.10 业务流程，维修反馈
服务名称
DevRep_FaultFeedback
接口声明
public DataItem_Rsp DevRep_FaultFeedback(string fault_Repair_Unit_Guid, string feedback_Memo, int repairMinute_DelayAppaly
, string fault_Reason_Category, string fault_Reason_Type
, string clientUser, string clientPwd, string clientIp)
描述
维修反馈

中文名
字段名
长度类型
非空
说明及数据要求

维修记录GUID
fault_Repair_Unit_Guid
string
Y

维修反馈说明
feedback_Memo
string
Y

维修延迟时长
repairMinute_DelayAppaly
Int32
Y
单位：分钟
故障原因大类
fault_Reason_Category
string
Y
故障类型编号，可在数据项中查询
故障原因细类
fault_Reason_Type
string
Y
故障类型编号，可在数据项中查询
登录帐号
clientUser
string
Y

登录密码
clientPwd
string
Y

用户IP
clientIp
string
Y

出参
IsError
0：有错误；
1：无错误
ItemType
数据项类型
ItemValue
数据项取值
ErrorDesc
错误描述
部署情况
设备维护平台

3.1.2.11 业务流程，维修审核
服务名称
DevRep_RepairAudit
接口声明
public DataItem_Rsp DevRep_RepairAudit(string fault_Repair_Unit_Guid, bool isAudit, string repairAuditMemo, int repairMinute_DelayAppaly
, string clientUser, string clientPwd, string clientIp)
描述
维修审核

中文名
字段名
长度类型
非空
说明及数据要求

维修记录GUID
fault_Repair_Unit_Guid
string
Y

审核结果
isAudit
bool
Y
True-维修审核通过
False-维修返工，重新反馈
维修审核说明
repairAuditMemo
string
Y

维修延迟时长
repairMinute_DelayAppaly
Int32
Y
单位：分钟
登录帐号
clientUser
string
Y

登录密码
clientPwd
string
Y

用户IP
clientIp
string
Y

出参
IsError
0：有错误；
1：无错误
ItemType
数据项类型
ItemValue
数据项取值
ErrorDesc
错误描述
部署情况
设备维护平台

17