NCV6编码规则红皮书修订版1113.docx

1、NCV6编码规则红皮书修订版1113编码规则红皮书1. 前言在nc中常常会有需要给新生成的单据一个单据编码，或某档案需要一个档案编码的情况，为了免除手工输入编码的情况，nc提供了自动生成单据号的功能。在nc中，用户可以按照需要，来为单据类型定义单据号编码规则，然后在生成单据号时，按照定义的编码规则来自动生成单据号，本文档就是对致力于解决这方面的需求的功能的说明。2. 功能介绍2.1 基本概念单据编码通常包含固定的字符串、分隔符、单据相关的数据项的值、时间和编号构成，在编码规则中用四种编码元素来描述上述的编码项： 固定值：来表示固定字符串和分隔符； 编码实体：来表示与单据相关的数据项的值（客商，

2、人员），而这些值通常不是简单的使用其编码名称等，通过编码映射功能（见2.2），将这些值映射为最终展现到编码段中的值。 时间项：来表示时间属性，包含系统时间（取值为服务器时间）和业务时间（取值为单据上的相关时间项，如制单日期等）； 流水号：用来顺序记录单据编号的定长号；2.2 编码映射这个功能是为了定义单据编码中能够使用的参与编码的实体的具体值转换为编码中出现的编码值的转换关系。下图就是编码映射节点：左侧树上的节点，就是可供编码规则定义使用的业务实体。在编码对象和编码实体关联表中注册了编码对象需要使用的编码实体，为编码实体定义映射规则有几个关键属性： 映射值长度：最终要体现在编码中的值的长度，一

3、旦设置不能改变； 补位方式：即如果通过转换规则的到的映射值长度不够，那么需要进行补位，补位可以在映射值的左边，也可以在右边； 补位符号：用什么占位符来为映射值补位；把实体值转换为映射值有两种方式： 通过公式定义默认的转换规则：编码实体的大多数值通过该方式定义，首先为编辑公式定义变量，这里最多支持两个变量，然后点击默认规则按钮，调用公式编辑器来定义公式即可。后台生成编码时，会根据定义的变量和公式自动算出映射值拼到编码中。 离散的为特定的编码实体值定义映射值：可以直接为特定的编码实体值定义要显示的编码值。后台生成编码时，直接到离散值定义表中查出值即可。在实体引用页签里面会列出引用了该编码实体的编码

4、规则，以便在进行修改映射规则时可以了解对那些编码规则产生了影响。2.3 编码规则定义首先介绍一下这个功能节点下的最基本的功能规则定义，一个完整的编码规则包含了基本信息和编码元素各部分，下面分别解释之。下图是编码规则定义页面：编码规则的基本信息包含如下几项： 规则编码，规则名称：左侧树上显示的是规则的名称； 编码方式：前编码方式即在用户新增单据时即生成编码，此时新增单据很多相关项 还没有赋值，所以前编码方式不能支持在编码中出现业务实体和业务时间，后编码方式是在用户新增单据后，保存时生成单据编码，没有什么特殊限制； 编码是否可编辑：对于前编码方式可用，控制单据编码的可编辑性； 是否断码补码：如果删

5、除一个单据，或者申请一个单据出错，那么它们所使用的单据号是否要再被使用。编码的可编辑性和断码补码是互斥的。 按组织归零：流水号是否随着组织的改变而重新计数，注意：如果按组织归零，且编码元素中不含有组织字段，那么编码唯一性校验范围就只能是组织级的。 是否集团默认规则：集团默认使用的规则，如果组织没有分配编码规则那么就使用这个默认规则，一个集团只能有一个默认规则。前文提到，编码元素包括固定值，编码实体，时间属性，流水号。编码规则由上述四种或其中几种组成，每种元素可以在编码规则中多次出现（当然流水好多次出现会看起来有点怪，但是如果喜欢也没问题）。对于每一个编码元素，有如下四种属性： 元素类型：固定值

6、，编码实体，时间属性，流水号； 元素值：固定值就是用户自定义的字符串；如果编码对象定义了元数据，那么业务实体值就是元数据上定义的属性，该属性必须是在编码映射中定义的且此编码对象可使用，如果非元数据，那么从单据类型与实体关联表中获取数据；如果是时间类型，编码对象定义了元数据，那么可以选择元数据上定义的时间属性或者系统时间作为值；流水号无此属性； 是否流水依据：此属性是针对编码实体和时间类型的。如果是编码实体，那么对于每一个实体值，都重新开始计数；对于时间类型，可以选择按年归零，按月归零，按日归零，这样在新的一年（月、日）流水号重新计数。 长度：对于固定值，长度即是输入的字符串长；对于业务实体，就

7、是在实体映射值设置的长度；对于时间，根据时间格式来确定最大长度；对于流水号，这个值是可编辑的，输入一个认为合适的长度。上文阐述集团默认规则时，提到规则分配。在NCV6中，在一个集团里，同一个单据类型可以定义多个单据编码规则，通过规则分配功能把编码规则分配给不同的组织，每个组织在同一单据类型下只能有一条编码规则，所以集团、组织、单据类型三个维度唯一确定一条单据编码规则。如果在该集团下，某组织在某单据下没有分配单据编码规则，那么将使用集团默认的单据编码规则。下面是规则分配页面，可分配规则范围通过需编码对象的组织类型确定（详见第4章）。此外，还可以对流水号和断号进行管理功能，对同一编码规则，因为设置

8、了流水依据，会根据流水依据的不同的值的组合，生成多套流水号，每套流水号都会有根据流水依据产生的唯一标识，可以手工修改流水号，修改后，流水号以当前修改的值作为基准继续流水。断号管理可以查看不同标识的流水断号情况。3. 接口介绍对于后编码非独立事务的业务：(1) 独立事务申请单据号，批量：单据基于元数据模型：IBillcodeManage. getBatchBillCodes_RequiresNew(String billTypeCode, String pk_group,String pk_org,Object billvo,int num) ;参数说明：billTypeCode 单据类型pk_

9、group 集团主键pk_org 组织主键billvo 编码实体数据需编码的单据是基于元数据的，billvo为单据vo， num 批取编码的数量单据不是基于元数据模型：IBillcodeManage.getBillCodeNoMeta_RequiresNew (String billTypeCode, String pk_group,String pk_org, EntityValueVO entivalue,int num)参数说明： EntityValueVO中存放编码实体和实体值对，类似于v5系列里面的BillCodeObjValueVO，如果是编码实体，那么键值是编码实体名称，如果编码

10、规则中使用业务时间，请把EntityValueVO.BUSITIME作为键，把具体时间作为值传到后台。非批量：单据基于元数据模型：IBillcodeManage.getBillCode_RequiresNew(String billTypeCode, String pk_group,String pk_org, String customBillCode,Object billvo);参数说明：customBillCode 自定义编码单据不是基于元数据模型：IBillcodeManage.getBatchBillCodesNoMeta_RequiresNew(String billTypeCo

11、de, String pk_group,String pk_org, String customBillCode,EntityValueVO entivalue) (2) 删除单据时非独立事务回退单据号：单据基于元数据模型：IBillcodeManage.returnBillCodeOnDelete (String billTypeCode, String pk_group,String pk_org, String billCode,Object billvo)单据不是基于元数据模型：returnBillCodeOnDeleteNoMeta(String billTypeCode, Stri

12、ng pk_group,String pk_org, String billCode,EntityValueVO entivalue)对于独立事务的业务，基本用法同上，但是需要额外调用另外3个方法：(1) 申请单据号区域 IBillcodeManage.requireNewRegion(String regionid)，用于开始独立事务之前(2) 释放单据号区域 IBillcodeManage.releaseRegion(String regionid),当业务正常结束时，调用此方法释放区域(3) 停用单据号区域 IBillcodeManage.stopRegion(String region

13、id),当业务非正常结束时，调用此方法固化此区域注意：(2)(3)方法是互斥的，不能同时被调用，写程序时请注意。推荐写法：try/申请特定内存区域SFAppServiceUtil. getBillcodeManage().requireNewRegion(regionid);/做独立事务业务操作/释放申请的内存区域SFAppServiceUtil. getBillcodeManage().releaseRegion(regionid);catch (Exception e) /停止申请的内存区域 SFAppServiceUtil. getBillcodeManage().stopRegion(

14、regionid); /异常处理代码对于前编码方式：获得前编码IBillcodeManage.getPreBillCode(String billTypeCode,String pk_group,String pk_org) 返回值 PreCodeResult返回值说明 PreCodeResult 包括两个属性，一个就是返回的编码，另一个是是否可编辑，如果不可编辑，需要调用者将编码的编辑器设为enable保存提交编码IBillcodeMmitPreBillCode(String billTypeCode,String pk_group,String pk_org,String customco

15、de,String billcode) 参数说明：customcode 从编码编辑器中获得的编码，Billcode 获取的前编码 单据保存时调用该方法提交生成的前编码。 取消回滚编码 IBillcodeManage. rollbackPreBillCode(String billTypeCode,String pk_group,String pk_org,String billcode) 参数说明：Billcode 获取的前编码单据取消时调用该方法提交生成的前编码注意：使用前编码方式时一定要按照要求对前编码进行提交或回滚，否则将有问题4. 开发流程给一个需要编码的对象定义编码规则需要以下流程：

16、 Step1：5系列编码规则都是基于单据类型的，在6中编码规则与单据类型无关，需要维护一个需编码对象注册表，要在pub_billcode_nbcr中注册需要编码的对象的信息，这样该对象才会显示到编码规则定义页面左侧的树中。该表字段说明如下：字段编码字段名称说明pk_nbcr主键metaid元数据id如果非元数据为空code编码使用一个易记唯一的编码，将作为该对象的标识name1名称1名称，支持多语name2名称2名称，支持多语name3名称3名称，支持多语codestyle编码类型支持的编码方式，在IBCRConst中定义codescope编码范围编码规则的定义范围，在IBCRConst中定义

17、orgtype组织类型编码规则的可分配组织，在改组织类型下codelenth编码长度编码的最大长度 Step2：注册编码对象要使用的编码属性，即编码对象和编码映射的关联关系，编码映射能够使用的资源一定是定义过元数据的，所以关联关系体现为编码对象主键和元数据id之间的关联，目标表：pub_billcode_entityrela Step3：进入编码映射节点，该页面会列出在第二步关联的所有元数据实体，为这些实体设置映射值，映射值范围为集团。 Step4：进入编码规则页面，找到相应的编码对象开始定义编码规则，如果使用编码实体，那么参照的编码实体就是在关联表中关联了的，且在编码映射节点定义了的编码实体

18、。 Step5：在代码中区分不同的业务场景，调用编码规则提供接口生成单据号。具体的业务场景在下一章介绍。5. 典型业务场景介绍 新增单据首先，调用IBillcodeManage.getBillCodeContext（）得到BillCodeContext，根据这个编码的上下文信息得到当前编码规则的一些属性，包括是否前编码方式，是否可编辑。如果是前编码方式，调用IBillcodeManage.getPreBillCode_RequiresNew（）得到前编码，将编码值设置到编码编辑器中，再跟据可编辑性设置单据编码编辑器的可编辑性。保存成功调IBillcodeMmitPreBillCode （），反

19、之IBillcodeManage.rollbackPreBillCode（），如果取消调IBillcodeManage.rollbackPreBillCode（）。如果是后编码方式，调用getBillCode_RequiresNew得到编码设置到编码字段即可。无论哪种方式保存单据时，如果校验单据号重复，那么抛出DuplicateException，当捕捉到该异常时，调用弃号AbandonBillCode_RequiresNew。 修改单据同上，先得到BillCodeContext，根据可编辑属性设置编辑器的编辑性。 删除单据调用IBillcodeManage.returnBillCodeOnDelete（）。