NCV5-单据号管理及开发红皮书

1、单据号管理及开发技术红皮书NC-UAP 5.0用友NC-UAP2022-01-28目 录第一章前言1第二章单据号管理功能介绍21.单据号编码规则定义22.对象标识定义33.单据号特点4第三章数据预制51.单据对象52.单据号编码规则5第四章对外接口61.方法详细说明72.申请批量单据号83.回退单据号(已经删除)84.删除单据号8第五章V5单据号新方案介绍101.单据号新方案介绍102.举例分析11第六章 V502新增功能介绍121、增加公司级单据号规则12第一章 前言在基于UAP-NC的企业管理系统内，根据企业的特点和行业规范，存在着大量的业务单据和基础档案数据，如何标识这些数据？如何自动给

2、每个新的业务单据分配一个唯一的单据号？并且保证单据号规则可以进行配置，可灵活嵌入业务对象、日期、时间及流水编号，还要求单据号可以保持连续，能自动在断号时进行补号，不重号，能处理集群及并发环境下的单据号申请，这些就是单据号管理模块需要解决的问题。对于应用产品和模块的开发人员，以上这些问题了解即可，主要面临的问题是如何在自己负责的业务单据中嵌入单据号管理功能，如何按标准规范去编写单据号相关代码。本红皮书主要的内容就是讲解如何开发各种单据类型的单据号管理功能，要给业务单据增加单据号管理功能，首先要为该单据类型定义单据编码规则，这样，申请单据号时将按照此规则生成唯一的单据号。另外如果单据编码规则定义中

3、选择了单据对象，则要对单据对象（如部门）的每个具体对象（如开发部）定义对象标识（RD），这样该标识将出现在申请的单据号中。NCV5版本的单据号管理功能较以前版本有一些变化和改进，请开发人员注意，主要体现在以下几点：n V5版本中增加了基础档案自动编号功能,初始化脚本在pub_billcode_basdoc里注册。n V5版本不再强制要求在PUB_BILLCODE_RULE表里注册初始化脚本,开发人员可以直接到单据号管理节点,从头开始定义单据号规则。适合新单据的开发。n 单据对象管理增加规则定义，可以批量设置单据对象标识。n 单据号申请及回退增加了内存管理功能及自动事务提交功能，详情可以参考第4

4、章“单据号管理新方案”由于API调用规范较以前版本有一些变化，所以开发人员在调用时请参考第5节，需严格按照规范进行代码调用，以免出现重号、丢号问题。第二章 单据号管理功能介绍1. 单据号编码规则定义单据号编码规则初始是系统预制的，程序员发版前要提供pub_billcode_rule表的初始化脚本。集团可以修改单据号编码规则，而公司只能浏览各单据类型的编码规则。1. 单据类型：以树型结构列示出系统内的单据类型。2. 编码范围：用来控制该单据号是集团统一编码或各公司自成体系或按照对象统一编码。3. 编码参数控制：如果设置唯一性检查，则申请的单据号不会和自定义单据号重复，唯一性检查范围和编码范围一致

5、；如果单据号保留占用，则删除的单据号不会再利用；如果设置了自动补号，则回退的单据号会被申请得到。4. 单据类型简称：可以定义单据类型简称作为单据号编码的一部分。这是可选项。5. 对象：最多可以选择两个对象作为单据号编码的一部分，如部门、仓库、存货分类、人员等。这两个对象也是可选，如果选择了对象，则此对象标识将出现在申请的单据号编码钟，具体的对象标识定义参见下一节。另外，对于不同的单据类型，其可以选择的对象可能不同，这部分数据是系统预制的。6. 顺序号：单据编码中，用来表示单据的顺序号的一串数字，包括年月日及流水号。1) 年：用2位字符来表示。2) 月：用2位字符来表示。如果选了月，也必须选年。

6、3) 日：用2位字符来表示。如果选了日，也必须选月。4) 流水号：流水号的位数可在2位到10位间进行设置，范围从0.1到9.9，例如：如果定义4位，则流水号范围为0001到9999。5) 流水号归0标志：归0表示流水号到一定时候会再从0开始编号；通过归0标志可以控制流水号是否归0或归0方式。按“日”归0表示流水号按日编码，每天的流水号都从0重新开始；按“月”归0表示流水号按月编码，每月的流水号都从0重新开始；按“年”归0表示流水号按年编码，每年的流水号都从0重新开始；不归0表示流水号一直编号下去，不会归0。6) 流水号的长度一定要结合编码规则及具体单据的业务量来设置。如果是按年流水的话，流水号

7、位数可以长些；如果是按日流水的话，则流水号可少些。7. 指定流水号：对于单据号编码范围是集团或公司，如果不希望单据号按照当前的流水号继续编号，则可以对此单据号编码规则重新指定流水号基准号。8. 生成单据号时检查唯一性，如果选择，那么生成单据号时检查生成的单据号是否与用户自定义号重复，而不检查生成的单据号与以前生成的单据号是否重复，所以建议产品组开发人员在保存单据时自行检查新生成的单据号与现有单据是否重复。唯一性检查范围和编码范围一致。9. 删除单据号时保留占用：该参数如果勾择，对于自动编号的单据，删除单据号时不会将删除的单据号回退到退号表，再增加新单据时，不会自动补前面的缺号，会自动生成一个新

8、的单据号，但此时如果手工输入删除的单据号，仍可以保存。如果设置了自动补号，则回退的单据号会被申请得到。10. 自动进行退号补号，如果选择，则生成单据号时会首先到回退表里去取，反之，则会直接生成新的单据号。需要注意的是，自定义号不会回退到退号表，如果发现自定义号被回退到退号表，则说明没用使用单据号申请API去申请自定义号，也就是说自定义号也需要调用API去申请一下，以便单据号模块统一管理。删除单据号时保留占用自动进行断号补号效果自动编号是是/否保留占用，不自动补号；但手工输入被删除的单号可以保存；否是自动补被删除的单据号；但手工输入被删除的单据号可以保存；否否不自动补号；但手工输入被删除的单据号

9、可以保存；手工编号是是/否被占用的号码删除后，手工输入也不能用；否是/否被占用的号码删除后，手工输入可以使用；11.2. 对象标识定义单据号对象也是系统预制的，程序员发版前需要提供pub_billcode_obj及pub_billobject的初始化脚本。对象的标识也是由集团设置，公司只能浏览。只有设置了对象的标识，使用此对象的单据号才能直观地表示出该对象。对象标识的设置尽量直观，该对象下的各标识长度必须保持一致。3. 单据号特点l 可针对不同单据类型灵活设置不同单据号编码规则。l 单据号编码可集团统一，也可各公司自成体系，还可按照对象编码。l 支持单个获取单据号，也支持批量获取单据号。l 保

10、证了单据号编码的唯一性与连续性，支持回退单据号的再获取。l 单据号自动编码与自定义编码灵活结合。如果不希望系统自动获得单据号，用户可以手工输入单据号来获取此自定义编码的单据号。第三章 数据预制如前所述，单据号开发中的很多数据是通过初始化数据脚本进行系统预制的。1. 单据对象1. 单据对象的多语翻译resid：每个对象都有一个多语resid。只有新增加对象才有必要提供此数据脚本。如下例，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表示单据类型，objtablength表示单据对象长度， 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. 单据号编码规则对于需要生成单据号的单据类型，都需要提供单据号编码规则数据脚本。如下例，pk_billcoderule表示pk，pk_billtypecode表示单据类型，billcodeshortname表示单据

13、类型简称，ishaveshortname表示单据号是否需要单据类型简称,controlpara表示编码范围（'Y'表示集团，'N'表示公司，'O'表示对象）,ischeck表示是否进行唯一性检查,object1表示对象1名称,object2表示对象2名称,year表示单据号年,month表示单据号月,day表示单据号日,snnum表示流水号位数,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)第四章 对外接口对于非独立事务的业务，原有独立事务回退号方法被删除，不再需要调用，现在只需要关心两个方法： (1) 独立事务申请单据号，批量：BillcodeGenerater. getBatchBillCodes()；非批量：BillcodeGenerater. getBillCode() (2) 删除单据时非独立事务回退单据号：IBillcodeRuleService.returnBillCodeOnDelete对于独立事务的业务，基本用法同上，但是需要额外调用另外3个方法：(1) 申请单据号区域 IBillcodeRuleService.requireNewRegion(St

16、ring regionid)，用于开始独立事务之前(2) 释放单据号区域 IBillcodeRuleService.releaseRegion(String regionid),当业务正常结束时，调用此方法释放区域(3) 停用单据号区域 IBillcodeRuleService.stopRegion(String regionid),当业务非正常结束时，调用此方法固化此区域注意：(2)(3)方法是互斥的，不能同时被调用，写程序时请注意。推荐写法：try/申请特定内存区域SFAppServiceUtil.getBillcodeRuleService().requireNewRegion(regi

17、onid);/做独立事务业务操作/释放申请的内存区域SFAppServiceUtil.getBillcodeRuleService().releaseRegion(regionid);catch (Exception e) /停止申请的内存区域SFAppServiceUtil.getBillcodeRuleService().stopRegion(regionid);/异常处理代码1. 方法详细说明getBillCode(String billTypeCode ,String pkcorp , String customBillCode , BillCodeObjValueVO voBill)

18、1. 方法说明：获得一个可用的单据号。在申请一个单据号时调用此方法。申请单据号之前必须为该单据类型定义一个单据号编码规则，否则无法获得单据号。2. 参数说明：1) billTypeCode表示单据类型编码，必须提供。 2) pkcorp表示公司主键，如果此单据类型的单据号规则按照公司编码，则必须提供。3) customBillCode表示手工录入的单据号，如果没有提供手工单据号，则设置为null。4) voBill保存了用于单据号编码中各个对象的取值，对于某一种单据类型的每一个对象。如果此单据类型的单据号规则没有使用对象，则设置为null。voBill可以调用setAttributeValue

19、(String name, Object value)或setAttributeValue(String name, Object value)方法设置各个对象的属性值，name为对象名称，value为具体对象的主键值。例如，销售订单总共有两个对象：部门，业务员，而两个对象的主键值分别为“001” ，“111”，那么可以编写如下代码： BillCodeObjValueVO vo=new BillCodeObjValueVO(); vo.setAttributeValue(“部门”,”001”)； vo.setAttributeValue(“业务员”,”111”);或者 BillCodeObjV

20、alueVO vo=new BillCodeObjValueVO(); String names=“部门”,”业务员”; String values=“001”,”111”; vo.setAttributeValue(names,values);5) 返回值说明：如果customBillCode非null，则返回此值，否则返回一个系统自动生成的单据号。如果自动生成的单据号中包含对象，但是没有为此对象定义标识，系统会根据该对象的标识长度生成由“*”组成的对象标识，例如“部门“对象标识长度为3，而没有为“开发部”定义对象标识，则使用此对象的单据号就会出现“*”。如果获取单据号失败，该方法将抛出nc

21、.vo.pub.ValidationException例外，例外中保存了失败的原因，可用e.getMessage()获得。失败原因可能包括：此单据号规则正在同时申请；流水号超出了其设置的位数长度；申请的单据号还没有定义单据号编码规则。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("业务类型",?);vo.setAttributeValue("部门",?);String billcode=null;billcode=（new BillcodeGenerater ()）.getBillCode(billTypecode,pkcorp,customBillCode,vo);2. 申请批量单据号getBatchBillCodes(String billTypeCode ,String p

23、kcorp , String customBillCode , BillCodeObjValueVO voBill, int count)此方法将获得多个单据号，具体返回多少个单据号由参数count指定。其和申请单个单据号的唯一区别是返回单据号的个数不同而已。但是此方法对于需要申请多个单据号的应用，能极大地提高效率，而不要利用循环一个一个地申请单据号。3. 回退单据号(已经删除)returnBillCode(String pkcorp, String billTypeCode, String billCode, BillCodeObjValueVO voBill)此方法已被删除，对于业务操作中

24、所有新申请的单据号，如果业务失败，将被自动回退，无需外界调用。此方法将对指定的单据号billCode进行回退，此回退的单据号下次可以被申请获得。如果是自定义单据号回退，则下次可以再申请此自定义单据号，而不会检查到此单据号重复。如果此单据类型的单据号编码规则的年、月、日和要回退的单据号billCode中的年、月、日不一致，则此单据号不会回退，比如：单据号编码规则的年、月、日分别为05、08、28，则单据号RM0508240001不会回退，由于此单据号是24日的，和28号不匹配。参数pkcorp、billTypeCode、voBill和前面的方法参数用法类似。4. 删除单据号returnBillC

25、odeOnDelete(String pkcorp, String billTypeCode, String billCode, BillCodeObjValueVO voBill)此方法表示删除单据号billCode。如果此单据类型的单据号编码规则没有设置“删除单据号时保留占用”，则此单据号将回退；否则不会回退，下次申请单据号时不会再获取此单据号。该方法和上一个方法returnBillCode的参数完全一致，主要区别是：returnBillCode没有参数“删除单据号时保留占用”的限制，而本方法有；另外，本方法只存在于SFAppServiceUtil.getBillcodeRuleService()中，为非独立事务，BillcodeGenerater中没有本方法。注意：做业务时申请了单据号，如果在做业务过程中出现异常，也不要在catch块中调用本方法进行单据号回退，否则可能会出申请自定义号申请不到的问题。第五章 V5单据号新方案介绍名词解释:业务独立事务：是指在前台发起一次调用批处处理多个相同的单据的批处理。处理的每一个业务单据为业务独立事务。1. 单据号新方案介绍方案：为每个前台连接建立回退区域，在连接关闭时一起退号；Ø 每个回退区域分为四个类型的段1、 删除单据号回退段a) 存放内容：删除业务，主动回退的单据号；b) 回退时机：业务正