1、文档编号： T-JKJS文档版本： 0.01项目编号： XX-DX- PECSXX 电信工程外部协作系统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
2、 编写目的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 获得文档的所有父
3、亲信息8.2.12 下载一个文档8.2.13 获得字典8.3 外协系统向施工系统发送请求8.3.1发送变更后的数据8.3.2发送变更后的字典8.3.3文档发送请求9 信息数据项9.1 数据表9.2 字段信息9.3 字典类型10 网页地址11 Web Service 接口11.1 接口命名规范11.2 输入参数11.3 输出参数11.4 外协系统提供的其他接口12 附录：待定问题1 引言1.1 编写目的本文档为 XX 电信工程外部协作系统（以下简称外协系统）与电信工程施工单位内部系统（以下简称施工系统）接口技术解决方案，以此作为外协系统与施工系统实施接口的技术方案依据和项目设计标准。1.2 覆盖
4、范围XX 电信工程外部协作系统项目组施工系统接口开发技术组1.3 预期读者与阅读建议XX 电信企业信息化部XX 电信工程建设部XXXX 公司开发人员施工系统开发人员1.4 文档约定粗体正文表示强调内容红色正文表示未完成或需要今后考虑的内容蓝色正文表示待讨论内容1.5 术语与缩略语术语、缩略语 定 义外协系统 XX 电信工程外部协作系统施工系统 电信工程施工单位内部系统PECS XX 电信工程外部协作系统英文简称1.6 参考文献(XXXX)2 概述建设 XX 电信工程外部协作系统的目标，是在工程项目的管理、建设、使用和实施单位之间搭建起数据交换和协同工作的信息平台，延伸与拓展工程建设管理信息化的
5、应用范围，实现通信工程建设过程的信息化管理，促进工程项目的管理部门、建设部门、实施部门和使用部门之间业务流程协调有序地开展，实现工程项目设计、施工、监理管理功能，将相关的设计、施工、监理单位纳入到工程建设管理中，完善工程项目建设过程管理体系，通过信息化推动管理的规范化，在信息化的应用过程中不断探索市场环境下工程建设管理的新思路和新方法。根据工程部业务工作的实际情况，项目首先满足工程建设管理中应用最广泛、问题最突出的基本需求。项目功能需求包括： 建立工程外部协作系统与 MSS 等系统的接口； 建立设计协作服务、监理协作服务、施工协作服务模块，为邮电设计院、电话监理公司和电信工程公司提供工程部所需
6、的协作服务，保证工程建设实施流程的开展； 在建立工程协作服务模块的基础上，建立工程外部协作系统与邮电设计院、电话监理公司、电信工程公司信息系统的接口，实现工程部与三家实施单位的信息交互与业务协作；本技术解决方案就是针对实现工程建设部与三家实施单位信息交互与业务协作接口中施工单位接口的技术解决方案的组成部分。在接口的调用过程中，存在施工系统调用外协系统接口的情况，这时候，施工系统作为客户端，外协系统作为服务端；也存在外协系统调用施工系统的情况，这时候，外协系统作为客户端，施工系统作为服务端。本方案中，除了特殊另外说明外，不考虑外协系统和施工系统角色换位的问题。如果一方发起了调用，那么它就是客户端
7、，另一方就是服务端。反之亦然。4 接口方式 工程外协系统与施工系统之间的接口采用 Web Service 接口形式来进行业务数据的交互。 接口数据传输采用 XML 数据交换格式，utf-8编码。 在外协系统中提供 Web Service 的 API 接口。提供由施工系统调用获得信息；并且提供施工系统提交信息的 API 接口。 同样，在施工系统中提供 Web Service 的 API 接口。提供由外协系统提交信息的 API接口。 考虑到工程外协中的数据信息不仅包括了 XX 电信工程公司的数据而且还包含了其他的施工单位的数据信息。而这些单位也各有其各自工程应用系统。这样，外协系统对各个施工单位系
8、统所提供的接口 API 及其参数信息、格式均是统一的。同时，也要求各个施工单位所提供的接口 API 及其参数、格式等也必须要求统一。外协系统与施工系统属于一对多的关系。 外协系统要求能够有目的，信息有过滤的把业务信息通过接口正确的发送给相应施工系统接口。非相关的信息不要发送给对应的施工系统。 施工系统建立用户映像对照表、字典对照表、单位对照表等数据映像，传递给外协的数据使用的是映像中转换后的外协系统能够识别数据；同时，接收到的数据也根据对照表转换成各自能够解释的数据格式。 数据初始化的时候，由施工系统主动调用外协系统的接口，以获得用户信息、字典信息、单位信息、项目信息等基础信息。以后，一旦发生
9、数据的变动，由外协系统主动往施工系统发送信息。 外协系统不主动请求施工系统获得数据，但是外协系统会主动请求施工系统发送数据。 施工系统主动请求外协系统获得数据，也会主动请求外协系统发送数据。4 接口安全4.1 接口认证调用认证：虽然接口双方都是存在于电信内部网络中，但是，仍不能排除接口服务被攻击、恶意调用以及非法调用等。所以，从接口调用上，必须考虑调用的认证安全问题。 本方案中的接口，在客户端调用服务端的时候，必须经过调用身份认证。考虑施工系统的开发平台的多样性，但同时接口服务运行平台都是 Windows 的情况，本方案采用Windows 安全身份认证的方式。即在访问接口所在的服务的时候，都必
10、须进行资格审查（使用 Credentials 发送认证信息） 。 另外，接口采用 SOAP 协议，因此在接口配置上面需要屏蔽 HTTP GET 和 HTTP POST 等其他协议。 在接口中审核并进行日志的记录。 使用最低权限的进程帐户运行 Web 服务（通过 Machine.config 中的 元素来配置） 。 接口不支持动态生成 WSDL,因此作为服务端，应该禁止文档协议。 在服务端禁用跟踪，禁用调式编译业务用户认证：由于接口涉及电信工程中的各个不同的业务，有获取字典、获得项目信息、发送开工报告等，所以，建立一套业务的用户认证机制是必须的。不同的用户，所具备有的授权不一样，所能执行的业务也
11、不一样。同时，业务用户认证中的用户信息也是记录接口日志中的重要组成部分。本方案采用的是在接口信息中包含业务认证用户信息的方式来进行认证。服务端在收到请求的时候，应先验证业务的授权用户，如果该业务用户没有执行当前业务的权限，应终止业务的执行，并给出非法用户的警告信息反馈回客户端。一般情况下，业务认证的用户是系统中的用户。业务认证其实就是应用系统认证的组成部分。业务认证的用户信息经过加密之后包含在要发送的信息（XML 体）中，即在发送的信息中包含业务用户的信息（参见下面的数据格式说明） 。4.2 数据安全数据的安全表现为如何保证数据在网络传输过程中不会被截获并被解析其中的内容而引起信息泄露与如何保
12、证数据在传输的过程中的数据的完整性两个方面。Web Service 采用 XML 数据格式来传输信息。所以，无论是发送数据还是返回结果，都要求采用对 XML 数据加密之后来传输。至于采用何种方式的加密技术，本方案为了保密，只能在开发的时候由开发人员口头告知。涉及到加密技术就要涉及到加密的密钥问题。目前，外协系统和施工系统接口上有很多种类型的业务，到底是每种类型的业务采用不同的密钥，还是按分组来采用同一种密钥的方式，还是所有的业务全部采用同一种的密钥的方式，按照需求各有不同的选择。本方案采用的是最后一种的方式。密钥的发布由作为服务方来发布，由客户端获取。密钥的发布方式待定。为了保证数据的完整性，
13、首先：方案采用数据签名（SOAP Security Extensions: Digital Signature） 。利用 XML 的数字签名（XML Digital Signature syntax XML-Signature）对 SOAP 进行扩展，在 SOAP 的头元素中定义签名属性（）来实现。其次：限制并验证 Web 方法输入的类型、长度、格式和范围，验证对 XML 输入数据的验证是基于已协商的架构等。5 事务处理事务是一组相关的任务，作为独立于其他任务的独立单元成功（提交）或失败（中止） 。分布式事务是影响多个资源的事务。要提交分布式事务，所有参与者都必须保证对数据的任何更改是永久的。
14、不论系统崩溃或是发生其他无法预料的事件，更改都必须是持久的。即使只有一个参与者无法保证这一点，整个事务也将失败，在事务范围内对数据的任何更改均将回滚。外协系统和施工系统是处于网络之上的两个分布式接口，使用的是分布式事务。要启用分布式事务，可能需要通过网络启用 MS DTC（考虑外协平台和施工平台都是运行在Windows 上） ，以便在使用应用了最新的 Service Pack 的较新操作系统（例如 Windows XP 或 Windows 2003）时使用分布式事务。如果启用了 Windows 防火墙（Windows XP Service Pack 2 的默认设置） ，必须允许 MS DTC
15、服务使用网络或打开 MS DTC 端口。接口中的服务端和客户端的环境事务始终相同，客户端创建的事务上下文并应用对于服务端的当前的事务，以便对于该事务上下文是当前的。这样的事务会造成性能损失，因为可能需要继承原来的上下文，但是，这样的事务确保了在数据库操作的时候信息的完整性。接口中事务的发起总是由客户端发起的，并负责事务的提交和回滚等控制。6 性能考虑在接口设计的时候就应该考虑性能上面的问题，不要在事后再加入性能。同时，在项目的开发过程要反复进行测试，可以从机器的吞吐量和响应时间两个基本的指标来衡量接口的性能。接口上面的性能考虑主要从下面几个方面来优化： 使用一次连接，多次调用，优化连接资源。
16、对于并行的接口调用使用异步的调用方式。 优化线程池减少竞争。 考虑使用 XML 压缩。 如果不需要返回，考虑使用单工通讯的方式。 适当的设置（如果有代理）代理超时，页面超时，WebService 超时。 设计“大块头“的接口减少往返。 基于消息的编程而不是远程过程调用(RPC) 。 使用 XML 字串作为参数。 尽量使用原始数据类型参数。 避免在调用之间维护服务器状态。 考虑为复杂的 WebMethod 提供输入校验。 考虑对 WebMethod 的结果使用缓存。 选择适用的大数据包传送方式。 避免调用本地的 WebService。7 容错处理客户端向服务端发送数据，服务端解析数据，反馈信息给
17、客户端，这中间的环节只要某一个环节出现问题，都会造成接口的失败。按照失败产生的环节分类，我们可以从三个方面来处理接口的失败。 网络连接失败：在调用接口的时候，由于网络不通，造成数据不能正常传输。这样，客户端应该能够记录发送的日志，按照一定的时间间隔重试发送。本方案定为重试发送20次，每次时间间隔2小时。如果一直发生网络不通的情况，该发送日志被保存下来，待后手工发送。所以，客户端系统应该实现手工发送数据的功能。 反馈错误信息：服务端在解析数据包，执行数据包业务的时候，可能会发生异常。所以，服务端应当能够捕捉异常信息，比如“非法 XML 格式”等，然后反馈给客户端。客户端在接受到这类的错误信息之后
18、，应当进行日志记录，能够自动或手工分析异常的信息。 网络连接正常，但是无信息反馈：这种情况下，一般是服务端出现了异常，但是又没有捕捉到的情况下发生。这种情况下，客户端把这种错误当作“网络连接失败”来处理。服务端应能够实现相同数据包重新发送过来的处理机制。8 数据格式在 Web Service 的调用过程中，无论是外协系统还是施工系统，都有发送数据和接收数据的要求，也即双方系统同时作为客户端又作为服务端。我们统称这些传递的数据为报文。客户端发送报文，属于调用；服务端接收报文，属于被调用。客户端和服务端互相之间通讯的请求报文和结果报文遵循 XML 格式。客户端发送请求报文，服务器解析调用报文，执行
19、报文中所在接口对应的服务功能。生成结果报文，以 xml 格式页返回给请求者。请求者拿到结果报文，进行解析，然后再进行相应的处理。8.1 约定 报文中所有的字典信息（比如性别1-男，2-女） ，都以代码的值（1或者2）来传递。施工单位向外协系统发送的报文中的代码都需要转换成外协的代码，外协系统向施工系统发送的报文中的代码无需转换。 报文中的其他数据类型，比如货币、RowID,自定义对象类型等，根据需要转换成文本、数值或二进制（最终转换成 Base64字符）的数据类型。 报文中数值信息，转换成文本，如：5012368.36 报文中数值不支持科学计数的方式。报文中数值的单位使用国标的单位，比如货币使
20、用“元” ，长度使用“米”等。无国标的单位以约定为准。 报文中的日期信息，转换成 YYYYMMDD HHmmss 文本格式（24小时制） 。如果是空日期，则转换成空文本。 报文中的 true 和 false 数据类型，转换成 0(表示 false)、1（表示 true） 报文中的二进制数据，转换成 Base64字符方式发送。 报文中的记录集，放在标签中；报文中一条记录，放在标签中。 报文中如果存在多条记录，则在标签中就包含多个的标签。如果报文中仅有一条记录，则标签中只包含一个标签.如果没有记录，则仅仅包含一个标签,没有标签。 如果返回结果数据集非常多，在性能考虑和数据量冲突的情况下，可以使用分
21、页返回数据集的方式分批返回数据（每次返回最多100条记录） 。服务端提供分批结果返回的功能。至于如何使用分页查询的功能，参见下面的 XML 框架说明。8.2 施工系统向外协系统发送请求施工系统向外协系统发送请求的数据目前有几点需要考虑： 如何请求查询一个业务数据 如何新增一条记录，新增之后如何点到记录的键值 如何修改一条记录 如何删除一条记录 文档如何上传 一条记录中一个 FileID 的字段如何上传多个文件 如何在一条记录中补充上传文档 如何在一条记录中删除一个文档 如何获得文档的基本信息 如何获得文档的所有兄弟信息 如何获得文档的所有父亲信息 如何下载一个文档针对这些问题，接口方案的解决方
22、法如下：8.2.1 请求查询一个业务数据施工系统针对外协系统发送的业务数据查询请求根据业务类型有很多种。为了简化接口，而不是在接口上进行业务操作，所以，外协系统将施工系统发起的数据查询请求看作是数据下载的一种方式，而不为了复杂的业务查询请求提供复杂的条件解析。外协系统提供的数据查询接口是从数据下载和数据延期性来考虑的。为了满足数据的下载，外协系统提供了按照某一个表的主键来下载数据和按照记录的变更时间范围来下载数据的两种方式查询请求。请求报文： ZhangSan123456012320061018 15300020061019 153000响应报文：100Value1Value2Value3Va
23、lue4Value1Value2Value3Value4Value1Value2Value3Value4报文说明：标签名 说明报文数据主体报文头部信息记录集合一行记录业务认证的用户信息业务用户登录名业务用户验证口令第一次请求的时候，客户端 RowID 发送0，表示从第0条记录开发返回。服务端根据条件查询，发现结果超过100条记录，则在返回的结果中，RowID 的值为99，表示服务端当前的记录位置处在第100条的位置上，后面还会有剩余的记录。客户端检查返回的结果，如果发现 RowID 大于0,则继续发送请求进行查询。但是，客户端第二次发送请求继续查询的时候，RowID 的值要赋值为第一次返回的值
24、，即 RowID=99。服务端第二次收到请求的时候，发现 RowID 是99,则从第100条返回结果。以此类推循环调用，直到服务端达到记录的末尾，这时候，服务端在返回的结果中RowID=0.客户端发现服务端 RowID=0，终止循环调用。字典、用户信息、单位信息，因为返回的字段比较少，不受100条记录返回的限制。一次调用，就返回全部的结果。查询时主键的值。这个和下面的是互斥的。如果在请求的时候提供了主键的值，表示客户端要求服务器按照主键的值查询一条记录。如果客户端提供了主键的值，则服务端将忽略中的值。字典、用户信息、单位信息，因为没有查询时间范围，所以即表示字典类型。查询时时间段范围。是起始时
25、间，是结束时间。表示客户端要求服务端查询在这个时间范围之内所有变更过的记录（包括新增、修改、删除） 。在外协中，一条记录新增的时候，它的创建时间和最后修改时间是一样的，以后修改记录的时候，创建时间不变，改变的仅仅是最后修改时间。同时，外协系统中删除记录仅仅在“记录是否删除”字段中标记“1”，并不是真正的物理删除记录。这里的时间指的是记录变更的时间，不是记录中的某个业务时间。如果用户需要按照业务时间来查询数据，则施工系统把外协系统的数据获取到本地进行保存，在施工系统中提供按照业务时间查询的功能。和是互斥的。如果客户端需要按照时间范围来查询，则必须空。一行记录中的英文字段名称。实际中，这些标签都是
26、字典的英文名。字段的标签全部是大写。具体的字段名称请参见提供的数据模型8.2.1 新增一条记录，得到记录的键值为了简化数据模型的处理，本方案不考虑主从表的并发处理情况。如果存在主从表的数据需要上传，那么，在一个事务中，施工单位首先先上传主表的记录，从反馈信息中获得主表的主键值。然后，把刚刚获得的主表的主键值赋值给从表的对应外键，再上传从表数据，得到从表的主键值。如果不是主从表，而是单表，则直接上传数据，从反馈信息中得到主键值。这种情况的优点是：数据和表相关，施工单位可以灵活的控制表之间的关系；同时，数据包中的报文比较简单，容易解析；接口上面比较清晰，与业务的耦合比较低。缺点是：一个业务涉及的主
27、从表不能在同一个报文中（这个缺点可以通过施工系统灵活的控制表之间关系来解决） ；一个业务中可能会使用到两个或两个以上的接口，造成业务完整性上面的分离（这种缺点可以通过把业务放在一个事务中来解决） ；键值的返回：在调用新增接口之后，外协会按照记录的顺序返回外外协中所生成的键值。 施工单位获得键值之后，可以在本地表中更新记录的主键值。请求报文：ZhangSan123456开工报告Value1Value2Value3Value4Value1Value2Value3Value4响应报文：成功 里面内容是：失败：（错误原因）Value1 Value2 报文说明：标签名 说明报文数据主体报文头部信息记录集
28、合一行记录业务认证的用户信息业务用户登录名业务用户验证口令业务的简单描述。比如：开工报告、施工组织方案 等请求中的 一行记录中的主键字段。在新增的时候，施工系统所给的主键字段内容为空。外协系统中根据主键字段内容为空，认为这是一条新增的记录响应中的 一行记录中的主键字段。外协系统返回的主键值。这里的主键值和施工系统发送的记录的顺序是一一对应的。反馈报文中的保存成功与否信息。如果保存成功，则信息是“成功”如果保存失败，则信息是“失败：（后面是错误的详细信息） ”8.2.3 修改一条记录施工系统在修改了一条记录的时候，上传的报文中与新增的报文类似，只是主键的信息不能为空。外协系统判断主键的信息，如果
29、发现主键的信息不为空，则认为是修改了一条记录。如果施工系统报文中主键不为空，而外协系统在数据库对应的表中又没有发现对应的记录，则自动转换成新增的方式来处理这条记录。外协系统在反馈中，还是会把主键返回给施工系统。但是，这种情况下，施工系统可能不再需要维护这个主键。即使是仅仅修改了一个字段，施工单位还得需要上传全部的字段信息（包含被修改的字段）给外协系统。施工系统不是对记录做物理删除，而仅仅是作了逻辑删除，即仅仅在记录的删除标志位上面做了“1”的标志。这种情况对记录来说，也是修改的范围。只是需要在业务的简单描述中说明“逻辑删除” 。即使是逻辑删除记录，施工系统也必须上传全部的字段到外协系统。请求报
30、文： ZhangSan123456停工通知确认KeyValue1Value1Value2Value3Value4KeyValue2Value1Value2Value3Value4响应报文：成功 里面内容是：失败：（错误原因）Value1 Value2 报文说明：标签名 说明报文数据主体报文头部信息记录集合一行记录业务认证的用户信息业务用户登录名业务用户验证口令业务的简单描述。比如：开工报告、施工组织方案 等请求中的 一行记录中的主键字段。在修改的时候，施工系统所给的主键字段内容不能为空。外协系统中根据主键字段内容不为空，认为这是一条修改的记录响应中的 一行记录中的主键字段。外协系统返回的主键值
31、。这里的主键值和施工系统发送的记录的顺序是一一对应的。反馈报文中的保存成功与否信息。如果保存成功，则信息是“成功”如果保存失败，则信息是“失败：（后面是错误的详细信息） ”一行记录中的英文字段名称。实际中，这些标签都是字典的英文名。字段的标签全部是大写。具体的字段名称请参见提供的数据模型8.2.4 删除一条记录这里的删除指的是物理删除。逻辑删除在记录修改的时候已经说明。物理删除是彻底的从数据库中删除一条记录，不能恢复。物理删除的时候，施工系统只要在报文中提供主键的信息提交，就能够实现。同样的，外协系统在反馈的报文中返回成功删除主键的信息，如果其中一条记录不能正常物理删除，则外协自动回滚所有删除
32、的操作。即一条记录不能删除，则所有的记录都不能删除。请求报文： ZhangSan123456物理删除 Value1Value2响应报文：成功 里面内容是：失败：（错误原因） ，同时，KeyField 的值为空Value1 Value2 报文说明：（参见数据修改说明）8.2.5 文档上传外协系统中，文档的信息是保存在另外的一个表中当中的，所以，许多的业务表，往往存在一个 FileID 的主键关联到文档表。在业务表中档，可能有一个 FileID 的字段，也可能会有两个或两个以上的 FileID 字段关联到文档信息表。涉及到文档的地方，往往文档的信息会比较大，所以，文档的信息不能包含在基础业务数据的
33、报文当中一起上传。处理的方法是：先上传文档的实体，从反馈的信息当中得到生成的文档 ID（FileID） ，然后，施工系统在本地记录中的相应字段赋值文档的 ID，最后再上传基本业务信息。如果一条记录中包含有两个或两个以上的文档字段，则施工系统必须依次上传文档获得文档 ID之后，赋值，再上传基本业务信息。一个文档报文当中，只能上传一个文档。文档报文如下：ZhangSan123456123456401施工组织方案.DOC电信工程公司张三20061031 153005张三项目 XXX 施工组织方案1/e5asfdfgafa#sdgsdg响应报文：成功 123456报文说明：标签名 说明报文数据主体报文
34、头部信息记录集合一行记录业务认证的用户信息业务用户登录名业务用户验证口令文档的 ID，在新增上传一个文档的时候，这个 ID 永远都是空的。外协系统根据这个文件 ID 是否为空来判断是否是新的文件。文档所属的项目 ID，对于工程协作系统来说，一个文档永远都是会属于某个项目的。这个项目 ID 可以是一级项目，也可以是三级项目。文件类型。标识文件的归类。比如：D401施工组织设计= 401D402施工项目计划进度= 402D403施工日报= 403里面的值是代码，文件类型的代码可以从字典接口中获得。文档的文件名称，带有扩展名。文件创建单位，中文名文档创建人(上传人)文档创建时间文档作者 （可为空）文
35、档标题 （可为空）是否允许多个文档同时有效。这个标签的值为 1 或 0。当值为1 的时候，则在同样的项目 ID、同样的文件类型中，同时可以存在多个的文档同时有效存在。这种情况下，多个文档之间是兄弟之间的关系，当前的文档是弟弟，以前的文档是兄长。当这个值为0的时候，则在同样的项目 ID、同样的文件类型中，只有最后上传的文档有效，后面上传的文档会把前面的文档“挤”到历史中，成为当前文档的“父亲” 。这种情况下，当前的文档和以前上传的文档之间是父子的关系。更详细的解释请参见后面的“一条记录中一个 FileID 的字段如何上传多个文件 ”主题相关内容。文件实体内容。文件实体内容用二进制读取出来之后，然
36、后转换成base64的格式。反馈报文中的保存成功与否信息。如果保存成功，则信息是“成功”如果保存失败，则信息是“失败：（后面是错误的详细信息） ”8.2.6 一条记录中一个文档字段上传多个文件外协系统中，文档是以一种“有关系”的方式来存储的。假设有这样一个业务表 Table1，里面有一个文档的外键字段 File_ID。当我们往 Table1表里面插入一条记录的时候，针对这一条记录，我们希望在 File_ID 字段中可以带有多个的文档，也即会有多个的 File_ID。当然，我们可以把这个表字段的数据模型这个定义：File1_ID，File2_ID,File3_ID，需要多少个文件，我们就定义几个
37、的 File_ID 字段。但是这样就会带来问题了，如果你定义了5个的 File_ID 字段，但是，用户如果想在一条记录中上传6个文档，那么，这样的数据模型就会满足不了用户的要求。还有一种情况，如果用户仅仅上传了2个文档，那么剩下的3 个 File_ID 字段就会白白空着。甚至用户对这条记录没有上传文件，这样定义的数据模型就白白浪费了数据库的资源。还有一种说法，我可以用记录的形式来表示啊。对的。上传多个文件，是可以在 Table1中新增多条记录方式来表示。但是，我们的前提是，Table1是一个业务表，里面的一条记录就是一笔业务。如果你产生了多条记录，那么意味这这样的业务进行了多次。显然违背了业务
38、数据保存的初衷。外协系统引入了“父子” ， “兄弟”的文档保存机制, 即在文档信息表(Files 表)中保存文档的基本信息和他们之间的关系。在同样的项目 ID、同样的文件类型中，如果可以存在多个的文档同时有效存在，这种情况下，多个文档之间是兄弟之间的关系。后来者文档是弟弟，先到的文档是兄长。在同样的项目 ID、同样的文件类型中，只有最后上传的文档有效，后面上传的文档会把前面的文档“挤”到历史中，成为当前文档的“父亲” 。这种情况下，后来的文档和以前上传的文档之间是父子的关系。如果文档之间是兄弟关系的话，则仅仅在业务表 Table1中保存最小兄弟的 File_ID；如果文档之间是父子关系的话，则
39、仅仅保存最小辈分的文档 File_ID。兄弟和父子的文档保存方式其实都是多个文档串联的一种保存方式，但是，还是会有使用上面的区别的。兄弟关系一般使用在文档之间是平级的情况下。比如施工组织方案，可以有多个文件，但是，这多个文件是互为补充的一部分，互相依赖，又缺一不可。这种情况下，施工系统可以把这类型的文件上传给外协系统，以兄弟的方式保存，施工系统仅仅在业务表当中保存最后上传反馈回来的 FileID 即可。以后，可以使用这个最小兄弟的 File_ID，向外协系统请求以获得他的所有兄长文档。父子的关系一般使用在下面的情景：当仅允许一个文档是最终有效的时候，或者一个文档修改之后再上传到外协系统，我们想
40、把最后上传的文档“覆盖”前面的文档，但是，又想保留文档历史修改痕迹的时候，一般就会用到父子关系。父子关系中，施工系统仅仅需要保留最小辈分的文档信息，以后，可以使用这个最小辈分的 File_ID，向外协系统请求以获得他的所有历史文档。8.2.7 补充上传文档根据前面的兄弟和父子关系的说明，一条记录中补充上传文档的方式就简单了许多。只要施工系统上传了文档，获得最后的文档 ID，然后，在施工系统中维护最后的文档 ID，再用修改记录的报文上报更新后的业务数据即可。流程：上传补充的文档 获得最后的文档 ID 用最后的文档 ID 更新业务数据 上传修改后的业务数据。8.2.8 在记录中删除一个文档向外协系
41、统请求删除一个文档，只需要向外协系统提交包含有要删除的文档 ID 即可。如果需要删除的是文档链当中的某一个文档，则需要向外协请求获得文档链的信息（参见后面的“如何获取文档信息” ） ，然后，从链中找到要删除的文档 ID，向外协系统提交。外协系统在删除文档的同时，会自动把链连接起来成为一个完整的链关系，同时，总是返回链的最末尾的文档 ID。施工系统获得链末尾的最后文档 ID 之后，更新业务表中的相应记录，再用修改的报文上报修改后的业务数据（此步骤不要忘记） 。请求删除文档的报文： ZhangSan123456123456响应报文：成功 456789 报文说明：标签名 说明报文数据主体报文头部信息
42、记录集合一行记录业务认证的用户信息业务用户登录名业务用户验证口令反馈报文中的保存成功与否信息。如果文档删除成功，则信息是“成功”如果文档删除失败，则信息是“失败：（后面是错误的详细信息） ”请求报文中 文档的 ID。要删除的文档 ID反馈报文中 文档的 ID。当删除链中的一个文档之后，外协系统自动维护链之间的关系，并返回链末尾最后一个文档的 ID8.2.9 获得文档的基本信息施工系统根据文档的 ID 向外协系统请求获得文档的基本信息。外协系统返回满足结果的文档基本信息。施工系统可以请求一个文档的基本信息，也可以请求多个（最多100个）文档的信息。这个接口不考虑文档链的情况，仅仅是按指定文档 I
43、D 返回结果。请求报文：ZhangSan123456123456456789响应报文：成功 123456Value1Value2Value3Value4Value5Value6Value7Value8Value9Value10Value11Value12 456789Value1Value2Value3Value4Value5Value6Value7Value8Value9Value10Value11Value12报文说明：标签名 说明报文数据主体报文头部信息记录集合一行记录业务认证的用户信息业务用户登录名业务用户验证口令反馈报文中的保存成功与否信息。如果文档获得成功，则信息是“成功”如果文档
44、获得失败，则信息是“失败：（后面是错误的详细信息） ”请求报文中 文档的 ID。要获取的文档 ID反馈报文中 文档的 ID。要获取的文档 ID文档所属项目 ID文档类型文档创建方式 默认：用户上传文档（文件）名称创建单位创建人创建日期文档大小文档作者文档标题兄弟节点 ID，如果没有兄长，则为 -1父亲节点 ID, 如果没有父亲，则为 -18.2.10 获得文档的所有兄弟信息获得文档所有兄弟信息与获得文档基本信息类似，区别之处在于在获得文档所有兄弟信息的时候，施工系统仅仅需要提交一个最小兄弟的节点，外协系统自动找出该文档的所有“兄长”文档信息返回。注意，在返回的所有兄弟报文中，最小的兄弟排在记录
45、的最前面，依序排序往上，最后，最大的兄弟排在最后面。下面的这个报文虽然和前面的“如何获得文档的基本信息”报文一样，但是，施工系统仅仅需要提交一条文档的 ID。而且，这个求情所调用的接口和前面的“如何获得文档的基本信息”的所调用的接口是不一样的。请求报文：ZhangSan123456123456响应报文：成功 123456Value1Value2Value3Value4Value5Value6Value7Value8Value9Value10456789Value12 456789Value1Value2Value3Value4Value5Value6Value7Value8Value9Valu
46、e10-1Value12各种标签说明：（参见前面的“如何获得文档的基本信息”说明）8.2.11 获得文档的所有父亲信息同“如何获得文档的所有兄弟信息”接口一样，施工系统向外协系统提交最小辈分的一个文档的 ID，外协系统自动返回所有的父辈文档信息，包含父亲，爷爷，祖爷爷等。请求报文：（参见“如何获得文档的所有兄弟信息”请求报文）响应报文：（参见“如何获得文档的所有兄弟信息”响应报文）各种标签说明：（参见前面的“如何获得文档的基本信息”说明） 8.2.12 下载一个文档获得文档的 ID 之后，施工系统可以向外协系统请求下载某一个文档的实体数据。外协系统把文档用二进制读取出来之后，转换成 base6
47、4的格式供施工系统下载。施工系统一次只能请求下载一个文档。请求报文：ZhangSan123456123456响应报文： 成功 /e5asfdfgafa#sdgsdg报文说明：标签名 说明报文数据主体报文头部信息记录集合一行记录业务认证的用户信息业务用户登录名业务用户验证口令文档的 ID。请求下载的文档 ID文件实体内容。文件实体内容用二进制读取出来之后，然后转换成base64的格式提供给施工系统。反馈报文中的下载成功与否信息。如果下载成功，则信息是“成功”如果下载失败，则信息是“失败：（后面是错误的详细信息） ”8.2.13 获得字典施工系统提交字典的分类 ID，向外协系统发送请求。外协系统根
48、据字典分类 ID，返回对应的字典代码信息。字典代码的信息返回不受最大返回记录100条的限制，一次返回全部的该类字典代码。请求报文： ZhangSan123456201响应报文： 成功 Value1Value2Value3Value1Value2Value3Value1Value2Value3报文说明：标签名 说明报文数据主体报文头部信息记录集合一行记录业务认证的用户信息业务用户登录名业务用户验证口令字典类型 ID。请求下载的字典类型，外协根据字典类型返回对应的字典。一行字典中的英文字段名称。实际中，这些标签都是字典的英文名。字段的标签全部是大写。具体的字段名称请参见提供的数据模型反馈报文中的下载成功与否信息。如果下载成功，则信息是“成功”如果下载失败，则信息是“失败：（后面是错误的详细信息） ”8.3 外协系统向施工系统发送请求外协系统向施工系统发送请求的数据目前有几点需要考虑： 如何请求发送一个变更后的业务数据 如何请求发送一个变更后的字典数据 文档发送请求外协系统不会主动发送文档
