发生了什么
平台和商户按租赁合同结算租金。合同约定租期和每期金额,系统按账期把租期切成一段段,每段生成一条租金账单,记录这一期该结算多少钱、什么时候到期。到了期限还没结清的账单会进入超期状态,也就是一线看到的“异常账单”。合同换签(旧合同结束后另签一份)之后,系统还要按上一份合同已经出过的账单做一次清算,把旧账结清,并生成对应的清算账单。
正常时,超期账单只出现在确实逾期没结清的账单上。4 月 23 日,系统上线一条调整:不再生成租金超期账单。按业务的理解,从这天起,账单列表里不应该再冒出新的超期账单。
4 月 28 日,业务侧反馈“租金异常账单不是没有了吗?还在生成”,实际又出现了一条。
查下来,问题出在上一份合同上。那份合同的租金账单在 23 日之前就已经超期,是调整上线前生成并落库的。清算按上一份合同的账单生成,读到的正是这条已经超期的旧账单,算出来的清算账单仍然落在超期,于是页面上又出现一条异常账单。
本质
一句话:这次调整只拦住了“上线之后新生成的租金账单”,没有处理已经落库的超期账单,而清算恰恰以这类旧账单为输入,规则从另一条路径被绕了过去。
- 23 日的调整改的是生成入口:新账单在生成时按新规则判断,属于超期的就不再生成。这一步只覆盖调整之后产生的数据。
- 存量账单没有动。上一份合同那条账单在调整前就已生成,状态是超期,仍留在库里,也不经过新的生成入口。
- 清算以上一份合同的账单为依据。合同换签后要结清旧账,程序读上一份合同的账单,按它的金额和状态算出清算账单。
- 旧账单是超期的,清算结果跟着超期。用户看到的现象与调整前一样,看上去像规则完全没生效。
- 处置是清理存量:23 日之前生成、仍处于超期的租金账单已经统一处理完成。这能止住这次的个例,但“停发只对新数据生效”的范围问题,还需要在下一次变更里定义清楚。
停发一类单据时,只改新生成的入口不够;已经存在的同类单据还在库里,下游读取它们时照样会把旧状态带进新结果。
修复方向有两部分:一是上线前盘出已处于该状态的存量单据,明确是作废、订正还是打标,并跟踪处理完成;二是把“是否超期”的判断收到一处,清算和日常出账都调用同一套规则,不再直接沿用旧账单的状态。存量数据已处理完成;是否补了代码、代码是否上线,目前没有确认。
错误代码
/** 日常出账:新规则下不再生成超期账单 */
public void generateDailyRentBills(LocalDate day) {
for (Contract c : contractRepository.findInEffect(day)) {
Bill bill = Bill.of(c, day);
if (rentRuleService.isOverdueBillStopped() && bill.isOverdue(day)) {
continue; // 为什么错:只拦住“今天新生成”的超期账单,
// 之前已落库的超期账单不经过这里
}
billRepository.save(bill);
}
}
/** 合同换签后的清算:按上一份合同的账单生成清算账单 */
public Bill settle(Contract current, Contract previous) {
Bill last = billRepository.findLastByContract(previous.getId());
Bill settlement = Bill.settlementOf(current, last);
settlement.setOverdue(last.isOverdue()); // 为什么错:直接沿用旧账单的超期状态,
// 新规则在这里完全没有被调用
return billRepository.save(settlement);
}
修复代码示例
/** 合同换签后的清算:先处理存量超期账单,再按统一规则算清算账单 */
public Bill settle(Contract current, Contract previous) {
List<Bill> prevBills = billRepository.findByContract(previous.getId());
List<Bill> overdue = prevBills.stream().filter(Bill::isOverdue).toList();
if (!overdue.isEmpty()) {
// 存量超期账单不能作为清算输入:先转清理,避免旧状态被再生成一次
legacyBillCleanupService.enqueue(overdue);
throw new BizException("上一份合同还有未处理的超期账单,已转人工处理");
}
Bill last = prevBills.get(prevBills.size() - 1);
Bill settlement = Bill.settlementOf(current, last);
// 状态由统一规则按清算账单自身计算,不再复制旧账单的状态
settlement.setOverdue(rentRuleService.isOverdue(settlement, LocalDate.now()));
return billRepository.save(settlement);
}
配合上线前的存量盘点:发布检查里查询仍处于超期、生成时间早于变更日的账单数量,数量不为 0 就不允许发布,或者先生成清理清单再发布。
下次遇到这些场景要警惕
- 停发某类单据或某类状态:先统计库里已经处于这个状态的存量单据有多少、分别属于哪些合同,再决定作废、订正还是保留;不能只改生成入口就认为停发了。
- 某个状态会被下游当作输入:列出所有读这张表的流程(清算、汇总、对账、通知),逐个确认它们是否直接复制旧状态;只要有一条复制,规则就还会从那里漏出来。
- 给“只对新数据生效”的规则做回归:构造一条调整前就已存在的目标状态数据,再执行一次下游流程,确认结果符合新规则;只测调整后新生成的数据会漏掉这一类。
- 用清数据收尾:确认清理范围包含的合同、账期和状态条件,并在清理后复跑一次原流程;清数据能止血,但不能替代规则范围的定义。