编号规则功能详细设计(2014版)(1).doc

版本：1.0 Beijing Targsoft Co.,Ltd TG-R-MB-XM-032 编号规则模块功能详细设计版本记录日期描述作者svn版本2014/1/22初稿潘微微1 模块说明1.1 模块作用编号规则属于工具模块，在系统的很多业务模块中都存在编号来标识数据，就需要有一个模块能尽量适用各种存在规律的编号的生成，编号规则负责该部分的工作，所以该模块属于工具模块，被各个地方所引用。1.2 名词解释l 编号：用于标识一个业务实例、数据条目的有一定业务规则的字串，业务称谓上通常由前缀、主号码、后缀等组成。整个编号字串从技术称谓上可以分为的一个或多个部份 ，这些部份叫“编号片段”，每个“编号片段”由一个原子级的编号规则构成。l 编号规则：本设计框架支持一套可扩展的编号规则库。目前本设计预制了以下几种规则：固定字串、自增（减）序号、枚举形序号库、年月日时分秒格式数字、当前账户组织单元属性、当前账户部门属性、当前账户人员属性、自定义参数注入。本系统将按这些规则实现不同的“规则提供器”。l 序号实例：对于自增（减）序号、枚举形序号规则系统建立序号实例库；这两种规则，需要根据不同的参数形成不同的序号实例。每个序号实例条目记录了：实例区分组合字串、当前序号最大（小）值等。1.3 原理与算法1.3.1 编号引擎1.3.2 规则定义说明规则定义分为：规则和规则明细定义。规则定义用于定义一个规则类型，用于识别不同的业务类型调用不同的编号规则。外部业务通过“单据类型编号”（TypeId）调用不同的编号规则。规则明细定义了编号片断的组成规则和需要配置的项目。规则明细以规则定义为表头。按排列顺序形成编号的组成规则。固定字段规则生成器：配置一个固定字串自增（减）序号：是按数字递增（简）规则产生编号片断的。可以配置数字格式如：“#”（缺位需用0补齐）或“#,#”（戴格式的数字）可以配置数字起步值、最大值、步长（负步长表示递减）。序号实例区分参数：支持的参数包括全部（除当前明细）的规则明细，这些明细可以按顺序配制成一个字串组合。当运行时，系统按当前请求根据这些参数组成一个字串，然后到“序号实例”库表里查找，如果没有找到，则创建数据条目并从本规则明细的数字起步值开始记录当前序号。如果找到，则从此条目当前序号加步长记录当前序号。此规则还可以通过“序号实例”界面查看当前所有序号实例条目数据，并支持单独维护（实例区分组合字串、当前参数值下的序号的实际值）。还可以配置是否强制连续序号：如果需要强制连续序号，则系统不再自主递增（减）序号，需要外部API来提交递增（减）序号。且如果跳号，则会抛错（具体算法见后面说明）。枚举形序号库：是按预定义好的序号库来输出编号片断的，比如：“A,B,C.”的字母顺序，当前如果是B了，则下次调用则产生C字母。序号库配置定义在规则明细上，采用“，”区分枚举项。还可以配置正序、倒序。仍可以配置“序号实例区分参数”和“配置是否强制连续序号”。（具体实现方案可以参照自增（减）序号规则提供器）年月日时分秒格式数字：从当前服务器时钟里获得编号片断的规则提供器。可以配置年月日时分秒的格式输出形式。当前账户组织单元属性、当前账户部门属性、当前账户人员属性：将从当前账户登录系统后形成的session里提取这些信息。系统支持“pertyname”形式配置提取信息。自定义参数注入：根据系统调用API的定义，支持从调用直接带入参数用于编号片断。系统支持前台ajaxAPI调用参数，基于json串识别参数名，参数值。后台map识别参数名，参数值。本规则可以配置一个参数名。还可以配置直接从：session、request、里提取参数。1.3.3 配置是否强制连续序号算法实现说明配置是否强制连续序号用于实现采用“由于自增（减）序号、枚举形序号库”的规则生成器。下面用是强制、否强制来简化称谓。否强制：系统将在调用编号请求API时就对序号进行自增（减）并持久化到序号实例库内。好处是使用简单，基本不用考虑序号重复问题。接近于随机数发生器。缺点是序号不连续（当产生时不提交业务或提交失败）。是强制：系统不会在调用编号请求API时就对序号进行自增（减），而是需要通过与业务提交同事务内的更新API来驱动对序号进行自增（减）并持久化到序号实例库内。举例某纯Integer数字递增序号提供器具体算法如下：调用时API分为初始化session缓存和获得编号两个API；假定获得编号时有两个session都要请求序号，而当前序号为4；则两个session内通过初始化API（用“实例区分组合字串”作为属性key）放入4（假定“实例区分组合字串”相同）。调用API时（此API从session里创建新序号）各装入（session1:567；session2:56789）则当前：session1最大序号值为7；session2为9。（如果界面都没有提交，则下次界面打开时需再次调用初始化API恢复真实序号最大值4）。如果提交业务，则需要调用更新写入序号API（提交编号API只能是后台API），对于session1，如上图：如果满足要持久化更新的编号个数与最大号是连续的，则进行持久化，按最大编号值更新序号实例库相应条目。对于session2假定8的序号由于业务没有使用，则需要更新5679，会因最大号与编号个数不一致抛出异常。由于与业务提交处于相同事务，则保证序号连续的一致性。如果session1和session2都正常提交了，提交API需要先从数据库内读取当前真实序号情况，然后识别当前提交是否是在当前序号基础上连续递增（减）的，如果不是则此事务也抛出异常。注意，初始化、获得、提交更新API都是以typeid为参数的，所以：session里应以typeid为key构建一个Map，再以编号明细的key为内部MAP构建值对象；对于序号类的规则，内部MAP的值为当前序号值。这套session内的数据结构用于维护一个事务中连续创建编号的情况（强制要求联号配置下）。1.4 参考文档1.5 模块注册表：模块名称模块ID上级模块说明编号规则（2014版）49970ad981c611e39ef4cddb3cb243e2systemManage2 相关页面界面说明2.1 编号规则入口页面2.1.1 /jsp/systemsettings/numBill/numBill/NumBillList.jsp列表结构：双表结构，主表为编号类别，子表为编号规则1） 编号类别的列表页面的数据来源于Num_NumBill表2） 编号规则的列表页面的数据来源于Num_NumRuler表3） 下面为页面格式查询条件：1） 主查询：类别编号 2） 高级查询：类别编号、类别名称 新建：通过“新建”可以创建编号类别，填写基本信息。 调用页面/jsp/systemsettings/numBill/numBill/NumBillEdit.jsp 进行编号类别的编辑工作。修改：通过修改可以维护基本信息。选择一条记录调用getObj方法获得记录，展示到编辑界面。调用numBillManagerAction.getObj方法删除：通过删除按钮能够删除编号类别 调用numBillManagerAction.delete新建规则明细：只通过该按钮可以创建子表数据（编号规则），点击该按钮会弹出下拉框选择创建的规则，创建不同的规则进入不同的的编辑页面。调用：/numRulerManagerAction.do?method=getObj方法，需要传入编号类别主键以及规则类别子表修改： 通过该按钮可以修改创建的规则。调用/numRulerManagerAction.do?method=getObj子表删除：调用该方法，可以删除规则 调用删除方法：/numRulerManagerAction.do?method=delete查看规则实例：只有自增减型字串、枚举型字串两种会存在规则实例，当业务调用编号规则主键时，会保存或者更新当前的编号实例库，记录当前使用的规则实例。通过“查看规则实例”按钮就能查看到生成的编号实例列表。调用/jsp/systemsettings/numBill/numRulerSub/NumRulerSubList.jsp? numRulerId=，传入规则类别的主键引用：/jsp/systemsettings/numBill/numBill/NumBillList.jsp资源注册及权限表：资源名称资源ID所属模块说明编号规则Num_NumBill49970ad981c611e39ef4cddb3cb243e2所属“编号规则（2014版）”操作点名称操作点ID数据过滤器说明维护9133900e81c611e39ef4cddb3cb243e22.1.2 /jsp/systemsettings/numBill/numBill/NumBillEdit.jsp保存：点击“保存”调用js中ajax方法，将数据更新或者保存到后台，保存成功后返回列表页面,调用NumBillEdit.js文件中的保存方法。规则类别编号：记录所属业务，用英文编制。编号类别名称：所属业务的描述。 创建人：默认当前人，从sessionScope中获取。创建时间：默认系统当前时间。状态类com.targ.systemsettings.numBill.numBill.uti.NumBillState.java草稿：0生效：1调用/numBillManagerAction.save(保存)/numBillManagerAction.update（更新）取消：取消返回编号规则的列表页面引用js: /jsp/systemsettings/numBill/numBill/NumBillEdit.js2.1.3 /jsp/systemsettings/numBill/numRuler/NumRulerEdit.jsp使用该页面文件的规则类别是：固定字串、时间字串、当前用户字串，其中的区分不大保存：点击“保存”调用js中ajax方法，将数据更新或者保存到后台，保存成功后返回列表页面,调用NumRulerEdit.js文件中的保存方法。规则类别编号：记录所属业务，从主表规则类别中代入展示。编号类别名称：所属业务的描述，从主表规则类别中代入展示。 规则类别：记录所属的规则类别的描述。固定字串：记录类别为“固定字串”规则中的描述，直接写字串即可。日期：可以选择日期，主要应用于记录规则复位的时间。日期格式：可以选择时间字串的日期格式，如果存在该格式会以选择的格式，进行格式化生成编号。当前用户信息：主要是从sesion中获取当前的用户的信息。是否输出：是否输出代表在生成编号的时候是否将生成的编号片段按顺序拼接到编号上。针对自增减字串、枚举型字串规则类别中的复合字串的拼接中不存在该区分。对应类：com.targ.systemsettings.numBill.numRuler.util.NumRulerEnum.java输出：true（拼接）不输出：false（不拼接）排序：排序是数字，按照编号规则的排序序号正序排序生成编号。创建人：默认当前人，从sessionScope中获取。创建时间：默认系统当前时间。调用/ numRulerManagerAction.save(保存)/ numRulerManagerAction.update（更新）取消：取消返回编号规则的列表页面引用js: /jsp/systemsettings/numBill/numRuler/NumRulerEdit.js2.1.4 /jsp/systemsettings/numBill/numRuler/NumRulerARSerialEdit.jsp使用该页面文件的规则类别是：自增（减）数字字串保存：点击“保存”调用js中ajax方法，将数据更新或者保存到后台，保存成功后返回列表页面,调用NumRulerEdit.js文件中的保存方法。规则类别编号：记录所属业务，从主表规则类别中代入展示。编号类别名称：所属业务的描述，从主表规则类别中代入展示。 规则类别：记录所属的规则类别的描述。是否连续：必须字段，是否连续代表在生成编号的时候生成的编号策略。不连续策略：获取，编号即被保存或更新入口，代表编号被占用。连续策略：获取，不占用编号，只有业务保存时调用编号保存接口，入库成功，代表编号被占用。对应类：com.targ.systemsettings.numBill.numRuler.util.NumRulerEnum.java连续：true不连续：false起步值：必须字段，代表生成编号的首位编号值。步长：必须字段，代表生成编号时，从当前编号值，增加或者减少几步。最大值：必须字段，代表生成编号时最大的值，如果超出最大值范围则抛出异常。序号：必须字段，排序是数字，按照编号规则的排序序号正序排序生成编号。序列格式：非必需必须字段，如果不填写按照原有生成数字拼接字串，如果存在格式，则生成数字后，需要对数字进行格式化，以#作为数字的占位符，不够最大值的位数以0填补。格式要求：#作为数字的占位符，且不够位数以0填补,例如：123，456_78对应格式#，#_#组合字串：必须字段，通过开窗选择组合字串，组合字串是本编号类别下的编号规则，当编号被调用入口时，通过组合字串获取每个规则的编号，拼接后入库到规则实例表中。组合字串作用：是否复位组合字串要求规则类别是：固定字串、当前用户信息字串、时间字串。备注：非必需字段创建人：默认当前人，从sessionScope中获取。创建时间：默认系统当前时间。调用/ numRulerManagerAction.save(保存)/ numRulerManagerAction.update（更新）取消：取消返回编号规则的列表页面引用js: /jsp/systemsettings/numBill/numRuler/NumRulerEdit.js2.1.5 /jsp/systemsettings/numBill/numRuler/NumRulerEdit.jsp使用该页面文件的规则类别是：枚举型字串保存：点击“保存”调用js中ajax方法，将数据更新或者保存到后台，保存成功后返回列表页面,调用NumRulerEdit.js文件中的保存方法。规则类别编号：记录所属业务，从主表规则类别中代入展示。编号类别名称：所属业务的描述，从主表规则类别中代入展示。 规则类别：记录所属的规则类别的描述。是否连续：必须字段，是否连续代表在生成编号的时候生成的编号策略。不连续策略：获取，编号即被保存或更新入口，代表编号被占用。连续策略：获取，不占用编号，只有业务保存时调用编号保存接口，入库成功，代表编号被占用。对应类：com.targ.systemsettings.numBill.numRuler.util.NumRulerEnum.java连续：true不连续：false起步值：必须字段，代表生成编号的首位编号值。步长：必须字段，代表生成编号时，从当前编号值，增加或者减少几步。序号库：记录“枚举型字串”类别的编号，数据来源，其中不同的数据以应为逗号”,”区分开，超出最后一个数据字串时抛出异常。序号：必须字段，排序是数字，按照编号规则的排序序号正序排序生成编号。组合字串：必须字段，通过开窗选择组合字串，组合字串是本编号类别下的编号规则，当编号被调用入口时，通过组合字串获取每个规则的编号，拼接后入库到规则实例表中。组合字串作用：是否复位组合字串要求规则类别是：固定字串、当前用户信息字串、时间字串。备注：非必需字段创建人：默认当前人，从sessionScope中获取。创建时间：默认系统当前时间。调用/ numRulerManagerAction.save(保存)/ numRulerManagerAction.update（更新）取消：取消返回编号规则的列表页面引用js: /jsp/systemsettings/numBill/numRuler/NumRulerEdit.js2.2 编号规则实例2.2.1 /jsp/systemsettings/numBill/numRulerSub/NumRulerSubList.jsp结构：单列表结构，数据来源于Num_NumRulerSub引用的js：/jsp/systemsettings/numBill/numRulerSub/NumRulerSubList.js在该文件里定义了向后台请求的查询方法,查询的数据是Num_NumRulerSub修改：通过修改可以维护基本信息。选择一条记录调用getObj方法获得记录，展示到编辑界面。编辑界面只能修改当前值调用numRulerSubManagerAction.getObj方法删除：通过删除按钮能够删除编号类别 调用numRulerSubManagerAction.delete2.2.2 /jsp/systemsettings/numBill/numRulerSub/NumRulerSubEdit.jsp保存：通过“保存”按钮调用NumRulerSubEdit.js中的ajax方法，将界面数据保存到数据库，成功后返回列表页面。调用后台方法：numRulerSubManagerAction.update取消：关闭当前窗口，返回列表页面。页面元素：当前序列值：只能修改当前序列值，即当前最后一个使用的编号。 引用：/jsp/systemsettings/numBill/numRulerSub/NumRulerSubEdit.js2.3 日期格式开窗组件2.3.1 /jsp/systemsettings/numBill/window/DateFormatWin.js功能说明：该组建主要应用于时间字串的编号规则，是选择日期格式的开窗组建。调用说明：1. 引入js文件/jsp/systemsettings/numBill/window/DateFormatWin.js2.初始化开窗var dateFormatWin ; /变量，不固定$(function()dateFormatWin = getDateFormatWindow(dataFormatId:serialformat); )dataFormatId：代表选择格式后，将格式字串打入的文本框组建的id3.调用selectWindow();开窗2.4 组合字串开窗组件2.4.1 /jsp/systemsettings/numBill/window/numRulerWin.js功能说明：该组建主要是应用于自增减型字串、枚举型字串的规则，通过该组件选择组合字串（即规则），该组合字串将从当前的编号类别中过滤出规则类别为：固定字串、时间字串、当前用户信息字串3种规则。调用说明：1. 引入js文件/jsp/systemsettings/numBill/window/numRulerWin.js2. 初始化a) numRulerId：为规则的主键的文本框idb) singleSelected：true代表单选,false代表表多选c) callback：为回调函数d) baseParams：代表给想后台请求传入的基础参数，一般是numBillId（编号类别主键）var numRulerWindows;/开窗变量$(function()numRulerWindows=getSelectNumRulerWindow(numRulerId :combNumRulerIdssingleSelected:false ,callback:setNumRuler,baseParams:serialRulerTypes:fixedSerial,dateSerial,userInfoSerial,numBillId:$(#numBillId).val();)3. 通过selectNumRuler()调用，弹出开窗选择2.5 编号生成器组件（供外部模块调用）2.5.1 /jsp/systemsettings/numBill/window/numGenerator.js功能说明：该组件主要是给外部模块生成编号时调用的，该文件应该有两个方法：方法1：/初始化编号规则并且获取首个编号 /setNumId：文本框id/typeId：编号规则中已经注册的编号规则类别function getInitNum(setNumId, typeId)；方法2： /如果需要额外的编号，初始化后只需要调用本方法获取编号即可/如果需要连续的号码，则还需通过后台调用编号的NumGeneratorService。saveNumGenerator接口/setNumId：文本框id/typeId：编号规则中已经注册的规则类型编号function getGeneratorNum(setNumId, typeId)调用说明：1. 引入js/jsp/systemsettings/numBill/window/numGenerator.js2. 初始化getInitNum(enterPersonName, exa_examination);$(function()/enterPersonName为文本框id，返回的编号会打入该文本框/ examination注册的规则类型编号getInitNum(enterPersonName, exa_examination1);)3. 获取编号（如果需要多个编号，在调用完初始化之后，只需要调用本方法即可）/如果需要额外的编号，初始化后只需要调用本方法获取编号即可/如果需要连续的号码，则还需通过后台调用编号的saveNumGenerator接口/setNumId：文本框id/typeId：编号规则中已经注册的编号规则类别getGeneratorNum(setNumId, typeId)4. 调用如果在注册编号规则时存在“自增减数字字串”、“枚举型字串”，并且设置成连续字串，则还需要在获取编号的业务的更新或者保存方法的事务中调用：targ.systemsettings.numBill.numGenerator.service.NumGeneratorService.saveNumGenerator接口保存，占用的编号。3 功能模块设计 模块类UML图: 模块代码列表：模块包体结构编号规则主体包结构 numBill编号类别包编号规则包编号实例包结构编号生成器包结构3.1 编号规则类别3.1.1 NumBillManagerAction.java类功能说明：处理数据加载、保存请求等接口说明：1.调用 NumBillService, 获得查询数据；2调用NumBillService，增、删、改。增加方法注意事项：3.1.2 NumBillForm类功能说明：是 ActionForm ，用于接收 NumBillEdit.jsp 表单提交的数据接口说明：注意事项：3.1.3 NumBillService类功能说明：在一个事物里处理数据的增、删、改，以及加载数据主要是可以被Action层调用接口说明：1.调用 NumBillDAO, 获得查询数据；2调用NumBillDAO，增、删、改。注意事项：3.1.4 NumBillDAO 类功能说明：与数据库交互实现 数据的存储，编辑、删除，查询接口说明：调用hibernate的方法保存、删除、修改、方法、查询注意事项：继承 BaseDao3.1.5 Spring配置文件applicationContext_NumBill.xml3.2 编号规则3.2.1 NumRulerManagerAction类功能说明：处理数据加载、保存请求等接口说明：1.调用 NumRulerService, 获得查询数据；2调用NumRulerService，增、删、改。注意事项：3.2.2 NumRulerForm类功能说明：是 ActionForm ，用于接收 NumRulerEdit.jsp/NumRulerARSerialEdit.jsp/NumRulerEnumSerialEdit.jsp表单提交的数据接口说明：注意事项：3.2.3 NumRulerService类功能说明：在一个事物里处理数据的增、删、改，以及加载数据主要是可以被Action层调用接口说明：1.调用 NumRulerDAO, 获得查询数据； 2调用NumRulerDAO，增、删、改。注意事项：3.2.4 NumRulerDAO 类功能说明：与数据库交互实现 数据的存储，编辑、删除，查询/* * 查询一个单据编号下制定类型的规则，编号类别是有效的 * param typeId 编号类别 * param serialRulerType 规则类别 * return */public List getNumRulerListByBumBillId(String typeId, String serialRulerType)接口说明：调用hibernate的方法保存、删除、修改、方法、查询注意事项：继承 BaseDao3.2.5 Spring配置文件applicationContext_NumBill.xml3.3 规则实例3.3.1 NumRulerSubManagerAction类功能说明：处理数据加载、保存请求等接口说明：1.调用 NumRulerSubService, 获得查询数据；2.用NumRulerSubService，增、删、改。注意事项：3.3.2 NumRulerSubForm类功能说明：是 ActionForm ，用于接收 NumRulerSubEdit.jsp 表单提交的数据接口说明：注意事项：3.3.3 NumRulerSubService类功能说明：在一个事物里处理数据的增、删、改，以及加载数据最主要的功能是实现推荐数据的交互，需要引入NumRulerSubDAO类进行数据保存。主要是可以被Action层调用接口说明：1.调用 NumRulerSubDAO, 获得查询数据；2调用NumRulerSubDAO，增、删、改。注意事项：3.3.4 NumRulerSubDAO 类功能说明：与数据库交互实现 数据的存储，编辑、删除，查询接口说明：调用hibernate的方法保存、删除、修改、方法、查询增加方法/* * 获得当前的编号实例 * param numRulerId 规则主键 * param combNum 组合字串 * return */public List getNumRulerSubList(String numRulerId,String combNum);注意事项：继承 BaseDao3.3.5 Spring配置文件applicationContext_NumBill.xml3.4 编号生成器3.4.1 NumGene