# SpringBoot+Vue3 财务凭证实现：单据先入队、模板再生成，失败不回滚审批


> 费用报销已经审批通过，财务凭证却因为 9 月账期未开启生成失败。此时如果把整个审批事务回滚，员工看到的是“领导明明同意了，单据又回到原处”；如果直接吞掉异常，财务月底又会发现少了一笔账。RuoYi Office 的做法是把业务事实和会计记账拆成两段：业务单据只负责可靠入队，财务人员再按账套、期间和模板生成凭证，失败原因留在队列里重试。

![业务事实通过队列变成借贷平衡凭证](https://developer.qcloudimg.com/http-save/yehe-7872026/5338ecd6cd1f73e03073b3e8f85e4c65.png)

*▲ 报销、付款、收款、折旧等业务事实先进入队列；模板把业务字段翻译成科目和金额，借贷平衡后才进入审核、过账*

---

## 引言：审批成功和记账成功，不该绑成一次成败

很多企业系统的“自动凭证”只有一句需求：审批通过后生成凭证。真正落地时至少会遇到五种不同失败：

| 失败点 | 业务单据是否真实成立 | 财务该怎么处理 |
|:---|:---:|:---|
| 账套没有对应会计期间 | 是 | 队列标失败，补期间后重试 |
| 期间已经结账 | 是 | 调整业务日期或反结账，不能硬写 |
| 来源类型没有匹配模板 | 是 | 补模板或指定模板生成 |
| 模板取不到末级科目 | 是 | 修科目映射后试算 |
| 模板借贷不平 | 是 | 禁止落凭证，保留失败原因 |

这五类问题都属于“业务事实已经发生，但会计表达还没准备好”。因此，正确边界不是把异常 `try/catch` 掉，而是建立一个可查询、可重试、可忽略、可追踪到原单的缓冲层。

本文聚焦这条链：

```text
业务单据完成
  → 提交凭证来源
  → 四维幂等入队
  → 校验账套与期间
  → 匹配凭证模板
  → 渲染科目/金额/辅助核算
  → 借贷平衡
  → 生成凭证
  → 审核与过账
```

---

## 一、产品能力：业务模块只交事实，财务模块负责翻译

### 1.1 一条队列接住多类业务单据

当前来源枚举覆盖费用报销、付款、收款、应收、应付、借款、还款、销项发票、进项发票、资产折旧、薪资、银行流水、内部转账、手工日记账和期末结转。

来源类型多，不等于业务模块都要理解会计科目。业务侧只提交这些稳定事实：

- 来源类型、来源单据 ID、单据编号；
- 法人主体或显式账套；
- 业务日期、金额；
- 可供模板取数的 `payload`；
- 来源版本。

财务侧再决定使用哪一个凭证字、哪套模板、借贷方向、辅助核算以及是否自动审核和过账。

### 1.2 队列有四态，不用“成功/失败”两个布尔值糊住

| 状态 | 含义 | 可执行动作 |
|:---:|:---|:---|
| 0 待生成 | 业务事实已入队，尚未生成凭证 | 生成、指定模板、忽略 |
| 1 已生成 | 已关联凭证 | 查看凭证 |
| 2 已忽略 | 财务确认无需记账 | 保留审计说明 |
| 3 生成失败 | 期间、模板或取数失败 | 修配置后重试 |

![业务凭证队列：已生成与失败记录并存](https://developer.qcloudimg.com/http-save/yehe-7872026/e8246fbbfc8875b0ca293a0602b5ca8e.png)

*▲ 队列不是错误日志，而是财务工作台；失败行仍能“生成”或“指定模板”，已生成行可反查凭证*

### 1.3 业务事实与凭证是一对可追溯关系

凭证保留 `sourceType`、`sourceId`、`sourceQueueId`、`templateId`。这四个字段回答四个问题：

1. 这张凭证来自哪类业务？
2. 对应哪一张原始单据？
3. 是队列中的哪次提交？
4. 当时使用哪套模板？

因此，业务生成的凭证不允许直接改分录。纠错要回到原单，必要时红冲旧凭证，再以新版本重新入队，而不是让“原单 500 元、凭证手改成 800 元”长期共存。

---

## 二、从一张报销单走完整条链

### 2.1 审批通过后，先把“发生了什么”写进队列

费用报销会把单据编号、总金额、费用科目编码、部门等字段组成 `payload`。这里配置的是 `autoGenerate=false`：业务先入队，生成时机交给财务工作台。

```java
FinanceVoucherSourceReqDTO req = new FinanceVoucherSourceReqDTO();
req.setSourceType(FinanceVoucherSourceTypeEnum.EXPENSE_CLAIM.getType());
req.setSourceId(bill.getId());
req.setSourceNo(bill.getBillCode());
req.setSourceVersion(1);
req.setCompanyId(bill.getCompanyId());
req.setBizDate(resolveVoucherBizDate(bill));
req.setAmount(bill.getTotalAmount());
req.setPayload(payload);
req.setAutoGenerate(false);
req.setRemark(StrUtil.blankToDefault(bill.getRemark(), "费用报销"));
voucherSourceService.submitSource(req);
```

这段代码的重点不是 DTO，而是边界：业务服务不查询会计科目，也不直接插入凭证分录。

### 2.2 四维幂等挡住回调重入

审批回调、消息重试、用户重复操作都可能再次提交同一事实。队列按“账套 + 来源类型 + 来源单据 + 来源版本”查重：

```java
Long bookId = resolveBookId(reqDTO);
Integer sourceVersion = ObjUtil.defaultIfNull(reqDTO.getSourceVersion(), 1);
FinanceVoucherSourceDO exists = voucherSourceMapper.selectByIdempotentKey(
        bookId, reqDTO.getSourceType(), reqDTO.getSourceId(), sourceVersion);
if (exists != null) {
    return convert(exists);
}

String period = FinancePeriodUtils.of(reqDTO.getBizDate());
FinanceVoucherSourceDO source = FinanceVoucherSourceDO.builder()
        .sourceType(reqDTO.getSourceType())
        .sourceId(reqDTO.getSourceId())
        .sourceNo(reqDTO.getSourceNo())
        .sourceVersion(sourceVersion)
        .bizDate(reqDTO.getBizDate())
        .period(period)
        .amount(reqDTO.getAmount())
        .payload(reqDTO.getPayload())
        .status(FinanceVoucherSourceStatusEnum.PENDING.getStatus())
        .build().ofBook(bookId, reqDTO.getCompanyId());
```

`sourceVersion` 不能省。原单发生合规变更时，新事实应该有新版本；如果只按单据 ID 唯一，历史凭证被红冲后，新金额反而无法重新入队。

### 2.3 期间不允许记账，也要留下这条业务事实

队列入库前会检查会计期间。关闭或未开启时，记录直接进入“生成失败”，但业务审批不回滚。页面上能看到单号、金额和失败原因，实施人员知道应该补期间，不必从后端日志猜哪张单漏了。

这也是本文最重要的设计取舍：**不能记账，不等于业务没有发生。**

### 2.4 模板把业务字段翻译成借贷分录

凭证模板支持固定科目和表达式取科目。以费用报销为例，借方可从费用类型映射得到 `expenseSubjectCode`，贷方挂其他应付款；付款单再借记其他应付款、贷记资金科目，避免报销和付款都直接贷现金造成双记。

![在这里插入图片描述](https://developer.qcloudimg.com/http-save/yehe-7872026/b72bd4e2a83bac183c558f0fc53eeb45.png)


*▲ 试算弹窗接受一条队列记录或业务字段 JSON；配置错误先在模板阶段暴露，不必拿正式凭证试错*

模板匹配按排序依次判断条件表达式，无条件模板作为兜底：

```java
for (FinanceVoucherTemplateDO template : templates) {
    if (StrUtil.isBlank(template.getConditionExpr())) {
        if (fallback == null) {
            fallback = template;
        }
        continue;
    }
    if (expressionService.evaluateBoolean(
            template.getConditionExpr(), env, false)) {
        return template;
    }
}
if (fallback != null) {
    return fallback;
}
return templates.stream()
        .filter(template -> Boolean.TRUE.equals(template.getDefaultFlag()))
        .findFirst()
        .orElseThrow(() -> exception(VOUCHER_TEMPLATE_NOT_MATCHED));
```

### 2.5 每一行先算金额，再解析科目，最后校验借贷平衡

金额为零的分录会跳过；金额为负时翻转借贷方向并取绝对值。所有行渲染完成后，少于两行或借贷不平都禁止正式生成：

```java
BigDecimal amount = expressionService.evaluateDecimal(
        templateItem.getAmountExpr(), env);
amount = amount == null ? BigDecimal.ZERO
        : amount.setScale(2, RoundingMode.HALF_UP);
if (amount.compareTo(BigDecimal.ZERO) == 0) {
    previewItem.setSkipReason("金额取数为 0");
    continue;
}
Integer direction = templateItem.getDirection();
if (amount.compareTo(BigDecimal.ZERO) < 0) {
    direction = FinanceBalanceDirectionEnum.isDebit(direction)
            ? FinanceBalanceDirectionEnum.CREDIT.getDirection()
            : FinanceBalanceDirectionEnum.DEBIT.getDirection();
    amount = amount.abs();
}
FinanceSubjectDO subject = resolveSubject(book, templateItem, env);
previewItem.setSubjectCode(subject.getCode());
previewItem.setSubjectName(StrUtil.blankToDefault(
        subject.getFullName(), subject.getName()));
Map<String, Object> auxData = resolveAuxData(
        subject, templateItem, env);
String summary = StrUtil.blankToDefault(
        expressionService.evaluateString(templateItem.getSummaryExpr(), env),
        StrUtil.blankToDefault(source.getSourceNo(), template.getName()));
FinanceVoucherItemSaveReqVO item = new FinanceVoucherItemSaveReqVO();
item.setSummary(summary);
item.setSubjectId(subject.getId());
item.setDirection(direction);
item.setAmount(amount);
item.setAuxData(auxData);
render.add(item, amount, direction);
if (render.debitTotal.compareTo(render.creditTotal) != 0 && !preview) {
    throw exception(VOUCHER_TEMPLATE_NOT_BALANCED);
}
```

### 2.6 生成后仍要经过凭证自己的状态机

模板生成的结果先落为凭证。是否自动审核、自动过账由模板开关决定，不是所有来源一刀切。

![费用报销生成的借贷平衡凭证](https://developer.qcloudimg.com/http-save/yehe-7872026/8a292dc6345abd9c97c4cffedc60944e.png)

*▲ 这张报销凭证借记差旅费、贷记其他应付款，来源单号和模板写入备注，借贷各 500 元*

凭证状态遵循：

```text
暂存 → 已审核 → 已过账
```

已过账凭证不能直接改分录；需要纠错时走反过账或红冲。作废保留凭证号占位，不参与账务计算。

---

## 三、设计怎么落地

### 3.1 ER：队列、模板、凭证各管一件事

![mermaid diagram](https://developer.qcloudimg.com/http-save/yehe-7872026/52fd1cd450c6545c0a07ddf83d43234e.png)

队列表不复制完整业务表，只保存生成凭证所需的稳定快照。模板后来被修改，历史凭证仍可通过 `templateId` 追溯当时使用的模板记录，但文章不把它宣传成完整模板版本快照；如果要求法规级配置版本化，还需要独立的模板版本机制。

### 3.2 时序：业务事务提交后再尝试自动生成

![mermaid diagram](https://developer.qcloudimg.com/http-save/yehe-7872026/062129f84b4de45a0b2f0b2336fd4147.png)

系统也支持事务提交后的自动生成，但失败只更新队列原因，不把已完成的业务事务标成 `rollback-only`。当前费用报销、付款、收款、应收应付等主要业务链明确采用“入队后由财务生成”的稳妥模式，不能把页面宣传成所有单据审批后都无人工介入。

### 3.3 批量生成必须逐条独立事务

批量操作最怕第一条失败把后面全部回滚。当前实现逐条调用代理方法，每一条队列记录独立事务，最后返回成功数和失败单号。财务能一次处理 50 条，也能明确知道哪 3 条因为模板或期间失败。

### 3.4 默认模板只补不盖

系统可为新账套补种费用报销、付款、收款、应收、应付、借还款、发票、折旧、薪资、转账等缺省模板。补种遵循“编码已存在则不覆盖”，客户调整过科目后，版本升级不会把配置改回系统默认。

---

## 四、边界：哪些地方不能说成“全自动”

| 边界 | 当前真实行为 |
|:---|:---|
| 业务单据是否都自动生成凭证 | 不一定；多数链路先入队，由财务生成 |
| 模板缺失是否影响审批 | 不回滚审批，队列标失败 |
| 业务生成凭证能否直接改 | 不能，纠错回原单或走红冲 |
| 自动审核、自动过账是否固定 | 按模板开关决定 |
| 历史模板是否完整版本化 | 当前凭证记 `templateId`，不等于法规级模板快照 |
| 批量生成是否全成全败 | 否，逐条独立事务并返回失败原因 |
| 默认模板是否覆盖客户配置 | 不覆盖同编码既有模板 |

---

## 五、快速体验


推荐按这条路径体验：

1. 财务 → 凭证管理 → 业务凭证，查看待生成、已生成和失败三类记录；
2. 找一条失败记录，阅读失败原因，再尝试“指定模板”；
3. 财务 → 凭证管理 → 凭证模板，打开费用报销模板试算；
4. 查看模板中的来源类型、自动审核、自动过账与分录规则；
5. 回到业务凭证生成一条记录；
6. 在凭证录入中查看借贷分录、来源单号和状态；
7. 对照原业务单金额，确认借贷合计相等。


---

## 常见问题（FAQ）

### 业务凭证生成失败，为什么不回滚审批？

因为审批确认的是业务事实，凭证确认的是会计表达。账期关闭、模板缺失等财务配置问题不应抹掉已经成立的报销或付款事实，正确做法是入队留痕并重试。

### 同一张单据会不会生成两张凭证？

同一账套、来源类型、来源单据 ID、来源版本组成幂等键；重复提交返回既有队列。发生真实变更时应提升来源版本，而不是覆盖旧记录。

### 为什么费用报销不直接贷银行存款？

报销确认与实际付款是两个业务时点。报销凭证先挂其他应付款，付款单再清应付并贷资金科目，可避免费用与现金重复记账。

### 模板试算成功就一定能过账吗？

不一定。试算主要验证条件、科目、金额和借贷平衡；正式生成、审核、过账还受账套启用状态、会计期间和凭证状态机约束。

### 已过账的业务凭证能直接删除吗？

不能。已入账数据必须通过反过账或红冲保留轨迹；业务侧撤销也不能静默删掉已生成凭证。

---

## 结语

业务单据生成凭证，最难的不是写两行借贷分录，而是定义两个事务的边界：业务事实必须可靠成立，财务表达必须可失败、可解释、可重试。

RuoYi Office 用来源队列隔离业务与总账，用四维幂等挡重复，用模板把业务字段翻译成科目与辅助核算，再用借贷平衡和凭证状态机守住入账底线。这样即使账期、科目或模板暂时没配好，也不会让审批回到过去，更不会让漏账悄悄消失。

---

费用报销已经审批通过，财务凭证却因为 9 月账期未开启生成失败。此时如果把整个审批事务回滚，员工看到的是“领导明明同意了，单据又回到原处”；如果直接吞掉异常，财务月底又会发现少了一笔账。RuoYi Office 的做法是把业务事实和会计记账拆成两段：业务单据只负责可靠入队，财务人员再按账套、期间和模板生成凭证，失败原因留在队列里重试。

SpringBoot+Vue3 财务凭证实现：单据先入队、模板再生成，失败不回滚审批

业务审批成功，凭证生成却因账期关闭或模板缺失失败，究竟该回滚哪一边？本文拆解 财务管理的业务事实入队、四维幂等、模板试算、借贷平衡、失败重试与红冲链路。

后端

架构设计

编程语言

SpringBoot+Vue3财务凭证生成采用队列缓冲设计，业务单据先入队、模板再生成，失败不回滚审批。支持四维幂等防重复，按账套期间匹配模板，借贷平衡校验保障入账准确。凭证生成失败可重试、可指定模板，财务工作台可视化追踪每笔来源单据，避免漏账丢账风险。

代码解释

JSON

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

SpringBoot+Vue3 财务凭证实现：单据先入队、模板再生成，失败不回滚审批-腾讯云开发者社区-腾讯云

SpringBoot+Vue3 财务凭证实现：单据先入队、模板再生成，失败不回滚审批

SpringBoot+Vue3 财务凭证实现：单据先入队、模板再生成，失败不回滚审批

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐