一個完整的接口技術(shù)解決方案（一）

題注：
      發(fā)表這篇解決方案，屬于非盈利目的。主要是為了讓大家了解一種接口技術(shù)解決方案文檔的編寫格式以及讓大家評審在我的這個技術(shù)解決方案中的不足之處，以便大家指出并加以改進(jìn)。
      轉(zhuǎn)載，下載或與各種形式使用這篇文章，必須注明文章的作者，出處。
      其他未盡事宜，以國家法律規(guī)定的為準(zhǔn)！
                                                                    作者：南瘋

 

 

《XX電信工程外部協(xié)作系統(tǒng)》

Project Exterior Cooperation System

 

施工單位接口技術(shù)解決方案

編寫人：	南瘋	日期：	2006-10-30
審核人：		日期：
批準(zhǔn)人：		日期：

XXXXXX信息科技股份有限公司

 

地址：	XXXXXXX	郵編：XXXXXX
電話：	XXXXXXXX	傳真：XXXXXX
網(wǎng)站：	XXXXXXXXX

版本號	批準(zhǔn)人	修改人	修改日期	修改記錄
0.01		南瘋	2006-10-30	第一次創(chuàng)建

 

0.02詳細(xì)修改記錄：

序號	內(nèi)容

 

1     引言.... 5

1.1       編寫目的... 5

1.2       覆蓋范圍... 5

1.3       預(yù)期讀者與閱讀建議... 5

1.4       文檔約定... 5

1.5       術(shù)語與縮略語... 5

1.6       參考文獻(xiàn)... 6

2     概述.... 7

3     接口方式.... 8

4     接口安全.... 9

4.1       接口認(rèn)證... 9

4.2       數(shù)據(jù)安全... 10

5     事務(wù)處理.... 10

6     性能考慮.... 11

7     容錯處理.... 12

8     數(shù)據(jù)格式.... 12

8.1       約定... 13

8.2       施工系統(tǒng)向外協(xié)系統(tǒng)發(fā)送請求... 13

8.2.1       請求查詢一個業(yè)務(wù)數(shù)據(jù)... 14

8.2.2       新增一條記錄，得到記錄的鍵值... 17

8.2.3       修改一條記錄... 19

8.2.4       刪除一條記錄... 21

8.2.5       文檔上傳... 23

8.2.6       一條記錄中一個文檔字段上傳多個文件... 25

8.2.7       補(bǔ)充上傳文檔... 26

8.2.8       在記錄中刪除一個文檔... 27

8.2.9       獲得文檔的基本信息... 28

8.2.10      獲得文檔的所有兄弟信息... 31

8.2.11      獲得文檔的所有父親信息... 32

8.2.12      下載一個文檔... 32

8.2.13      獲得字典... 34

8.3       外協(xié)系統(tǒng)向施工系統(tǒng)發(fā)送請求... 35

8.3.1發(fā)送變更后的數(shù)據(jù)... 36

8.3.2發(fā)送變更后的字典... 38

8.3.3文檔發(fā)送請求... 40

9     信息數(shù)據(jù)項.... 40

9.1       數(shù)據(jù)表... 40

9.2       字段信息... 42

9.3       字典類型... 42

10       網(wǎng)頁地址.... 44

11    Web Service接口.... 44

11.1     接口命名規(guī)范... 44

11.2     輸入?yún)?shù)... 44

11.3     輸出參數(shù)... 45

11.4     外協(xié)系統(tǒng)提供的其他接口... 45

12       附錄：待定問題.... 45

 

1       引言

1.1    編寫目的

   本文檔為XX電信工程外部協(xié)作系統(tǒng)（以下簡稱外協(xié)系統(tǒng)）與電信工程施工單位內(nèi)部系統(tǒng)（以下簡稱施工系統(tǒng)）接口技術(shù)解決方案，以此作為外協(xié)系統(tǒng)與施工系統(tǒng)實施接口的技術(shù)方案依據(jù)和項目設(shè)計標(biāo)準(zhǔn)。

1.2    覆蓋范圍

   XX電信工程外部協(xié)作系統(tǒng)項目組

   施工系統(tǒng)接口開發(fā)技術(shù)組

1.3    預(yù)期讀者與閱讀建議

   XX電信企業(yè)信息化部

     XX電信工程建設(shè)部

   XXXX公司開發(fā)人員

   施工系統(tǒng)開發(fā)人員

1.4    文檔約定

粗體正文表示強(qiáng)調(diào)內(nèi)容

   紅色正文表示未完成或需要今后考慮的內(nèi)容

   藍(lán)色正文表示待討論內(nèi)容

1.5    術(shù)語與縮略語

術(shù)語、縮略語	定    義
外協(xié)系統(tǒng)	XX電信工程外部協(xié)作系統(tǒng)
施工系統(tǒng)	電信工程施工單位內(nèi)部系統(tǒng)
PECS	XX電信工程外部協(xié)作系統(tǒng)英文簡稱

1.6    參考文獻(xiàn)

(XXXX)

2       概述

   建設(shè)XX電信工程外部協(xié)作系統(tǒng)的目標(biāo)，是在工程項目的管理、建設(shè)、使用和實施單位之間搭建起數(shù)據(jù)交換和協(xié)同工作的信息平臺，延伸與拓展工程建設(shè)管理信息化的應(yīng)用范圍，實現(xiàn)通信工程建設(shè)過程的信息化管理，促進(jìn)工程項目的管理部門、建設(shè)部門、實施部門和使用部門之間業(yè)務(wù)流程協(xié)調(diào)有序地開展，實現(xiàn)工程項目設(shè)計、施工、監(jiān)理管理功能，將相關(guān)的設(shè)計、施工、監(jiān)理單位納入到工程建設(shè)管理中，完善工程項目建設(shè)過程管理體系，通過信息化推動管理的規(guī)范化，在信息化的應(yīng)用過程中不斷探索市場環(huán)境下工程建設(shè)管理的新思路和新方法。

根據(jù)工程部業(yè)務(wù)工作的實際情況，項目首先滿足工程建設(shè)管理中應(yīng)用最廣泛、問題最突出的基本需求。

項目功能需求包括：

Ø         建立工程外部協(xié)作系統(tǒng)與MSS等系統(tǒng)的接口；

Ø         建立設(shè)計協(xié)作服務(wù)、監(jiān)理協(xié)作服務(wù)、施工協(xié)作服務(wù)模塊，為郵電設(shè)計院、電話監(jiān)理公司和電信工程公司提供工程部所需的協(xié)作服務(wù)，保證工程建設(shè)實施流程的開展；

Ø         在建立工程協(xié)作服務(wù)模塊的基礎(chǔ)上，建立工程外部協(xié)作系統(tǒng)與郵電設(shè)計院、電話監(jiān)理公司、電信工程公司信息系統(tǒng)的接口，實現(xiàn)工程部與三家實施單位的信息交互與業(yè)務(wù)協(xié)作；

本技術(shù)解決方案就是針對實現(xiàn)工程建設(shè)部與三家實施單位信息交互與業(yè)務(wù)協(xié)作接口中施工單位接口的技術(shù)解決方案的組成部分。

在接口的調(diào)用過程中，存在施工系統(tǒng)調(diào)用外協(xié)系統(tǒng)接口的情況，這時候，施工系統(tǒng)作為客戶端，外協(xié)系統(tǒng)作為服務(wù)端；也存在外協(xié)系統(tǒng)調(diào)用施工系統(tǒng)的情況，這時候，外協(xié)系統(tǒng)作為客戶端，施工系統(tǒng)作為服務(wù)端。本方案中，除了特殊另外說明外，不考慮外協(xié)系統(tǒng)和施工系統(tǒng)角色換位的問題。如果一方發(fā)起了調(diào)用，那么它就是客戶端，另一方就是服務(wù)端。反之亦然。

4  接口方式

u       工程外協(xié)系統(tǒng)與施工系統(tǒng)之間的接口采用Web Service接口形式來進(jìn)行業(yè)務(wù)數(shù)據(jù)的交互。

u       接口數(shù)據(jù)傳輸采用XML數(shù)據(jù)交換格式，utf-8編碼。

u       在外協(xié)系統(tǒng)中提供Web Service的API接口。提供由施工系統(tǒng)調(diào)用獲得信息；并且提供施工系統(tǒng)提交信息的API接口。

u       同樣，在施工系統(tǒng)中提供Web Service的API接口。提供由外協(xié)系統(tǒng)提交信息的API接口。

u       考慮到工程外協(xié)中的數(shù)據(jù)信息不僅包括了XX電信工程公司的數(shù)據(jù)而且還包含了其他的施工單位的數(shù)據(jù)信息。而這些單位也各有其各自工程應(yīng)用系統(tǒng)。這樣，外協(xié)系統(tǒng)對各個施工單位系統(tǒng)所提供的接口API及其參數(shù)信息、格式均是統(tǒng)一的。同時，也要求各個施工單位所提供的接口API及其參數(shù)、格式等也必須要求統(tǒng)一。外協(xié)系統(tǒng)與施工系統(tǒng)屬于一對多的關(guān)系。

u       外協(xié)系統(tǒng)要求能夠有目的，信息有過濾的把業(yè)務(wù)信息通過接口正確的發(fā)送給相應(yīng)施工系統(tǒng)接口。非相關(guān)的信息不要發(fā)送給對應(yīng)的施工系統(tǒng)。

u       施工系統(tǒng)建立用戶映像對照表、字典對照表、單位對照表等數(shù)據(jù)映像，傳遞給外協(xié)的數(shù)據(jù)使用的是映像中轉(zhuǎn)換后的外協(xié)系統(tǒng)能夠識別數(shù)據(jù)；同時，接收到的數(shù)據(jù)也根據(jù)對照表轉(zhuǎn)換成各自能夠解釋的數(shù)據(jù)格式。

u       數(shù)據(jù)初始化的時候，由施工系統(tǒng)主動調(diào)用外協(xié)系統(tǒng)的接口，以獲得用戶信息、字典信息、單位信息、項目信息等基礎(chǔ)信息。以后，一旦發(fā)生數(shù)據(jù)的變動，由外協(xié)系統(tǒng)主動往施工系統(tǒng)發(fā)送信息。

u       外協(xié)系統(tǒng)不主動請求施工系統(tǒng)獲得數(shù)據(jù)，但是外協(xié)系統(tǒng)會主動請求施工系統(tǒng)發(fā)送數(shù)據(jù)。

u      施工系統(tǒng)主動請求外協(xié)系統(tǒng)獲得數(shù)據(jù)，也會主動請求外協(xié)系統(tǒng)發(fā)送數(shù)據(jù)。