红皮书-1.0单据号管理及开发新一代云ERP解决方案2目录一.前言..3二.单据号管理功能介绍..42.1.单据号编码规则定义.42.2.对象标识定义.62.3.单据号特点.7三.数据预制..83.1.单据对象.83.2.单据号编码规则.8四.对外接口..104.1.方法详细说明.114.2.申请批量单据号.124.3.删除单据号.13五.单据号方案介绍..145.1.单据号方案介绍.145.2.举例分析.15六.特殊功能介绍..176.1.公司级单据号规则.17新一代云ERP解决方案3一.前言在基于U8cloud的企业管理系统内，根据企业的特点和行业规范，存在着大量的业务单据和基础档案数据，如何标识这些数据？如何自动给每个新的业务单据分配一个唯一的单据号？并且保证单据号规则可以进行配置，可灵活嵌入业务对象、日期、时间及流水编号，还要求单据号可以保持连续，能自动在断号时进行补号，不重号，能处理集群及并发环境下的单据号申请，这些就是单据号管理模块需要解决的问题。对于应用产品和模块的开发人员，以上这些问题了解即可，主要面临的问题是如何在自己负责的业务单据中嵌入单据号管理功能，如何按标准规范去编写单据号相关代码。本红皮书主要的内容就是讲解如何开发各种单据类型的单据号管理功能，要给业务单据增加单据号管理功能，首先要为该单据类型定义单据编码规则，这样，申请单据号时将按照此规则生成唯一的单据号。另外如果单据编码规则定义中选择了单据对象，则要对单据对象（如部门）的每个具体对象（如开发部）定义对象标识（RD），这样该标识将出现在申请的单据号中。单据号管理功能请开发人员注意以下几点：增加了基础档案自动编号功能,初始化脚本在pub_billcode_basdoc里注册。不再强制要求在PUB_BILLCODE_RULE表里注册初始化脚本,开发人员可以直接到[单据号管理]节点,从头开始定义单据号规则。适合新单据的开发。单据对象管理增加规则定义，可以批量设置单据对象标识。单据号申请及回退增加了内存管理功能及自动事务提交功能，详情可以参考第5章“单据号方案介绍”新一代云ERP解决方案4二.单据号管理功能介绍2.1.单据号编码规则定义单据号编码规则初始是系统预制的，程序员发版前要提供pub_billcode_rule表的初始化脚本。集团可以修改单据号编码规则，而公司只能浏览各单据类型的编码规则。1.单据类型：以树型结构列示出系统内的单据类型。2.编码范围：用来控制该单据号是集团统一编码或各公司自成体系或按照对象统一编码。3.编码参数控制：如果设置唯一性检查，则申请的单据号不会和自定义单据号重复，唯一性检查范围和编码范围一致；如果单据号保留占用，则删除的单据号不会再利用；如果设置了自动补号，则回退的单据号会被申请得到。4.单据类型简称：可以定义单据类型简称作为单据号编码的一部分。这是可选项。新一代云ERP解决方案55.对象：最多可以选择两个对象作为单据号编码的一部分，如部门、仓库、存货分类、人员等。这两个对象也是可选，如果选择了对象，则此对象标识将出现在申请的单据号编码钟，具体的对象标识定义参见下一节。另外，对于不同的单据类型，其可以选择的对象可能不同，这部分数据是系统预制的。6.顺序号：单据编码中，用来表示单据的顺序号的一串数字，包括年月日及流水号。1)年：用2位字符来表示。2)月：用2位字符来表示。如果选了月，也必须选年。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.指定流水号：对于单据号编码范围是集团或公司，如果不希望单据号按照当前的流水号继续编号，则可以对此单据号编码规则重新指定流水号基准号。8.生成单据号时检查唯一性，如果选择，那么生成单据号时检查生成的单据号是否与用户自定义号重复，而不检查生成的单据号与以前生成的单据号是否重复，所以建议产品组开发人员在保存单据时自行检查新生成的单据号与现有单据是否重复。唯一性检查范围和编码范围一致。9.删除单据号时保留占用：该参数如果勾择，对于自动编号的单据，删除单据号时不会将删除的单据号回退到退号表，再增加新单据时，不会自动补前面的缺号，会自动生成一个新的单据号，但此时如果手工输入删除的单据号，仍可以保存。如果设置了自动补号，则回退的单据号会被申请得到。10.自动进行退号补号，如果选择，则生成单据号时会首先到回退表里去取，反之，则会新一代云ERP解决方案6直接生成新的单据号。需要注意的是，自定义号不会回退到退号表，如果发现自定义号被回退到退号表，则说明没用使用单据号申请API去申请自定义号，也就是说自定义号也需要调用API去申请一下，以便单据号模块统一管理。删除单据号时保留占用自动进行断号补号效果自动编号是是/否保留占用，不自动补号；但手工输入被删除的单号可以保存；否是自动补被删除的单据号；但手工输入被删除的单据号可以保存；否否不自动补号；但手工输入被删除的单据号可以保存；手工编号是是/否被占用的号码删除后，手工输入也不能用；否是/否被占用的号码删除后，手工输入可以使用；2.2.对象标识定义单据号对象也是系统预制的，程序员发版前需要提供pub_billcode_obj及pub_billobject的初始化脚本。对象的标识也是由集团设置，公司只能浏览。只有设置了对象的标识，使用此对象的单据号才能直观地表示出该对象。新一代云ERP解决方案7对象标识的设置尽量直观，该对象下的各标识长度必须保持一致。2.3.单据号特点 可针对不同单据类型灵活设置不同单据号编码规则。 单据号编码可集团统一，也可各公司自成体系，还可按照对象编码。 支持单个获取单据号，也支持批量获取单据号。 保证了单据号编码的唯一性与连续性，支持回退单据号的再获取。 单据号自动编码与自定义编码灵活结合。如果不希望系统自动获得单据号，用户可以手工输入单据号来获取此自定义编码的单据号。新一代云ERP解决方案8三.数据预制如前所述，单据号开发中的很多数据是通过初始化数据脚本进行系统预制的。3.1.单据对象1.单据对象的多语翻译resid：每个对象都有一个多语resid。只有新增加对象才有必要提供此数据脚本。如下例，dr为0，ts表示日期，objname为对象名称，resid表示多语id，pk_billobject表示pk：insertintopub_billobject(dr,ts,objname,resid,pk_billobject)values(0,'2005-03-1413:54:21','部门','obj-0000000000','smobj000000000000001')2.如下例，pk_billcodeobj表示pk，objname为对象名称，objref表示参照名称（如果是自定义的参照类，则要写类名，比如nc.ui.prm.ref.SaleStruRefModel），pk_billtypecode表示单据类型，objtablength表示单据对象长度，ts表示日期，dr为0：insertintopub_billcode_obj(pk_billcodeobj,objname,objref,pk_billtypecode,objtablength,ts,dr)values('sm200000000000000001','公司','公司目录','20',null,'2001-11-1212:09:43',0)3.2.单据号编码规则对于需要生成单据号的单据类型，都需要提供单据号编码规则数据脚本。如下例，pk_billcoderule表示pk，pk_billtypecode表示单据类型，billcodeshortname表示单据类型简称，ishaveshortname表示单据号是否需要单据类型简称,controlpara表示编码范围（'Y'表示集团，'N'表示公司，'O'表示对象）,ischeck表示是否进行唯一性检查,object1表示对象1名称,object2表示对象2名称,year表示单据号年,month表示单据号月,day表示单据号日,snnum表示流水号位数,lastsn为'0000',ts表示日期,dr为0：新一代云ERP解决方案9insertintopub_billcode_rule(pk_billcoderule,pk_billtypecode,billcodeshortname,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-2615:32:04',0)新一代云ERP解决方案10四.对外接口对于非独立事务的业务，原有独立事务回退号方法被删除，不再需要调用，现在只需要关心两个方法：(1)独立事务申请单据号，批量：BillcodeGenerater.getBatchBillCodes()；非批量：BillcodeGenerater.getBillCode()(2)删除单据时非独立事务回退单据号：IBillcodeRuleService.returnBillCodeOnDelete对于独立事务的业务，基本用法同上，但是需要额外调用另外3个方法：(1)申请单据号区域IBillcodeRuleService.requireNewRegion(Stringregionid)，用于开始独立事务之前(2)释放单据号区域IBillcodeRuleService.releaseRegion(Stringregionid),当业务正常结束时，调用此方法释放区域(3)停用单据号区域IBillcodeRuleService.stopRegion(Stringregionid),当业务非正常结束时，调用此方法固化此区域注意：(2)(3)方法是互斥的，不能同时被调用，写程序时请注意。推荐写法：try{//申请特定内存区域SFAppServiceUtil.getBillcodeRuleService().requireNewRegion(regionid);//做独立事务业务操作//释放申请的内存区域SFAppServiceUtil.getBillcodeRuleService().releaseRegion(regionid);}catch(Exceptione){//停止申请的内存区域SFAppServiceUtil.getBillcodeRuleService().stopRegion(regionid);新一代云ERP解决方案11//异常处理代码}4.1.方法详细说明getBillCode(StringbillTypeCode,Stringpkcorp,StringcustomBillCode,BillCodeObjValueVOvoBill)1.方法说明：获得一个可用的单据号。在申请一个单据号时调用此方法。申请单据号之前必须为该单据类型定义一个单据号编码规则，否则无法获得单据号。2.参数说明：1)billTypeCode表示单据类型编码，必须提供。2)pkcorp表示公司主键，如果此单据类型的单据号规则按照公司编码，则必须提供。3)customBillCode表示手工录入的单据号，如果没有提供手工单据号，则设置为null。4)voBill保存了用于单据号编码中各个对象的取值，对于某一种单据类型的每一个对象。如果此单据类型的单据号规则没有使用对象，则设置为null。voBill可以调用setAttributeValue(String[]name,Object[]value)或setAttributeValue(Stringname,Objectvalue)方法设置各个对象的属性值，name为对象名称，value为具体对象的主键值。例如，销售订单总共有两个对象：部门，业务员，而两个对象的主键值分别为“001”，“111”，那么可以编写如下代码：BillCodeObjValueVOvo=newBillCodeObjValueVO();vo.setAttributeValue(“部门”,”001”)；vo.setAttributeValue(“业务员”,”111”);或者BillCodeObjValueVOvo=newBillCodeObjValueVO();String[]names={“部门”,”业务员”};String[]values={“001”,”111”};vo.setAttributeValue(names,values);5)返回值说明：如果customBillCode非null，则返回此值，否则返回一个系统自动生成的单据号。新一代云ERP解决方案12如果自动生成的单据号中包含对象，但是没有为此对象定义标识，系统会根据该对象的标识长度生成由“*”组成的对象标识，例如“部门“对象标识长度为3，而没有为“开发部”定义对象标识，则使用此对象的单据号就会出现“***”。如果获取单据号失败，该方法将抛出nc.vo.pub.ValidationException例外，例外中保存了失败的原因，可用e.getMessage()获得。失败原因可能包括：此单据号规则正在同时申请；流水号超出了其设置的位数长度；申请的单据号还没有定义单据号编码规则。3.示例……StringcustomBillCode=null;Stringpkcorp=”1001”;StringbillTypecode=”30”;//生成一个BillCodeObjValueVOnc.vo.pub.billcodemanage.BillCodeObjValueVOvo=newnc.vo.pub.billcodemanage.BillCodeObjValueVO();vo.setAttributeValue("操作员",???);vo.setAttributeValue("业务类型",???);vo.setAttributeValue("部门",???);……Stringbillcode=null;billcode=（newBillcodeGenerater()）.getBillCode(billTypecode,pkcorp,customBillCode,vo);……4.2.申请批量单据号getBatchBillCodes(StringbillTypeCode,Stringpkcorp,StringcustomBillCode,BillCodeObjValueVOvoBill,intcount)此方法将获得多个单据号，具体返回多少个单据号由参数count指定。其和申请单个单据号的唯一区别是返回单据号的个数不同而已。但是此方法对于需要申请多个单据号的应用，能极大地提高效率，而不要利用循环一个一个地申请单据号。新一代云ERP解决方案134.3.删除单据号returnBillCodeOnDelete(Stringpkcorp,StringbillTypeCode,StringbillCode,BillCodeObjValueVOvoBill)此方法表示删除单据号billCode。如果此单据类型的单据号编码规则没有设置“删除单据号时保留占用”，则此单据号将回退；否则不会回退，下次申请单据号时不会再获取此单据号。该方法和上一个方法returnBillCode的参数完全一致，主要区别是：returnBillCode没有参数“删除单据号时保留占用”的限制，而本方法有；另外，本方法只存在于SFAppServiceUtil.getBillcodeRuleService()中，为非独立事务，BillcodeGenerater中没有本方法。注意：做业务时申请了单据号，如果在做业务过程中出现异常，也不要在catch块中调用本方法进行单据号回退，否则可能会出申请自定义号申请不到的问题。新一代云ERP解决方案14五.单据号方案介绍名词解释:业务独立事务：是指在前台发起一次调用批处处理多个相同的单据的批处理。处理的每一个业务单据为业务独立事务。5.1.单据号方案介绍方案：为每个前台连接建立回退区域，在连接关闭时一起退号；➢每个回退区域分为四个类型的段1、删除单据号回退段a)存放内容：删除业务，主动回退的单据号；b)回退时机：业务正常结束，连接关闭；2、新增单据号回退段a)存放内容：申请成功的单据号；b)回退时机：业务异常结束，连接关闭；3、业务独立事务：新增单据号回退段a)存放内容：按事务申请子段，每个字段存放该独立事务中申请成功的单据号。若事务正常结束则释放该子段，，即不需保留回退信息；b)业务结束，连接关闭（无条件）；4、业务独立事务：删除单据号回退段a)存放内容：按事务申请子段，每个字段存放该独立事务中删除业务，主动回退的单据号。若事务异常常结束则释放该子段，即不需回退；b)业务结束，连接关闭（无条件）；➢连接关闭时回退单据号与相关业务操作相应联系对照表类型成功失败删除单据号回退段回退新一代云ERP解决方案15新增单据号回退段回退独立事务新增单据号回退段回退回退独立事务删除单据号回退段回退回退➢独立事务业务代码调用对照表类型成功失败独立事务新增单据号回退段清除待回退数据独立事务删除单据号回退段清除待回退数据5.2.举例分析1.普通新增流程，无独立事务说明：图中绿色部分为申请单据号；代码流程为A-B-D-C顺序；分析：因为只有新增所以只创建业务失败回退段，申请成功将单据号放入段内；➢业务成功：不做任何处理，释放回退区域➢业务异常：假设C保存异常，但申请单据号成功段内数据：B1，D1，C1全部回退2.删除流程，无独立事务A审批B保存（B1）C保存（C1）B审批C审批D保存（D1）新一代云ERP解决方案16说明：图中绿色部分为申请单据号；代码流程为A-B-D-C顺序；分析：因为只有新增所以只创建业务成功回退段，将回退单据号放入段内；➢业务成功：回退单据号业务异常：不做任何操作D弃审B删除（B1）C删除（C1）A弃审A删除（D1）新一代云ERP解决方案17六.特殊功能介绍6.1.公司级单据号规则用户集团登陆，打开单据号规则节点，通过复制按钮，选择目标公司后，目标公司可以生成一条公司级单据号规则，该规则只能在公司修改。生成规则后，用户申请该公司该单据类型的单据号，系统将提供该公司级的单据号规则，而不是使用集团的。新一代云ERP解决方案18新一代云ERP解决方案NewGenerationofCloudERPSolution用友网络科技股份有限公司YonyouNetworkTechCo.Ltd.
