文档编号：T-JKJS
文档版本：0.01
项目编号：XX-DX- PECS
《XX电信工程外部协作系统》
Project Exterior Cooperation
System
施工单位接口技术解决方案
编写人：南疯日期：2006-10-30
审核人：日期：
批准人：日期：
XXXXXX信息科技股份有限公司
地址：XXXXXXX 邮编：XXXXXX
电话：XXXXXXXX传真：XXXXXX
网站：XXXXXXXXX
修改记录（Revision Chart）
1引言
1.1编写目的
本文档为XX电信工程外部协作系统（以下简称外协系统）与电信工程施工单位内部系统（以下简称施工系统）接口技术解决方案，以此作为外协系统与施工系统实施接口的技术方案依据和项目设计标准。
1.2覆盖范围
XX电信工程外部协作系统项目组
施工系统接口开发技术组
1.3预期读者与阅读建议
XX电信企业信息化部
XX电信工程建设部
XXXX公司开发人员
施工系统开发人员
1.4文档约定
粗体正文表示强调内容
红色正文表示未完成或需要今后考虑的内容
蓝色正文表示待讨论内容
1.5术语与缩略语
术语、缩略语定义
外协系统XX电信工程外部协作系统
施工系统电信工程施工单位内部系统
PECS XX电信工程外部协作系统英文简称
1.6参考文献
(XXXX)
2概述
建设XX电信工程外部协作系统的目标，是在工程项目的管理、建设、使用和实施单位之间搭建起数据交换和协同工作的信息平台，延伸与拓展工程建设管理信息化的应用范围，实现通信工程建设过程的信息化管理，促进工程项目的管理部门、建设部门、实施部门和使用部门之间业务流程协调有序地开展，实现工程项目设计、施工、监理管理功能，将相关的设计、施工、监理单位纳入到工程建设管理中，完善工程项目建设过程管理体系，通过信息化推动管理的规范化，在信息化的应用过程中不断探索市场环境下工程建设管理的新思路和新方法。
根据工程部业务工作的实际情况，项目首先满足工程建设管理中应用最广泛、问题最突出的基本需求。
项目功能需求包括：
?建立工程外部协作系统与MSS等系统的接口；
?建立设计协作服务、监理协作服务、施工协作服务模块，为邮电设计院、电话监理公司和电信工程公司提供工程部所需的协作服务，保证工程建设实施流程的开展；
?在建立工程协作服务模块的基础上，建立工程外部协作系统与邮电设计院、电话监理公司、电信工程公司信息系统的接口，实现工程部与三家实施单位的信息交互与业务协作；
本技术解决方案就是针对实现工程建设部与三家实施单位信息交互与业务协作接口中施工单位接口的技术解决方案的组成部分。
在接口的调用过程中，存在施工系统调用外协系统接口的情况，这时候，施工系统作为客户端，外协系统作为服务端；也存在外协系统调用施工系统的情况，这时候，外协系统作为客户端，施工系统作为服务端。本方案中，除了特殊另外说明外，不考虑外协系统和施工系统角色换位的问题。如果一方发起了调用，那么它就是客户端，另一方就是服务端。反之亦然。
4 接口方式
◆工程外协系统与施工系统之间的接口采用Web Service接口形式来进行业务数据的交
互。
◆接口数据传输采用XML数据交换格式，utf-8编码。
◆在外协系统中提供Web Service的API接口。提供由施工系统调用获得信息；并且提供
施工系统提交信息的API接口。
◆同样，在施工系统中提供Web Service的API接口。提供由外协系统提交信息的API接
口。
◆考虑到工程外协中的数据信息不仅包括了XX电信工程公司的数据而且还包含了其他的
施工单位的数据信息。而这些单位也各有其各自工程应用系统。这样，外协系统对各个施
工单位系统所提供的接口API及其参数信息、格式均是统一的。同时，也要求各个施工单
位所提供的接口API及其参数、格式等也必须要求统一。外协系统与施工系统属于一对多
的关系。
◆外协系统要求能够有目的，信息有过滤的把业务信息通过接口正确的发送给相应施工系
统接口。非相关的信息不要发送给对应的施工系统。
◆施工系统建立用户映像对照表、字典对照表、单位对照表等数据映像，传递给外协的数
据使用的是映像中转换后的外协系统能够识别数据；同时，接收到的数据也根据对照表转
换成各自能够解释的数据格式。
◆数据初始化的时候，由施工系统主动调用外协系统的接口，以获得用户信息、字典信息、
单位信息、项目信息等基础信息。以后，一旦发生数据的变动，由外协系统主动往施工系
统发送信息。
◆外协系统不主动请求施工系统获得数据，但是外协系统会主动请求施工系统发送数据。
◆施工系统主动请求外协系统获得数据，也会主动请求外协系统发送数据。
4接口安全
4.1接口认证
调用认证：
虽然接口双方都是存在于电信内部网络中，但是，仍不能排除接口服务被攻击、恶意调用以及非法调用等。所以，从接口调用上，必须考虑调用的认证安全问题。
◆本方案中的接口，在客户端调用服务端的时候，必须经过调用身份认证。考虑施工系统
的开发平台的多样性，但同时接口服务运行平台都是Windows的情况，本方案采用Windows
安全身份认证的方式。即在访问接口所在的服务的时候，都必须进行资格审查（使用
Credentials发送认证信息）。
◆另外，接口采用SOAP协议，因此在接口配置上面需要屏蔽HTTP GET 和HTTP POST等其
他协议。
◆在接口中审核并进行日志的记录。
◆使用最低权限的进程帐户运行 Web 服务（通过 Machine.config 中的
元素来配置）。
◆接口不支持动态生成WSDL,因此作为服务端，应该禁止文档协议。
◆在服务端禁用跟踪，禁用调式编译
业务用户认证：
由于接口涉及电信工程中的各个不同的业务，有获取字典、获得项目信息、发送开工报告等，所以，建立一套业务的用户认证机制是必须的。不同的用户，所具备有的授权不一样，所能执行的业务也不一样。同时，业务用户认证中的用户信息也是记录接口日志中的重要组成部分。
本方案采用的是在接口信息中包含业务认证用户信息的方式来进行认证。服务端在收到请求的时候，应先验证业务的授权用户，如果该业务用户没有执行当前业务的权限，应终止业务的执行，并给出非法用户的警告信息反馈回客户端。
一般情况下，业务认证的用户是系统中的用户。业务认证其实就是应用系统认证的组成部分。
业务认证的用户信息经过加密之后包含在要发送的信息（XML体）中，即在发送的信息中包含业务用户的信息（参见下面的数据格式说明）。
4.2数据安全
数据的安全表现为如何保证数据在网络传输过程中不会被截获并被解析其中的内容而引起信息泄露与如何保证数据在传输的过程中的数据的完整性两个方面。
Web Service采用XML数据格式来传输信息。所以，无论是发送数据还是返回结果，都要求采用对XML数据加密之后来传输。至于采用何种方式的加密技术，本方案为了保密，只能在开发的时候由开发人员口头告知。涉及到加密技术就要涉及到加密的密钥问题。目前，外协系统和施工系统接口上有很多种类型的业务，到底是每种类型的业务采用不同的密钥，还是按分组来采用同一种密钥的方式，还是所有的业务全部采用同一种的密钥的方式，按照需求各有不同的选择。本方案采用的是最后一种的方式。密钥的发布由作为服务方来发布，由客户端获取。密钥的发布方式待定。
为了保证数据的完整性，首先：方案采用数据签名（SOAP Security Extensions: Digital Signature）。利用XML的数字签名（XML Digital Signature syntax [XML-Signature]）对SOAP进行扩展，在SOAP的头元素中定义签名属性（
5事务处理
事务是一组相关的任务，作为独立于其他任务的独立单元成功（提交）或失败（中止）。分布式事务是影响多个资源的事务。要提交分布式事务，所有参与者都必须保证对数据的任何更改是永久的。不论系统崩溃或是发生其他无法预料的事件，更改都必须是持久的。即使只有一个参与者无法保证这一点，整个事务也将失败，在事务范围内对数据的任何更改均将
回滚。
外协系统和施工系统是处于网络之上的两个分布式接口，使用的是分布式事务。要启用分布式事务，可能需要通过网络启用 MS DTC（考虑外协平台和施工平台都是运行在Windows 上），以便在使用应用了最新的 Service Pack 的较新操作系统（例如 Windows XP 或Windows 2003）时使用分布式事务。如果启用了 Windows 防火墙（Windows XP Service Pack 2 的默认设置），必须允许 MS DTC 服务使用网络或打开 MS DTC 端口。
接口中的服务端和客户端的环境事务始终相同，客户端创建的事务上下文并应用对于服务端的当前的事务，以便对于该事务上下文是当前的。这样的事务会造成性能损失，因为可能需要继承原来的上下文，但是，这样的事务确保了在数据库操作的时候信息的完整性。接口中事务的发起总是由客户端发起的，并负责事务的提交和回滚等控制。
6性能考虑
在接口设计的时候就应该考虑性能上面的问题，不要在事后再加入性能。同时，在项目的开发过程要反复进行测试，可以从机器的吞吐量和响应时间两个基本的指标来衡量接口的性能。接口上面的性能考虑主要从下面几个方面来优化：
◆使用一次连接，多次调用，优化连接资源。
◆对于并行的接口调用使用异步的调用方式。
◆优化线程池减少竞争。
◆考虑使用XML压缩。
◆如果不需要返回，考虑使用单工通讯的方式。
◆适当的设置（如果有代理）代理超时，页面超时，WebService超时。
◆设计"大块头"的接口减少往返。
◆基于消息的编程而不是远程过程调用(RPC) 。
◆使用XML字串作为参数。
◆尽量使用原始数据类型参数。
◆避免在调用之间维护服务器状态。
◆考虑为复杂的WebMethod提供输入校验。
◆考虑对WebMethod的结果使用缓存。
◆选择适用的大数据包传送方式。
◆避免调用本地的WebService。
7容错处理
客户端向服务端发送数据，服务端解析数据，反馈信息给客户端，这中间的环节只要某一个环节出现问题，都会造成接口的失败。按照失败产生的环节分类，我们可以从三个方面来处理接口的失败。
◆网络连接失败：在调用接口的时候，由于网络不通，造成数据不能正常传输。
这样，客户端应该能够记录发送的日志，按照一定的时间间隔重试发送。本方案定
为重试发送20次，每次时间间隔2小时。如果一直发生网络不通的情况，该发送日
志被保存下来，待后手工发送。所以，客户端系统应该实现手工发送数据的功能。
◆反馈错误信息：服务端在解析数据包，执行数据包业务的时候，可能会发生异
常。所以，服务端应当能够捕捉异常信息，比如“非法XML格式”等，然后反馈给
客户端。客户端在接受到这类的错误信息之后，应当进行日志记录，能够自动或手
工分析异常的信息。
◆网络连接正常，但是无信息反馈：这种情况下，一般是服务端出现了异常，但
是又没有捕捉到的情况下发生。这种情况下，客户端把这种错误当作“网络连接失
败”来处理。服务端应能够实现相同数据包重新发送过来的处理机制。
8数据格式
在Web Service的调用过程中，无论是外协系统还是施工系统，都有发送数据和接收数据的要求，也即双方系统同时作为客户端又作为服务端。我们统称这些传递的数据为报文。
客户端发送报文，属于调用；服务端接收报文，属于被调用。
客户端和服务端互相之间通讯的请求报文和结果报文遵循XML格式。客户端发送请求报文，服务器解析调用报文，执行报文中所在接口对应的服务功能。生成结果报文，以xml格式页返回给请求者。请求者拿到结果报文，进行解析，然后再进行相应的处理。
8.1约定
◆报文中所有的字典信息（比如性别1-男，2-女），都以代码的值（1或者2）来传递。施
工单位向外协系统发送的报文中的代码都需要转换成外协的代码，外协系统向施工系统发
送的报文中的代码无需转换。
◆报文中的其他数据类型，比如货币、RowID,自定义对象类型等，根据需要转换成文本、
数值或二进制（最终转换成Base64字符）的数据类型。
◆报文中数值信息，转换成文本，如：
◆报文中数值不支持科学计数的方式。报文中数值的单位使用国标的单位，比如货币使用
“元”，长度使用“米”等。无国标的单位以约定为准。
◆报文中的日期信息，转换成YYYYMMDD HHmmss文本格式（24小时制）。如果是空日期，
则转换成空文本。
◆报文中的true和false数据类型，转换成 0(表示false)、1（表示true）
◆报文中的二进制数据，转换成Base64字符方式发送。
◆报文中的记录集，放在< Records>标签中；报文中一条记录，放在< Records>标签中。
◆报文中如果存在多条记录，则在
文中仅有一条记录，则
包含一个
◆如果返回结果数据集非常多，在性能考虑和数据量冲突的情况下，可以使用分页返回数
据集的方式分批返回数据（每次返回最多100条记录）。服务端提供分批结果返回的功能。
至于如何使用分页查询的功能，参见下面的XML框架说明。
8.2施工系统向外协系统发送请求
施工系统向外协系统发送请求的数据目前有几点需要考虑：
◆如何请求查询一个业务数据
◆如何新增一条记录，新增之后如何点到记录的键值
◆如何修改一条记录
◆如何删除一条记录
◆文档如何上传
◆一条记录中一个FileID的字段如何上传多个文件
◆如何在一条记录中补充上传文档
◆如何在一条记录中删除一个文档
◆如何获得文档的基本信息
◆如何获得文档的所有兄弟信息
◆如何获得文档的所有父亲信息
◆如何下载一个文档
针对这些问题，接口方案的解决方法如下：
8.2.1请求查询一个业务数据
施工系统针对外协系统发送的业务数据查询请求根据业务类型有很多种。为了简化接口，而不是在接口上进行业务操作，所以，外协系统将施工系统发起的数据查询请求看作是数据下载的一种方式，而不为了复杂的业务查询请求提供复杂的条件解析。
外协系统提供的数据查询接口是从数据下载和数据延期性来考虑的。为了满足数据的下载，外协系统提供了按照某一个表的主键来下载数据和按照记录的变更时间范围来下载数据的两种方式查询
请求。
请求报文：
响应报文：
报文说明：
标签名说明
服务端根据条件查询，发现结果超过100条记录，则在返回的结果中，RowID
的值为99，表示服务端当前的记录位置处在第100条的位置上，后面还会
有剩余的记录。客户端检查返回的结果，如果发现RowID大于0,则继续发
送请求进行查询。但是，客户端第二次发送请求继续查询的时候，RowID
的值要赋值为第一次返回的值，即RowID=99。服务端第二次收到请求的时
候，发现RowID是99,则从第100条返回结果。以此类推循环调用，直到服
务端达到记录的末尾，这时候，服务端在返回的结果中RowID=0.客户端发
现服务端RowID=0，终止循环调用。
字典、用户信息、单位信息，因为返回的字段比较少，不受100条记
录返回的限制。一次调用，就返回全部的结果。
键的值，表示客户端要求服务器按照主键的值查询一条记录。如果客户端
提供了主键的值，则服务端将忽略
值。
字典、用户信息、单位信息，因为没有查询时间范围，所以
即表示字典类型。
查询时时间段范围。
在外协中，一条记录新增的时候，它的创建时间和最后修改时间是一样的，以后修改记录的时候，创建时间不变，改变的仅仅是最后修改时间。同时，外协系统中删除记录仅仅在“记录是否删除”字段中标记“1”，并不是真正的物理删除记录。
这里的时间指的是记录变更的时间，不是记录中的某个业务时间。如果用户需要按照业务时间来查询数据，则施工系统把外协系统的数据获取到本地进行保存，在施工系统中提供按照业务时间查询的功能。
具体的字段名称请参见提供的数据模型
8.2.1新增一条记录，得到记录的键值
为了简化数据模型的处理，本方案不考虑主从表的并发处理情况。如果存在主从表的数据需要上传，那么，在一个事务中，施工单位首先先上传主表的记录，从反馈信息中获得主表的主键值。然后，把刚刚获得的主表的主键值赋值给从表的对应外键，再上传从表数据，得到从表的主键值。
如果不是主从表，而是单表，则直接上传数据，从反馈信息中得到主键值。
这种情况的优点是：数据和表相关，施工单位可以灵活的控制表之间的关系；同时，数据包中的报文比较简单，容易解析；接口上面比较清晰，与业务的耦合比较低。
缺点是：一个业务涉及的主从表不能在同一个报文中（这个缺点可以通过施工系统灵活的控制表之间关系来解决）；一个业务中可能会使用到两个或两个以上的接口，造成业务完整性上面的分离（这种缺点可以通过把业务放在一个事务中来解决）；
键值的返回：在调用新增接口之后，外协会按照记录的顺序返回外外协中所生成的键值。施工单位获得键值之后，可以在本地表中更新记录的主键值。
请求报文：
响应报文：
报文说明：
标签名说明
请求中的
空。外协系统中根据主键字段内容为空，认为这是一条新增的记录
响应中的
统发送的记录的顺序是一一对应的。
如果保存成功，则信息是“成功”
如果保存失败，则信息是“失败：（后面是错误的详细信息）”
8.2.3修改一条记录
施工系统在修改了一条记录的时候，上传的报文中与新增的报文类似，只是主键的信息不能为空。外协系统判断主键的信息，如果发现主键的信息不为空，则认为是修改了一条记录。如果施工系统报文中主键不为空，而外协系统在数据库对应的表中又没有发现对应的记录，则自动转换成新增的方式来处理这条记录。
外协系统在反馈中，还是会把主键返回给施工系统。但是，这种情况下，施工系统可能不再需要维护这个主键。
即使是仅仅修改了一个字段，施工单位还得需要上传全部的字段信息（包含被修改的字段）给外协系统。
施工系统不是对记录做物理删除，而仅仅是作了逻辑删除，即仅仅在记录的删除标志位上面做了“1”的标志。这种情况对记录来说，也是修改的范围。只是需要在
请求报文：
响应报文：
报文说明：
标签名说明
请求中的
能为空。外协系统中根据主键字段内容不为空，认为这是一条修改的记录响应中的
统发送的记录的顺序是一一对应的。
如果保存成功，则信息是“成功”
如果保存失败，则信息是“失败：（后面是错误的详细信息）”
的标签全部是大写。
具体的字段名称请参见提供的数据模型
8.2.4删除一条记录
这里的删除指的是物理删除。逻辑删除在记录修改的时候已经说明。
物理删除是彻底的从数据库中删除一条记录，不能恢复。物理删除的时候，施工系统只要在报文中提供主键的信息提交，就能够实现。
同样的，外协系统在反馈的报文中返回成功删除主键的信息，如果其中一条记录不能正常物理删除，则外协自动回滚所有删除的操作。即一条记录不能删除，则所有的记录都不能删除。
请求报文：
响应报文：
报文说明：（参见数据修改说明）
8.2.5文档上传
外协系统中，文档的信息是保存在另外的一个表中当中的，所以，许多的业务表，往往存在一个FileID的主键关联到文档表。在业务表中档，可能有一个FileID的字段，也可能会有两个或两个以上的FileID字段关联到文档信息表。
涉及到文档的地方，往往文档的信息会比较大，所以，文档的信息不能包含在基础业务数据的报文当中一起上传。处理的方法是：
先上传文档的实体，从反馈的信息当中得到生成的文档ID（FileID），然后，施工系统在本地记
录中的相应字段赋值文档的ID，最后再上传基本业务信息。
如果一条记录中包含有两个或两个以上的文档字段，则施工系统必须依次上传文档获得文档ID 之后，赋值，再上传基本业务信息。
一个文档报文当中，只能上传一个文档。
文档报文如下：
响应报文：
报文说明：
标签名说明
统根据这个文件ID是否为空来判断是否是新的文件。
个项目的。这个项目ID可以是一级项目，也可以是三级项目。
D401施工组织设计= 401
D402施工项目计划进度= 402
D403施工日报= 403
则在同样的项目ID、同样的文件类型中，同时可以存在多个的文档同时有
效存在。这种情况下，多个文档之间是兄弟之间的关系，当前的文档是弟
弟，以前的文档是兄长。当这个值为0的时候，则在同样的项目ID、同样
的文件类型中，只有最后上传的文档有效，后面上传的文档会把前面的文
档“挤”到历史中，成为当前文档的“父亲”。这种情况下，当前的文档
和以前上传的文档之间是父子的关系。更详细的解释请参见后面的“一条
记录中一个FileID的字段如何上传多个文件”主题相关内容。
的格式。
如果保存成功，则信息是“成功”
如果保存失败，则信息是“失败：（后面是错误的详细信息）”
8.2.6一条记录中一个文档字段上传多个文件
外协系统中，文档是以一种“有关系”的方式来存储的。假设有这样一个业务表Table1，里面有一个文档的外键字段File_ID。当我们往Table1表里面插入一条记录的时候，针对这一条记录，我们希望在File_ID字段中可以带有多个的文档，也即会有多个的File_ID。当然，我们可以把这个表字段的数据模型这个定义：File1_ID，File2_ID,File3_ID……，需要多少个文件，我们就定义几个的File_ID字段。但是这样就会带来问题了，如果你定义了5个的File_ID字段，但是，用户如果想在一条记录中上传6个文档，那么，这样的数据模型就会满足不了用户的要求。还有一种情况，如果用户仅仅上传了2个文档，那么剩下的3个File_ID字段就会白白空着。甚至用户对这条记录没有上传文件，这样定义的数据模型就白白浪费了数据库的资源。
还有一种说法，我可以用记录的形式来表示啊。对的。上传多个文件，是可以在Table1中新增多条记录方式来表示。但是，我们的前提是，Table1是一个业务表，里面的一条记录就是一笔业务。如果你产生了多条记录，那么意味这这样的业务进行了多次。显然违背了业务数据保存的初衷。
外协系统引入了“父子”，“兄弟”的文档保存机制, 即在文档信息表(Files表)中保存文档的基本信息和他们之间的关系。在同样的项目ID、同样的文件类型中，如果可以存在多个的文档同时有效存在，这种情况下，多个文档之间是兄弟之间的关系。后来者文档是弟弟，先到的文档是兄长。在同样的项目ID、同样的文件类型中，只有最后上传的文档有效，后面上传的文档会把前面的文档“挤”到历史中，成为当前文档的“父亲”。这种情况下，后来的文档和以前上传的文档之间是父子的关系。
如果文档之间是兄弟关系的话，则仅仅在业务表Table1中保存最小兄弟的File_ID；如果文档之间是父子关系的话，则仅仅保存最小辈分的文档File_ID。
兄弟和父子的文档保存方式其实都是多个文档串联的一种保存方式，但是，还是会有使用上面的区别的。兄弟关系一般使用在文档之间是平级的情况下。比如施工组织方案，可以有多个文件，但是，这多个文件是互为补充的一部分，互相依赖，又缺一不可。这种情况下，施工系统可以把这类型的文件上传给外协系统，以兄弟的方式保存，施工系统仅仅在业务表当中保存最后上传反馈回来的FileID 即可。以后，可以使用这个最小兄弟的File_ID，向外协系统请求以获得他的所有兄长文档。父子的关系一般使用在下面的情景：当仅允许一个文档是最终有效的时候，或者一个文档修改之后再上传到外协系统，我们想把最后上传的文档“覆盖”前面的文档，但是，又想保留文档历史修改痕迹的时候，一般就会用到父子关系。
父子关系中，施工系统仅仅需要保留最小辈分的文档信息，以后，可以使用这个最小辈分的File_ID，向外协系统请求以获得他的所有历史文档。
8.2.7补充上传文档
根据前面的兄弟和父子关系的说明，一条记录中补充上传文档的方式就简单了许多。只要施工系统上传了文档，获得最后的文档ID，然后，在施工系统中维护最后的文档ID，再用修改记录的报文上报更新后的业务数据即可。流程：
上传补充的文档→获得最后的文档ID →用最后的文档ID更新业务数据→上传修改后的业务数据。
8.2.8在记录中删除一个文档
向外协系统请求删除一个文档，只需要向外协系统提交包含有要删除的文档ID即可。
如果需要删除的是文档链当中的某一个文档，则需要向外协请求获得文档链的信息（参见后面的“如何获取文档信息”），然后，从链中找到要删除的文档ID，向外协系统提交。外协系统在删除文
档的同时，会自动把链连接起来成为一个完整的链关系，同时，总是返回链的最末尾的文档ID。施工系统获得链末尾的最后文档ID之后，更新业务表中的相应记录，再用修改的报文上报修改后的业务数据（此步骤不要忘记）。
请求删除文档的报文：
响应报文：
报文说明：
标签名说明
XXXX系统 Web Services业务接口规范说明书 拟制 审核 会签 批准 【公司名称】
版本历史
目录 1.范围 (1) 2.术语、定义和缩略语 (1) 2.1 术语、定义 (1) 2.2 缩略语 (1) 3.接口设计 (1) 3.1 接口公共参数 (1) 3.1.1请求参数 (1) 3.1.2返回参数 (2) 3.2 业务功能接口 (3) 3.2.1业务模块1 (3) 4.MD5加密 (6) 5.参考文献 (6)
1.范围 本规范文档主要适用于XXXX系统和其它业务系统信息数据的接入。 2.术语、定义和缩略语 2.1术语、定义 2.2缩略语 3.接口设计 3.1接口公共参数 接口服务器通过：http://IP:port/EIP/WebService/ 连接服务器，同时对外提供业务功能接口，接收的参数和返回的参数都用一定的xml格式进行封装。 3.1.1请求参数 1.请求类型为String类型
3.请求参数体param定义 参数体param中的具体请求参数，根据不同的业务而不同，详见各业务接口。 3.1.2返回参数 1.返回类型为String类型
XXX接口说明书(版本：V1.0)
修订记录
1简介 1.1文档目的 接口文档是前端与后端交互密不可分的环节，接口的规范性会直接影响双方对接过程中的效率和质量。本着快速高效开发的目的性，避免对接过程中的错误率。 1.2接口规范 (1) 遵循RESTful API设计风格 (2) 数据格式采用json格式 (3) 返回统一结构数据 例如： 结构：data（数据）、errorCode（状态码）、msg（提示信息） { data:{}, // 数据类型不一定为object类型 errorCode:10001, msg:'' } (4) 枚举型参数应列举参数所有值及说明 例如： gender：性别（男：1，女：2） userInfo:{ name:'张三', age:23, gender:1 }
(5) 具有嵌套关系的参数应指明嵌套关系及子级数据结构例如： billList: 账单列表(父级) billList:[ { id:'001', billName:'测试数据', billStauts:1, address:'雁塔区' } ] (6) 返回参数数据类型保持一致性 例如： billList: 账单列表（有数据） billList:[ { id:'001', billName:'测试数据', billStauts:1, address:'雁塔区' } ] billList: 账单列表（无数据） billList:[] 返回的参数数据类型都为：array (7) 下拉及选择型数据以键值对的形式返回 例如： orderOperate：订单操作 orderOperate:[
{产品名称} 软件需求规格说明书 编写人： 编写日期：年月日
目录 1.产品描述 (3) 1.1.编写目的 (3) 1.2.产品名称 (3) 1.3.名词定义（可选） (3) 2.产品需求概述 (3) 2.1.功能简介 (3) 2.2.运行环境 (3) 2.3.条件与限制（可选） (3) 3.功能需求 (3) 3.1.功能划分（可选） (3) 3.2.功能1 (4) 3.3.功能N (4) 3.4.不支持的功能 (4) 4.数据描述 (4) 5.性能需求（可选） (4) 6.运行需求（可选） (4) 6.1.用户界面 (4) 6.2.硬件接口 (4) 6.3.软件接口 (5) 6.4.通信接口 (5) 7.其它需求（可选） (5) 8.特殊需求（可选） (5) 9.不确定的问题（可选） (5) 10.编写人员及编写日期 (5) 11.附录 (5) 11.1.引用文件 (5) 11.2.参考资料 (5)
1.产品描述 1.1.编写目的 【说明编写本软件需求规格说明书的目的，指出预期的读者。】 1.2.产品名称 【本项目的名称，包括项目的全名、简称、代号、版本号。】 1.3.名词定义（可选） 【对重要的或是具有特殊意义的名词（包括词头和缩写）进行定义，以便读者可以正确地解释软件需求说明。】 2.产品需求概述 2.1.功能简介 【对产品的基本功能做一个简介，包括： 1.本产品的开发意图、应用目标及作用范围。 2．概略介绍了产品所具有的主要功能。可以用列表的方法给出，也可以用图形表示主要的需求分组以及它们之间的联系，例如数据流程图的顶层图或类图等。 3．说明本产品与其他相关产品的关系，是独立产品还是一个较大产品的组成部分。 可以用表示外部接口和数据流的系统高层次图，或者方框图说明。】 2.2.运行环境 1.硬件环境： 【详细列出本软件运行时所必须的最低硬件配置、推荐硬件配置(如主机、显示器、外部设备等)以及其它特殊设备。】 2.软件环境： 【如操作系统、网络软件、数据库系统以及其它特殊软件要求。】 2.3.条件与限制（可选） 【说明本软件在实现时所必须满足的条件和所受的限制，并给出相应的原因。 必须满足的条件包括输入数据的范围以及格式。 所受的限制包括软件环境、硬件环境等方面的内容。例如：必须使用或者避免的特定技术、工具、编程语言和数据库；企业策略、政府法规或工业标准；硬件限制，例如定时需求或存储器限制；经费限制、开发期限；项目对外部因素存在的依赖。例如其它项目开发的组件。等等】 3.功能需求 【功能需求描述系统特性，即产品所提供的主要服务。可以通过使用实例、运行模式、用户类、对象类或功能等级等不同方法来描述，还可以把它们组合起来使用。 功能需求的表述形式可以参见《需求分析和管理指南》第8.2节。】 3.1.功能划分（可选） 【此部分从用户的角度描述将软件划分成不同的部分，并给出总体功能结构。对于复杂
文档编号：T-JKJS 文档版本：0.01 项目编号：XX-DX- PECS 《XX电信工程外部协作系统》 Project Exterior Cooperation System 施工单位接口技术解决方案 编写人：南疯日期：2006-10-30 审核人：日期： 批准人：日期： XXXXXX信息科技股份有限公司 地址：XXXXXXX 邮编：XXXXXX 电话：XXXXXXXX传真：XXXXXX 网站：XXXXXXXXX 修改记录（Revision Chart） 版本号批准人修改人修改0.01南疯2006-10-30 0.02详细修改记录： 序号
1引言 1.1编写目的 1.2覆盖范围 1.3预期读者与阅读建议 1.4文档约定 1.5术语与缩略语 1.6参考文献 2概述 3接口方式 4接口安全 4.1接口认证 4.2数据安全 5事务处理 6性能考虑 7容错处理 8数据格式 8.1约定 8.2施工系统向外协系统发送请求 8.2.1请求查询一个业务数据 8.2.2新增一条记录，得到记录的键值 8.2.3修改一条记录 8.2.4删除一条记录 8.2.5文档上传 8.2.6一条记录中一个文档字段上传多个文件 8.2.7补充上传文档 8.2.8在记录中删除一个文档 8.2.9获得文档的基本信息 8.2.10获得文档的所有兄弟信息 8.2.11获得文档的所有父亲信息 8.2.12下载一个文档 8.2.13获得字典 8.3外协系统向施工系统发送请求 8.3.1发送变更后的数据 8.3.2发送变更后的字典 8.3.3文档发送请求 9信息数据项 9.1数据表 9.2字段信息 9.3字典类型
XXAPI 接口设计说明书 公司 2016年11月25日 文档管理信息表 主题XX api接口设计说明书 版本V0.1 内容 关键字 参考文档 创建时间 创建人 最新发布日期 文档变更记录表 修改人修改时间修改内容 创建
目录 文档变更记录表 .................................................................................................................................................................................. 目录 .................................................................................................................................................................................................... 引言 ...................................................................................................................................................................................................... 编写目的 背景 定义 参考资料 综述 ...................................................................................................................................................................................................... 统一的输入输出参数 必须登录才能访问的接口 错误返回码列表 用户接口 .............................................................................................................................................................................................. 用户注册（user/signup） 用户登录（user/signin） 优惠券接口 .......................................................................................................................................................................................... 我的优惠券（coupon/mycoupon）
XXX接口说明书 (版本： 文档编号保密等级 作者最后修改日期 审核人最后审批日期 批准人最后批准日期
修订记录 日期版本修订说明修订人
1简介 1.1文档目的 接口文档是前端与后端交互密不可分的环节，接口的规范性会直接影响双方对接过程中的效率和质量。本着快速高效开发的目的性，避免对接过程中的错误率。 1.2接口规范 (1) 遵循RESTful API设计风格 (2) 数据格式采用json格式 (3) 返回统一结构数据 例如： 结构：data（数据）、errorCode（状态码）、msg（提示信息） { data:{}, .] 订单列表 orderList orderId string 否订单id orderName string 否订单名称
isStudent boolean 是false false 是否学生（是：true，否： false） 返回参数： 参数名类型示例值默认值描述 data array […]返回的数据 data id string 用户id gender number 1 1 用户性别（男：1，女：2）invoiceTitle string 抬头 address string 地址 billList array [...] 订单列表数据 billList id string 订单id billName string 订单名称 billStauts number 1 1 订单状态（待开票：1，回款： 2，核销：3） address string 客户地址 userInfo object {} 用户信息 userInfo name name 用户姓名 age number 用户年龄 gender string 1 1 用户性别（男：1，女：2）errorCode number 状态信息 msg string 信息提示 返回示例值: { data:[ { id:'1', gender:2, invoiceTitle:'帝国快运', address:'陕西省西安市雁塔区科技路24号', billList:[ { id:'001', billName:'测试数据', billStauts:1, address:'雁塔区' }, { id:'002', billName:'测试数据02',
POE模块说明 一、POE简介 POE被称为基于局域网的供电系统(POL, Power over LAN )或有源以太网( Active Ethernet)，有时也被简称为以太网供电，这是利用现存标准以太网传输电缆的同时传送数据和电功率的最新标准规范，并保持了与现存以太网系统和用户的兼容性。 POE有两个通用标准： 1.IEEE 80 2.3at：最新POE供电标准，为大功率终端的需求而诞生，最大可以提供30W的输出功率。 2.IEEE 802.3af ：首个POE供电标准，规定了以太网供电标准，是现在POE应用的主流实现标准，最大可以输出13W的功率。 POE标准为使用以太网传输电缆输送直流电到POE兼容的设备定义了两种方法： 1.中间跨接法(Mid -Span)：使用以太网电缆中没有被使用的空闲线对来传输直流电，需要8芯网线来供电，4芯数据线，4芯供电线。 2.末端跨接法(End-Span)：在传输数据所用的芯线上同时传输直流电,其输电采用与以太网数据信号不同的频率。总共只需要4芯线，既传数据，也可以供电。 我司开发的POE模块支持IEEE 802.3at标准也兼容IEEE 802.3af标准，采用标准的38*38大小，同时支持mid-span及end-span两种方法，可以与我们现有的电源板直接对接，有着极好的兼容性，使用方便。
二、接口说明 1.1 POE 模块正面接口 图1 POE 正面图 表1 POE 正面详细接口列表 图中代号 接口详细编号 接口定义 接口定义 实现功能 P1 1 NC 空脚 2 NC 空脚 3 GND 地 4 +12Vin +12V 电源输入 输入 P2 1 +48 48V 正极 输入 2 +48_GND 48V 负极 输入 3 GND 地 4 +12Vin +12V 电源输出 输出
软件需求说明书编写规范
————————————————————————————————作者：————————————————————————————————日期: ?
案卷号 日期 <项目名称＞ 软件需求说明书 作者:王浩天 完成日期: 8.２3 签收人： 签收日期: 修改情况记录: 版本号修改批准人修改人安装日期签收人
目录 １引言 .................................................................................................. 错误!未定义书签。 1.1 编写目的.................................................................................................... 错误!未定义书签。 1.2范围?错误!未定义书签。 1．３定义?错误!未定义书签。 1．４参考资料............................................................................................... 错误!未定义书签。 2 项目概述?错误!未定义书签。 2.１产品描述?错误!未定义书签。 2．2 产品功能................................................................................................. 错误!未定义书签。2．3 用户特点................................................................................................. 错误!未定义书签。 2.4 一般约束.................................................................................................... 错误!未定义书签。 ２.５假设和依据............................................................................................ 错误!未定义书签。 ３具体需求?错误!未定义书签。 3.1 功能需求.................................................................................................... 错误!未定义书签。 3.1.1 功能需求１?错误!未定义书签。 3.1.2 功能需求２......................................................................................... 错误!未定义书签。 3.１.ｎ功能需求n...................................................................................... 错误!未定义书签。 ３．2 外部接口需求....................................................................................... 错误!未定义书签。 3.2.1 用户接口?错误!未定义书签。 3.２.2 硬件接口?错误!未定义书签。 3．２．３软件接口................................................................................. 错误!未定义书签。 3.2．4 通信接口?错误!未定义书签。 ３．3 性能需求?错误!未定义书签。 3.4 设计约束.................................................................................................... 错误!未定义书签。 ３.4．１其他标准的约束.......................................................................... 错误!未定义书签。 ３.4.2 硬件的限制?错误!未定义书签。 3.5 属性?错误!未定义书签。 3.5.１可用性?错误!未定义书签。 3.5.2 安全性?错误!未定义书签。 3．5．3 可维护性....................................................................................... 错误!未定义书签。 3．5．4 可转移\转换性............................................................................ 错误!未定义书签。 3.5.5 警告?错误!未定义书签。 3.6 其他需求.................................................................................................... 错误!未定义书签。 3．6．1 数据库........................................................................................... 错误!未定义书签。 3.6．２操作 (7) ３．６.３场合适应性需求?错误!未定义书签。 ４附录 .................................................................................................. 错误!未定义书签。
需求规格说明书 软件需求规格说明书是软件开发过程需求分析阶段需要产出的文档，是为了使用户和软件开发者对软件的规格有一个共同的理解而撰写的，软件需求规格说明有标准的模板 方法/步骤 第一章是引言。 描述软件需求规格说明书的纵览，帮助读者理解文档如何编写并且如何阅读和理解，包含五
个部分： 1.1 编写目的 //对产品(项目)进行定义，在该文档中详尽说明这个产品的软件需求，包 //括修正或发行版本号。如果这个软件需求规格说明书只与整个系统的一 //部分有关，那么只定义文档中说明的部分或子系统。 1.2 文档约定 //描述编写文档时所采用的标准或排版约定，包括正文风格，提示区或重 //要符号。例如，说明高层需求的优先级是否可以被所有细化分需求所继 //承，或者每个需求陈述是否都有优先级。 1.3 读者对象和阅读建议 //列举软件需求规格说明书所针对的不同读者，例如开发人员、项目经理、//营销人员、用户、测试人员等。描述文档中剩余部分的内容及其组织结//构。提出最适合每一类读者阅读文档的建议。 1.4 项目范围 //提供对指定的软件及其目的的简短描述，包括利益和目标。把软件与企业 //目标或业务策略相联系。可以参考项目范围文档，而不是将其内容复制到 //这里 1.5 参考资料 //列举编写软件需求规格说明书时所参考的资料或其它来源。可能包括用户 //界面风格指导、合同、标准、系统需求规格说明书，用户需求、相关产品 //的软件需求规格说明书。这里应给出详细的信息，包括标题名称、作者、 //版本号、日期、出版单位或资料来源，以方便读者查阅这些文献。
第二章是总体描述。包含六个部分： 2.1 产品前景 //描述软件需求规格说明书中所定义的产品的背景和起源。说明该产品是否 //是产品系列中的下一个成员，是否是成熟产品所改进的下一代产品，是否 //是现有应用程序的替代品，或者什邡市一个全新的产品。 //如果软件需求规格说明书定义了大系统的一个组成部分，那么就要说明这 //部分软件是怎样与整个系统相关联的，并且要定义出两者之间的接口。建 //议使用系统结构图或者实体关系图表示 2.2 产品的功能 //概述产品所具有的主要功能，详细内容在第4节描述，所以这里只需要概括 //总结，例如用列表的方法给出。很好地组织产品的功能，使每个读者都易 //于理解。用图形表示主要的需求分组以及它们之间的联系。 //建议使用数据流程图（DFD）的顶层图或者类图来实现图形化
<项目名称> 需求规格说明书 腾讯科技（深圳）有限公司版权所有侵权必究
修订记录
目录 修订记录 (2) 目录 (3) 1前言 (4) 1.1文档目的和范围 (4) 1.2参考文献 (4) 1.3术语表 (4) 2总体描述 (4) 2.1业务执行角色 (4) 2.2运行环境 (5) 2.3设计和实现上的约束 (5) 2.4整体流程/逻辑关系 (5) 3特性 (5) 3.1特性F MMM F EA TURE (5) 3.1.1特性描述 (5) 3.1.2功能性需求(Functional Requirements，FR) (6) 3.1.2.1Fmmm.FR.nnn 功能需求1 (6) 3.1.3性能需求（Performance Requirements，PR） (6) 3.1.3.1Fmmm.PR.nnn 性能需求1 (6) 3.1.4用户界面（User Interface，UI） (6) 3.1.5接口需求（Interface Requirements，IR） (6) 3.1.6安全性需求（Security Requirements ,SR） (7) 3.1.7国际化需求(Internationalization Requirements,I18NR ) (7) 3.1.8数据统计需求(Date Statistic Requirements，DSR) (7) 3.1.9其他需求 (7) 3.1.10该特性受限时的用户体验 (7) 3.2特性F MMM F EA TURE (7) 4附录 (8)
说明：本文中蓝色斜体字体为说明性文字，写文档时请删除。 1前言 1.1文档目的和范围 1)文档目的:本文档针对 **系统/模块的目标、范围的描述，以此作为系统选型、设计、 开发和实施的依据。 2)范围：软件产品名称标识 ****。说明产品将干什么，若需要还将说明产品不干什么。 1.2参考文献 说明：列出本文档的所有参考文献（可以是非正式出版物）； 格式如：[标识符] 作者，文献名称，出版单位（或归属单位），日期；参考网址则列出URL。 1.3术语表 说明：列出本文档中所用到的专门术语的定义和缩略语的全称和解释。 2总体描述 2.1业务执行角色 说明：阐述本产品的各种角色及其相应的活动或权限。各种角色的具体行为将在功能性需求中描述。如QQ会员、蓝钻、黄钻用户等
1 引言 1．1编写目的 说明编写这份详细设计说明书的目的，指出预期的读者。 1．2背景 说明：a．待开发软件系统的名称 ；b．本项目的任务提出者、开发者、用户和运行该程序系统的计算中心。 1．3定义 列出本文件中用到专门术语的定义和 外文首字母组词的原词组。 1．4参考资料 列出有关的参考资料，如：a．本项目的经核准的计划任务书或合同、上级机关的 批文；b．属于本项目的其他已发表的文件；c．本文件中各处引用到的文件资料，包括所要用到的软件开发标准。列出这些 文件的标题、文件编号、发表日期和出版单位，说明能够取得这些文件的来源。 2 程序系统的结构 用一系列图表列出本程序系 统内的每个程序（包括每个模块和子程序）的名称、标识符和它们之间的层次结构关系。
3 程序 1（标识符）设计说明从本章 开始，逐个地给出各个层次中的每个程序的设计考虑。以下给出的提纲是针对一般情况的。对于一个具体的模块，尤其是层次比 较低的模块或子程序，其很多条目的内容往往与它所隶属的上一层模块的对应条目的内容相同，在这种情况下，只要简单地说明 这一点即可。 3．1程序描述 给出对该程序的简要描述，主要说明安排设计本程序的目的意义，并且，还要说明本程序的特点 （如是常驻内存还是非常驻？是否子程序？是可重人的还是不可重人的？有无覆盖要求？是顺序处理还是并发处理卜…．．等 ）。 3．2功能 说明该程序应具有的功能，可采用IPO图（即输入一处理一输出图）的形式。 3．3性能 说明对该程序的全部性 能要求，包括对精度、灵活性和时间特性的要求。 3．4输人项 给出对每一个输入项的特性，包括名称、标识、数据的类型和格 式、数据值的有效范围、输入的方式。数量和频度、输入媒体、输入数据的来源和安全保密条件等等。 3．5输出项 给出对每
1 具体需求 1.1 功能需求 1.1.1 功能需求1 对于每一类功能或者有时对于每一个功能，需要具体描述其输入、加工和输出的需求。由四个部分组成： a．引言 描述的是功能要达到的目标、所彩的方法和技术，还应清楚说明功能意图的由来 和背景。 b．输入 1)详细描述该功能的所有输入数据，如：输入源、数量、度量单位、时间设定、 有效输入范围（包括精度和公差）； 2)操作员控制细节的需求。其中有名字、操作员活动的描述、控制台或操作员的 位置。例如：当打印检查时，要求操作员进行格式调整； 3)指明引用接口说明或接口控制文件的参考资料。 c．加工 定义输入数据、中间参数，以获得预期输出结果的全部操作。它包括如下的说明： 1)输入数据的有效性检查； 2)操作的顺序，包括事件的时间设定； 3)响应，例如，溢出、通信故障、错误处理等； 4)受操作影响的参数； 5)降级运行的要求； 6)用于把系统输入变换成相应输出的任何方法（方程式、数学算法、逻辑操作等）； 7)输出数据的有效性检查。 d．输出 1)详细描述该功能所有输出数据，例如：输出目的地、数量、度量单位、时间关
系、有效输出的范围（包括精度和公差）、非法值的处理、出错信息； 2)有关接口说明或接口控制文件的参考资料。 此外，对着重于输入输出行为的系统来说，需求说明应指定所有有意义的输入、 输出对及其序列。当一个系统要求记忆它的状态时，需要这个序列，使得它可以 根据本次输入和以前的状态作出响应。也就是说，这种情况犹如有限状态机。1.1.2 功能需求2 ．．．．．． 1.1.n 功能需求n 1.2 外部接口需求 1.2.1 用户接口 提供用户使用软件产品时的接口需求。例如，如果系统的用户通过显示终端进行操作，就必须指定如下要求： a．对屏幕格式的要求； b．报表或菜单的页面打印格式和内容； c．输入输出的相对时间； d．程序功能键的可用性。 1.2.2 硬件接口 要指出软件产品和系统硬部件之间每一个接口的逻辑特点。还可能包括如下事宜：支撑什么样的设备，如何支撑这些设备，有何约定。
XXX接口说明书(版本：V1.0) 修订记录
1简介 1.1文档目的 接口文档是前端与后端交互密不可分的环节，接口的规范性会直接影响双方对接过程中的效率和质量。本着快速高效开发的目的性，避免对接过程中的错误率。 1.2接口规范 (1) 遵循RESTful API设计风格 (2) 数据格式采用json格式 (3) 返回统一结构数据 例如： 结构：data（数据）、errorCode（状态码）、msg（提示信息） { data:{}, // 数据类型不一定为object类型 errorCode:10001, msg:'' } (4) 枚举型参数应列举参数所有值及说明 例如： gender：性别（男：1，女：2） userInfo:{ name:'张三', age:23, gender:1 } (5) 具有嵌套关系的参数应指明嵌套关系及子级数据结构 例如： billList: 账单列表(父级) billList:[ {
id:'001', billName:'测试数据', billStauts:1, address:'雁塔区' } ] (6) 返回参数数据类型保持一致性 例如： billList: 账单列表（有数据） billList:[ { id:'001', billName:'测试数据', billStauts:1, address:'雁塔区' } ] billList: 账单列表（无数据） billList:[] 返回的参数数据类型都为：array (7) 下拉及选择型数据以键值对的形式返回例如： orderOperate：订单操作 orderOperate:[ { label:'待开票' value:1001 }, { label:'回款' value:1003 } ] (8) “操作类型”的接口必须返回msg信息内容 (9) 返回的展示型数据应具有可用性 例如： createTime：生成时间（建议格式） {
湖南省地方金融征信与监管服务平台金融生态建设管理系统 接 口 规 范 说 明 书 省政府金融办信息中心 中科软科技股份有限公司 2015年12月
记录更改历史
目录 第1章系统接口 (4) 第2章获取金融机构数据接口 (4) 第3章获取金融业数据接口 (4) 第4章提供手机APP接口 (5) 第5章提供微信接口 (6)
第1章系统接口 数据接口的传送方式以JSON数据格式包装数据，对于保密安全级别高的数据，传送过程进行数据加密，防止数据泄密影响数据安全。第2章获取金融机构数据接口 ●从金融服务平台中获取金融机构数据。 获取金融机构基本信息，用于在GIS上显示。 接口名：queryFinancialInstitution4Gis 输入数据项：机构类型、地区。 返回数据项：机构类型、地区、机构名称、联系人、联系方式、地址、经度、纬度。 第3章获取金融业数据接口 从门户网站中数据上报系统中获取金融业数据。 ●获取数据名称 获取哪些数据可以查询。 接口名：queryIndexData4Gis 输入数据项：无。 返回数据项：数据名称 ●获取数值
获取具体数据的值。 接口名：queryIndexData4Gis 输入数据项：数据名称(如：上市企业数)、时间(多个)、地区(多个)。 返回数据项：数据名称、时间、地区、数值。 第4章提供手机APP接口 ●获取文档列表接口 接口名：queryDocListData 输入数据项：栏目、最后获取时间。 返回数据项：文档id、文档标题、发布时间。 ●获取文档内容 接口名：queryDocContentData 输入数据项：文档id。 返回数据项：文档标题、文档内容、发布人、发布时间。 ●登录 接口名：queryLoginData 输入数据项：用户名、密码。 返回数据项：单位、部门、用户名等用户基本信息。 ●获取指标 接口名：getIndexList 输入数据项：地域、年度。
设备维护平台 接口技术规范说明书 （版本号 V1.0） 杭州天梦科技有限公司 二〇一〇年五月
更改履历 进行修改。
设备维护平台接口技术规范说明书 目录 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) 3WEBSERVICE服务 (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服务接收到请求后从传入参数中获取用户名和密码，进行认证，认证通过后再调用具体服务。
设备维护平台接口技术规说明书（版本号 V1.0） 天梦科技 二〇一〇年五月
更改履历 进行修改。
目录 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) 3WEBSERVICE服务 (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服务接收到请求后从传入参数中获取用户名和密码，进行认证，认证通过后再调用具体服务。