NCV5-單據(jù)號管理及開發(fā)紅皮書

1、單據(jù)號管理及開發(fā)技術(shù)紅皮書NC-UAP 5.0用友NC-UAP2022-01-28目 錄第一章前言1第二章單據(jù)號管理功能介紹21.單據(jù)號編碼規(guī)則定義22.對象標識定義33.單據(jù)號特點4第三章數(shù)據(jù)預(yù)制51.單據(jù)對象52.單據(jù)號編碼規(guī)則5第四章對外接口61.方法詳細說明72.申請批量單據(jù)號83.回退單據(jù)號(已經(jīng)刪除)84.刪除單據(jù)號8第五章V5單據(jù)號新方案介紹101.單據(jù)號新方案介紹102.舉例分析11第六章 V502新增功能介紹121、增加公司級單據(jù)號規(guī)則12第一章 前言在基于UAP-NC的企業(yè)管理系統(tǒng)內(nèi)，根據(jù)企業(yè)的特點和行業(yè)規(guī)范，存在著大量的業(yè)務(wù)單據(jù)和基礎(chǔ)檔案數(shù)據(jù)，如何標識這些數(shù)據(jù)？如何自動給

2、每個新的業(yè)務(wù)單據(jù)分配一個唯一的單據(jù)號？并且保證單據(jù)號規(guī)則可以進行配置，可靈活嵌入業(yè)務(wù)對象、日期、時間及流水編號，還要求單據(jù)號可以保持連續(xù)，能自動在斷號時進行補號，不重號，能處理集群及并發(fā)環(huán)境下的單據(jù)號申請，這些就是單據(jù)號管理模塊需要解決的問題。對于應(yīng)用產(chǎn)品和模塊的開發(fā)人員，以上這些問題了解即可，主要面臨的問題是如何在自己負責的業(yè)務(wù)單據(jù)中嵌入單據(jù)號管理功能，如何按標準規(guī)范去編寫單據(jù)號相關(guān)代碼。本紅皮書主要的內(nèi)容就是講解如何開發(fā)各種單據(jù)類型的單據(jù)號管理功能，要給業(yè)務(wù)單據(jù)增加單據(jù)號管理功能，首先要為該單據(jù)類型定義單據(jù)編碼規(guī)則，這樣，申請單據(jù)號時將按照此規(guī)則生成唯一的單據(jù)號。另外如果單據(jù)編碼規(guī)則定義中

3、選擇了單據(jù)對象，則要對單據(jù)對象（如部門）的每個具體對象（如開發(fā)部）定義對象標識（RD），這樣該標識將出現(xiàn)在申請的單據(jù)號中。NCV5版本的單據(jù)號管理功能較以前版本有一些變化和改進，請開發(fā)人員注意，主要體現(xiàn)在以下幾點：n V5版本中增加了基礎(chǔ)檔案自動編號功能,初始化腳本在pub_billcode_basdoc里注冊。n V5版本不再強制要求在PUB_BILLCODE_RULE表里注冊初始化腳本,開發(fā)人員可以直接到單據(jù)號管理節(jié)點,從頭開始定義單據(jù)號規(guī)則。適合新單據(jù)的開發(fā)。n 單據(jù)對象管理增加規(guī)則定義，可以批量設(shè)置單據(jù)對象標識。n 單據(jù)號申請及回退增加了內(nèi)存管理功能及自動事務(wù)提交功能，詳情可以參考第4

4、章“單據(jù)號管理新方案”由于API調(diào)用規(guī)范較以前版本有一些變化，所以開發(fā)人員在調(diào)用時請參考第5節(jié)，需嚴格按照規(guī)范進行代碼調(diào)用，以免出現(xiàn)重號、丟號問題。第二章 單據(jù)號管理功能介紹1. 單據(jù)號編碼規(guī)則定義單據(jù)號編碼規(guī)則初始是系統(tǒng)預(yù)制的，程序員發(fā)版前要提供pub_billcode_rule表的初始化腳本。集團可以修改單據(jù)號編碼規(guī)則，而公司只能瀏覽各單據(jù)類型的編碼規(guī)則。1. 單據(jù)類型：以樹型結(jié)構(gòu)列示出系統(tǒng)內(nèi)的單據(jù)類型。2. 編碼范圍：用來控制該單據(jù)號是集團統(tǒng)一編碼或各公司自成體系或按照對象統(tǒng)一編碼。3. 編碼參數(shù)控制：如果設(shè)置唯一性檢查，則申請的單據(jù)號不會和自定義單據(jù)號重復(fù)，唯一性檢查范圍和編碼范圍一致

5、；如果單據(jù)號保留占用，則刪除的單據(jù)號不會再利用；如果設(shè)置了自動補號，則回退的單據(jù)號會被申請得到。4. 單據(jù)類型簡稱：可以定義單據(jù)類型簡稱作為單據(jù)號編碼的一部分。這是可選項。5. 對象：最多可以選擇兩個對象作為單據(jù)號編碼的一部分，如部門、倉庫、存貨分類、人員等。這兩個對象也是可選，如果選擇了對象，則此對象標識將出現(xiàn)在申請的單據(jù)號編碼鐘，具體的對象標識定義參見下一節(jié)。另外，對于不同的單據(jù)類型，其可以選擇的對象可能不同，這部分數(shù)據(jù)是系統(tǒng)預(yù)制的。6. 順序號：單據(jù)編碼中，用來表示單據(jù)的順序號的一串數(shù)字，包括年月日及流水號。1) 年：用2位字符來表示。2) 月：用2位字符來表示。如果選了月，也必須選年。

6、3) 日：用2位字符來表示。如果選了日，也必須選月。4) 流水號：流水號的位數(shù)可在2位到10位間進行設(shè)置，范圍從0.1到9.9，例如：如果定義4位，則流水號范圍為0001到9999。5) 流水號歸0標志：歸0表示流水號到一定時候會再從0開始編號；通過歸0標志可以控制流水號是否歸0或歸0方式。按“日”歸0表示流水號按日編碼，每天的流水號都從0重新開始；按“月”歸0表示流水號按月編碼，每月的流水號都從0重新開始；按“年”歸0表示流水號按年編碼，每年的流水號都從0重新開始；不歸0表示流水號一直編號下去，不會歸0。6) 流水號的長度一定要結(jié)合編碼規(guī)則及具體單據(jù)的業(yè)務(wù)量來設(shè)置。如果是按年流水的話，流水號

7、位數(shù)可以長些；如果是按日流水的話，則流水號可少些。7. 指定流水號：對于單據(jù)號編碼范圍是集團或公司，如果不希望單據(jù)號按照當前的流水號繼續(xù)編號，則可以對此單據(jù)號編碼規(guī)則重新指定流水號基準號。8. 生成單據(jù)號時檢查唯一性，如果選擇，那么生成單據(jù)號時檢查生成的單據(jù)號是否與用戶自定義號重復(fù)，而不檢查生成的單據(jù)號與以前生成的單據(jù)號是否重復(fù)，所以建議產(chǎn)品組開發(fā)人員在保存單據(jù)時自行檢查新生成的單據(jù)號與現(xiàn)有單據(jù)是否重復(fù)。唯一性檢查范圍和編碼范圍一致。9. 刪除單據(jù)號時保留占用：該參數(shù)如果勾擇，對于自動編號的單據(jù)，刪除單據(jù)號時不會將刪除的單據(jù)號回退到退號表，再增加新單據(jù)時，不會自動補前面的缺號，會自動生成一個新

8、的單據(jù)號，但此時如果手工輸入刪除的單據(jù)號，仍可以保存。如果設(shè)置了自動補號，則回退的單據(jù)號會被申請得到。10. 自動進行退號補號，如果選擇，則生成單據(jù)號時會首先到回退表里去取，反之，則會直接生成新的單據(jù)號。需要注意的是，自定義號不會回退到退號表，如果發(fā)現(xiàn)自定義號被回退到退號表，則說明沒用使用單據(jù)號申請API去申請自定義號，也就是說自定義號也需要調(diào)用API去申請一下，以便單據(jù)號模塊統(tǒng)一管理。刪除單據(jù)號時保留占用自動進行斷號補號效果自動編號是是/否保留占用，不自動補號；但手工輸入被刪除的單號可以保存；否是自動補被刪除的單據(jù)號；但手工輸入被刪除的單據(jù)號可以保存；否否不自動補號；但手工輸入被刪除的單據(jù)號

9、可以保存；手工編號是是/否被占用的號碼刪除后，手工輸入也不能用；否是/否被占用的號碼刪除后，手工輸入可以使用；11.2. 對象標識定義單據(jù)號對象也是系統(tǒng)預(yù)制的，程序員發(fā)版前需要提供pub_billcode_obj及pub_billobject的初始化腳本。對象的標識也是由集團設(shè)置，公司只能瀏覽。只有設(shè)置了對象的標識，使用此對象的單據(jù)號才能直觀地表示出該對象。對象標識的設(shè)置盡量直觀，該對象下的各標識長度必須保持一致。3. 單據(jù)號特點l 可針對不同單據(jù)類型靈活設(shè)置不同單據(jù)號編碼規(guī)則。l 單據(jù)號編碼可集團統(tǒng)一，也可各公司自成體系，還可按照對象編碼。l 支持單個獲取單據(jù)號，也支持批量獲取單據(jù)號。l 保

10、證了單據(jù)號編碼的唯一性與連續(xù)性，支持回退單據(jù)號的再獲取。l 單據(jù)號自動編碼與自定義編碼靈活結(jié)合。如果不希望系統(tǒng)自動獲得單據(jù)號，用戶可以手工輸入單據(jù)號來獲取此自定義編碼的單據(jù)號。第三章 數(shù)據(jù)預(yù)制如前所述，單據(jù)號開發(fā)中的很多數(shù)據(jù)是通過初始化數(shù)據(jù)腳本進行系統(tǒng)預(yù)制的。1. 單據(jù)對象1. 單據(jù)對象的多語翻譯resid：每個對象都有一個多語resid。只有新增加對象才有必要提供此數(shù)據(jù)腳本。如下例，dr為0，ts表示日期，objname為對象名稱，resid表示多語id，pk_billobject表示pk：insert into pub_billobject(dr,ts,objname,resid,pk_b

11、illobject) values( 0,'2005-03-14 13:54:21','部門','obj-0000000000','smobj000000000000001')2. 如下例，pk_billcodeobj表示pk，objname為對象名稱，objref表示參照名稱（如果是自定義的參照類，則要寫類名，比如nc.ui.prm.ref.SaleStruRefModel），pk_billtypecode表示單據(jù)類型，objtablength表示單據(jù)對象長度， ts表示日期，dr為0：insert into pub_billc

12、ode_obj(pk_billcodeobj,objname,objref,pk_billtypecode,objtablength,ts,dr) values( 'sm200000000000000001','公司','公司目錄','20',null,'2001-11-12 12:09:43',0)2. 單據(jù)號編碼規(guī)則對于需要生成單據(jù)號的單據(jù)類型，都需要提供單據(jù)號編碼規(guī)則數(shù)據(jù)腳本。如下例，pk_billcoderule表示pk，pk_billtypecode表示單據(jù)類型，billcodeshortname表示單據(jù)

13、類型簡稱，ishaveshortname表示單據(jù)號是否需要單據(jù)類型簡稱,controlpara表示編碼范圍（'Y'表示集團，'N'表示公司，'O'表示對象）,ischeck表示是否進行唯一性檢查,object1表示對象1名稱,object2表示對象2名稱,year表示單據(jù)號年,month表示單據(jù)號月,day表示單據(jù)號日,snnum表示流水號位數(shù),lastsn為'0000',ts表示日期,dr為0：insert into pub_billcode_rule(pk_billcoderule,pk_billtypecode,billco

14、deshortname,ishaveshortname,controlpara,ischeck,object1,object2,year,month,day,snnum,lastsn,ts,dr) values( 'sm300000000000000001','30','SO','Y','N','Y','部門',null,'01','01','01',4,'0000','2001-11-26 15:32:04&#

15、39;,0)第四章 對外接口對于非獨立事務(wù)的業(yè)務(wù)，原有獨立事務(wù)回退號方法被刪除，不再需要調(diào)用，現(xiàn)在只需要關(guān)心兩個方法： (1) 獨立事務(wù)申請單據(jù)號，批量：BillcodeGenerater. getBatchBillCodes()；非批量：BillcodeGenerater. getBillCode() (2) 刪除單據(jù)時非獨立事務(wù)回退單據(jù)號：IBillcodeRuleService.returnBillCodeOnDelete對于獨立事務(wù)的業(yè)務(wù)，基本用法同上，但是需要額外調(diào)用另外3個方法：(1) 申請單據(jù)號區(qū)域 IBillcodeRuleService.requireNewRegion(St

16、ring regionid)，用于開始獨立事務(wù)之前(2) 釋放單據(jù)號區(qū)域 IBillcodeRuleService.releaseRegion(String regionid),當業(yè)務(wù)正常結(jié)束時，調(diào)用此方法釋放區(qū)域(3) 停用單據(jù)號區(qū)域 IBillcodeRuleService.stopRegion(String regionid),當業(yè)務(wù)非正常結(jié)束時，調(diào)用此方法固化此區(qū)域注意：(2)(3)方法是互斥的，不能同時被調(diào)用，寫程序時請注意。推薦寫法：try/申請?zhí)囟▋?nèi)存區(qū)域SFAppServiceUtil.getBillcodeRuleService().requireNewRegion(regi

17、onid);/做獨立事務(wù)業(yè)務(wù)操作/釋放申請的內(nèi)存區(qū)域SFAppServiceUtil.getBillcodeRuleService().releaseRegion(regionid);catch (Exception e) /停止申請的內(nèi)存區(qū)域SFAppServiceUtil.getBillcodeRuleService().stopRegion(regionid);/異常處理代碼1. 方法詳細說明getBillCode(String billTypeCode ,String pkcorp , String customBillCode , BillCodeObjValueVO voBill)

18、1. 方法說明：獲得一個可用的單據(jù)號。在申請一個單據(jù)號時調(diào)用此方法。申請單據(jù)號之前必須為該單據(jù)類型定義一個單據(jù)號編碼規(guī)則，否則無法獲得單據(jù)號。2. 參數(shù)說明：1) billTypeCode表示單據(jù)類型編碼，必須提供。 2) pkcorp表示公司主鍵，如果此單據(jù)類型的單據(jù)號規(guī)則按照公司編碼，則必須提供。3) customBillCode表示手工錄入的單據(jù)號，如果沒有提供手工單據(jù)號，則設(shè)置為null。4) voBill保存了用于單據(jù)號編碼中各個對象的取值，對于某一種單據(jù)類型的每一個對象。如果此單據(jù)類型的單據(jù)號規(guī)則沒有使用對象，則設(shè)置為null。voBill可以調(diào)用setAttributeValue

19、(String name, Object value)或setAttributeValue(String name, Object value)方法設(shè)置各個對象的屬性值，name為對象名稱，value為具體對象的主鍵值。例如，銷售訂單總共有兩個對象：部門，業(yè)務(wù)員，而兩個對象的主鍵值分別為“001” ，“111”，那么可以編寫如下代碼： BillCodeObjValueVO vo=new BillCodeObjValueVO(); vo.setAttributeValue(“部門”,”001”)； vo.setAttributeValue(“業(yè)務(wù)員”,”111”);或者 BillCodeObjV

20、alueVO vo=new BillCodeObjValueVO(); String names=“部門”,”業(yè)務(wù)員”; String values=“001”,”111”; vo.setAttributeValue(names,values);5) 返回值說明：如果customBillCode非null，則返回此值，否則返回一個系統(tǒng)自動生成的單據(jù)號。如果自動生成的單據(jù)號中包含對象，但是沒有為此對象定義標識，系統(tǒng)會根據(jù)該對象的標識長度生成由“*”組成的對象標識，例如“部門“對象標識長度為3，而沒有為“開發(fā)部”定義對象標識，則使用此對象的單據(jù)號就會出現(xiàn)“*”。如果獲取單據(jù)號失敗，該方法將拋出nc

21、.vo.pub.ValidationException例外，例外中保存了失敗的原因，可用e.getMessage()獲得。失敗原因可能包括：此單據(jù)號規(guī)則正在同時申請；流水號超出了其設(shè)置的位數(shù)長度；申請的單據(jù)號還沒有定義單據(jù)號編碼規(guī)則。3. 示例String customBillCode=null;String pkcorp=”1001”;String billTypecode=”30”;/生成一個BillCodeObjValueVOnc.vo.pub.billcodemanage.BillCodeObjValueVO vo=new nc.vo.pub.billcodemanage.BillCo

22、deObjValueVO();vo.setAttributeValue("操作員",?);vo.setAttributeValue("業(yè)務(wù)類型",?);vo.setAttributeValue("部門",?);String billcode=null;billcode=（new BillcodeGenerater ()）.getBillCode(billTypecode,pkcorp,customBillCode,vo);2. 申請批量單據(jù)號getBatchBillCodes(String billTypeCode ,String p

23、kcorp , String customBillCode , BillCodeObjValueVO voBill, int count)此方法將獲得多個單據(jù)號，具體返回多少個單據(jù)號由參數(shù)count指定。其和申請單個單據(jù)號的唯一區(qū)別是返回單據(jù)號的個數(shù)不同而已。但是此方法對于需要申請多個單據(jù)號的應(yīng)用，能極大地提高效率，而不要利用循環(huán)一個一個地申請單據(jù)號。3. 回退單據(jù)號(已經(jīng)刪除)returnBillCode(String pkcorp, String billTypeCode, String billCode, BillCodeObjValueVO voBill)此方法已被刪除，對于業(yè)務(wù)操作中

24、所有新申請的單據(jù)號，如果業(yè)務(wù)失敗，將被自動回退，無需外界調(diào)用。此方法將對指定的單據(jù)號billCode進行回退，此回退的單據(jù)號下次可以被申請獲得。如果是自定義單據(jù)號回退，則下次可以再申請此自定義單據(jù)號，而不會檢查到此單據(jù)號重復(fù)。如果此單據(jù)類型的單據(jù)號編碼規(guī)則的年、月、日和要回退的單據(jù)號billCode中的年、月、日不一致，則此單據(jù)號不會回退，比如：單據(jù)號編碼規(guī)則的年、月、日分別為05、08、28，則單據(jù)號RM0508240001不會回退，由于此單據(jù)號是24日的，和28號不匹配。參數(shù)pkcorp、billTypeCode、voBill和前面的方法參數(shù)用法類似。4. 刪除單據(jù)號returnBillC

25、odeOnDelete(String pkcorp, String billTypeCode, String billCode, BillCodeObjValueVO voBill)此方法表示刪除單據(jù)號billCode。如果此單據(jù)類型的單據(jù)號編碼規(guī)則沒有設(shè)置“刪除單據(jù)號時保留占用”，則此單據(jù)號將回退；否則不會回退，下次申請單據(jù)號時不會再獲取此單據(jù)號。該方法和上一個方法returnBillCode的參數(shù)完全一致，主要區(qū)別是：returnBillCode沒有參數(shù)“刪除單據(jù)號時保留占用”的限制，而本方法有；另外，本方法只存在于SFAppServiceUtil.getBillcodeRuleService()中，為非獨立事務(wù)，BillcodeGenerater中沒有本方法。注意：做業(yè)務(wù)時申請了單據(jù)號，如果在做業(yè)務(wù)過程中出現(xiàn)異常，也不要在catch塊中調(diào)用本方法進行單據(jù)號回退，否則可能會出申請自定義號申請不到的問題。第五章 V5單據(jù)號新方案介紹名詞解釋:業(yè)務(wù)獨立事務(wù)：是指在前臺發(fā)起一次調(diào)用批處處理多個相同的單據(jù)的批處理。處理的每一個業(yè)務(wù)單據(jù)為業(yè)務(wù)獨立事務(wù)。1. 單據(jù)號新方案介紹方案：為每個前臺連接建立回退區(qū)域，在連接關(guān)閉時一起退號；Ø 每個回退區(qū)域分為四個類型的段1、 刪除單據(jù)號回退段a) 存放內(nèi)容：刪除業(yè)務(wù)，主動回退的單據(jù)號；b) 回退時機：業(yè)務(wù)正