NCV5单据号管理及开发红皮书.docx
《NCV5单据号管理及开发红皮书.docx》由会员分享，可在线阅读，更多相关《NCV5单据号管理及开发红皮书.docx（14页珍藏版）》请在冰豆网上搜索。
NCV5单据号管理及开发红皮书
单据号管理及开发
技术红皮书
NC-UAP5.0
用友NC-UAP
2018-10-13
目录
第一章前言1
第二章单据号管理功能介绍2
1.单据号编码规则定义2
2.对象标识定义3
3.单据号特点4
第三章数据预制5
1.单据对象5
2.单据号编码规则5
第四章对外接口6
1.方法详细说明7
2.申请批量单据号8
3.回退单据号（已经删除）8
4.删除单据号8
第五章V5单据号新方案介绍10
1.单据号新方案介绍10
2.举例分析11
第一章前言
在基于UAP-NC的企业管理系统内，根据企业的特点和行业规范，存在着大量的业务单据和基础档案数据，如何标识这些数据？
如何自动给每个新的业务单据分配一个唯一的单据号？
并且保证单据号规则可以进行配置，可灵活嵌入业务对象、日期、时间及流水编号，还要求单据号可以保持连续，能自动在断号时进行补号，不重号，能处理集群及并发环境下的单据号申请，这些就是单据号管理模块需要解决的问题。
对于应用产品和模块的开发人员，以上这些问题了解即可，主要面临的问题是如何在自己负责的业务单据中嵌入单据号管理功能，如何按标准规范去编写单据号相关代码。
本红皮书主要的内容就是讲解如何开发各种单据类型的单据号管理功能，要给业务单据增加单据号管理功能，首先要为该单据类型定义单据编码规则，这样，申请单据号时将按照此规则生成唯一的单据号。
另外如果单据编码规则定义中选择了单据对象，则要对单据对象（如部门）的每个具体对象（如开发部）定义对象标识（RD），这样该标识将出现在申请的单据号中。
NCV5版本的单据号管理功能较以前版本有一些变化和改进，请开发人员注意，主要体现在以下几点：
⏹V5版本中增加了基础档案自动编号功能,初始化脚本在pub_billcode_basdoc里注册。
⏹V5版本不再强制要求在PUB_BILLCODE_RULE表里注册初始化脚本,开发人员可以直接到[单据号管理]节点,从头开始定义单据号规则。
适合新单据的开发。
⏹单据对象管理增加规则定义，可以批量设置单据对象标识。
⏹单据号申请及回退增加了内存管理功能及自动事务提交功能，详情可以参考第4章“单据号管理新方案”
由于API调用规范较以前版本有一些变化，所以开发人员在调用时请参考第5节，需严格按照规范进行代码调用，以免出现重号、丢号问题。
第二章单据号管理功能介绍
1.单据号编码规则定义
单据号编码规则初始是系统预制的，程序员发版前要提供pub_billcode_rule表的初始化脚本。
集团可以修改单据号编码规则，而公司只能浏览各单据类型的编码规则。
1.单据类型：
以树型结构列示出系统内的单据类型。
2.编码范围：
用来控制该单据号是集团统一编码或各公司自成体系或按照对象统一编码。
3.编码参数控制：
如果设置唯一性检查，则申请的单据号不会和自定义单据号重复，唯一性检查范围和编码范围一致；如果单据号保留占用，则删除的单据号不会再利用；如果设置了自动补号，则回退的单据号会被申请得到。
4.单据类型简称：
可以定义单据类型简称作为单据号编码的一部分。
这是可选项。
5.对象：
最多可以选择两个对象作为单据号编码的一部分，如部门、仓库、存货分类、人员等。
这两个对象也是可选，如果选择了对象，则此对象标识将出现在申请的单据号编码钟，具体的对象标识定义参见下一节。
另外，对于不同的单据类型，其可以选择的对象可能不同，这部分数据是系统预制的。
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.指定流水号：
对于单据号编码范围是集团或公司，如果不希望单据号按照当前的流水号继续编号，则可以对此单据号编码规则重新指定流水号基准号。
2.对象标识定义
单据号对象也是系统预制的，程序员发版前需要提供pub_billcode_obj及pub_billobject的初始化脚本。
对象的标识也是由集团设置，公司只能浏览。
只有设置了对象的标识，使用此对象的单据号才能直观地表示出该对象。
对象标识的设置尽量直观，该对象下的各标识长度必须保持一致。
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）
2.单据号编码规则
对于需要生成单据号的单据类型，都需要提供单据号编码规则数据脚本。
如下例，pk_billcoderule表示pk，pk_billtypecode表示单据类型，billcodeshortname表示单据类型简称，ishaveshortname表示单据号是否需要单据类型简称,controlpara表示编码范围（'Y'表示集团，'N'表示公司，'0'表示对象）,ischeck表示是否进行唯一性检查,object1表示对象1名称,object2表示对象2名称,year表示单据号年,month表示单据号月,day表示单据号日,snnum表示流水号位数,lastsn为'0000',ts表示日期,dr为0：
insertintopub_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）
第四章对外接口
对于非独立事务的业务，原有独立事务回退号方法被删除，不再需要调用，现在只需要关心两个方法：
（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）;
//异常处理代码
}
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，则返回此值，否则返回一个系统自动生成的单据号。
如果自动生成的单据号中包含对象，但是没有为此对象定义标识，系统会根据该对象的标识长度生成由“*”组成的对象标识，例如“部门“对象标识长度为3，而没有为“开发部”定义对象标识，则使用此对象的单据号就会出现“***”。
如果获取单据号失败，该方法将抛出nc.vo.pub.ValidationException例外，例外中保存了失败的原因，可用e.getMessage（）获得。
失败原因可能包括：
此单据号规则正在同时申请；流水号超出了其设置的位数长度；申请的单据号还没有定义单据号编码规则。
3.示例
……
StringcustomBillCode=null;
Stringpkcorp=”1001”;
StringbillTypecode=”30”;
//生成一个BillCodeObjValueVO
nc.vo.pub.billcodemanage.BillCodeObjValueVO
vo=newnc.vo.pub.billcodemanage.BillCodeObjValueVO（）;
vo.setAttributeValue（"操作员",?
?
?
）;
vo.setAttributeValue（"业务类型",?
?
?
）;
vo.setAttributeValue（"部门",?
?
?
）;
……
Stringbillcode=null;
billcode=（newBillcodeGenerater（））.getBillCode（billTypecode,pkcorp,customBillCode,vo）;
……
2.申请批量单据号
getBatchBillCodes（StringbillTypeCode,Stringpkcorp,StringcustomBillCode,BillCodeObjValueVOvoBill,intcount）
此方法将获得多个单据号，具体返回多少个单据号由参数count指定。
其和申请单个单据号的唯一区别是返回单据号的个数不同而已。
但是此方法对于需要申请多个单据号的应用，能极大地提高效率，而不要利用循环一个一个地申请单据号。
3.回退单据号（已经删除）
returnBillCode（Stringpkcorp,StringbillTypeCode,StringbillCode,
BillCodeObjValueVOvoBill）
此方法已被删除，对于业务操作中所有新申请的单据号，如果业务失败，将被自动回退，无需外界调用。
此方法将对指定的单据号billCode进行回退，此回退的单据号下次可以被申请获得。
如果是自定义单据号回退，则下次可以再申请此自定义单据号，而不会检查到此单据号重复。
如果此单据类型的单据号编码规则的年、月、日和要回退的单据号billCode中的年、月、日不一致，则此单据号不会回退，比如：
单据号编码规则的年、月、日分别为05、08、28，则单据号RM0508240001不会回退，由于此单据号是24日的，和28号不匹配。
参数pkcorp、billTypeCode、voBill和前面的方法参数用法类似。
4.删除单据号
returnBillCodeOnDelete（Stringpkcorp,StringbillTypeCode,StringbillCode,
BillCodeObjValueVOvoBill）
此方法表示删除单据号billCode。
如果此单据类型的单据号编码规则没有设置“删除单据号时保留占用”，则此单据号将回退；否则不会回退，下次申请单据号时不会再获取此单据号。
该方法和上一个方法returnBillCode的参数完全一致，主要区别是：
returnBillCode没有参数“删除单据号时保留占用”的限制，而本方法有；另外，本方法只存在于SFAppServiceUtil.getBillcodeRuleService（）中，为非独立事务，BillcodeGenerater中没有本方法。
第五章V5单据号新方案介绍
名词解释:
业务独立事务：
是指在前台发起一次调用批处处理多个相同的单据的批处理。
处理的每一个业务单据为业务独立事务。
1.单据号新方案介绍
方案：
为每个前台连接建立回退区域，在连接关闭时一起退号；
Ø每个回退区域分为四个类型的段
1、删除单据号回退段
a）存放内容：
删除业务，主动回退的单据号；
b）回退时机：
业务正常结束，连接关闭；
2、新增单据号回退段
a）存放内容：
申请成功的单据号；
b）回退时机：
业务异常结束，连接关闭；
3、业务独立事务：
新增单据号回退段
a）存放内容：
按事务申请子段，每个字段存放该独立事务中申请成功的单据号。
若事务正常结束则释放该子段，，即不需保留回退信息；
b）业务结束，连接关闭（无条件）；
4、业务独立事务：
删除单据号回退段
a）存放内容：
按事务申请子段，每个字段存放该独立事务中删除业务，主动回退的单据号。
若事务异常常结束则释放该子段，即不需回退；
b）业务结束，连接关闭（无条件）；
Ø连接关闭时回退单据号与相关业务操作相应联系对照表
类型
成功
失败
删除单据号回退段
回退
新增单据号回退段
回退
独立事务新增单据号回退段
回退
回退
独立事务删除单据号回退段
回退
回退
Ø独立事务业务代码调用对照表
类型
成功
失败
独立事务新增单据号回退段
清除待回退数据
独立事务删除单据号回退段
清除待回退数据
2.举例分析
1.普通新增流程，无独立事务
说明：
图中绿色部分为申请单据号；
代码流程为A-B-D-C顺序；
分析：
因为只有新增所以只创建业务失败回退段，申请成功将单据号放入段内；
Ø业务成功：
不做任何处理，释放回退区域
Ø业务异常：
假设C保存异常，但申请单据号成功
段内数据：
B1，D1，C1全部回退
2.删除流程，无独立事务
说明：
图中绿色部分为申请单据号；
代码流程为A-B-D-C顺序；
分析：
因为只有新增所以只创建业务成功回退段，将回退单据号放入段内；
Ø业务成功：
回退单据号
业务异常：
不做任何操作
升级会员 