完整的接口解決方案說明書

1、文檔編號T-JKJS文檔版本項目編號XX-DX- PECSXX電信工程外部協(xié)作系統(tǒng)Project Exterior Cooperati on System施工單位接口技術解決方案編寫人：南瘋日期：2006-10-30審核人：日期：批準人：日期：XXXXXX信息科技股份有限公司地址XXXXXXX由E編：XXXXXX電話XXXXXXXX傳真：XXXXXX網(wǎng)站XXXXXXXXX修改記錄(Revision Chart)版本號批準人修改人修改南瘋2006-10-30詳細修改記錄：丿序號1引言編寫目的覆蓋范圍預期讀者與閱讀建議 文檔約定術語與縮略語參考文獻2 概述3 接口方式4 接口安全接口認證數(shù)據(jù)安全5

2、 事務處理6 性能考慮7 容錯處理8 數(shù)據(jù)格式約定施工系統(tǒng)向外協(xié)系統(tǒng)發(fā)送請求請求查詢一個業(yè)務數(shù)據(jù)新增一條記錄，得到記錄的鍵值修改一條記錄刪除一條記錄文檔上傳一條記錄中一個文檔字段上傳多個文件補充上傳文檔在記錄中刪除一個文檔獲得文檔的基本信息獲得文檔的所有兄弟信息獲得文檔的所有父親信息下載一個文檔獲得字典夕卜協(xié)系統(tǒng)向施工系統(tǒng)發(fā)送請求發(fā)送變更后的數(shù)據(jù)發(fā)送變更后的字典文檔發(fā)送請求數(shù)據(jù)表網(wǎng)頁地址9 信息數(shù)據(jù)項1011 Web Service 接口接口命名規(guī)范輸入?yún)?shù)輸出參數(shù)外協(xié)系統(tǒng)提供的其他接口12 附錄：待定問題1引言編寫目的本文檔為XX電信工程外部協(xié)作系統(tǒng)（以下簡稱外協(xié)系統(tǒng)）與電信工程施工單位內部

3、系統(tǒng)（以 下簡稱施工系統(tǒng)）接口技術解決方案，以此作為外協(xié)系統(tǒng)與施工系統(tǒng)實施接口的技術方案依據(jù)和 項目設計標準。覆蓋范圍XX電信工程外部協(xié)作系統(tǒng)項目組施工系統(tǒng)接口開發(fā)技術組預期讀者與閱讀建議XX電信企業(yè)信息化部XX電信工程建設部XXXX公司開發(fā)人員施工系統(tǒng)開發(fā)人員文檔約定粗體正文表示強調內容紅色正文表示未完成或需要今后考慮的內容藍色正文表示待討論內容術語與縮略語術語、縮略語定義外協(xié)系統(tǒng)XX電信工程外部協(xié)作系統(tǒng)I施工系統(tǒng)電信工程施工單位內部系統(tǒng)PECSXX電信工程外部協(xié)作糸統(tǒng)英文簡稱參考文獻(XXXX)2概述建設XX電信工程外部協(xié)作系統(tǒng)的目標，是在工程項目的管理、建設、使用和實施單位之間 搭建起數(shù)

4、據(jù)交換和協(xié)同工作的信息平臺，延伸與拓展工程建設管理信息化的應用范圍，實現(xiàn)通信工程建設過程的信息化管理， 促進工程項目的管理部門、 建設部門、實施部門和使用部門之間業(yè) 務流程協(xié)調有序地開展，實現(xiàn)工程項目設計、施工、監(jiān)理管理功能，將相關的設計、施工、監(jiān)理 單位納入到工程建設管理中，完善工程項目建設過程管理體系，通過信息化推動管理的規(guī)范化， 在信息化的應用過程中不斷探索市場環(huán)境下工程建設管理的新思路和新方法。根據(jù)工程部業(yè)務工作的實際情況， 項目首先滿足工程建設管理中應用最廣泛、問題最突岀的基本項目功能需求包括：?建立工程外部協(xié)作系統(tǒng)與 MSS等系統(tǒng)的接口；?建立設計協(xié)作服務、監(jiān)理協(xié)作服務、施工協(xié)作服

5、務模塊，為郵電設計院、電話監(jiān)理公司和電 信工程公司提供工程部所需的協(xié)作服務，保證工程建設實施流程的開展；?在建立工程協(xié)作服務模塊的基礎上，建立工程外部協(xié)作系統(tǒng)與郵電設計院、電話監(jiān)理公司、 電信工程公司信息系統(tǒng)的接口，實現(xiàn)工程部與三家實施單位的信息交互與業(yè)務協(xié)作；本技術解決方案就是針對實現(xiàn)工程建設部與三家實施單位信息交互與業(yè)務協(xié)作接口中施工 單位接口的技術解決方案的組成部分。在接口的調用過程中，存在施工系統(tǒng)調用外協(xié)系統(tǒng)接口的情況，這時候，施工系統(tǒng)作為客 戶端，外協(xié)系統(tǒng)作為服務端；也存在外協(xié)系統(tǒng)調用施工系統(tǒng)的情況，這時候，外協(xié)系統(tǒng)作為客 戶端，施工系統(tǒng)作為服務端。本方案中，除了特殊另外說明外，不考

6、慮外協(xié)系統(tǒng)和施工系統(tǒng)角 色換位的問題。如果一方發(fā)起了調用，那么它就是客戶端，另一方就是服務端。反之亦然。4 接口方式u工程外協(xié)系統(tǒng)與施工系統(tǒng)之間的接口采用Web Service接口形式來進行業(yè)務數(shù)據(jù)的交互。u接口數(shù)據(jù)傳輸采用XML數(shù)據(jù)交換格式，utf-8編碼。u在外協(xié)系統(tǒng)中提供 Web Service的API接口。提供由施工系統(tǒng)調用獲得信息；并且提供施工系 統(tǒng)提交信息的API接口。u同樣，在施工系統(tǒng)中提供 Web Service的API接口。提供由外協(xié)系統(tǒng)提交信息的 API接口。 u考慮到工程外協(xié)中的數(shù)據(jù)信息不僅包括了XX電信工程公司的數(shù)據(jù)而且還包含了其他的施工單位的數(shù)據(jù)信息。而這些單位也各有

7、其各自工程應用系統(tǒng)。這樣，外協(xié)系統(tǒng)對各個施工單位 系統(tǒng)所提供的接口 API及其參數(shù)信息、格式均是統(tǒng)一的。同時，也要求各個施工單位所提 供的接口 API及其參數(shù)、格式等也必須要求統(tǒng)一。外協(xié)系統(tǒng)與施工系統(tǒng)屬于一對多的關系。u外協(xié)系統(tǒng)要求能夠有目的，信息有過濾的把業(yè)務信息通過接口正確的發(fā)送給相應施工系統(tǒng)接 口。非相關的信息不要發(fā)送給對應的施工系統(tǒng)。u施工系統(tǒng)建立用戶映像對照表、字典對照表、單位對照表等數(shù)據(jù)映像，傳遞給外協(xié)的數(shù)據(jù)使用 的是映像中轉換后的外協(xié)系統(tǒng)能夠識別數(shù)據(jù)；同時，接收到的數(shù)據(jù)也根據(jù)對照表轉換成各 自能夠解釋的數(shù)據(jù)格式。u數(shù)據(jù)初始化的時候，由施工系統(tǒng)主動調用外協(xié)系統(tǒng)的接口，以獲得用戶信息

8、、字典信息、單位 信息、項目信息等基礎信息。以后，一旦發(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ù)。4接口安全接口認證調用認證：雖然接口雙方都是存在于電信內部網(wǎng)絡中，但是，仍不能排除接口服務被攻擊、惡意調用以及非法調用等。所以，從接口調用上，必須考慮調用的認證安全問題。u本方案中的接口，在客戶端調用服務端的時候，必須經(jīng)過調用身份認證。考慮施工系統(tǒng)的開發(fā) 平臺的多樣性，但同時接口服務運行平臺都是 Windows的情況，本方案采用 Windows安全

9、 身份認證的方式。即在訪問接口所在的服務的時候，都必須進行資格審查（使用Credentials 發(fā)送認證信息）。u另外，接口采用 SOAP協(xié)議，因此在接口配置上面需要屏蔽 HTTP GET和HTTP POST等其他協(xié) 議。u在接口中審核并進行日志的記錄。u使用最低權限的進程帳戶運行 Web服務（通過 中的processModel元素來配置）。u接口不支持動態(tài)生成WSDL因此作為服務端，應該禁止文檔協(xié)議。u在服務端禁用跟蹤，禁用調式編譯業(yè)務用戶認證：由于接口涉及電信工程中的各個不同的業(yè)務，有獲取字典、獲得項目信息、發(fā)送開工報告等，所以，建立一套業(yè)務的用戶認證機制是必須的。不同的用戶，所具備有的授

10、權不一樣，所能執(zhí)行的業(yè)務也不一樣。同時，業(yè)務用戶認證中的用戶信息也是記錄接口日志中的重要組成部分。本方案采用的是在接口信息中包含業(yè)務認證用戶信息的方式來進行認證。服務端在收到請求的時候，應先驗證業(yè)務的授權用戶， 如果該業(yè)務用戶沒有執(zhí)行當前業(yè)務的權限， 應終止 業(yè)務的執(zhí)行，并給出非法用戶的警告信息反饋回客戶端。一般情況下，業(yè)務認證的用戶是系統(tǒng)中的用戶。業(yè)務認證其實就是應用系統(tǒng)認證的組成部分。業(yè)務認證的用戶信息經(jīng)過加密之后包含在要發(fā)送的信息（XML體）中，即在發(fā)送的信息中包含業(yè)務用戶的信息（參見下面的數(shù)據(jù)格式說明）。數(shù)據(jù)安全數(shù)據(jù)的安全表現(xiàn)為如何保證數(shù)據(jù)在網(wǎng)絡傳輸過程中不會被截獲并被解析其中的內容而

11、 引起信息泄露與如何保證數(shù)據(jù)在傳輸?shù)倪^程中的數(shù)據(jù)的完整性兩個方面。Web Service采用XML數(shù)據(jù)格式來傳輸信息。所以，無論是發(fā)送數(shù)據(jù)還是返回結果，都 要求采用對XML數(shù)據(jù)加密之后來傳輸。至于采用何種方式的加密技術，本方案為了保密， 只能在開發(fā)的時候由開發(fā)人員口頭告知。 涉及到加密技術就要涉及到加密的密鑰問題。目前，外協(xié)系統(tǒng)和施工系統(tǒng)接口上有很多種類型的業(yè)務，到底是每種類型的業(yè)務采用不同的密鑰， 還是按分組來采用同一種密鑰的方式，還是所有的業(yè)務全部采用同一種的密鑰的方式，按照需求各有不同的選擇。本方案采用的是最后一種的方式。密鑰的發(fā)布由作為服務方來發(fā)布， 由客戶端獲取。密鑰的發(fā)布方式待定。

12、為了保證數(shù)據(jù)的完整性，首先：方案采用數(shù)據(jù)簽名（SOAP Security Exte nsio ns: DigitalSig nature ）。利用 XML 的數(shù)字簽名（XML Digital Sig nature sy ntax XML-Sig nature）對 SOAP 進 行擴展，在SOAP的頭元素中定義簽名屬性（SOAP-SEC:Signature來實現(xiàn)。其次：限制并 驗證 Web方法輸入的類型、長度、格式和范圍，驗證對XML輸入數(shù)據(jù)的驗證是基于已協(xié)商的架構等。5事務處理事務是一組相關的任務，作為獨立于其他任務的獨立單元成功（提交）或失敗（中止）分布式事務是影響多個資源的事務。要提交分布

13、式事務，所有參與者都必須保證對數(shù)據(jù)的任何更改是永久的。不論系統(tǒng)崩潰或是發(fā)生其他無法預料的事件，更改都必須是持久的。 即使只有一個參與者無法保證這一點，整個事務也將失敗，在事務范圍內對數(shù)據(jù)的任何更改均將回滾。外協(xié)系統(tǒng)和施工系統(tǒng)是處于網(wǎng)絡之上的兩個分布式接口，使用的是分布式事務。要啟用分布式事務，可能需要通過網(wǎng)絡啟用MS DTC （考慮外協(xié)平臺和施工平臺都是運行在Windows 上），以便在使用應用了最新的 Service Pack的較新操作系統(tǒng)（例如 Windows XP 或 Windows 2003 ）時使用分布式事務。如果啟用了 Windows防火墻（Windows XP ServicePa

14、ck 2的默認設置），必須允許 MS DTC服務使用網(wǎng)絡或打開MS DTC端口。接口中的服務端和客戶端的環(huán)境事務始終相同，客戶端創(chuàng)建的事務上下文并應用對于服務端的當前的事務，以便對于該事務上下文是當前的。這樣的事務會造成性能損失，因為可能需要繼承原來的上下文，但是，這樣的事務確保了在數(shù)據(jù)庫操作的時候信息的完整性。接口中事務的發(fā)起總是由客戶端發(fā)起的，并負責事務的提交和回滾等控制。在接口設計的時候就應該考慮性能上面的問題，不要在事后再加入性能。同時，在項目的開發(fā)過程要反復進行測試，可以從機器的吞吐量和響應時間兩個基本的指標來衡量接口的 性能。接口上面的性能考慮主要從下面幾個方面來優(yōu)化：u使用一次連

15、接，多次調用，優(yōu)化連接資源。u對于并行的接口調用使用異步的調用方式。u優(yōu)化線程池減少競爭。u考慮使用XML壓縮。u如果不需要返回，考慮使用單工通訊的方式。u適當?shù)脑O置（如果有代理）代理超時，頁面超時，WebService超時。u設計"大塊頭”的接口減少往返。u基于消息的編程而不是遠程過程調用（RPC）。u使用XML字串作為參數(shù)。u盡量使用原始數(shù)據(jù)類型參數(shù)。u避免在調用之間維護服務器狀態(tài)。u考慮為復雜的WebMethod提供輸入校驗。u考慮對 WebMethod的結果使用緩存。u選擇適用的大數(shù)據(jù)包傳送方式。u避免調用本地的 WebService。7容錯處理客戶端向服務端發(fā)送數(shù)據(jù)， 服務

16、端解析數(shù)據(jù)，反饋信息給客戶端，這中間的環(huán)節(jié)只要某 一個環(huán)節(jié)出現(xiàn)問題，都會造成接口的失敗。按照失敗產(chǎn)生的環(huán)節(jié)分類，我們可以從三個方面 來處理接口的失敗。u網(wǎng)絡連接失敗：在調用接口的時候，由于網(wǎng)絡不通，造成數(shù)據(jù)不能正常傳輸。這樣，發(fā)送20次，每次時間間隔2小時。如果一直發(fā)生網(wǎng)絡不通的情況，該發(fā)送日志被保 存下來，待后手工發(fā)送。所以，客戶端系統(tǒng)應該實現(xiàn)手工發(fā)送數(shù)據(jù)的功能。u反饋錯誤信息：服務端在解析數(shù)據(jù)包，執(zhí)行數(shù)據(jù)包業(yè)務的時候，可能會發(fā)生異常。所 以，服務端應當能夠捕捉異常信息，比如非法XML格式”等，然后反饋給客戶端?？蛻舳嗽诮邮艿竭@類的錯誤信息之后，應當進行日志記錄，能夠自動或手工分析異常的信息

17、。u網(wǎng)絡連接正常，但是無信息反饋：這種情況下，一般是服務端出現(xiàn)了異常，但是又沒 有捕捉到的情況下發(fā)生。這種情況下，客戶端把這種錯誤當作 網(wǎng)絡連接失敗”來處 理。服務端應能夠實現(xiàn)相同數(shù)據(jù)包重新發(fā)送過來的處理機制。8數(shù)據(jù)格式在Web Service的調用過程中，無論是外協(xié)系統(tǒng)還是施工系統(tǒng)，都有發(fā)送數(shù)據(jù)和接收數(shù)據(jù)的要求，也即雙方系統(tǒng)同時作為客戶端又作為服務端。我們統(tǒng)稱這些傳遞的數(shù)據(jù)為報文?？蛻舳税l(fā)送報文，屬于調用；服務端接收報文，屬于被調用?？蛻舳撕头斩嘶ハ嘀g通訊的請求報文和結果報文遵循XML格式?？蛻舳税l(fā)送請求報文，服務器解析調用報文，執(zhí)行報文中所在接口對應的服務功能。生成結果報文，以xml格

18、式頁返回給請求者。請求者拿到結果報文，進行解析，然后再進行相應的處理。約定u報文中所有的字典信息（比如性別1-男，2-女），都以代碼的值（1或者2）來傳遞。施工單位向 外協(xié)系統(tǒng)發(fā)送的報文中的代碼都需要轉換成外協(xié)的代碼，外協(xié)系統(tǒng)向施工系統(tǒng)發(fā)送的報文 中的代碼無需轉換。u報文中的其他數(shù)據(jù)類型，比如貨幣、RowID,自定義對象類型等，根據(jù)需要轉換成文本、數(shù)值或二進制（最終轉換成Base64字符）的數(shù)據(jù)類型。u報文中數(shù)值信息，轉換成文本，如：vltemCou nt>50</ltemCou nt><ValueSum>v/ValueSum>u報文中數(shù)值不支持科學計數(shù)的方

19、式。報文中數(shù)值的單位使用國標的單位，比如貨幣使用元”,長度使用 米”等。無國標的單位以約定為準。u報文中的日期信息，轉換成 YYYYMMDD HHmms文本格式（24小時制）。如果是空日期，則轉 換成空文本。u報文中的true和false數(shù)據(jù)類型，轉換成 0（表示false）、1 （表示true）u報文中的二進制數(shù)據(jù)，轉換成 Base64字符方式發(fā)送。u報文中的記錄集，放在 < Records標簽中；報文中一條記錄，放在 < Records：標簽中。u報文中如果存在多條記錄， 則在vRecords：標簽中就包含多個的<Record>!簽。如果報文中僅有 一條記錄，則vR

20、ecords：標簽中只包含一個<Record>!簽.如果沒有記錄，則僅僅包含一個 vRecords：標簽,沒有 vRecord 簽。u如果返回結果數(shù)據(jù)集非常多，在性能考慮和數(shù)據(jù)量沖突的情況下，可以使用分頁返回數(shù)據(jù)集的 方式分批返回數(shù)據(jù)（每次返回最多100條記錄）。服務端提供分批結果返回的功能。至于如施工系統(tǒng)向外協(xié)系統(tǒng)發(fā)送請求施工系統(tǒng)向外協(xié)系統(tǒng)發(fā)送請求的數(shù)據(jù)目前有幾點需要考慮：u如何請求查詢一個業(yè)務數(shù)據(jù)u如何新增一條記錄，新增之后如何點到記錄的鍵值u如何修改一條記錄u如何刪除一條記錄u文檔如何上傳u 一條記錄中一個FilelD的字段如何上傳多個文件u如何在一條記錄中補充上傳文檔u如何

21、在一條記錄中刪除一個文檔u如何獲得文檔的基本信息u如何獲得文檔的所有兄弟信息u如何獲得文檔的所有父親信息u如何下載一個文檔針對這些問題，接口方案的解決方法如下：請求查詢一個業(yè)務數(shù)據(jù)施工系統(tǒng)針對外協(xié)系統(tǒng)發(fā)送的業(yè)務數(shù)據(jù)查詢請求根據(jù)業(yè)務類型有很多種。為了簡化接口，而不是在接口上進行業(yè)務操作，所以，外協(xié)系統(tǒng)將施工系統(tǒng)發(fā)起的數(shù)據(jù)查詢請求看作是數(shù)據(jù)下載的一種方式，而不為了復雜的業(yè)務查詢請求提供復雜的條件解析。外協(xié)系統(tǒng)提供的數(shù)據(jù)查詢接口是從數(shù)據(jù)下載和數(shù)據(jù)延期性來考慮的。為了滿足數(shù)據(jù)的下載，外協(xié)系統(tǒng)提供了按照某一個表的主鍵來下載數(shù)據(jù)和按照記錄的變更時間范圍來下載數(shù)據(jù)的兩種方式查詢 請求。請求報文：<xm

22、l version="" encoding="utf-8" > <XmlData>vUserl nfo><User>Zha ngSanv/ User><PassWord>123456</ PassWord></ Userl nfo>vDescription ><RowID>0</ RowID><KeyValue>123</ KeyValue>vQueryBegi nTime> 153000</QueryBegi

23、nTime >vQueryE ndTime> 153000</ QueryE ndTime></ Descripti on></XmlData>響應報文:<xml versi on="” en cod in g="utf-8" ><XmlData>vDescription >vRowlD>100</ RowlD></ Descripti on><Records><Record>vFieldl >Value1</ Field

24、l ><Field2>Value2</ Field2><Field3>Value3</ Field3><Field4>Value4</ Field4></ Record><Record><Field1 >Value1</ Field1 ><Field2>Value2</ Field2><Field3>Value3</ Field3><Field4>Value4</ Field4></ Reco

25、rd><Record><Field1 >Value1</ Field1 ><Field2>Value2</ Field2><Field3>Value3</ Field3><Field4>Value4</ Field4></ Record></ Records></XmlData>報文說明：1標簽名說明<XmlData>:報文數(shù)據(jù)主體<Descripti on>報文頭部信息<Records>記錄集合<Rec

26、ord>一行記錄<UserInfo>業(yè)務認證的用戶信息<User>業(yè)務用戶登錄名<PassWord>業(yè)務用戶驗證口令<RowID>第一次請求的時候，客戶端 RowID發(fā)送0,表示從第0條記錄開發(fā)返 回。服務端根據(jù)條件查詢，發(fā)現(xiàn)結果超過 100條記錄，則在返回的結果中， RowID的值為99,表示服務端當前的記錄位置處在第 100條的位置上，后 面還會有剩余的記錄?？蛻舳藱z查返回的結果，如果發(fā)現(xiàn)RowID大于0,則繼續(xù)發(fā)送請求進行查詢。但是，客戶端第二次發(fā)送請求繼續(xù)查詢的時候， RowID的值要賦值為第一次返回的值，即RowID=99o服務端

27、第二次收到請求的時候，發(fā)現(xiàn)RowID是99,則從第100條返回結果。以此類推循環(huán)調用， 直到服務端達到記錄的末尾，這時候，服務端在返回的結果中RowID=0.客戶端發(fā)現(xiàn)服務端 RowlD=0,終止循環(huán)調用。字典、用戶信息、單位信息，因為返回的字段比較少，不受100條記錄返回的限制。一次調用，就返回全部的結果。<KeyValue>查詢時主鍵的值。這個KeyValue和下面的 vQueryBeginTimexQueryEndTime是互斥的。如果在請求的時候提供了主 鍵的值，表示客戶端要求服務器按照主鍵的值查詢一條記錄。如果客戶端 提供了主鍵的值，則服務端將忽略vQueryBeginT

28、imexQueryEndTime中的 值。字典、用戶信息、單位信息，因為沒有查詢時間范圍，所以KeyValue 即表示字典類型。vQueryBeg in Time vQueryE ndTime>查詢時時間段范圍。vQueryBeginTime是起始時間，vQueryEndTime 是結束時間。表示客戶端要求服務端查詢在這個時間范圍之內所有變更過 的記錄（包括新增、修改、刪除）。在外協(xié)中，一條記錄新增的時候，它的創(chuàng)建時間和最后修改時間是一 樣的，以后修改記錄的時候，創(chuàng)建時間不變，改變的僅僅是最后修改時間。 同時，外協(xié)系統(tǒng)中刪除記錄僅僅在 記錄是否刪除”字段中標記“ 1,并不是 真正的物理刪

29、除記錄。這里的時間指的是記錄變更的時間，不是記錄中的某個業(yè)務時間。 如果用戶需要按照業(yè)務時間來查詢數(shù)據(jù)，則施工系統(tǒng)把外協(xié)系統(tǒng)的數(shù)據(jù)獲取 到本地進行保存，在施工系統(tǒng)中提供按照業(yè)務時間查詢的功能。vQueryBeginTimexQueryEndTime和心28山&是互斥的。如果客戶 端需要按照時間范圍來查詢，則必須 KeyValue空。<Field1><Field2><Field3><Field4>一行記錄中的英文字段名稱。實際中，這些標簽都是字典的英文名。字段 的標簽全部是大寫。具體的字段名稱請參見提供的數(shù)據(jù)模型新增一條記錄，得到記錄的鍵值

30、為了簡化數(shù)據(jù)模型的處理，本方案不考慮主從表的并發(fā)處理情況。如果存在主從表的數(shù)據(jù)需要上 傳，那么，在一個事務中，施工單位首先先上傳主表的記錄， 從反饋信息中獲得主表的主鍵值。 然后， 把剛剛獲得的主表的主鍵值賦值給從表的對應外鍵，再上傳從表數(shù)據(jù)，得到從表的主鍵值。如果不是主從表，而是單表，則直接上傳數(shù)據(jù)，從反饋信息中得到主鍵值。這種情況的優(yōu)點是：數(shù)據(jù)和表相關，施工單位可以靈活的控制表之間的關系；同時，數(shù)據(jù)包中的報文比較簡單，容易解析；接口上面比較清晰，與業(yè)務的耦合比較低。缺點是：一個業(yè)務涉及的主從表不能在同一個報文中（這個缺點可以通過施工系統(tǒng)靈活的控制表之間關系來解決）；一個業(yè)務中可能會使用到兩

31、個或兩個以上的接口，造成業(yè)務完整性上面的分離（這種缺點可以通過把業(yè)務放在一個事務中來解決）；鍵值的返回：在調用新增接口之后，外協(xié)會按照記錄的 順序返回外外協(xié)中所生成的鍵值。施工單位獲得鍵值之后，可以在本地表中更新記錄的主鍵值。請求報文:<xml versi on="” en cod in g="utf-8" ><XmlData>vUserl nfo><User>Zha ngSan</ User><PassWord>123456</ PassWord></ UserI nfo>

32、<Description ><Note>開工報告 </Note></Descripti on><Records><Record><KeyField></KeyField><NormalField1 >Value1</NormalField1 ><NormalField2 >Value2</ NormalField2 ><NormalField3 >Value3</ NormalField3 ><NormalField4 &

33、gt;Value4</ NormalField4 ></ Record><Record><KeyField></KeyField><NormalField1 >Value1</NormalField1 ><NormalField2 >Value2</ NormalField2 ><NormalField3 >Value3</ NormalField3 ><NormalField4 >Value4</ NormalField4 ></

34、Record></ Records></XmlData>響應報文：<xml versi on="” en cod in g="utf-8" ><XmlData><Description ><Result>成功</Result> <!-如果失敗，貝0 <Result>里面內容是：失?。海ㄥe誤原因）-></ Descripti on><Records><Record><KeyField>Value1</

35、 KeyField></ Record><Record><KeyField>Value2</ KeyField></ Record></ Records></XmlData>報文說明:標簽名說明<XmlData>報文數(shù)據(jù)主體vDescripti on>報文頭部信息<Records>記錄集合<Record>一行記錄<UserInfo>業(yè)務認證的用戶信息<User>業(yè)務用戶登錄名<PassWord>業(yè)務用戶驗證口令<Note&

36、gt;業(yè)務的簡單描述。比如：開工報告、施工組織方案等請求中的<KeyField>一行記錄中的主鍵字段。在新增的時候，施工系統(tǒng)所給的主鍵字段內容為 空。外協(xié)系統(tǒng)中根據(jù)主鍵字段內容為空，認為這是一條新增的記錄響應中的<KeyField>一行記錄中的主鍵字段。外協(xié)系統(tǒng)返回的主鍵值。這里的主鍵值和施工系 統(tǒng)發(fā)送的記錄的順序是一一對應的。<Result>反饋報文中的保存成功與否信息。如果保存成功，則信息是成功”如果保存失敗，則信息是 失?。海ê竺媸清e誤的詳細信息）”修改一條記錄施工系統(tǒng)在修改了一條記錄的時候，上傳的報文中與新增的報文類似，只是主鍵的信息不能為空。 外協(xié)

37、系統(tǒng)判斷主鍵的信息，如果發(fā)現(xiàn)主鍵的信息不為空，則認為是修改了一條記錄。如果施工系統(tǒng)報 文中主鍵不為空，而外協(xié)系統(tǒng)在數(shù)據(jù)庫對應的表中又沒有發(fā)現(xiàn)對應的記錄，則自動轉換成新增的方式來處理這條記錄。外協(xié)系統(tǒng)在反饋中，還是會把主鍵返回給施工系統(tǒng)。但是，這種情況下，施工系統(tǒng)可能不再需要 維護這個主鍵。即使是僅僅修改了一個字段，施工單位還得需要上傳全部的字段信息（包含被修改的字段）給外 協(xié)系統(tǒng)。施工系統(tǒng)不是對記錄做物理刪除，而僅僅是作了邏輯刪除，即僅僅在記錄的刪除標志位上面做了“1的標志。這種情況對記錄來說，也是修改的范圍。只是需要在<Note>業(yè)務的簡單描述中說明 邏輯刪除”即使是邏輯刪除記錄

38、，施工系統(tǒng)也必須上傳全部的字段到外協(xié)系統(tǒng)。請求報文：<xml versi on=" en cod in g="utf-8" ><XmlData>vUserl nfo><User>Zha ngSanv/ User><PassWord>123456</ PassWord></ Userl nfo>vDescription ><Note>停工通知確認</Note></ Descripti on><Records><Record&

39、gt;<KeyField>KeyValue1</ KeyField><NormalField1 >Value1</NormalField1 ><NormalField2 >Value2</NormalField2 ><NormalField3 >Value3</NormalField3 ><NormalField4 >Value4</NormalField4 ></ Record><Record><KeyField >KeyValue2&l

40、t;/ KeyField><NormalField1 >Value1</NormalField1 ><NormalField2 >Value2</ NormalField2 ><NormalField3 >Value3</ NormalField3 ><NormalField4 >Value4</ NormalField4 ></ Record></ Records></XmlData>響應報文:標簽名說明報文說明：標簽名說明<xml versi on

41、="” en cod in g="utf-8" ><XmlData><Description ><Result>成功</Result> <!-如果失敗，貝0 <Result>里面內容是：失敗：（錯誤原因）-></ Descripti on><Records><Record><KeyField>Value1</ KeyField></ Record><Record><KeyField>Value

42、2</ KeyField></ Record></ Records></XmlData><XmlData>報文數(shù)據(jù)主體vDescripti on>報文頭部信息<Records>記錄集合<Record>一行記錄<UserInfo>業(yè)務認證的用戶信息<User>業(yè)務用戶登錄名<PassWord>業(yè)務用戶驗證口令<Note>業(yè)務的簡單描述。比如：開工報告、施工組織方案等請求中的<KeyField>一行記錄中的主鍵字段。在修改的時候，施工系統(tǒng)所給的主鍵字

43、段內容不 能為空。外協(xié)系統(tǒng)中根據(jù)主鍵字段內容不為空，認為這是一條修改的記錄響應中的<KeyField>一行記錄中的主鍵字段。外協(xié)系統(tǒng)返回的主鍵值。這里的主鍵值和施工系 統(tǒng)發(fā)送的記錄的順序是一一對應的。<Result>反饋報文中的保存成功與否信息。如果保存成功，則信息是成功”如果保存失敗，則信息是 失敗：（后面是錯誤的詳細信息）”<NormalField >一行記錄中的英文字段名稱。實際中，這些標簽都是字典的英文名。字段 的標簽全部是大寫。具體的字段名稱請參見提供的數(shù)據(jù)模型刪除一條記錄這里的刪除指的是物理刪除。邏輯刪除在記錄修改的時候已經(jīng)說明。物理刪除是徹底的

44、從數(shù)據(jù)庫中刪除一條記錄，不能恢復。物理刪除的時候，施工系統(tǒng)只要在報文 中提供主鍵的信息提交，就能夠實現(xiàn)。同樣的，夕卜協(xié)系統(tǒng)在反饋的報文中返回成功刪除主鍵的信息，如果其中一條記錄不能正常物理刪除，則外協(xié)自動回滾所有刪除的操作。即一條記錄不能刪除，則所有的記錄都不能刪除請求報文：<xml version="” encoding="utf-8" ><XmlData><UserI nfo><User>Zha ngSar</ User><PassWord>123456</PassWord>&

45、lt;/UserI nfo><Descripti on><Note>物理刪除 </Note></Descripti on><Records><Record><KeyField>Value1</KeyField></ Record<Record>vKeyField>Value2v/KeyField> </ Record></Records></XmlData>響應報文：<xml version="” encodin

46、g="utf-8"><XmlData>vDescripti on><Result>成功</Result> <!-如果失敗，則<Result>里面內容是：失?。海ㄥe誤原因），同時，KeyFi eld的值為空->v/Descripti on><Records><Record><KeyField>Value1</KeyField></ Record><Record><KeyField>Value2</KeyFiel

47、d></ Record></Records></XmlData>報文說明：（參見數(shù)據(jù)修改說明）文檔上傳外協(xié)系統(tǒng)中，文檔的信息是保存在另外的一個表中當中的，所以，許多的業(yè)務表，往往存在一個FilelD的主鍵關聯(lián)到文檔表。在業(yè)務表中檔，可能有一個FilelD的字段，也可能會有兩個或兩個以上的FilelD字段關聯(lián)到文檔信息表。涉及到文檔的地方，往往文檔的信息會比較大，所以，文檔的信息不能包含在基礎業(yè)務數(shù)據(jù)的報文當中一起上傳。處理的方法是：先上傳文檔的實體，從反饋的信息當中得到生成的文檔ID（FilelD），然后，施工系統(tǒng)在本地記錄中的相應字段賦值文檔的ID，

48、最后再上傳基本業(yè)務信息。如果一條記錄中包含有兩個或兩個以上的文檔字段，則施工系統(tǒng)必須依次上傳文檔獲得文檔ID之后，賦值，再上傳基本業(yè)務信息。一個文檔報文當中，只能上傳一個文檔。文檔報文如下：<User>Zha ngSar</ User><PassWorc>123456v/PassWorc></UserI nfo>vDescripti on>v/Descripti on><Records><Record><ID>v/ID><FILE_PRJD123456</FILE_PRJ_I

49、DvFILE TYPE401v/FILE TYPE<FILE NAME施工組織方案.DO«/FILE NAME<FILE UNIT>電信工程公司 </FILE UNIT<FILE MAN>張三 </FILE MAN><FILE CREATE TIME153005</FILE CREATE TIME<FILE AUTHO>張三 </FILE AUTHOR<FILE TITLE項目 XXX施工組織方案 </FILE TITLE<KeepMutiFile>1 v/KeepMutiFile

50、><FileData>/e5asfdfgafa#sdgsdg </-FileData></ Record></Records></XmlData>響應報文:<xml version="” encoding="utf-8"><XmlData>vDescripti on><Result>成功</Result><!-如果失敗，則返回信息是失?。海ㄥe誤信息）”->v/Descripti on><Records><Rec

51、ord><ID>123456</ID></ Record></Records></XmlData>報文說明:標簽名說明<XmlData>報文數(shù)據(jù)主體vDescripti on>報文頭部信息<Records>記錄集合<Record>一行記錄<Jserlnfo>業(yè)務認證的用戶信息<User>業(yè)務用戶登錄名<PassWord>業(yè)務用戶驗證口令<ID>文檔的ID,在新增上傳一個文檔的時候，這個ID永遠都是空的。外協(xié)系統(tǒng)根據(jù)這個文件ID是否為空來判斷

52、是否是新的文件。<FILE_PRJ_ID文檔所屬的項目ID,對于工程協(xié)作系統(tǒng)來說，一個文檔永遠都是會屬于某 個項目的。這個項目ID可以是一級項目，也可以是三級項目。<FILE_TYPE文件類型。標識文件的歸類。比如：D401施工組織設計=401D402施工項目計劃進度 =402D403施工日報=403<FILE TYPE里面的值是代碼，文件類型的代碼可以從字典接口中獲得。<FILE_NAME>文檔的文件名稱，帶有擴展名。<FILE_UNP>文件創(chuàng)建單位，中文名<FILE_MAN>文檔創(chuàng)建人（上傳人）<FILE_CREATE_TIME文

53、檔創(chuàng)建時間<FILE_AUTHOR文檔作者（可為空）<FILE_TITLE文檔標題（可為空）<KeepMutiFile >是否允許多個文檔同時有效。 這個標簽的值為1或0。當值為1的時候， 則在同樣的項目ID、同樣的文件類型中，同時可以存在多個的文檔同時有 效存在。這種情況下，多個文檔之間是兄弟之間的關系，當前的文檔是弟 弟，以前的文檔是兄長。當這個值為 0的時候，則在同樣的項目ID、同樣 的文件類型中，只有最后上傳的文檔有效，后面上傳的文檔會把前面的文 檔 擠”到歷史中，成為當前文檔的父親”這種情況下，當前的文檔和以前上傳的文檔之間是父子的關系。更詳細的解釋請參見后面

54、的一條記錄中一個FilelD的字段如何上傳多個文件”主題相關內容。<FileData>文件實體內容。文件實體內容用二進制讀取岀來之后，然后轉換成base64 的格式。<Result>反饋報文中的保存成功與否信息。如果保存成功，則信息是成功”如果保存失敗，則信息是 失?。海ê竺媸清e誤的詳細信息）”一條記錄中一個文檔字段上傳多個文件外協(xié)系統(tǒng)中，文檔是以一種有關系”的方式來存儲的。假設有這樣一個業(yè)務表Tablel，里面有一個文檔的外鍵字段File_ID。當我們往Tablel表里面插入一條記錄的時候，針對這一條記錄，我們希望 在File_ID字段中可以帶有多個的文檔，也即會有多

55、個的File_ID。當然，我們可以把這個表字段的數(shù)據(jù)模型這個定義：FilelD, File2_ID,File3_ID廠需要多少個文件，我們就定義幾個的File_ID字段。但是這樣就會帶來問題了，如果你定義了5個的File_ID字段，但是，用戶如果想在一條記錄中上傳6個文檔，那么，這樣的數(shù)據(jù)模型就會滿足不了用戶的要求。還有一種情況，如果用戶僅僅上傳了2個文檔，那么剩下的3個 File_ID字段就會白白空著。甚至用戶對這條記錄沒有上傳文件，這樣定義的數(shù)據(jù)模型就白白浪費了數(shù)據(jù)庫的資源。還有一種說法，我可以用記錄的形式來表示啊。對的。上傳多個文件，是可以在Tablel中新增多條記錄方式來表示。但是，我

56、們的前提是，Tablel是一個業(yè)務表，里面的一條記錄就是一筆業(yè)務。如果你產(chǎn)生了多條記錄，那么意味這這樣的業(yè)務進行了多次。顯然違背了業(yè)務數(shù)據(jù)保存的初衷。夕卜協(xié)系統(tǒng)弓I入了 父子”兄弟”的文檔保存機制，即在文檔信息表（Files表）中保存文檔的基本信息 和他們之間的關系。在同樣的項目ID、同樣的文件類型中，如果可以存在多個的文檔同時有效存在， 這種情況下，多個文檔之間是兄弟之間的關系。后來者文檔是弟弟，先到的文檔是兄長。在同樣的項 目ID、同樣的文件類型中，只有最后上傳的文檔有效，后面上傳的文檔會把前面的文檔 擠”到歷史中，成為當前文檔的父親”這種情況下，后來的文檔和以前上傳的文檔之間是父子的關系

57、。如果文檔之間是兄弟關系的話，則僅僅在業(yè)務表Tablel中保存最小兄弟的File_ID；如果文檔之間是父子關系的話，則僅僅保存最小輩分的文檔File_IDo兄弟和父子的文檔保存方式其實都是多個文檔串聯(lián)的一種保存方式，但是，還是會有使用上面的區(qū)別的。兄弟關系一般使用在文檔之間是平級的情況下。比如施工組織方案，可以有多個文件，但是，這多個文件是互為補充的一部分，互相依賴，又缺一不可。這種情況下，施工系統(tǒng)可以把這類型的文 件上傳給外協(xié)系統(tǒng)，以兄弟的方式保存，施工系統(tǒng)僅僅在業(yè)務表當中保存最后上傳反饋回來的FilelD即可。以后，可以使用這個最小兄弟的File_ID，向外協(xié)系統(tǒng)請求以獲得他的所有兄長文檔

58、。父子的關系一般使用在下面的情景：當僅允許一個文檔是最終有效的時候，或者一個文檔修改之后再上傳到外 協(xié)系統(tǒng)，我們想把最后上傳的文檔覆蓋”前面的文檔，但是，又想保留文檔歷史修改痕跡的時候，一般就會用到父子關系。父子關系中，施工系統(tǒng)僅僅需要保留最小輩分的文檔信息，以后，可以使用這個最小輩分 的File_ID，向外協(xié)系統(tǒng)請求以獲得他的所有歷史文檔。補充上傳文檔根據(jù)前面的兄弟和父子關系的說明， 一條記錄中補充上傳文檔的方式就簡單了許多。只要施工系統(tǒng)上傳了文檔，獲得最后的文檔 ID，然后，在施工系統(tǒng)中維護最后的文檔ID，再用修改記錄的報文上報更新后的業(yè)務數(shù)據(jù)即可。流程：上傳補充的文檔 a獲得最后的文檔i

59、d a用最后的文檔id更新業(yè)務數(shù)據(jù) a上傳修改后的業(yè)務數(shù) 據(jù)。在記錄中刪除一個文檔向外協(xié)系統(tǒng)請求刪除一個文檔，只需要向外協(xié)系統(tǒng)提交包含有要刪除的文檔id即可。如果需要刪除的是文檔鏈當中的某一個文檔，則需要向外協(xié)請求獲得文檔鏈的信息（參見后面的 如何獲取文檔信息”，然后，從鏈中找到要刪除的文檔id，向外協(xié)系統(tǒng)提交。外協(xié)系統(tǒng)在刪除文檔的同時，會自動把鏈連接起來成為一個完整的鏈關系，同時，總是返回鏈的最末尾的文檔IDo施工系統(tǒng)獲得鏈末尾的最后文檔ID之后，更新業(yè)務表中的相應記錄，再用修改的報文上報修改后的業(yè)務數(shù) 據(jù)（此步驟不要忘記）。vDescription ></ Descripti

60、on><Records><ID>123456v/ID></ Records></XmlData>響應報文：<xml versi on="” en cod in g="utf-8" ><XmlData><Description ><Result>成功</ Result><!-如果失敗，則返回信息是 失敗：（錯誤信息）”-></ Descripti on><Records><Record><ID&

61、gt;456789v/ID><!-這個是鏈當中的最后一個文檔ID,如果鏈已經(jīng)不存在，返回-1 -></ Record</ Records></XmlData>報文說明:標簽名說明<XmlData>報文數(shù)據(jù)主體<Descripti on>報文頭部信息<Records>記錄集合<Record>一行記錄<UserInfo>業(yè)務認證的用戶信息<User>業(yè)務用戶登錄名<PassWord>業(yè)務用戶驗證口令<Result>反饋報文中的保存成功與否信息。如果文檔刪除

62、成功，則信息是 成功”如果文檔刪除失敗，則信息是失?。海ê竺媸清e誤的詳細信息）”請求報文中<ID>文檔的ID。要刪除的文檔ID反饋報文中<ID>文檔的ID。當刪除鏈中的一個文檔之后，外協(xié)系統(tǒng)自動維護鏈之間的關系， 并返回鏈末尾最后一個文檔的ID獲得文檔的基本信息施工系統(tǒng)根據(jù)文檔的ID向外協(xié)系統(tǒng)請求獲得文檔的基本信息。外協(xié)系統(tǒng)返回滿足結果的文檔基 本信息。施工系統(tǒng)可以請求一個文檔的基本信息，也可以請求多個（最多100個）文檔的信息。這個接口不考慮文檔鏈的情況，僅僅是按指定文檔ID返回結果請求報文：vxml version="” encoding="utf-8&quo