发生了什么
网点每个月要为电费结算上传发票。发票不是把文件存起来就结束:系统收到文件后,先调用第三方的发票验真服务,核对这张发票是不是真的,同时把票面上的税率、金额、发票类型等信息读出来,写进系统自己的发票记录。发票入库后还要绑定到对应的结算批次,参与该批次的余额抵扣,抵扣结果依赖入库的发票数据。所以正常流程里,票面写的是 6%,库里存的也必须是 6%,两边一致,后面的抵扣才有依据。
这次的不同出现在第三方验真服务上。一批发票上传时,验真结果里没有返回税率这个字段,而票面本身是正常的 6%。系统没有把这当成异常:保存发票时用的是一个“空值就取 0”的转换方法,凡是入参为 null 或空串,都返回 0。于是空税率被转换成 0,和发票的其他信息一起写进了库。
业务先发现的是系统里发票的税率是 0%,而发票图片上写的是 6%。核对后确认不是页面展示问题,是入库时就存成了 0。处理时把这些发票的税率订正回 6%,并把已经绑定到批次、税率为 0 的发票逐张梳理出来重新核对。
本质
错误发生在把验真结果写入发票记录的那一步,根子是对“空值”的处理方式。
- 第三方验真服务这次返回的税率是空值。空值在这里表示“这次没有识别出来”或“没有返回”,并不表示“税率真的是 0%”。这两种情况在业务上完全不同:0% 本身是一个允许出现的税率值,空值是需要处理的异常。
- 本地保存发票时没有区分这两种情况。代码调用了统一的数值转换方法,而这个方法在遇到 null 或空串时直接返回 0。调用方拿到的是一个看起来完全合法的数字,不会抛异常,也不会进入任何失败分支。
- 这个 0 被当成真实税率写进发票记录。票面上 6% 的信息在入库这一步就丢了,库里留下的是一张“税率 0”的发票。
- 后续环节读的都是库里这份发票数据:绑定批次、核对抵扣金额。库里的值错了,这些判断就都建立在一个错误前提上,而且从数据本身看不出问题——字段有值、类型正确、取值也在允许范围内。
- 因此这类错误既不报错也不触发告警,只能靠人对照票面或对账时发现。而且这不是单张发票的问题:只要验真结果里没有税率,同一批上传的发票都会以 0% 入库,需要按批次把已经绑定出去的发票全部找回来。
把第三方返回的空值默认填成 0 再入库,等于替上游把“没识别出来”改写成了“税率为 0”。
修复方向是在入库前对必填票面字段做显式校验:空值不默认赋值,而是拒绝入库或标记为待人工核验,同时保留验真返回的原始结果;对于税率这种“0 也可能是真实值”的字段,必须能区分“没有值”和“值为 0”。长期看,明细校验应当以库里已存的数据为准,验真服务只负责发票类型和验真入参,避免同一份数据在多个环节各取一次、各自转换。短期处理是把已存的 0 税率发票订正为 6%,并核对已绑定批次的发票。修复上线后的验证情况,记录里没有说明。
错误代码
public class InvoiceOcrResult {
private String invoiceNo;
private String taxRate; // 第三方返回的税率,可能是 null 或空串
}
// 通用转换:空值一律当 0
public static BigDecimal toDecimalOrZero(String value) {
if (value == null || value.trim().isEmpty()) {
// 为什么错:把“没返回”和“真的是 0”合并成同一个结果,调用方察觉不到缺字段
return BigDecimal.ZERO;
}
return new BigDecimal(value.trim());
}
public void saveInvoice(InvoiceOcrResult ocr) {
Invoice invoice = new Invoice();
invoice.setInvoiceNo(ocr.getInvoiceNo());
// 为什么错:这次验真没有返回税率,这里直接写入了 0,票面 6% 被覆盖
invoice.setTaxRate(toDecimalOrZero(ocr.getTaxRate()));
invoiceMapper.insert(invoice); // 入库成功、无异常,错误数据开始向下游流转
}
修复代码示例
// 只在确实有值时转换;空值返回 null,把“缺失”交给调用方决定
public static BigDecimal toDecimalOrNull(String value) {
if (value == null || value.trim().isEmpty()) {
return null; // 不伪造 0
}
return new BigDecimal(value.trim());
}
public void saveInvoice(InvoiceOcrResult ocr) {
BigDecimal taxRate = toDecimalOrNull(ocr.getTaxRate());
if (taxRate == null) {
// 缺必填票面字段:不入库,转人工核验,并保留验真原始结果备查
throw new OcrFieldMissingException(
"验真结果缺少税率,待人工核验: " + ocr.getInvoiceNo());
}
Invoice invoice = new Invoice();
invoice.setInvoiceNo(ocr.getInvoiceNo());
invoice.setTaxRate(taxRate); // 缺字段已被拦住,这里写入的一定是返回值
invoiceMapper.insert(invoice);
}
下次遇到这些场景要警惕
- 接入第三方识别、验真接口并落库:先列出必须入库的字段,逐个构造“返回 null、空串、整个字段缺失”的响应,确认系统是拒绝入库、转人工还是报错,而不是悄悄存成一个默认值。
- 代码里出现“空值转 0”这类工具方法:查清它的所有调用点,标出哪些字段 0 本身是合法业务值(税率、折扣、运费),这些位置必须额外判断“是否缺失”,不能只靠 0 兜底。
- 新增或修改发票字段映射:拿一张票面税率 6% 的发票完整走一遍上传流程,把库里的税率、金额与票面逐项比对,而不是只看页面能否正常显示。
- 批量上传之后:按批次抽查绑定发票的税率和金额,遇到“合法但可疑”的 0 税率,回查票面和验真原始结果,先确认影响范围,再决定是否整批重新入库。