基于Unieap的物资申领系统设计：主子表、审批流与分页导出

简介Unieap 简单小项目面向刚接触业务流程管理框架的 Java 开发者与初学者提供一份可运行的示例工程用于理解 Unieap 3.4 在工作流引擎、表单设计、数据模型和权限控制上的基本用法。项目通过实际代码演示应用的启动、流程定义与部署以及与框架交互的业务逻辑可作为入门练手或团队培训的参考样例。资源以 7z 压缩包形式提供整体约 82.8MB上游暂未给出文件数量与类型明细按示例工程惯例主要包含工程配置、流程定义文件与示例源码等部分可按目录逐层查阅。已有 387 人学习说明其在企业级应用入门场景具备一定参考价值。读者可从配置和流程定义入手梳理工程组织方式理解 BPMN 2.0 流程由图形化设计转为可执行代码的过程并借鉴表单与数据模型的集成思路为搭建审批、跨部门协作等业务流程打基础。1. 一张纸质申领单牵出的 Unieap 简单项目实验室的物资申领还在跑纸单子填一张表、找三位老师签字、再去库房核一遍库存赶上导师临时问一句“上个月那批耗材谁申的”只能翻柜子。这类需求说大不大说小也不小——它有完整的主子表、一条审批线、一套权限和导出正好是 Unieap 这类 Java 企业级开发平台最擅长的场景。用 Unieap 做一个简单项目难点从来不在业务本身而在于平台把很多东西做成了“配置”你不清楚哪些该配、哪些该写代码就会在“页面打得开、数据出不来”之间反复横跳。下面这套方案按需求、设计、实现、验收四段推进5 张表、3 个页面、1 条状态线一周左右能落地也足够支撑一份课程设计或毕设的完整章节。2. 需求拆解与选型这个 Java 小项目为什么落在 Unieap 上先把角色摆出来不然后面所有权限配置都是拍脑袋。这套申领系统只有四类人申请人负责填单和撤回部门负责人负责审批库房管理员负责核库存和归档系统管理员只管菜单、字典和账号。角色一确定页面数量基本就定死了——申请人两个页面列表 编辑审批人一个页面待办管理员不单独做页面直接用平台自带的后台管理。2.1 业务流程拆成四段每段对应一个交付物整条线拆成“填报、提交、审批、归档”四段每段都能落到一个可验收的产物上这是小项目不跑偏的关键。填报段要解决的是“少填错”。申领单是典型的主子表一张单子下面挂若干条物资明细每条明细有物资、数量、单价、金额。这里有个容易被忽略的点——物资只能从字典里选不能让用户手打否则一年之后库房会对着一堆“打印纸”“A4 打印纸”“A4纸”发呆。填报段还要允许存草稿草稿可以反复改不占库存、不进审批流。提交段要解决的是“敢提交”。提交前必须做三件事明细不能为空、数量必须为正整数、库存不足要拦下来但允许申请人改数量。提交成功后单据状态从草稿变为待审同时写一条审批日志。日志这张表别省答辩的时候被问“怎么证明这单是谁批的”翻日志比翻数据库强得多。审批段要解决的是“能追溯”。负责人只看得到本部门的待审单通过或驳回都必须填意见驳回后单据回到申请人手里可以改完再提。这里不引入完整的流程引擎一条两节点的线性流转用状态字段加日志表就够了硬上工作流引擎反而会让一个简单项目变成部署事故。归档段要解决的是“能出口”。库房管理员对已通过的单据点归档扣减库存、写归档时间。列表页要支持按单号、部门、状态、日期区间查询并且能把当前查询结果导出成 Excel——国内的项目验收现场导出功能几乎是必被点名的。2.2 技术选型与工程目录小项目更要卡死分层选 Unieap 的理由很实在它自带组织机构、用户角色、菜单权限、数据字典、分页组件和导出工具这些都是 Java Web 项目里最枯燥、最容易写崩的部分。如果自己从零搭一套 Spring Boot 前端框架光登录和权限就够写三天最后业务代码只占三成。用平台做把组织、字典、权限全部复用内置的业务只写申领这一条线工期能压到原来的三分之一。技术栈锁定为Unieap 平台页面建模 内置基础服务 Java 服务层 平台通用数据访问 关系型数据库。不引额外前端框架不自己建用户表和部门表不写自己的一套分页。这三个“不”是纪律破一个就会连锁反应。工程目录我一般按下面这样切跟平台的标准结构对齐别人接手时不用猜apply-demo/ ├── src/main/java/com/demo/apply/ │ ├── action/ # 页面动作层只做参数接收和结果跳转 │ ├── service/ # 业务接口事务边界都在这一层 │ ├── service/impl/ # 业务实现校验、计算、状态判断 │ ├── dao/ # 数据访问接口继承平台通用 Dao │ ├── model/ # 实体与表单对象ApplyOrder / ApplyItem │ └── common/ # 单号生成、状态常量、导出工具 ├── src/main/resources/ │ ├── sqlmap/ # SQL 映射文件一表一文件 │ └── config/ # 平台配置文件、字典与菜单初始化脚本 ├── src/main/webapp/ │ ├── apply/ # 三个业务页面及其配置 │ └── common/ # 公共 JS 校验、样式 └── db/ # 建表脚本、初始化数据脚本action层只做三件事取请求参数、调一次 service、把结果丢回页面。任何if判断超过两行的业务逻辑都不该出现在这里否则后期加一个“库存不足拦截”你得在两个地方改。service层是唯一允许开事务的地方这一点后面 3.3 会展开。sqlmap一表一文件是为了让改 SQL 的人不用在几百行里找自己那张表。3. 总体设计五张表、三个页面、一条状态线的骨架总体设计这一章要能画在一张纸上五张表撑数据三个页面撑交互一条状态线撑流程。设计阶段多花半天实现阶段能省两天。3.1 数据模型设计主子表加日志表怎么切五张表分别是申领主表、申领明细表、物资表、审批日志表加上平台内置的字典表状态值放这里不单独建。核心字段如下表名关键字段设计说明T_APPLY_ORDERORDER_ID、ORDER_NO、APPLICANT_ID、DEPT_ID、STATUS、TOTAL_AMOUNT主表TOTAL_AMOUNT 冗余明细汇总列表页免 joinT_APPLY_ITEMITEM_ID、ORDER_ID、MATERIAL_ID、QTY、UNIT_PRICE、AMOUNT明细表ORDER_ID 建普通索引删单先删明细T_MATERIALMATERIAL_ID、MATERIAL_NAME、SPEC、UNIT、STOCK物资字典STOCK 只在归档时扣减T_APPROVE_LOGLOG_ID、ORDER_ID、NODE、OPERATOR_ID、ACTION、OPINION、OP_TIME日志表只增不改驳回原因从此可查几个约定值得写进设计文档。主键统一用 32 位 UUID 字符串由服务层生成不用数据库自增——平台的组织表、用户表都是字符串主键混用自增在关联查询时会有类型转换的麻烦。业务单号ORDER_NO单独生成格式为“SQ yyyyMMdd 4 位流水”加唯一索引它是给人看的主键是给机器看的别混。金额字段统一两位小数后端用BigDecimal前端传上来的金额一律不采信重新算。状态值用两位字符串而不用数字是为了列表页按状态排序时不用再写转换函数10草稿、20待审、30已通过、40已驳回、50已归档、90已作废。这套编码同时写进平台字典表页面上的状态下拉框直接引字典码别在 JSP 里硬编码option。3.2 页面与字典配置能配的交给平台要算的留给 Java三个页面的分工要清晰不能一个页面什么都能干apply_list我的申领列表。查询区四个条件单号、部门、状态、申请日期区间列表列显示单号、申请日期、部门、金额、状态、操作。apply_edit申领单编辑。上半部分是主表信息下半部分是明细表格支持增行删行提交时一次性保存。approve_list审批待办。查询条件锁定本部门操作列只有“通过”和“驳回”两个按钮。页面用平台自带的页面建模工具生成配置手写也认结构大同小异。查询区配置我一般写成这样字段名必须和后台接收参数的 key 一字不差!-- 列表页查询区name 即后台取参的 keyoperator 决定拼 like 还是 -- query-panel idqryApply field nameorderNo label申领单号 typetext operatorlike/ field namedeptId label申请部门 typeorg operator/ field namestatus label单据状态 typedict dictCodeAPPLY_STATUS operator/ field nameapplyDate label申请日期 typedaterange columnAPPLY_DATE operatorbetween/ /query-paneloperatorlike服务端会拼成ORDER_NO LIKE %值%所以单号输入框要在提交前trim否则前后空格会让查询莫名其妙查不到。typeorg是平台的组织选择控件返回值直接是部门 ID不用自己再做树形下拉。dictCode指向字典表里的编码字典里加一个状态页面自动多一个选项这就是“能配的交给平台”的实际收益。日期区间控件返回两个值后台按between处理注意闭区间和开区间的差别用户选 3 月 1 日到 3 月 1 日期望的是当天全天所以结束日期要补到23:59:59这个坑在 5.2 会再提一次。3.3 服务层与事务边界一次提交只允许开一个事务服务层按业务动作划分方法一个动作一个方法方法名就是事务切点public interface IApplyOrderService { String saveDraft(ApplyOrderForm form, String operatorId); // 存草稿可反复调用 String submit(ApplyOrderForm form, String operatorId); // 保存并提交写日志 void approve(String orderId, String action, String opinion, String operatorId); // 通过/驳回 void archive(String orderId, String operatorId); // 归档并扣库存 }四个方法对应四个事务事务只加在impl的实现方法上用平台的声明式事务配置按方法名匹配save* / submit* / approve* / archive*。这里有个纪律Action 层绝不开事务。原因很直接——Action 里一旦调了两个 Service 方法第一个成功第二个失败事务边界就乱了数据会“存一半”。如果确实需要跨两个 Service就在上层再包一个 Service 方法把两个调用放进去而不是在 Action 里手动begin/commit。另外审批和归档这两个动作都要做幂等保护。用户手快连点两下“通过”如果不加条件更新日志会写两条、状态会被覆盖。做法在 4.2 里给。4. 关键模块实现表单落库、状态流转与分页导出这一章是能直接抄的部分。三段代码对应项目里最容易出问题的三个动作保存、审批、查询。4.1 表单保存主子表一次落库金额只认后端先看服务层实现。这段代码承担了主键生成、单号生成、金额重算、主子表写入四件事全部放在一个事务里Override public String saveDraft(ApplyOrderForm form, String operatorId) throws AppException { // 1. 主键与单号只在这一处生成避免页面和后台各生成一次导致重复 String orderId form.getOrderId(); boolean isNew StringUtils.isBlank(orderId); if (isNew) { orderId IdUtil.uuid(); form.setOrderId(orderId); form.setOrderNo(OrderNoGen.next(SQ)); // SQ 日期 4 位流水 form.setStatus(OrderStatus.DRAFT); // 新建一律草稿不接受前端传状态 } // 2. 金额不信任前端按明细逐行重算后汇总 BigDecimal total BigDecimal.ZERO; for (ApplyItem item : form.getItems()) { if (item.getQty() null || item.getQty().compareTo(BigDecimal.ZERO) 0) { throw new AppException(第 (form.getItems().indexOf(item) 1) 行数量必须大于 0); } item.setAmount(item.getQty().multiply(item.getUnitPrice()).setScale(2, RoundingMode.HALF_UP)); total total.add(item.getAmount()); } form.setTotalAmount(total.setScale(2, RoundingMode.HALF_UP)); // 3. 先删后插明细不做差异比对小单据全量覆盖最简单也最不容易错 commonDao.delete(ApplyItem.deleteByOrderId, orderId); commonDao.insertOrUpdate(ApplyOrder.save, form.toDataObject()); for (ApplyItem item : form.getItems()) { item.setOrderId(orderId); // 回填主键靠这个字段关联 item.setItemId(IdUtil.uuid()); commonDao.insert(ApplyItem.insert, item.toDataObject()); } return orderId; }几个参数和写法要说明。IdUtil.uuid()是工程里自己封的工具返回去掉横线的 32 位串和平台其他表的主键格式保持一致。OrderNoGen.next(SQ)内部用“前缀 当天日期 数据表当日最大流水 1”实现必须放在事务内并且对流水号加唯一索引兜底否则并发下两个请求可能拿到同一个号这是血泪经验。commonDao是平台通用数据访问对象insertOrUpdate会根据主键是否存在自动判断新增还是更新省掉一个if。规范上还有一条容易被忽略item.setOrderId(orderId)这行必须在循环内、insert之前执行不能指望 page 端传过来。页面上的明细行是动态加的前端并不知道主键只能靠后端回填。如果漏了这行明细表里会出现一堆ORDER_ID为空的孤儿数据列表页 join 不出来看着就像“保存成功但明细丢了”。4.2 审批流转用带条件的 UPDATE 卡住并发审批的难点不在业务在并发和幂等。两个负责人同时点“通过”或者一个人连点两下都会出问题。做法是把状态判断放进 SQL 的WHERE里用受影响行数判断有没有抢到-- 审批通过只有当单据当前仍是「待审(20)」时才允许更新 UPDATE T_APPLY_ORDER SET STATUS 30, UPDATE_TIME SYSDATE WHERE ORDER_ID #{orderId} AND STATUS 20;服务层拿到返回值后判断int rows commonDao.update(ApplyOrder.updateStatus, params); if (rows 0) { // 说明单据已被人处理过、或状态不对直接拒绝不写日志 throw new AppException(该单据已被处理请刷新后重试); } commonDao.insert(ApproveLog.insert, log); // 只有抢到才写日志#{orderId}是命名参数占位符具体写法按项目所用 SQL 映射方式调整。STATUS 20这个条件就是乐观锁它保证同一张单子只有一个请求能把状态从 20 改成 30第二个请求的rows一定是 0直接给用户提示刷新。日志写在rows判断之后顺序不能反——先写日志再更新状态一旦更新失败日志里就会多出一条根本不存在的审批记录追溯的时候最坑人。驳回同理条件里加上AND STATUS 20意见字段做非空校验长度上限跟表字段对齐本例 500 字符。归档则要额外扣库存UPDATE T_MATERIAL SET STOCK STOCK - #{qty} WHERE MATERIAL_ID #{id} AND STOCK #{qty}同样用受影响行数判断库存不足时整笔事务回滚把已经改掉的单据状态一起撤销。4.3 列表分页与导出把慢查询挡在翻页之前分页最容易出的两个问题总数和列表对不上、导出时把整个库拉出来。核心是让 count 和 list 共用一套查询条件public PageResultApplyOrderVO queryPage(ApplyQuery query) { // 1. 页码和每页条数做上下限保护防止前端把 pageSize 改成 99999 int pageNo Math.max(query.getPageNo(), 1); int pageSize Math.min(Math.max(query.getPageSize(), 10), 100); // 2. 条件集中组装一次count 与 list 共用杜绝两处 where 写得不一致 MapString, Object params new HashMap(); params.put(status, query.getStatus()); params.put(deptId, query.getDeptId()); params.put(orderNo, StringUtils.trimToNull(query.getOrderNo())); params.put(dateFrom, query.getDateFrom()); params.put(dateTo, DateUtil.endOfDay(query.getDateTo())); // 补到 23:59:59 params.put(dataScope, query.getDataScope()); // 部门数据权限 long total commonDao.count(ApplyOrder.countByCondition, params); if (total 0) { return new PageResult(0, Collections.emptyList(), pageNo, pageSize); } // 3. 分页参数在数据库侧生效不要查全量再在内存里 subList params.put(startRow, (pageNo - 1) * pageSize); params.put(endRow, pageNo * pageSize); ListApplyOrderVO list commonDao.queryList(ApplyOrder.selectByCondition, params); return new PageResult(total, list, pageNo, pageSize); }参数上endOfDay把用户选的结束日期补到当天最后一秒解决“选同一天查不到数据”的问题dataScope是部门数据权限的开关申请人是普通用户时传本部门管理员传空表示不过滤这个判断放在 Service 里不要放在 SQL 里写死。startRow / endRow的写法适配常见数据库的分页语法换库时只改映射文件。导出单独走一条链路不能直接复用queryPage然后传pageSize 999999。正确做法是导出前先count超过一万行提示用户缩小查询范围或者走异步导出生成文件。同步导出也要设条数上限并且导出用的 SQL 去掉ORDER BY之外的所有排序字段——大数据量下ORDER BY能让一次导出从 3 秒变 3 分钟。5. 避坑与排查Unieap 小项目最容易翻车的五处小项目出问题八成不是业务逻辑写错而是环境、事务、权限这三类“平台层”的问题。下面五条是这类项目里重复率最高的。5.1 环境与启动页面打得开不等于跑得起来现象本地访问页面正常部署到测试环境后 404或者页面出来了但点任何按钮都提示“系统异常”日志里只有一行ClassNotFoundException。原因平台的 jar 包版本和编译时用的不一致或者本地引用了工具类里的某个方法而这个方法是新版才有的测试环境还是旧包。另一种常见情况是 JDK 版本不匹配本地 1.8 编译、服务器跑 1.7字节码版本对不上。还有一种是配置文件没跟着打包sqlmap目录漏了启动时不报错第一次查询才炸。解决固定一套“编译 - 打包 - 部署 - 冒烟”的流程部署包里的 jar 清单用md5比对一次别靠肉眼。JDK 版本、平台版本、数据库驱动版本写进 README交接时一目了然。本地跑通之后先在一个干净的测试库上完整走一遍“建表 → 初始化字典 → 登录 → 建单 → 审批”这四步能过基本不会再出现环境问题。启动脚本里的内存参数也别忽略默认配置在数据量稍大时容易 OOM小项目给到 1G 起比较稳。5.2 数据与事务存了一半的数据最难查现象申领单保存成功列表能看到点进详情明细是空的或者审批通过了日志表里却查不到审批记录。原因明细没回填ORDER_ID见 4.1或者主子表写入不在同一个事务里主表成功、明细抛异常后被吞掉。日志缺失通常是“先写日志后更新状态”的顺序问题也可能是异常被catch住之后只打了日志没抛出去事务不回滚。解决所有写操作只在 Service 层开事务Action 里不允许出现try-catch之后啥也不干的情况。开发期把 SQL 日志打开保存一次看实际执行了几条INSERT比对着代码猜快得多。另外把“日期区间查不到数据”也归到这一类——多半是结束日期没补时分秒或者数据库字段是DATE而参数是TIMESTAMP隐式转换把时间截断了。5.3 权限与发布本地好好的一部署就白屏现象新加的功能菜单在本地能看到部署后管理员登录也找不到入口或者菜单点得开但列表提示“无权限访问”。原因菜单和权限是平台自带的不走代码发布流程。本地开发时给账号配了管理员所以什么都能看部署后菜单数据没初始化或者菜单里绑定的资源编码和页面实际路径不一致。还有一种数据权限的部门过滤在 SQL 里写死了当前用户的部门换个账号就查不到数据。解决把菜单、字典、初始账号的初始化脚本放进db目录和建表脚本一起版本管理每次部署先执行脚本再发应用。资源编码统一用“模块_页面_操作”的格式比如apply_order_export页面和代码里引用同一个常量别手敲字符串。上线前用三个账号各走一遍管理员看全部、负责人看本部门、申请人看自己三遍都过权限这块基本就稳了。6. 验收与答辩一份自检清单走完再交验收现场最常见的场景是演示到一半评委问“这个单据能不能导出”你点了导出转圈十秒然后报错。问题不在导出没做而在做的时候只测了三条数据。所以我把验收拆成一张清单功能、数据、异常三条线各走一遍走完再点“提交”。验收项检查方法合格标准主流程用申请人账号建单、提交换负责人账号审批通过状态从 10 → 20 → 30日志三条齐全驳回回退审批时点驳回并填意见申请人改完重新提交状态回到 20原意见可查并发保护两个浏览器同时点同一单的“通过”一个成功另一个提示刷新边界数据明细只填一行、数量填 1、金额填 0.01能存能查金额不出现 0.009999查询导出日期区间选同一天、选跨月、导出 500 条结果不为空导出文件行数一致权限隔离三个角色分别登录看列表各自只看到该看的演示脚本要提前写好控制在五分钟先讲一句业务背景然后申请、审批、驳回、再提交、通过、归档一路走完。中途不要打开代码编辑器也不要现场改数据。评委最常追问的三个问题基本固定——“数据权限怎么做的”“并发提交怎么防的”“单据状态为什么用字符串不用数字”答案分别在第 3.2、4.2、3.1 里提前背熟比临场发挥靠谱。答辩 PPT 别超过十页业务背景一页、功能清单一页、表结构一页、流程图一页、关键代码一页、验收结果一页剩下的留给演示。表格截图比文字描述有说服力尤其是状态流转那张把每一步的状态值和操作人标出来比讲十分钟设计思路管用。带过几个这样的小项目之后我养成一个习惯功能写完先不急着美化页面而是拿一个空库从头跑一遍建表脚本和初始化脚本跑通了再开始点页面。因为翻车几乎都发生在“我以为环境是干净的”这个假设上——本地库里有半年前的老数据、有手工加的字典项、有一条已经改成 30 的测试单页面看着一切正常换个库就原形毕露。这套流程后来成了我每个小项目的固定动作从建表到验收一条龙走完再交出去心里才踏实。希望帮到你。本文还有配套的精品资源点击获取