发生了什么
平台和房东之间按账期结算。每个账期,平台为房东形成若干笔账单,账单上记着应付金额和结算状态,还没付出去的状态叫“待结算”。同一个账期里待结算的账单会归到一张结算单上,房东为这张结算单开票、把发票上传到平台;发票到齐后,系统按结算单发起结算,生成付款单交给财务打款。
正常情况是:账期结束时发票已经上传齐全,账单进入结算,结算单往前推进,付款单随之生成,财务完成打款。整条流程不需要人盯着。
这次不一样。有一批结算单的发票一直没到,账单停在待结算,一停就是 30 多天。房东后来把发票补齐、上传到平台,拦住结算的原因按理说已经消失,结算单应该自己往前走。实际结果是它仍停在待结算,付款单也没有生成。最后是研发对这两张结算单手动触发了一次结算,才生成两张付款单。在后续优化上线之前,这类没有自动恢复的结算单都要研发手动触发。
影响很直接:房东的收款要等人工处理,卡住的结算单越多,人工触发被漏掉或推迟的可能越大。
本质
一句话:发票齐了只是让结算单满足了条件,但没有任何动作因此再去发起结算,结算就停在原地。
- 账单生成时是待结算。要发起结算,这张结算单的发票得先上传齐全;发票没到,账单就进不了结算,停在待结算等着。
- 房东上传发票时,处理这件事的程序只做发票这一侧:登记发票、把结算单的发票状态改成“已上传”,然后结束。
- 把账单提交结算、生成付款单的动作不在这条流程里。发票从“未上传”变成“已上传”之后,没有环节回头再看这些仍在待结算的账单。
- 于是出现这样的结果:拦住结算的条件已经消失,却没有任何动作重新发起结算,账单和结算单都停在原处,付款单也就不会生成。
- 人工触发能补这一次:研发直接对结算单发起结算,账单才进入结算、生成付款单。但人工触发不是恢复机制,下一条卡住的结算单仍然要等人发现。
根子在流程把“前置条件”和“推进动作”放在了两个地方,却没有把两者接起来:发票没到,账单进不了结算;发票后来到齐,也没有任何环节重新推进一次。同时也没有对超期未推进的结算单做兜底扫描,卡住之后只能等业务方反馈。
修复方向是把发票上传完成接成结算的触发点:上传成功后,按账期找出仍在待结算的账单,逐笔发起结算;同时对超过约定时长仍未推进的结算单做兜底扫描,能自动重试的自动重试,不能的报出来提示人工。恢复动作要幂等,同一张结算单只生成一张付款单。后续产品已提需求做逻辑优化,计划在 11 月 13 日上线;是否已验证尚未确认,修复上线状态待确认。
下面两段是脱敏教学示例,用于说明错误与修复思路,不代表实际项目源码或已上线实现。
错误代码
// 教学示例:房东上传发票后只更新发票状态
public void uploadInvoice(Long settlementId, InvoiceFile file) {
SettlementBill settlement = settlementRepo.getById(settlementId);
settlement.setInvoiceStatus(InvoiceStatus.UPLOADED);
settlement.setInvoiceNo(file.getNo());
settlementRepo.updateInvoice(settlement);
// 为什么错:方法到此结束。这张结算单下仍停在“待结算”的账单
// 没有在这里发起结算,也没有别的地方因发票补齐再推进一次
}
// 示意:结算推进入口,发票没上传就直接返回
public void settle(SettlementBill settlement) {
if (settlement.getInvoiceStatus() != InvoiceStatus.UPLOADED) {
// 为什么错:返回之后这批账单不会再被扫到,
// 发票后来补传也不会有人重跑这里
return;
}
for (Bill b : billRepo.listPending(settlement.getPeriod())) {
settlementService.submit(b);
}
}
修复代码示例
// 修复示例:发票补齐后主动重推,不再等人工触发
public void uploadInvoice(Long settlementId, InvoiceFile file) {
SettlementBill settlement = settlementRepo.getById(settlementId);
settlement.setInvoiceStatus(InvoiceStatus.UPLOADED);
settlement.setInvoiceNo(file.getNo());
settlementRepo.updateInvoice(settlement);
// 修复点:发票状态落库后立刻推进这张结算单
settle(settlement);
}
public void settle(SettlementBill settlement) {
if (settlement.getInvoiceStatus() != InvoiceStatus.UPLOADED) {
return;
}
for (Bill b : billRepo.listPending(settlement.getPeriod())) {
// 由“账单号 + 账期”唯一键兜底:自动恢复与人工触发同时发生也只生成一张付款单
settlementService.submitIfAbsent(b);
}
}
// 兜底:定时扫描停留过久、发票已齐却仍在待结算的结算单
public void resumeStuckSettlements() {
for (SettlementBill s : settlementRepo.listStuckBefore(stuckDeadline())) {
if (s.getInvoiceStatus() == InvoiceStatus.UPLOADED) {
settle(s);
}
}
}
下次遇到这些场景要警惕
- 只要流程里有“某个条件满足才能推进”的门槛,比如发票、审批、资质、影像件,先把条件补齐的入口列全,逐个确认补齐之后会重新推进被拦住的单据;不要只在发起时判断一次。
- 凡是会卡住的单据,都要能按状态加停留时长查出来,并有兜底扫描或告警:能自动重试的自动重试,不能的重试就给出人工入口和清单。指望业务方发现,等于没有兜底。
- 恢复动作要幂等。自动恢复和人工触发可能同时发生,按结算单号或账单号加唯一约束,已经生成付款单的不能再生成一张。
- 验证时造一组“发票未到、结算停住、再补传发票”的数据跑完整流程,观察结算单是否自动进入结算、付款单是否只生成一条;再补一组“补传前已有人工触发”的情况,确认不会重复生成。