发生了什么
网点是平台在线下开的经营点位,租场地、放设备、对外营业。签约之前它叫“潜在网点”:资料已经录进系统,还没和场地方走完合同,系统给它挂一个子状态“待签约”,表示这个点位随时可以发起签约。签约要走内部的审批工作流,运营在后台提交一份签约申请,工作流按级别逐级审批,审批通过后签约系统再生成一份合同记录,记录这份合同走到哪一步:合同生成中、签署中、已签成、已作废。审批工作流自己还有一套状态:审批中、审批通过、撤回、作废。
两套状态各管一段,靠消息连接。工作流状态一变,审批平台就给签约系统推一条状态消息,签约系统的回调消费程序收到后按状态改合同记录,同时改潜在网点的子状态。
正常情况是:审批通过,回调把合同记录推进到生成中、签署中,签成后置为已签成,网点子状态变成已签约;如果审批在通过之前被撤回或作废,回调应当把合同记录置为已作废,网点子状态退回待签约,运营可以重新发起一份申请。
这次是一位提报人自己把审批撤回了。工作流上显示撤回,网点后台却仍然认为这个点位有合同在进行中,重新发起签约走不下去,只能把问题反馈过来。研发核对后确认:撤回的状态消息已经推到签约系统,回调消费程序收到后没有处理,合同记录停在“合同生成中”这类进行中状态,潜在网点的子状态也没有回退。当天用内部的状态更新接口把这条合同记录置为已作废、子状态改回待签约,重新签约才恢复。确认影响是这一个点位在订正前无法重新签约,网点的营业状态没有受影响。
本质
审批回调消费程序是按状态编码分支处理的:审批中走一条,审批通过走一条,其余全部直接返回。
- 撤回的状态编码是 6,作废是 4 和 5。这三个值都不在任何分支里,全部落到最后的 return 上。程序既不写合同记录,也不回退网点子状态,也没有留下“这个状态我没处理”的记录。
- 合同记录因此停在“合同生成中”。从业务看,这是一条还活着的合同,签约流程没有结束。
- 潜在网点的子状态也没有回到“待签约”。重新发起签约依赖子状态为待签约,子状态不动,发起动作就卡住;这次正是把子状态改回待签约之后才恢复的。
- 系统里其实有一个对账任务,会比对工作流状态和本地合同记录。它能扫出这类不一致,但对 4、5、6 这几种状态只发告警,不做订正。告警发出后没有自动处置,记录就一直挂着,最后变成业务群里的反馈。
- 合同签署侧的状态枚举里也没有“撤回”这一项。将来在签署回调里处理撤回,得先补上这个值,否则消息到了也没有状态可写。
回调只覆盖了审批通过这一条路径,撤回和作废落到 default 后静默返回,合同记录和网点子状态一起停在中间态。
修复方向是:回调里补撤回、作废分支,统一把合同记录置为已作废并回退网点子状态;对账任务从“只告警”升级为“自动订正”,用灰度开关控制;签署侧状态枚举补上撤回值,并在签署状态变更回调里增加分支。本次是手工订正,上述改造的上线状态待确认。代码为脱敏教学示例,用来说明缺口与补法,不代表实际项目源码或已上线实现。
错误代码
// 审批状态回调:只处理审批中与审批通过
public void onApprovalMessage(ApprovalMessage msg) {
if (msg.getStatus() == APPROVING) {
contractService.markApplying(msg.getBizId());
return;
}
if (msg.getStatus() == APPROVED) {
contractService.startGenerate(msg.getBizId());
return;
}
// 为什么错:撤回(6)、作废(4/5) 都落到这里直接返回,
// 合同记录不改、网点子状态不回退,也没有任何告警
return;
}
// 对账任务:扫出不一致后只告警,不订正
public void reconcile() {
for (ContractRecord r : recordMapper.listInconsistent()) {
// 为什么错:告警发完没人接手,记录继续锁着网点
alert.warn("合同状态与审批流不一致", r.getId());
}
}
修复代码示例
// 审批状态回调:撤回、作废显式接住,未知状态不静默返回
public void onApprovalMessage(ApprovalMessage msg) {
switch (msg.getStatus()) {
case APPROVING -> contractService.markApplying(msg.getBizId());
case APPROVED -> contractService.startGenerate(msg.getBizId());
case RECALL, VOID, INVALID -> {
// 合同记录作废,网点子状态回退到待签约
contractService.cancel(msg.getBizId());
nodeService.resetSubStatus(msg.getNodeId(), WAIT_SIGN);
}
default -> alert.warn("未覆盖的审批状态 " + msg.getStatus()); // 不静默返回
}
}
// 对账任务:灰度范围内直接订正,范围外转人工
public void reconcile() {
for (ContractRecord r : recordMapper.listInconsistent()) {
if (!autoFixSwitch.isOn(r.getNodeId())) {
alert.warn("未开自动订正,转人工", r.getId());
continue;
}
contractService.cancel(r.getId());
nodeService.resetSubStatus(r.getNodeId(), WAIT_SIGN);
}
}
下次遇到这些场景要警惕
- 评审审批状态回调:把工作流的状态枚举全量列出来,逐个确认有没有分支;对没有分支的值,实际构造一次撤回,观察合同记录、网点子状态和日志三处是否都有变化。
- 对账任务只发告警:找一条被扫出的不一致记录,跟踪告警之后由谁处理、多久处理完;没有处置人和时限,等于只做了检测,问题仍在。
- 状态机要新增撤回、作废:先确认状态枚举里有没有这个值,再看所有写这份状态的地方——工作流回调、签署回调、定时任务——是否都认识它。
- 签约资格按子状态判定:把子状态手工改回待签约再走一遍发起流程,确认卡点确实在子状态而不是其他校验,避免只改一面。