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

2、 事務(wù)處理6 性能考慮7 容錯處理8 數(shù)據(jù)格式約定施工系統(tǒng)向外協(xié)系統(tǒng)發(fā)送請求請求查詢一個業(yè)務(wù)數(shù)據(jù)新增一條記錄，得到記錄的鍵值修改一條記錄刪除一條記錄文檔上傳一條記錄中一個文檔字段上傳多個文件補(bǔ)充上傳文檔在記錄中刪除一個文檔獲得文檔的基本信息獲得文檔的所有兄弟信息獲得文檔的所有父親信息下載一個文檔獲得字典夕卜協(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)）與電信工程施工單位內(nèi)部

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

4、據(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é)作服

5、務(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ù)端。本方案中，除了特殊另外說明外，不考

6、慮外協(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ù)信息。而這些單位也各有

7、其各自工程應(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)的接口，以獲得用戶信息

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

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

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

11、 引起信息泄露與如何保證數(shù)據(jù)在傳輸?shù)倪^程中的數(shù)據(jù)的完整性兩個方面。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ā)布方式待定。

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

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

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

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

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

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

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

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

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

21、在一條記錄中刪除一個文檔u如何獲得文檔的基本信息u如何獲得文檔的所有兄弟信息u如何獲得文檔的所有父親信息u如何下載一個文檔針對這些問題，接口方案的解決方法如下：請求查詢一個業(yè)務(wù)數(shù)據(jù)施工系統(tǒng)針對外協(xié)系統(tǒng)發(fā)送的業(yè)務(wù)數(shù)據(jù)查詢請求根據(jù)業(yè)務(wù)類型有很多種。為了簡化接口，而不是在接口上進(jìn)行業(yè)務(wù)操作，所以，外協(xié)系統(tǒng)將施工系統(tǒng)發(fā)起的數(shù)據(jù)查詢請求看作是數(shù)據(jù)下載的一種方式，而不為了復(fù)雜的業(yè)務(wù)查詢請求提供復(fù)雜的條件解析。外協(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>響應(yīng)報文:<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標(biāo)簽名說明<XmlData>:報文數(shù)據(jù)主體<Descripti on>報文頭部信息<Records>記錄集合<Rec

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

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

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

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

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

31、個或兩個以上的接口，造成業(yè)務(wù)完整性上面的分離（這種缺點可以通過把業(yè)務(wù)放在一個事務(wù)中來解決）；鍵值的返回：在調(diào)用新增接口之后，外協(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>響應(yīng)報文：<xml versi on="” en cod in g="utf-8" ><XmlData><Description ><Result>成功</Result> <!-如果失敗，貝0 <Result>里面內(nèi)容是：失敗：（錯誤原因）-></ Descripti on><Records><Record><KeyField>Value1</

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

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

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

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>停工通知確認(rèn)</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>響應(yīng)報文:標(biāo)簽名說明報文說明：標(biāo)簽名說明<xml versi on

41、="” en cod in g="utf-8" ><XmlData><Description ><Result>成功</Result> <!-如果失敗，貝0 <Result>里面內(nèi)容是：失敗：（錯誤原因）-></ 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è)務(wù)認(rèn)證的用戶信息<User>業(yè)務(wù)用戶登錄名<PassWord>業(yè)務(wù)用戶驗證口令<Note>業(yè)務(wù)的簡單描述。比如：開工報告、施工組織方案等請求中的<KeyField>一行記錄中的主鍵字段。在修改的時候，施工系統(tǒng)所給的主鍵字

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

44、從數(shù)據(jù)庫中刪除一條記錄，不能恢復(fù)。物理刪除的時候，施工系統(tǒng)只要在報文 中提供主鍵的信息提交，就能夠?qū)崿F(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>響應(yīng)報文：<xml version="” encodin

46、g="utf-8"><XmlData>vDescripti on><Result>成功</Result> <!-如果失敗，則<Result>里面內(nèi)容是：失敗：（錯誤原因），同時，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)中，文檔的信息是保存在另外的一個表中當(dāng)中的，所以，許多的業(yè)務(wù)表，往往存在一個FilelD的主鍵關(guān)聯(lián)到文檔表。在業(yè)務(wù)表中檔，可能有一個FilelD的字段，也可能會有兩個或兩個以上的FilelD字段關(guān)聯(lián)到文檔信息表。涉及到文檔的地方，往往文檔的信息會比較大，所以，文檔的信息不能包含在基礎(chǔ)業(yè)務(wù)數(shù)據(jù)的報文當(dāng)中一起上傳。處理的方法是：先上傳文檔的實體，從反饋的信息當(dāng)中得到生成的文檔ID（FilelD），然后，施工系統(tǒng)在本地記錄中的相應(yīng)字段賦值文檔的ID，

48、最后再上傳基本業(yè)務(wù)信息。如果一條記錄中包含有兩個或兩個以上的文檔字段，則施工系統(tǒng)必須依次上傳文檔獲得文檔ID之后，賦值，再上傳基本業(yè)務(wù)信息。一個文檔報文當(dāng)中，只能上傳一個文檔。文檔報文如下：<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>響應(yīng)報文:<xml version="” encoding="utf-8"><XmlData>vDescripti on><Result>成功</Result><!-如果失敗，則返回信息是失敗：（錯誤信息）”->v/Descripti on><Records><Rec

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

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

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

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

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

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

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

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

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

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

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