完整的接口解決具體實施方案說明書

1、個人收集整理-僅供參考31 / 29文檔編號：T-JKJS文檔版本：0.01項目編號：XX-DX- PECSXX電信工程外部協(xié)作系統(tǒng)Project Exterior Cooperation System施工單位接口技術(shù)解決方案編寫人：南瘋?cè)掌冢?006-10-30審核人：日期：批準人：日期：XXXXX福息科技股份有限公司地址：XXXXXXX郵編：XXXXXX電話：XXXXXXXX傳真：XXXXXX網(wǎng)站：XXXXXXXXX修改記錄(Revision Chart )版本號批準人修改人1修10.01南瘋2006-10-300.02詳細修改記錄：1.1 編寫目地1.2 覆蓋范圍1.3 預(yù)期讀者與閱讀建

2、議1.4 文檔約定1.5 術(shù)語與縮略語1.6 參考文獻2 概述3 接口方式接口認證數(shù)據(jù)安全4 接口安全5事務(wù)處理6性能考慮7容錯處理8數(shù)據(jù)格式約定8.2施工系統(tǒng)向外協(xié)系統(tǒng)發(fā)送請求8.2.1請求查詢一個業(yè)務(wù)數(shù)據(jù)8.2.2新tA條記錄，得到記錄地鍵值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外協(xié)系統(tǒng)向施工系統(tǒng)發(fā)送請求8.3

3、.1 發(fā)送變更后地數(shù)據(jù)8.3.2 發(fā)送變更后地字典8.3.3 文檔發(fā)送請求9 信息數(shù)據(jù)項9.1 數(shù)據(jù)表9.2 字段信息9.3 字典類型10 網(wǎng)頁地址11 Web Service 接口11.1 接口命名規(guī)范11.2 輸入?yún)?shù)11.3 輸出參數(shù)11.4 外協(xié)系統(tǒng)提供地其他接口12 附錄：待定問題1引言12.1 寫目地本文檔為XX電信工程外部協(xié)作系統(tǒng)（以下簡稱外協(xié)系統(tǒng)）與電信工程施工單位內(nèi)部系統(tǒng)（以下簡稱施工系統(tǒng)）接口技術(shù)解決方案，以此作為外協(xié)系統(tǒng)與施工系統(tǒng)實施接口地技術(shù)方案依據(jù)和項 目設(shè)計標準.b5E2R12.2 蓋范圍XX電信工程外部協(xié)作系統(tǒng)項目組施工系統(tǒng)接口開發(fā)技術(shù)組12.3 期讀者與閱讀建議

4、XX電信企業(yè)信息化部XX 電信工程建設(shè)部XXXX公司開發(fā)人員施工系統(tǒng)開發(fā)人員12.4 檔約定粗體正文表示強調(diào)內(nèi)容紅色正文表示未完成或需要今后考慮地內(nèi)容藍色正文表示待討論內(nèi)容12.5 語與縮略語術(shù)語、縮略語定義外協(xié)系統(tǒng)XX電信工程外部協(xié)作系統(tǒng)I施工系統(tǒng)電信工程施工單位內(nèi)部系統(tǒng)PECSXX電信工程外部協(xié)作系統(tǒng)英文簡稱12.6 考文獻(XXXX)2概述建設(shè)XX電信工程外部協(xié)作系統(tǒng)地目標， 是在工程項目地管理、建設(shè)、使用和實施單位之間搭 建起數(shù)據(jù)交換和協(xié)同工作地信息平臺， 延伸與拓展工程建設(shè)管理信息化地應(yīng)用范圍，實現(xiàn)通信工程建設(shè)過程地信息化管理， 促進工程項目地管理部門、 建設(shè)部門、實施部門和使用部門

5、之間業(yè)務(wù) 流程協(xié)調(diào)有序地開展，實現(xiàn)工程項目設(shè)計、施工、監(jiān)理管理功能，將相關(guān)地設(shè)計、施工、監(jiān)理單 位納入到工程建設(shè)管理中， 完善工程項目建設(shè)過程管理體系， 通過信息化推動管理地規(guī)范化， 在 信息化地應(yīng)用過程中不斷探索市場環(huán)境下工程建設(shè)管理地新思路和新方法.plEan。根據(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è)實施流程地開展；DXDiT。在建立工程協(xié)作服務(wù)模塊地基礎(chǔ)

6、上，建立工程外部協(xié)作系統(tǒng)與郵電設(shè)計院、電話監(jiān)理公司、電信工程公司信息系統(tǒng)地接口，實現(xiàn)工程部與三家實施單位地信息交互與業(yè)務(wù)協(xié)作；RTCr本技術(shù)解決方案就是針對實現(xiàn)工程建設(shè)部與三家實施單位信息交互與業(yè)務(wù)協(xié)作接口中施工單位接口地技術(shù)解決方案地組成部分.5PCzV在接口地調(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ù)端.反之亦然.jLBHr4 接

7、口方式工程外協(xié)系統(tǒng)與施工系統(tǒng)之間地接口采用Web Service接口形式來進行業(yè)務(wù)數(shù)據(jù)地交互.接口數(shù)據(jù)傳輸采用XML數(shù)據(jù)交換格式，utf-8編碼.在外協(xié)系統(tǒng)中提供 Web Service地API接口 .提供由施工系統(tǒng)調(diào)用獲得信息；并且提供施工系統(tǒng)提交信息地API接口 . xHAQX同樣，在施工系統(tǒng)中提供 Web Service地API接口.提供由外協(xié)系統(tǒng)提交信息地 API接口.考慮到工程外協(xié)中地數(shù)據(jù)信息不僅包括了XX電信工程公司地數(shù)據(jù)而且還包含了其他地施工單位地數(shù)據(jù)信息.而這些單位也各有其各自工程應(yīng)用系統(tǒng).這樣，外協(xié)系統(tǒng)對各個施工單位系 統(tǒng)所提供地接口 API及其參數(shù)信息、格式均是統(tǒng)一地.同時

8、，也要求各個施工單位所提供地 接口 API及其參數(shù)、格式等也必須要求統(tǒng)一.外協(xié)系統(tǒng)與施工系統(tǒng)屬于一對多地關(guān)系.LDAYt外協(xié)系統(tǒng)要求能夠有目地，信息有過濾地把業(yè)務(wù)信息通過接口正確地發(fā)送給相應(yīng)施工系統(tǒng)接口 非相關(guān)地信息不要發(fā)送給對應(yīng)地施工系統(tǒng) .Zzz6Z。施工系統(tǒng)建立用戶映像對照表、字典對照表、單位對照表等數(shù)據(jù)映像，傳遞給外協(xié)地數(shù)據(jù)使用 地是映像中轉(zhuǎn)換后地外協(xié)系統(tǒng)能夠識別數(shù)據(jù)；同時，接收到地數(shù)據(jù)也根據(jù)對照表轉(zhuǎn)換成各 自能夠解釋地數(shù)據(jù)格式.dvzfv。數(shù)據(jù)初始化地時候，由施工系統(tǒng)主動調(diào)用外協(xié)系統(tǒng)地接口，以獲得用戶信息、字典信息、單位信息、項目信息等基礎(chǔ)信息.以后，一旦發(fā)生數(shù)據(jù)地變動，由外協(xié)系統(tǒng)主

9、動往施工系統(tǒng)發(fā)送 信息.rqyn1。外協(xié)系統(tǒng)不主動請求施工系統(tǒng)獲得數(shù)據(jù)，但是外協(xié)系統(tǒng)會主動請求施工系統(tǒng)發(fā)送數(shù)據(jù)施工系統(tǒng)主動請求外協(xié)系統(tǒng)獲得數(shù)據(jù)，也會主動請求外協(xié)系統(tǒng)發(fā)送數(shù)據(jù)4接口安全4.1 接口認證調(diào)用認證：雖然接口雙方都是存在于電信內(nèi)部網(wǎng)絡(luò)中，但是，仍不能排除接口服務(wù)被攻擊、 惡意調(diào)用以及非法調(diào)用等.所以，從接口調(diào)用上，必須考慮調(diào)用地認證安全問題.Emxv%本方案中地接口，在客戶端調(diào)用服務(wù)端地時候，必須經(jīng)過調(diào)用身份認證.考慮施工系統(tǒng)地開發(fā)平臺地多樣性，但同時接口服務(wù)運行平臺都是Windows地情況，本方案采用 Windows安全身份認證地方式.即在訪問接口所在地服務(wù)地時候，都必須進行資格審查

10、（使用Credentials 發(fā)送認證信息）.SixE2。另外，接口采用SOA刖議，因此在接口配置上面需要屏蔽HTTP GET和HTTP POS售其他協(xié)議.6ewMy在接口中審核并進行日志地記錄.使用最低權(quán)限地進程帳戶運行 Web服務(wù)（通過Machine.config 中地 元素 來配置）.kavU4接口不支持動態(tài)生成WSDL因此作為服務(wù)端，應(yīng)該禁止文檔協(xié)議.在服務(wù)端禁用跟蹤，禁用調(diào)式編譯業(yè)務(wù)用戶認證：由于接口涉及電信工程中地各個不同地業(yè)務(wù)，有獲取字典、獲得項目信息、發(fā)送開工報告等，所以，建立一套業(yè)務(wù)地用戶認證機制是必須地.不同地用戶，所具備有地授權(quán)不一樣，所能執(zhí)行地業(yè)務(wù)也不一樣.同時，業(yè)務(wù)用

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

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

13、sQsAE為了保證數(shù)據(jù)地完整性， 首先：方案采用數(shù)據(jù)簽名（SOAPSecurity Extensions: Digital Signature ）.利用 XMLM數(shù)字簽名（XML Digital Signature syntax XML-Signature ）對 SOARS行擴展，在 SOAFM頭元素中定義簽名屬性（ ）來實現(xiàn).其次： 限制并驗證Web方法輸入地類型、長度、格式和范圍，驗證對XML輸入數(shù)據(jù)地驗證是基于 已協(xié)商地架構(gòu)等.GMsIa5事務(wù)處理事務(wù)是一組相關(guān)地任務(wù)，作為獨立于其他任務(wù)地獨立單元成功（提交）或失?。ㄖ兄梗? 分布式事務(wù)是影響多個資源地事務(wù).要提交分布式事務(wù)，所有參與者都

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

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

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

17、反饋信息給客戶端，這中間地環(huán)節(jié)只要某一個環(huán)節(jié)出現(xiàn)問題，都會造成接口地失敗.按照失敗產(chǎn)生地環(huán)節(jié)分類，我們可以從三個方面來處理接口地失敗.NrpoJ。網(wǎng)絡(luò)連接失?。涸谡{(diào)用接口地時候，由于網(wǎng)絡(luò)不通，造成數(shù)據(jù)不能正常傳輸.這樣，客戶端應(yīng)該能夠記錄發(fā)送地日志，按照一定地時間間隔重試發(fā)送.本方案定為重試發(fā)送20次，每次時間間隔2小時.如果一直發(fā)生網(wǎng)絡(luò)不通地情況，該發(fā)送日志被保存下來，待后手工發(fā)送.所以，客戶端系統(tǒng)應(yīng)該實現(xiàn)手工發(fā)送數(shù)據(jù)地功能.1nowf。反饋錯誤信息：服務(wù)端在解析數(shù)據(jù)包，執(zhí)行數(shù)據(jù)包業(yè)務(wù)地時候，可能會發(fā)生異常.所以，服務(wù)端應(yīng)當能夠捕捉異常信息，比如“非法XML格式”等，然后反饋2客戶端.客戶端

18、在接受到這類地錯誤信息之后，應(yīng)當進行日志記錄，能夠自動或手工分析異常地信息.fjnFL。網(wǎng)絡(luò)連接正常，但是無信息反饋：這種情況下，一般是服務(wù)端出現(xiàn)了異常，但是又沒 有捕捉到地情況下發(fā)生.這種情況下，客戶端把這種錯誤當作“網(wǎng)絡(luò)連接失敗”來 處理.服務(wù)端應(yīng)能夠?qū)崿F(xiàn)相同數(shù)據(jù)包重新發(fā)送過來地處理機制.tfnNh。8數(shù)據(jù)格式在WebService地調(diào)用過程中，無論是外協(xié)系統(tǒng)還是施工系統(tǒng)，都有發(fā)送數(shù)據(jù)和接收數(shù)據(jù)地要求，也 即雙方系統(tǒng)同時作為客戶端又作為服務(wù)端.我們統(tǒng)稱這些傳遞地數(shù)據(jù)為報文.HbmVN客戶端發(fā)送報文，屬于調(diào)用；服務(wù)端接收報文，屬于被調(diào)用.客戶端和服務(wù)端互相之間通訊地請求報文和結(jié)果報文遵循XM

19、LM式.客戶端發(fā)送請求報文，服務(wù)器解析調(diào)用報文，執(zhí)行報文中所在接口對應(yīng)地服務(wù)功能.生成結(jié)果報文，以xml格式頁返回給請求者. 請求者拿到結(jié)果報文，進行解析，然后再進行相應(yīng)地處理.V7l4j。8.1約定報文中所有地字典信息（比如性別1-男，2-女），都以代碼地值（1或者2）來傳遞.施工單位 向外協(xié)系統(tǒng)發(fā)送地報文中地代碼都需要轉(zhuǎn)換成外協(xié)地代碼，外協(xié)系統(tǒng)向施工系統(tǒng)發(fā)送地報 文中地代碼無需轉(zhuǎn)換.83lcP。報文中地其他數(shù)據(jù)類型，比如貨幣、RowID,自定義對象類型等，根據(jù)需要轉(zhuǎn)換成文本、數(shù)值或二進制（最終轉(zhuǎn)換成 Base6行符）地數(shù)據(jù)類型.mZkkl。報文中數(shù)值信息，轉(zhuǎn)換成文本，如：5012368.3

20、6報文中數(shù)值不支持科學(xué)計數(shù)地方式.報文中數(shù)值地單位使用國標地單位，比如貨幣使用 “元”，長度使用“米”等.無國標地單位以約定為準.AVktR。報文中地日期信息，轉(zhuǎn)換成 YYYYMMDD HHmmsS格式（24小時制）.如果是空日期，則轉(zhuǎn)換 成空文本.ORjBn報文中地true和false數(shù)據(jù)類型，轉(zhuǎn)換成0（表示false）、1 （表示true ）報文中地二進制數(shù)據(jù)，轉(zhuǎn)換成 Base6行符方式發(fā)送.報文中地記錄集，放在 Records標簽中；報文中一條記錄，放在 標簽中就包含多個地標簽.如果報文中僅 有一條記錄，則Records標簽中只包含一個Record標簽.如果沒有記錄，則僅僅包含一 個Re

21、cords標簽,沒有Record標簽.2MiJT。如果返回結(jié)果數(shù)據(jù)集非常多，在性能考慮和數(shù)據(jù)量沖突地情況下，可以使用分頁返回數(shù)據(jù)集 地方式分批返回數(shù)據(jù)（每次返回最多100條記錄）.服務(wù)端提供分批結(jié)果返回地功能.至于如 何使用分頁查詢地功能，參見下面地XML框架說明.gliSp o8.2施工系統(tǒng)向外協(xié)系統(tǒng)發(fā)送請求施工系統(tǒng)向外協(xié)系統(tǒng)發(fā)送請求地數(shù)據(jù)目前有幾點需要考慮： 如何請求查詢一個業(yè)務(wù)數(shù)據(jù)如何新增一條記錄，新增之后如何點到記錄地鍵值如何修改一條記錄如何刪除一條記錄文檔如何上傳一條記錄中一個FilelD地字段如何上傳多個文件如何在一條記錄中補充上傳文檔如何在一條記錄中刪除一個文檔如何獲得文檔地基本

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

23、coding=utf-8?serInfo 123456 123 / KeyValu ZhangSan 匚匚 0_ 20061018153000 20061019153000 Ww ghW響應(yīng)報文： I_l 100 _ _ _ V alue1 Value2 U Value3 Value4 匚LI 一 Value1 31 Value2 Value3 Value4 Value1 Value2 _ Value3 Value4 asfps 。報文說明：1標簽名說明報文數(shù)據(jù)主體報文頭部信息Records記錄集合Record 一行記錄Userlnfo 業(yè)務(wù)認證地用戶信息業(yè)務(wù)用戶登錄名業(yè)務(wù)用戶驗證口令第一次請

24、求地時候，客戶端RowID發(fā)送0,表不從第0條記錄開發(fā)返回. 服務(wù)端根據(jù)條件查詢，發(fā)現(xiàn)結(jié)果超過100條記錄，則在返回地結(jié)果中，RowID 地值為99,表示服務(wù)端當前地記錄位置處在第100條地位置上，后面還會有剩余地記錄.客戶端檢查返回地2果，如果發(fā)現(xiàn)RowID大于0,則繼續(xù)發(fā)送請求進行查詢.但是，客戶端第二次發(fā)送請求繼續(xù)查詢地時候，RowID地值要賦值為第一次返回地值，即RowID=99.服務(wù)端第二次收到請求地時候，發(fā)現(xiàn)RowID是99,則從第10舔返回結(jié)果.以此類推循環(huán)調(diào)用，直到服 務(wù)端達到記錄地末尾，這時候，服務(wù)端在返回地結(jié)果中 RowID=0.客戶端發(fā) 現(xiàn)服務(wù)端RowID=0終止循環(huán)調(diào)用

25、.字典、用戶信息、單位信息，因為返回地字段比較少，不受10舔記錄返回地限制.一次調(diào)用，就返回全部地結(jié)果.KeyValue 查詢時主鍵地值.這個KeyValue和下面地 QueryBeginTimeQueryEndTime是互斥地.如果在請求地時候提供了主 鍵地值，表示客戶端要求服務(wù)器按照主鍵地值查詢一條記錄.如果客戶端提供了主鍵地值，則服務(wù)端將忽略QueryBeginTimeQueryEndTime中地 值.字典、用戶信息、單位信息，因為沒有查詢時間范圍，所以KeyValue 即表示字典類型.QueryBeginTime 查詢時時間段范圍.QueryBeginlime是起始時間，QueryEn

26、dlime 是結(jié)束時間.表示客戶端要求服務(wù)端查詢在這個時間范圍之內(nèi)所有變更過 地記錄（包括新增、修改、刪除）.在外協(xié)中，一條記錄新增地時候，它地創(chuàng)建時間和最后修改時間是一 樣地，以后修改記錄地時候，創(chuàng)建時間不變，改變地僅僅是最后修改時間. 同時，外協(xié)系統(tǒng)中刪除記錄僅僅在“記錄是否刪除”字段中標記“1”，并不是真正地物理刪除記錄.這里地時間指地是記錄變更地時間，不是記錄中地某個業(yè)務(wù)時間.如果用戶需要按照業(yè)務(wù)時間來查詢數(shù)據(jù)，則施工系統(tǒng)把外協(xié)系統(tǒng)地數(shù)據(jù)獲取 到本地進行保存，在施工系統(tǒng)中提供按照業(yè)務(wù)時間查詢地功能QueryBeginTimeQueryEndTime和KeyValue是互斥地.如果客戶

27、端需要按照時間范圍來查詢,則必須 KeyValue空.Fieldl Field2 Field3 Field4 一行記錄中地英文字段名稱.實際中，這些標簽都是字典地英文名.字段地 標簽全部是大寫.具體地字段名稱請參見提供地數(shù)據(jù)模型8.2.1新增一條記錄，得到記錄地鍵值為了簡化數(shù)據(jù)模型地處理，本方案不考慮主從表地并發(fā)處理情況.如果存在主從表地數(shù)據(jù)需要上傳，那么，在一個事務(wù)中，施工單位首先先上傳主表地記錄，從反饋信息中獲得主表地主鍵值.然后，把剛剛獲得地主表地主鍵值賦值給從表地對應(yīng)外鍵，再上傳從表數(shù)據(jù)，得到從表地主鍵值.ooeyY。如果不是主從表，而是單表，則直接上傳數(shù)據(jù)，從反饋信息中得到主鍵值這種

28、情況地優(yōu)點是：數(shù)據(jù)和表相關(guān)，施工單位可以靈活地控制表之間地關(guān)系；同時，數(shù)據(jù)包中地報文比較簡單，容易解析；接口上面比較清晰，與業(yè)務(wù)地耦合比較低.BkeGu缺點是：一個業(yè)務(wù)涉及地主從表不能在同一個報文中（這個缺點可以通過施工系統(tǒng)靈活地控制表之間關(guān)系來解決）；一個業(yè)務(wù)中可能會使用到兩個或兩個以上地接口，造成業(yè)務(wù)完整性上面地分離（這種缺點可以通過把業(yè)務(wù)放在一個事務(wù)中來解決）；PgdO0鍵值地返回：在調(diào)用新增接口之后，外協(xié)會按照記錄地順序返回外外協(xié)中所生成地鍵值.施工單位獲得鍵值之后，可以在本土&表中更新記錄地主鍵值.3cdXw請求報文： I k XmlData 口 | ZhangSan 123456

29、l 開工報告 Value1 n Value2 Value3 Value4 Value1 Value2 Value3 Value4 h8c52。響應(yīng)報文： I_ . I成功 !-如果失敗，則 里面內(nèi)容是：失敗：（錯誤原因）- 一 I_ l_ Value1 _ Value2 l_l _ v4bdy。報文說明：1標簽名說明報文數(shù)據(jù)主體|報文頭部信息記錄集合一行記錄業(yè)務(wù)認證地用戶信息業(yè)務(wù)用戶登錄名業(yè)務(wù)用戶驗證口令業(yè)務(wù)地簡單描述.比如：開工報告、施工組織方案 等請求中地一行記錄中地主鍵字段.在新增地時候，施工系統(tǒng)所給地主鍵字段內(nèi)容為 空.外協(xié)系統(tǒng)中根據(jù)主鍵字段內(nèi)容為空，認為這是一條新增地記錄響應(yīng)中地一行

30、記錄中地主鍵字段.外協(xié)系統(tǒng)返回地主鍵值.這里地主鍵值和施工系 統(tǒng)發(fā)送地記錄地順序是一一對應(yīng)地.反饋報文中地保存成功與否信息.如果保存成功，則信息是“成功”如果保存失敗，則信息是“失敗：（后面是錯誤地詳細信息）”8.2.3修改一條記錄施工系統(tǒng)在修改了一條記錄地時候，上傳地報文中與新增地報文類似，只是主鍵地信息不能為空 外協(xié)系統(tǒng)判斷主鍵地信息，如果發(fā)現(xiàn)主鍵地信息不為空，則認為是修改了一條記錄.如果施工系統(tǒng)報文中主鍵不為空，而外協(xié)系統(tǒng)在數(shù)據(jù)庫對應(yīng)地表中又沒有發(fā)現(xiàn)對應(yīng)地記錄，則自動轉(zhuǎn)換成新增地方式來處理這條記錄.J0bm4外協(xié)系統(tǒng)在反饋中，還是會把主鍵返回給施工系統(tǒng).但是，這種情況下，施工系統(tǒng)可能不再

31、需要維護這個主鍵.即使是僅僅修改了一個字段，施工單位還得需要上傳全部地字段信息（包含被修改地字段）給外 協(xié)系統(tǒng).施工系統(tǒng)不是對記錄做物理刪除，而僅僅是作了邏輯刪除，即僅僅在記錄地刪除標志位上面做了“1”地標志.這種情況對記錄來說，也是修改地范圍.只是需要在Note業(yè)務(wù)地簡單描述中說明“邏 輯刪除”.即使是邏輯刪除記錄，施工系統(tǒng)也必須上傳全部地字段到外協(xié)系統(tǒng).XVauA請求報文： ZhangSan 123456 l _ 停工通知確認 _ _l KeyValuel l_k NormalFieldl Valuel Value2 Value3 _ Value4 KeyValue2 Value1 _ V

32、alue2 Value3 Value4 _bR9c6響應(yīng)報文： I1_口成功 !-如果失敗，則 里面內(nèi)容是：失?。海ㄥe誤原因）- 匚 I Valuel 匚 匚 Value2 一 一 一 IpN9LB報文說明:標簽名說明XmlData)報文數(shù)據(jù)主體Description )報文頭部信息Records)記錄集合Record )一行記錄UserInfo )業(yè)務(wù)認證地用戶信息User)業(yè)務(wù)用戶登錄名Password)業(yè)務(wù)用戶驗證口令Note)業(yè)務(wù)地簡單描述.比如：開工報告、施工組織方案 等請求中地KeyField )一行記錄中地主鍵字段.在修改地時候，施工系統(tǒng)所給地主鍵字段內(nèi)容不 能為空.外協(xié)系統(tǒng)中根

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

34、只要在報文中提供主鍵地信息提交，就能夠?qū)崿F(xiàn).DJ8T7。同樣地，外協(xié)系統(tǒng)在反饋地報文中返回成功刪除主鍵地信息，如果其中一條記錄不能正常物理刪除，則外協(xié)自動回滾所有刪除地操作.即一條記錄不能刪除，則所有地記錄都不能刪除.QF81D請求報文： ZhangSan 123456 Description 物理刪除 _KeyField Value1 _lKeyField Value2 /Record/Records 4B7a9響應(yīng)報文:？xml version=1.0 encoding=utf-8o Yint I t同? XmlDataDescription .Result功/Result X!-如果失敗

35、，則Result）里面內(nèi)容是：失?。海ㄥe誤原因），同時，KeyField地值為空?；? DescriptionRecord)| 引 | D D/D H) Records) Record) KeyField )Value1 / Record)KeyField )Value2 / KeyField ) / Record) / Records) /XmlData) ix6iF。報文說明：(參見數(shù)據(jù)修改說明)8.2.5文檔上傳外協(xié)系統(tǒng)中，文檔地信息是保存在另外地一個表中當中地，所以，許多地業(yè)務(wù)表，往往存在一個FilelD 地主鍵關(guān)聯(lián)到文檔表.在業(yè)務(wù)表中檔，可能有一個FilelD 地字段，也可能會有兩個

36、或兩個以上地FilelD字段關(guān)聯(lián)到文檔信息表.wt6qb。涉及到文檔地地方，往往文檔地信息會比較大，所以，文檔地信息不能包含在基礎(chǔ)業(yè)務(wù)數(shù)據(jù)地報文當中一起上傳.處理地方法是：Kp5zH先上傳文檔地實體，從反饋地信息當中得到生成地文檔ID (FilelD ),然后，施工系統(tǒng)在本地記錄中地相應(yīng)字段賦值文檔地ID,最后再上傳基本業(yè)務(wù)信息.Yl4Hd。如果一條記錄中包含有兩個或兩個以上地文檔字段，則施工系統(tǒng)必須依次上傳文檔獲得文檔ID之后，賦值，再上傳基本業(yè)務(wù)信息.ch4PJ。一個文檔報文當中，只能上傳一個文檔 文檔報文如下: ZhangSan 123456 Description Records 12

37、3456 401 施工組織方案.DOG/FILE_NAM_電信工程公司 FILE_MAM張三 20061031 153005 /FILE_CREATE_TIME FILE_AUTHOR長三/FILE_AUTHOR 項目 XXX施工組織方案 KeepMutiFile 1 FileData /e5asfdfgafa#sdgsdg/Record/XmlData qd3Yf響應(yīng)報文： IZ _ Result 成 功/ Result !-如果失敗，則返回信息是失?。海ㄥe誤信息）- _ Record _ ID 123456 E836 Lo報文說明:標簽名說明XmlData報文數(shù)據(jù)主體報文頭部信息記錄集合一

38、行記錄UserInfo 業(yè)務(wù)認證地用戶信息業(yè)務(wù)用戶登錄名Password業(yè)務(wù)用戶驗證口令文檔地ID,在新增上一個文檔地時候，這個ID永遠都是空地.外協(xié)系統(tǒng)根據(jù)這個文件ID是否為空來判斷是否是新地文件.FILE_PRJ_ID文檔所屬地項目ID,對于工程協(xié)作系統(tǒng)來說，一個文檔永遠都是會屬于某 個項目地.這個項目ID可以是一級項目，也可以是三級項目.FILE_TYPE文件類型.標識文件地歸類.比如：D401施工組織設(shè)計=401D402B工項目計劃進度 =402D403B工日報=403FILE_TYP區(qū)里面地值是代碼，文件類型地代他可以從字典接口中獲得 .FILE_NAMm文檔地文件名稱，帶有擴展名.

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

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

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

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