设备维护平台接口关键技术标准规范说明指导书.doc

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

杭州天梦科技
二〇一〇年五月

更改履历
版本号
修改编号
更改时间
更改
图表和章节
更改简明描述
更改人
同意人
V1.0

-05-13

创建，形成初稿
叶庆国

V1.1

-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

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”，如“-06-22”。
2. 年月格式为“YYYYMM”，如“06”。
3. 包含时间日期格式统一为“YYYY-MM-DDTHH:MI:SS”，如“-06-22T14:00:00”。
4. 假如未约定日期格式，则DATE类型默认为“YYYY-MM-DD”，如“-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//XMLSchema-instance" xmlns:xsd="http://www.w3.org//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></NODE_CODE>
<NODE_PARENT>ead3b6fb-0c5e-482c-892d-d629f57b75ef</NODE_PARENT>
<NODE_VALUE />
<NODE_LEVEL xsi:nil="true" />
<NODE_CATEGORY></NODE_CATEGORY>
<NODE_TYPE></NODE_TYPE>
<NODE_SORT>10</NODE_SORT>
<ENABLE_STATE>1</ENABLE_STATE>
<NODE_MEMO>可控故障维修</NODE_MEMO>
<ADD_TIME>-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></NODE_CODE>
<NODE_PARENT>ead3b6fb-0c5e-482c-892d-d629f57b75ef</NODE_PARENT>
<NODE_VALUE />
<NODE_LEVEL xsi:nil="true" />
<NODE_CATEGORY></NODE_CATEGORY>
<NODE_TYPE></NODE_TYPE>
<NODE_SORT>20</NODE_SORT>
<ENABLE_STATE>1</ENABLE_STATE>
<NODE_MEMO>不可控故障维修</NODE_MEMO>
<ADD_TIME>-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></NODE_CODE>
<NODE_PARENT>ead3b6fb-0c5e-482c-892d-d629f57b75ef</NODE_PARENT>
<NODE_VALUE />
<NODE_LEVEL xsi:nil="true" />
<NODE_CATEGORY></NODE_CATEGORY>
<NODE_TYPE></NODE_TYPE>
<NODE_SORT>22</NODE_SORT>
<ENABLE_STATE>1</ENABLE_STATE>
<NODE_MEMO>频繁上下线</NODE_MEMO>
<ADD_TIME>-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//XMLSchema-instance" xmlns:xsd="http://www.w3.org//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
故障原因大类-
故障原因细类-
节点细类
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
故障类型编号，可在数据项中查询，参考参数以下
节点大类，
节点细类，
故障描述
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
错误描述
布署情况
设备维护平台