完整的接口解决方案报告书说明书

./文档编号：T-JKJS文档版本：0.01项目编号：XX-DX-PECS《XX电信工程外部协作系统》ProjectExteriorCooperationSystem施工单位接口技术解决方案

编写人：南疯日期：2006-10-30审核人：日期：批准人：日期：XXXXXX信息科技股份有限公司地址：XXXXXXX邮编：XXXXXX电话：XXXXXXXX传真：XXXXXX网站：XXXXXXXXX修改记录〔RevisionChart版本号批准人修改人修改日期修改记录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.3外协系统向施工系统发送请求发送变更后的数据发送变更后的字典文档发送请求9信息数据项9.1数据表9.2字段信息9.3字典类型10网页地址11WebService接口11.1接口命名规范11.2输入参数11.3输出参数11.4外协系统提供的其他接口12附录：待定问题1引言1.1编写目的本文档为XX电信工程外部协作系统〔以下简称外协系统与电信工程施工单位内部系统〔以下简称施工系统接口技术解决方案,以此作为外协系统与施工系统实施接口的技术方案依据和项目设计标准。1.2覆盖范围XX电信工程外部协作系统项目组施工系统接口开发技术组1.3预期读者与阅读建议XX电信企业信息化部XX电信工程建设部XXXX公司开发人员施工系统开发人员1.4文档约定粗体正文表示强调内容红色正文表示未完成或需要今后考虑的内容蓝色正文表示待讨论内容1.5术语与缩略语术语、缩略语定义外协系统XX电信工程外部协作系统施工系统电信工程施工单位内部系统PECSXX电信工程外部协作系统英文简称1.6参考文献<XXXX>

2概述建设XX电信工程外部协作系统的目标,是在工程项目的管理、建设、使用和实施单位之间搭建起数据交换和协同工作的信息平台,延伸与拓展工程建设管理信息化的应用范围,实现通信工程建设过程的信息化管理,促进工程项目的管理部门、建设部门、实施部门和使用部门之间业务流程协调有序地开展,实现工程项目设计、施工、监理管理功能,将相关的设计、施工、监理单位纳入到工程建设管理中,完善工程项目建设过程管理体系,通过信息化推动管理的规范化,在信息化的应用过程中不断探索市场环境下工程建设管理的新思路和新方法。根据工程部业务工作的实际情况,项目首先满足工程建设管理中应用最广泛、问题最突出的基本需求。项目功能需求包括：建立工程外部协作系统与MSS等系统的接口；建立设计协作服务、监理协作服务、施工协作服务模块,为邮电设计院、电话监理公司和电信工程公司提供工程部所需的协作服务,保证工程建设实施流程的开展；在建立工程协作服务模块的基础上,建立工程外部协作系统与邮电设计院、电话监理公司、电信工程公司信息系统的接口,实现工程部与三家实施单位的信息交互与业务协作；本技术解决方案就是针对实现工程建设部与三家实施单位信息交互与业务协作接口中施工单位接口的技术解决方案的组成部分。在接口的调用过程中,存在施工系统调用外协系统接口的情况,这时候,施工系统作为客户端,外协系统作为服务端；也存在外协系统调用施工系统的情况,这时候,外协系统作为客户端,施工系统作为服务端。本方案中,除了特殊另外说明外,不考虑外协系统和施工系统角色换位的问题。如果一方发起了调用,那么它就是客户端,另一方就是服务端。反之亦然。4接口方式工程外协系统与施工系统之间的接口采用WebService接口形式来进行业务数据的交互。接口数据传输采用XML数据交换格式,utf-8编码。在外协系统中提供WebService的API接口。提供由施工系统调用获得信息；并且提供施工系统提交信息的API接口。同样,在施工系统中提供WebService的API接口。提供由外协系统提交信息的API接口。考虑到工程外协中的数据信息不仅包括了XX电信工程公司的数据而且还包含了其他的施工单位的数据信息。而这些单位也各有其各自工程应用系统。这样,外协系统对各个施工单位系统所提供的接口API及其参数信息、格式均是统一的。同时,也要求各个施工单位所提供的接口API及其参数、格式等也必须要求统一。外协系统与施工系统属于一对多的关系。外协系统要求能够有目的,信息有过滤的把业务信息通过接口正确的发送给相应施工系统接口。非相关的信息不要发送给对应的施工系统。施工系统建立用户映像对照表、字典对照表、单位对照表等数据映像,传递给外协的数据使用的是映像中转换后的外协系统能够识别数据；同时,接收到的数据也根据对照表转换成各自能够解释的数据格式。数据初始化的时候,由施工系统主动调用外协系统的接口,以获得用户信息、字典信息、单位信息、项目信息等基础信息。以后,一旦发生数据的变动,由外协系统主动往施工系统发送信息。外协系统不主动请求施工系统获得数据,但是外协系统会主动请求施工系统发送数据。施工系统主动请求外协系统获得数据,也会主动请求外协系统发送数据。4接口安全4.1接口认证调用认证：虽然接口双方都是存在于电信内部网络中,但是,仍不能排除接口服务被攻击、恶意调用以及非法调用等。所以,从接口调用上,必须考虑调用的认证安全问题。本方案中的接口,在客户端调用服务端的时候,必须经过调用身份认证。考虑施工系统的开发平台的多样性,但同时接口服务运行平台都是Windows的情况,本方案采用Windows安全身份认证的方式。即在访问接口所在的服务的时候,都必须进行资格审查〔使用Credentials发送认证信息。另外,接口采用SOAP协议,因此在接口配置上面需要屏蔽HTTPGET和HTTPPOST等其他协议。在接口中审核并进行日志的记录。使用最低权限的进程帐户运行Web服务〔通过Machine.config中的<processModel>元素来配置。接口不支持动态生成WSDL,因此作为服务端,应该禁止文档协议。在服务端禁用跟踪,禁用调式编译业务用户认证：由于接口涉及电信工程中的各个不同的业务,有获取字典、获得项目信息、发送开工报告等,所以,建立一套业务的用户认证机制是必须的。不同的用户,所具备有的授权不一样,所能执行的业务也不一样。同时,业务用户认证中的用户信息也是记录接口日志中的重要组成部分。本方案采用的是在接口信息中包含业务认证用户信息的方式来进行认证。服务端在收到请求的时候,应先验证业务的授权用户,如果该业务用户没有执行当前业务的权限,应终止业务的执行,并给出非法用户的警告信息反馈回客户端。一般情况下,业务认证的用户是系统中的用户。业务认证其实就是应用系统认证的组成部分。业务认证的用户信息经过加密之后包含在要发送的信息〔XML体中,即在发送的信息中包含业务用户的信息〔参见下面的数据格式说明。4.2数据安全数据的安全表现为如何保证数据在网络传输过程中不会被截获并被解析其中的内容而引起信息泄露与如何保证数据在传输的过程中的数据的完整性两个方面。WebService采用XML数据格式来传输信息。所以,无论是发送数据还是返回结果,都要求采用对XML数据加密之后来传输。至于采用何种方式的加密技术,本方案为了保密,只能在开发的时候由开发人员口头告知。涉及到加密技术就要涉及到加密的密钥问题。目前,外协系统和施工系统接口上有很多种类型的业务,到底是每种类型的业务采用不同的密钥,还是按分组来采用同一种密钥的方式,还是所有的业务全部采用同一种的密钥的方式,按照需求各有不同的选择。本方案采用的是最后一种的方式。密钥的发布由作为服务方来发布,由客户端获取。密钥的发布方式待定。为了保证数据的完整性,首先：方案采用数据签名〔SOAPSecurityExtensions:DigitalSignature。利用XML的数字签名〔XMLDigitalSignaturesyntax[XML-Signature]对SOAP进行扩展,在SOAP的头元素中定义签名属性〔<SOAP-SEC:Signature>来实现。其次：限制并验证Web方法输入的类型、长度、格式和范围,验证对XML输入数据的验证是基于已协商的架构等。5事务处理事务是一组相关的任务,作为独立于其他任务的独立单元成功〔提交或失败〔中止。分布式事务是影响多个资源的事务。要提交分布式事务,所有参与者都必须保证对数据的任何更改是永久的。不论系统崩溃或是发生其他无法预料的事件,更改都必须是持久的。即使只有一个参与者无法保证这一点,整个事务也将失败,在事务范围内对数据的任何更改均将回滚。外协系统和施工系统是处于网络之上的两个分布式接口,使用的是分布式事务。要启用分布式事务,可能需要通过网络启用MSDTC〔考虑外协平台和施工平台都是运行在Windows上,以便在使用应用了最新的ServicePack的较新操作系统〔例如WindowsXP或Windows2003时使用分布式事务。如果启用了Windows防火墙〔WindowsXPServicePack2的默认设置,必须允许MSDTC服务使用网络或打开MSDTC端口。接口中的服务端和客户端的环境事务始终相同,客户端创建的事务上下文并应用对于服务端的当前的事务,以便对于该事务上下文是当前的。这样的事务会造成性能损失,因为可能需要继承原来的上下文,但是,这样的事务确保了在数据库操作的时候信息的完整性。接口中事务的发起总是由客户端发起的,并负责事务的提交和回滚等控制。6性能考虑在接口设计的时候就应该考虑性能上面的问题,不要在事后再加入性能。同时,在项目的开发过程要反复进行测试,可以从机器的吞吐量和响应时间两个基本的指标来衡量接口的性能。接口上面的性能考虑主要从下面几个方面来优化：使用一次连接,多次调用,优化连接资源。对于并行的接口调用使用异步的调用方式。优化线程池减少竞争。考虑使用XML压缩。如果不需要返回,考虑使用单工通讯的方式。适当的设置〔如果有代理代理超时,页面超时,WebService超时。设计"大块头"的接口减少往返。基于消息的编程而不是远程过程调用<RPC>。使用XML字串作为参数。尽量使用原始数据类型参数。避免在调用之间维护服务器状态。考虑为复杂的WebMethod提供输入校验。考虑对WebMethod的结果使用缓存。选择适用的大数据包传送方式。避免调用本地的WebService。7容错处理客户端向服务端发送数据,服务端解析数据,反馈信息给客户端,这中间的环节只要某一个环节出现问题,都会造成接口的失败。按照失败产生的环节分类,我们可以从三个方面来处理接口的失败。网络连接失败：在调用接口的时候,由于网络不通,造成数据不能正常传输。这样,客户端应该能够记录发送的日志,按照一定的时间间隔重试发送。本方案定为重试发送20次,每次时间间隔2小时。如果一直发生网络不通的情况,该发送日志被保存下来,待后手工发送。所以,客户端系统应该实现手工发送数据的功能。反馈错误信息：服务端在解析数据包,执行数据包业务的时候,可能会发生异常。所以,服务端应当能够捕捉异常信息,比如"非法XML格式"等,然后反馈给客户端。客户端在接受到这类的错误信息之后,应当进行日志记录,能够自动或手工分析异常的信息。网络连接正常,但是无信息反馈：这种情况下,一般是服务端出现了异常,但是又没有捕捉到的情况下发生。这种情况下,客户端把这种错误当作"网络连接失败"来处理。服务端应能够实现相同数据包重新发送过来的处理机制。8数据格式在WebService的调用过程中,无论是外协系统还是施工系统,都有发送数据和接收数据的要求,也即双方系统同时作为客户端又作为服务端。我们统称这些传递的数据为报文。客户端发送报文,属于调用；服务端接收报文,属于被调用。客户端和服务端互相之间通讯的请求报文和结果报文遵循XML格式。客户端发送请求报文,服务器解析调用报文,执行报文中所在接口对应的服务功能。生成结果报文,以xml格式页返回给请求者。请求者拿到结果报文,进行解析,然后再进行相应的处理。8.1约定报文中所有的字典信息〔比如性别1-男,2-女,都以代码的值〔1或者2来传递。施工单位向外协系统发送的报文中的代码都需要转换成外协的代码,外协系统向施工系统发送的报文中的代码无需转换。报文中的其他数据类型,比如货币、RowID,自定义对象类型等,根据需要转换成文本、数值或二进制〔最终转换成Base64字符的数据类型。报文中数值信息,转换成文本,如：<ItemCount>50</ItemCount><ValueSum>12368.36</ValueSum>报文中数值不支持科学计数的方式。报文中数值的单位使用国标的单位,比如货币使用"元",长度使用"米"等。无国标的单位以约定为准。报文中的日期信息,转换成YYYYMMDDHHmmss文本格式〔24小时制。如果是空日期,则转换成空文本。报文中的true和false数据类型,转换成0<表示false>、1〔表示true报文中的二进制数据,转换成Base64字符方式发送。报文中的记录集,放在<Records>标签中；报文中一条记录,放在<Records>标签中。报文中如果存在多条记录,则在<Records>标签中就包含多个的<Record>标签。如果报文中仅有一条记录,则<Records>标签中只包含一个<Record>标签.如果没有记录,则仅仅包含一个<Records>标签,没有<Record>标签。如果返回结果数据集非常多,在性能考虑和数据量冲突的情况下,可以使用分页返回数据集的方式分批返回数据〔每次返回最多100条记录。服务端提供分批结果返回的功能。至于如何使用分页查询的功能,参见下面的XML框架说明。8.2施工系统向外协系统发送请求施工系统向外协系统发送请求的数据目前有几点需要考虑：如何请求查询一个业务数据如何新增一条记录,新增之后如何点到记录的键值如何修改一条记录如何删除一条记录文档如何上传一条记录中一个FileID的字段如何上传多个文件如何在一条记录中补充上传文档如何在一条记录中删除一个文档如何获得文档的基本信息如何获得文档的所有兄弟信息如何获得文档的所有父亲信息如何下载一个文档针对这些问题,接口方案的解决方法如下：8.2.1请求查询一个业务数据施工系统针对外协系统发送的业务数据查询请求根据业务类型有很多种。为了简化接口,而不是在接口上进行业务操作,所以,外协系统将施工系统发起的数据查询请求看作是数据下载的一种方式,而不为了复杂的业务查询请求提供复杂的条件解析。外协系统提供的数据查询接口是从数据下载和数据延期性来考虑的。为了满足数据的下载,外协系统提供了按照某一个表的主键来下载数据和按照记录的变更时间范围来下载数据的两种方式查询请求。请求报文：<?xmlversion="1.0"encoding="utf-8"?><XmlData><UserInfo><User>ZhangSan</User><PassWord>123456</PassWord></UserInfo><Description><RowID>0</RowID><KeyValue>123</KeyValue><QueryBeginTime>20061018153000</QueryBeginTime><QueryEndTime>20061019153000</QueryEndTime></Description></XmlData>响应报文：<?xmlversion="1.0"encoding="utf-8"?><XmlData><Description><RowID>100</RowID></Description><Records><Record><Field1>Value1</Field1><Field2>Value2</Field2><Field3>Value3</Field3><Field4>Value4</Field4></Record><Record><Field1>Value1</Field1><Field2>Value2</Field2><Field3>Value3</Field3><Field4>Value4</Field4></Record><Record><Field1>Value1</Field1><Field2>Value2</Field2><Field3>Value3</Field3><Field4>Value4</Field4></Record></Records></XmlData>报文说明：标签名说明<XmlData>报文数据主体<Description>报文头部信息<Records>记录集合<Record>一行记录<UserInfo>业务认证的用户信息<User>业务用户登录名<PassWord>业务用户验证口令<RowID>第一次请求的时候,客户端RowID发送0,表示从第0条记录开发返回。服务端根据条件查询,发现结果超过100条记录,则在返回的结果中,RowID的值为99,表示服务端当前的记录位置处在第100条的位置上,后面还会有剩余的记录。客户端检查返回的结果,如果发现RowID大于0,则继续发送请求进行查询。但是,客户端第二次发送请求继续查询的时候,RowID的值要赋值为第一次返回的值,即RowID=99。服务端第二次收到请求的时候,发现RowID是99,则从第100条返回结果。以此类推循环调用,直到服务端达到记录的末尾,这时候,服务端在返回的结果中RowID=0.客户端发现服务端RowID=0,终止循环调用。字典、用户信息、单位信息,因为返回的字段比较少,不受100条记录返回的限制。一次调用,就返回全部的结果。<KeyValue>查询时主键的值。这个<KeyValue>和下面的<QueryBeginTime><QueryEndTime>是互斥的。如果在请求的时候提供了主键的值,表示客户端要求服务器按照主键的值查询一条记录。如果客户端提供了主键的值,则服务端将忽略<QueryBeginTime><QueryEndTime>中的值。字典、用户信息、单位信息,因为没有查询时间范围,所以<KeyValue>即表示字典类型。<QueryBeginTime><QueryEndTime>查询时时间段范围。<QueryBeginTime>是起始时间,<QueryEndTime>是结束时间。表示客户端要求服务端查询在这个时间范围之内所有变更过的记录〔包括新增、修改、删除。在外协中,一条记录新增的时候,它的创建时间和最后修改时间是一样的,以后修改记录的时候,创建时间不变,改变的仅仅是最后修改时间。同时,外协系统中删除记录仅仅在"记录是否删除"字段中标记"1",并不是真正的物理删除记录。这里的时间指的是记录变更的时间,不是记录中的某个业务时间。如果用户需要按照业务时间来查询数据,则施工系统把外协系统的数据获取到本地进行保存,在施工系统中提供按照业务时间查询的功能。<QueryBeginTime><QueryEndTime>和<KeyValue>是互斥的。如果客户端需要按照时间范围来查询,则必须<KeyValue>空。<Field1><Field2><Field3><Field4>一行记录中的英文字段名称。实际中,这些标签都是字典的英文名。字段的标签全部是大写。具体的字段名称请参见提供的数据模型8.2.1新增一条记录,得到记录的键值为了简化数据模型的处理,本方案不考虑主从表的并发处理情况。如果存在主从表的数据需要上传,那么,在一个事务中,施工单位首先先上传主表的记录,从反馈信息中获得主表的主键值。然后,把刚刚获得的主表的主键值赋值给从表的对应外键,再上传从表数据,得到从表的主键值。如果不是主从表,而是单表,则直接上传数据,从反馈信息中得到主键值。这种情况的优点是：数据和表相关,施工单位可以灵活的控制表之间的关系；同时,数据包中的报文比较简单,容易解析；接口上面比较清晰,与业务的耦合比较低。缺点是：一个业务涉及的主从表不能在同一个报文中〔这个缺点可以通过施工系统灵活的控制表之间关系来解决；一个业务中可能会使用到两个或两个以上的接口,造成业务完整性上面的分离〔这种缺点可以通过把业务放在一个事务中来解决；键值的返回：在调用新增接口之后,外协会按照记录的顺序返回外外协中所生成的键值。施工单位获得键值之后,可以在本地表中更新记录的主键值。请求报文：<?xmlversion="1.0"encoding="utf-8"?><XmlData><UserInfo><User>ZhangSan</User><PassWord>123456</PassWord></UserInfo><Description><Note>开工报告</Note></Description><Records><Record><KeyField></KeyField><NormalField1>Value1</NormalField1><NormalField2>Value2</NormalField2><NormalField3>Value3</NormalField3><NormalField4>Value4</NormalField4></Record><Record><KeyField></KeyField><NormalField1>Value1</NormalField1><NormalField2>Value2</NormalField2><NormalField3>Value3</NormalField3><NormalField4>Value4</NormalField4></Record></Records></XmlData>响应报文：<?xmlversion="1.0"encoding="utf-8"?><XmlData><Description><Result>成功</Result><!--如果失败,则<Result>里面内容是：失败：〔错误原因--></Description><Records><Record><KeyField>Value1</KeyField></Record><Record><KeyField>Value2</KeyField></Record></Records></XmlData>报文说明：标签名说明<XmlData>报文数据主体<Description>报文头部信息<Records>记录集合<Record>一行记录<UserInfo>业务认证的用户信息<User>业务用户登录名<PassWord>业务用户验证口令<Note>业务的简单描述。比如：开工报告、施工组织方案等请求中的<KeyField>一行记录中的主键字段。在新增的时候,施工系统所给的主键字段内容为空。外协系统中根据主键字段内容为空,认为这是一条新增的记录响应中的<KeyField>一行记录中的主键字段。外协系统返回的主键值。这里的主键值和施工系统发送的记录的顺序是一一对应的。<Result>反馈报文中的保存成功与否信息。如果保存成功,则信息是"成功"如果保存失败,则信息是"失败：〔后面是错误的详细信息"8.2.3修改一条记录施工系统在修改了一条记录的时候,上传的报文中与新增的报文类似,只是主键的信息不能为空。外协系统判断主键的信息,如果发现主键的信息不为空,则认为是修改了一条记录。如果施工系统报文中主键不为空,而外协系统在数据库对应的表中又没有发现对应的记录,则自动转换成新增的方式来处理这条记录。外协系统在反馈中,还是会把主键返回给施工系统。但是,这种情况下,施工系统可能不再需要维护这个主键。即使是仅仅修改了一个字段,施工单位还得需要上传全部的字段信息〔包含被修改的字段给外协系统。施工系统不是对记录做物理删除,而仅仅是作了逻辑删除,即仅仅在记录的删除标志位上面做了"1"的标志。这种情况对记录来说,也是修改的范围。只是需要在<Note>业务的简单描述中说明"逻辑删除"。即使是逻辑删除记录,施工系统也必须上传全部的字段到外协系统。请求报文：<?xmlversion="1.0"encoding="utf-8"?><XmlData><UserInfo><User>ZhangSan</User><PassWord>123456</PassWord></UserInfo><Description><Note>停工通知确认</Note></Description><Records><Record><KeyField>KeyValue1</KeyField><NormalField1>Value1</NormalField1><NormalField2>Value2</NormalField2><NormalField3>Value3</NormalField3><NormalField4>Value4</NormalField4></Record><Record><KeyField>KeyValue2</KeyField><NormalField1>Value1</NormalField1><NormalField2>Value2</NormalField2><NormalField3>Value3</NormalField3><NormalField4>Value4</NormalField4></Record></Records></XmlData>响应报文：<?xmlversion="1.0"encoding="utf-8"?><XmlData><Description><Result>成功</Result><!--如果失败,则<Result>里面内容是：失败：〔错误原因--></Description><Records><Record><KeyField>Value1</KeyField></Record><Record><KeyField>Value2</KeyField></Record></Records></XmlData>报文说明：标签名说明<XmlData>报文数据主体<Description>报文头部信息<Records>记录集合<Record>一行记录<UserInfo>业务认证的用户信息<User>业务用户登录名<PassWord>业务用户验证口令<Note>业务的简单描述。比如：开工报告、施工组织方案等请求中的<KeyField>一行记录中的主键字段。在修改的时候,施工系统所给的主键字段内容不能为空。外协系统中根据主键字段内容不为空,认为这是一条修改的记录响应中的<KeyField>一行记录中的主键字段。外协系统返回的主键值。这里的主键值和施工系统发送的记录的顺序是一一对应的。<Result>反馈报文中的保存成功与否信息。如果保存成功,则信息是"成功"如果保存失败,则信息是"失败：〔后面是错误的详细信息"<NormalField>一行记录中的英文字段名称。实际中,这些标签都是字典的英文名。字段的标签全部是大写。具体的字段名称请参见提供的数据模型8.2.4删除一条记录这里的删除指的是物理删除。逻辑删除在记录修改的时候已经说明。物理删除是彻底的从数据库中删除一条记录,不能恢复。物理删除的时候,施工系统只要在报文中提供主键的信息提交,就能够实现。同样的,外协系统在反馈的报文中返回成功删除主键的信息,如果其中一条记录不能正常物理删除,则外协自动回滚所有删除的操作。即一条记录不能删除,则所有的记录都不能删除。请求报文：<?xmlversion="1.0"encoding="utf-8"?><XmlData><UserInfo><User>ZhangSan</User><PassWord>123456</PassWord></UserInfo><Description><Note>物理删除</Note></Description><Records><Record><KeyField>Value1</KeyField></Record><Record><KeyField>Value2</KeyField></Record></Records></XmlData>响应报文：<?xmlversion="1.0"encoding="utf-8"?><XmlData><Description><Result>成功</Result><!--如果失败,则<Result>里面内容是：失败：〔错误原因,同时,KeyField的值为空--></Description><Records><Record><KeyField>Value1</KeyField></Record><Record><KeyField>Value2</KeyField></Record></Records></XmlData>报文说明：〔参见数据修改说明8.2.5文档上传外协系统中,文档的信息是保存在另外的一个表中当中的,所以,许多的业务表,往往存在一个FileID的主键关联到文档表。在业务表中档,可能有一个FileID的字段,也可能会有两个或两个以上的FileID字段关联到文档信息表。涉及到文档的地方,往往文档的信息会比较大,所以,文档的信息不能包含在基础业务数据的报文当中一起上传。处理的方法是：先上传文档的实体,从反馈的信息当中得到生成的文档ID〔FileID,然后,施工系统在本地记录中的相应字段赋值文档的ID,最后再上传基本业务信息。如果一条记录中包含有两个或两个以上的文档字段,则施工系统必须依次上传文档获得文档ID之后,赋值,再上传基本业务信息。一个文档报文当中,只能上传一个文档。文档报文如下：<?xmlversion="1.0"encoding="utf-8"?><XmlData><UserInfo><User>ZhangSan</User><PassWord>123456</PassWord></UserInfo><Description></Description><Records><Record><ID></ID><FILE_PRJ_ID>123456</FILE_PRJ_ID><FILE_TYPE>401</FILE_TYPE><FILE_NAME>施工组织方案.DOC</FILE_NAME><FILE_UNIT>电信工程公司</FILE_UNIT><FILE_MAN>张三</FILE_MAN><FILE_CREATE_TIME>20061031153005</FILE_CREATE_TIME><FILE_AUTHOR>张三</FILE_AUTHOR><FILE_TITLE>项目XXX施工组织方案</FILE_TITLE><KeepMutiFile>1</KeepMutiFile><FileData>/e5asf@dfgafa#sdgsdg……</FileData></Record></Records></XmlData>响应报文：<?xmlversion="1.0"encoding="utf-8"?><XmlData><Description><Result>成功</Result><!--如果失败,则返回信息是"失败：〔错误信息"--></Description><Records><Record><ID>123456</ID></Record></Records></XmlData>报文说明：标签名说明<XmlData>报文数据主体<Description>报文头部信息<Records>记录集合<Record>一行记录<UserInfo>业务认证的用户信息<User>业务用户登录名<PassWord>业务用户验证口令<ID>文档的ID,在新增上传一个文档的时候,这个ID永远都是空的。外协系统根据这个文件ID是否为空来判断是否是新的文件。<FILE_PRJ_ID>文档所属的项目ID,对于工程协作系统来说,一个文档永远都是会属于某个项目的。这个项目ID可以是一级项目,也可以是三级项目。<FILE_TYPE>文件类型。标识文件的归类。比如：D401施工组织设计=401D402施工项目计划进度=402D403施工日报=403<FILE_TYPE>里面的值是代码,文件类型的代码可以从字典接口中获得。<FILE_NAME>文档的文件名称,带有扩展名。<FILE_UNIT>文件创建单位,中文名<FILE_MAN>文档创建人<上传人><FILE_CREATE_TIME>文档创建时间<FILE_AUTHOR>文档作者〔可为空<FILE_TITLE>文档标题〔可为空<KeepMutiFile>是否允许多个文档同时有效。这个标签的值为1或0。当值为1的时候,则在同样的项目ID、同样的文件类型中,同时可以存在多个的文档同时有效存在。这种情况下,多个文档之间是兄弟之间的关系,当前的文档是弟弟,以前的文档是兄长。当这个值为0的时候,则在同样的项目ID、同样的文件类型中,只有最后上传的文档有效,后面上传的文档会把前面的文档"挤"到历史中,成为当前文档的"父亲"。这种情况下,当前的文档和以前上传的文档之间是父子的关系。更详细的解释请参见后面的"一条记录中一个FileID的字段如何上传多个文件"主题相关内容。<FileData>文件实体内容。文件实体内容用二进制读取出来之后,然后转换成base64的格式。<Result>反馈报文中的保存成功与否信息。如果保存成功,则信息是"成功"如果保存失败,则信息是"失败：〔后面是错误的详细信息"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之后,更新业务表中的相应记录,再用修改的报文上报修改后的业务数据〔此步骤不要忘记。请求删除文档的报文：<?xmlversion="1.0"encoding="utf-8"?><XmlData><UserInfo><User>ZhangSan</User><PassWord>123456</PassWord></UserInfo><Description></Description><Records><ID>123456</ID></Records></XmlData>响应报文：<?xmlversion="1.0"encoding="utf-8"?><XmlData><Description><Result>成功</Result><!--如果失败,则返回信息是"失败：〔错误信息"--></Description><Records><Record><ID>456789</ID><!--这个是链当中的最后一个文档ID,如果链已经不存在,返回-1--></Record></Records></XmlData>报文说明：标签名说明<XmlData>报文数据主体<Description>报文头部信息<Records>记录集合<Record>一行记录<UserInfo>业务认证的用户信息<User>业务用户登录名<PassWord>业务用户验证口令<Result>反馈报文中的保存成功与否信息。如果文档删除成功,则信息是"成功"如果文档删除失败,则信息是"失败：〔后面是错误的详细信息"请求报文中<ID>文档的ID。要删除的文档ID反馈报文中<ID>文档的ID。当删除链中的一个文档之后,外协系统自动维护链之间的关系,并返回链末尾最后一个文档的ID8.2.9获得文档的基本信息施工系统根据文档的ID向外协系统请求获得文档的基本信息。外协系统返回满足结果的文档基本信息。施工系统可以请求一个文档的基本信息,也可以请求多个〔最多100个文档的信息。这个接口不考虑文档链的情况,仅仅是按指定文档ID返回结果。请求报文：<?xmlversion="1.0"encoding="utf-8"?><XmlData><UserInfo><User>ZhangSan</User><PassWord>123456</PassWord></UserInfo><Description></Description><Records><Record><ID>123456</ID></Record><Record><ID>456789</ID></Record></Records></XmlData>响应报文：<?xmlversion="1.0"encoding="utf-8"?><XmlData><Description><Result>成功</Result><!--如果失败,则返回信息是"失败：〔错误信息"--></Description><Records><Record><ID>123456</ID><FILE_PRJ_ID>Value1</FILE_PRJ_ID><FILE_TYPE>Value2</FILE_TYPE><FILE_CREAET_MODE>Value3</FILE_CREAET_MODE><FILE_NAME>Value4</FILE_NAME><FILE_UNIT>Value5</FILE_UNIT><FILE_MAN>Value6</FILE_MAN><FILE_CREATE_TIME>Value7</FILE_CREATE_TIME><FILE_SIZE>Value8</FILE_SIZE><FILE_AUTHOR>Value9</FILE_AUTHOR><FILE_TITLE>Value10</FILE_TITLE><FILE_BROTHER_ID>Value11</FILE_BROTHER_ID><FILE_PARENT_ID>Value12</FILE_PARENT_ID></Record><Record><ID>456789</ID><FILE_PRJ_ID>Value1</FILE_PRJ_ID><FILE_TYPE>Value2</FILE_TYPE><FILE_CREAET_MODE>Value3</FILE_CREAET_MODE><FILE_NAME>Value4</FILE_NAME><FILE_UNIT>Value5</FILE_UNIT><FILE_MAN>Value6</FILE_MAN><FILE_CREATE_TIME>Value7</FILE_CREATE_TIME><FILE_SIZE>Value8</FILE_SIZE><FILE_AUTHOR>Value9</FILE_AUTHOR><FILE_TITLE>Value10</FILE_TITLE><FILE_BROTHER_ID>Value11</FILE_BROTHER_ID><FILE_PARENT_ID>Value12</FILE_PARENT_ID></Record></Records></XmlData>报文说明：标签名说明<XmlData>报文数据主体<Description>报文头部信息<Records>记录集合<Record>一行记录<UserInfo>业务认证的用户信息<User>业务用户登录名<PassWord>业务用户验证口令<Result>反馈报文中的保存成功与否信息。如果文档获得成功,则信息是"成功"如果文档获得失败,则信息是"失败：〔后面是错误的详细信息"请求报文中<ID>文档的ID。要获取的文档ID反馈报文中<ID>文档的ID。要获取的文档ID<FILE_PRJ_ID>文档所属项目ID<FILE_TYPE>文档类型<FILE_CREAET_MODE>文档创建方式默认：用户上传<FILE_NAME>文档〔文件名称<FILE_UNIT>创建单位<FILE_MAN>创建人<FILE_CREATE_TIME>创建日期<FILE_SIZE>文档大小<FILE_AUTHOR>文档作者<FILE_TITLE>文档标题<FILE_BROTHER_ID>兄弟节点ID,如果没有兄长,则为-1<FILE_PARENT_ID>父亲节点ID,如果没有父亲,则为-18.2.10获得文档的所有兄弟信息获得文档所有兄弟信息与获得文档基本信息类似,区别之处在于在获得文档所有兄弟信息的时候,施工系统仅仅需要提交一个最小兄弟的节点,外协系统自动找出该文档的所有"兄长"文档信息返回。注意,在返回的所有兄弟报文中,最小的兄弟排在记录的最前面,依序排序往上,最后,最大的兄弟排在最后面。下面的这个报文虽然和前面的"如何获得文档的基本信息"报文一样,但是,施工系统仅仅需要提交一条文档的ID。而且,这个求情所调用的接口和前面的"如何获得文档的基本信息"的所调用的接口是不一样的。请求报文：<?xmlversion="1.0"encoding="utf-8"?><XmlData><UserInfo><User>ZhangSan</User><PassWord>123456</PassWord></UserInfo><Description></Description><Records><Record><ID>123456</ID></Record></Records></XmlData>响应报文：<?xmlversion="1.0"encoding="utf-8"?><XmlData><Description><Result>成功</Result><!--如果失败,则返回信息是"失败：〔错误信息"--></Description><Records><Record><ID>123456</ID><FILE_PRJ_ID>Value1</FILE_PRJ_ID><FILE_TYPE>Value2</FILE_TYPE><FILE_CREAET_MODE>Value3</FILE_CREAET_MODE><FILE_NAME>Value4</FILE_NAME><FILE_UNIT>Value5</FILE_UNIT><FILE_MAN>Value6</FILE_MAN><FILE_CREATE_TIME>Value7</FILE_CREATE_TIME><FILE_SIZE>Value8</FILE_SIZE><FILE_AUTHOR>Value9</FILE_AUTHOR><FILE_TITLE>Value10</FILE_TITLE><FILE_BROTHER_ID>456789</FILE_BROTHER_ID><FILE_PARENT_ID>Value12</FILE_PARENT_ID></Record><Record><ID>456789</ID><FILE_PRJ_ID>Value1</FILE_PRJ_ID><FILE_TYPE>Value2</FILE_TYPE><FILE_CREAET_MODE>Value3</FILE_CREAET_MODE><FILE_NAME>Value4</FILE_NAME><FILE_UNIT>Value5</FILE_UNIT><FILE_MAN>Value6</FILE_MAN><FILE_CREATE_TIME>Value7</FILE_CREATE_TIME><FILE_SIZE>Value8</FILE_SIZE><FILE_AUTHOR>Value9</FILE_AUTHOR><FILE_TITLE>Value10</FILE_TITLE><FILE_BROTHER_ID>-1</FILE_BROTHER_ID><FILE_PARENT_ID>Value12</FILE_PARENT_ID></Record></Records></XmlData>

各种标签说明：〔参见前面的"如何获得文档的基本信息"说明8.2.11获得文档的所有父亲信息同"如何获得文档的所有兄弟信息"接口一样,施工系统向外协系统提交最小辈分的一个文档的ID,外协系统自动返回所有的父辈文档信息,包含父亲,爷爷,祖爷爷等。请求报文：〔参见"如何获得文档的所有兄弟信息"请求报文响应报文：〔参见"如何获得文档的所有兄弟信息"响应报文各种标签说明：〔参见前面的"如何获得文档的基本信息"说明8.2.12下载一个文档获得文档的ID之后,施工系统可以向外协系统请求下载某一个文档的实体数据。外协系统把文档用二进制读取出来之后,转换成base64的格式供施工系统下载。施工系统一次只能请求下载一个文档。请求报文：<?xmlversion="1.0"encoding="utf-8"?><XmlData><UserInfo><User>ZhangSan</User><PassWord>123456</PassWord></UserInfo><Description></Description><Records><ID>123456</ID></Records></XmlData>响应报文：<?xmlversion="1.0"encoding="utf-8"?><XmlData><Description><Result>成功</Result><!--如果失败,则返回信息是"失败：〔错误信息"--></Description><Records><Record><FileData>/e5asf@dfgafa#sdgsdg……</FileData></Record></Records></XmlData>报文说明：标签名说明<XmlData>报文数据主体<Description>报文头部信息<Records>记录集合<Record>一行记录<UserInfo>业务认证的用户信息<User>业务用户登录名<PassWord>业务用户验证口令<ID>文档的ID。请求下载的文档ID<FileData>文件实体内容。文件实体内容用二进制读取出来之后,然后转换成base64的格式提供给施工系统。<Result>反馈报文中的下载成功与否信息。如果下载成功,则信息是"成功"如果下载失败,则信息是"失败：〔后面是错误的详细信息"8.2.13获得字典施工系统提交字典的分类ID,向外协系统发送请求。外协系统根据字典分类ID,返回对应的字典代码信息。字典代码的信息返回不受最大返回记录100条的限制,一次返回全部的该类字典代码。请求报文：<?xmlversion="1.0"encoding="utf-8"?><XmlData><UserInfo><User>ZhangSan</User><PassWord>123456</PassWord></UserInfo><Description></Description><Records><DictionaryID>201</DictionaryID></Records></XmlData>响应报文：<?xmlversion="1.0"encoding="utf-8"?><XmlData><Description><Result>成功</Result><!--如果失败,则返回信息是"失败：〔错误信息"--></Description><Records><Record><Field1>Value1</Field1><Field2>Value2</Field2><Field3>Value3</Field3></Record><Record><Field1>Value1</Field1><Field2>Value2</Field2><Field3>Value3</Field3></Record><Record><Field1>Value1</Field1><Field2>Value2</Field2><Field3>Value3</Field3></Record></Records></XmlData>报文说明：标签名说明<XmlData>报文数据主体<Description>报文头部信息<Records>记录集合<Record>一行记录<UserInfo>业务认证的用户信息<User>业务用户登录名<PassWord>业务用户验证口令<DictionaryID>字典类型ID。请求下载的字典类型,外协根据字典类型返回对应的字典。<Field1><Field2><Field3><Field4>一行字典中的英文字段名称。实际中,这些标签都是字典的英文名。字段的标签全部是大写。具体的字段名称请参见提供的数据模型<Result>反馈报文中的下载成功与否信息。如果下载成功,则信息是"成功"如果下载失败,则信息是"失败：〔后面是错误的详细信息"8.3外协系统向施工系统发送请求外协系统向施工系统发送请求的数据目前有几点需要考虑：如何请求发送一个变更后的业务数据如何请求发送一个变更后的字典数据文档发送请求外协系统不会主动发送文档的变更信息给施工系统,因为文档的信息〔文档的ID变更是体现在业务的信息当中的,外协系统向施工系统发送业务的变更信息当中就包含了变更了的文档ID,只有在施工系统中进行业务需要获得文档的信息的时候,由施工系统主动发送请求到外协系统获得文档的信息或下载文档。针对前面这些问题,接口方案的解决方法如下：发送变更后的数据外协系统在业务数据发生变更〔新增、修改、逻辑删除的时候,会自动发送请求到施工系统要求施工系统进行更新。注意,外协系统中没有记录上的物理删除,外协系统中所有的删除业务都是逻辑上的删除,仅仅在删除标志位上面标记为"1"。所以,外协系统没有向施工系统发送物理删除的请求。请求报文：<?xmlversion="1.0"encoding="utf-8"?><XmlData><UserInfo><User>ZhangSan</User><PassWord>123456</PassWord></UserInfo><Description><Note>项目经理已经对数据进行了审批</Note></Description><Records><Record><KeyField>KeyValue</KeyField><Field1>Value1</Field1><Field2>Value2</Field2><Field3>Value3</Field3><Field4>Value4</Field4></Record><Record><KeyField>KeyValue</KeyField><Field1>Value1</Field1><Field2>Value2</Field2><Field3>Value3</Field3><Field4>Value4</Field4></Record><Record><KeyField>KeyValue</KeyField><Field1>Value1</Field1><Field2>Value2</Field2><Field3>Value3</Field3><Field4>Value4</Field4></Record></Records></XmlData>响应报文：<?xmlversion="1.0"encoding="utf-8"?><XmlData><Description><Result>成功</Result><!--如果失败,则<Result>里面内容是：失败：〔错误原因,同时,KeyField的值为空--></Description><Records></Records></XmlData>报文说明：标签名说明<XmlData>报文数据主体<Description>报文头部信息<Records>记录集合<Record>一行记录<UserInfo>业务认证的用户信息<User>业务用户登录名<PassWord>业务用户验证口令<Note>业务的简单描述。比如：开工报告审批、施工组织方案审批等<KeyField>一行记录中的主键英文字段名称。实际中,这些标签都是字典的英文名。字段的标签全部是大写。具体的主键字段名称请参见提供的数据模型<Field1><Field2><Field3><Field4>一行记录中的英文字段名称。实际中,这些标签都是字典的英文名。字段的标签全部是大写。具体的字段名称请参见提供的数据模型<Result>反馈报文中的保存成功与否信息。如果保存成功,则信息是"成功"如果保存失败,则信息是"失败：〔后面是错误的详细信息"8.3.2发送变更后的字典外协系统在字典数据发生变更〔新增、修改、逻辑删除的时候,会自动发送请求到施工系统要求施工系统进行更新施工系统的对照字典。即使是仅仅一个字典条目发生了改变,外协系统向施工系统发送的报文中还是包含了该类字典的所有条目。请求报文：<?xmlversion="1.0"encoding="utf-8"?><XmlData><UserInfo><User>ZhangSan</User><PassWord>123456</PassWord></UserInfo><Description><DictionaryID>201</DictionaryID></Description><Records><Record><Field1>Value1</Field1><Field2>Value2</Field2><Field3>Value3</Field3><Field4>Value4</Field4></Record><Record><Field1>Value1</Field1><Field2>Value2</Field2><Field3>Value3</Field3><Field4>Value4</Field4></Record><Record><Field1>Value1</Field1><Field2>Value2</Field2><Field3>Value3</Field3>