发生了什么
商户和平台签框架协议,约定双方怎么合作、按什么税目开票、怎么结算。协议在系统里落成一条合同记录,记录上有一项「税目」,是开票时票面必须填的税收分类;还有一个付款方式,决定先开票还是先付款。签完合同也不算结束:系统要按这份合同给商户建一条「结算规则」,规则里带着税目和结算信息,后续收款和发票校验都以它为准。商户把发票上传到平台时,系统取结算规则上的税目,与票面税目比对,一致才收下,不一致就提示税目或税率不对。
正常的顺序是:商户在签约平台签完,签约平台把合同置为已签署并归档,同时发出一条状态变更消息;本地合同程序收到后,把合同状态从签约中改成已签署,回写归档时间,再按新合同建结算规则。之后商户按合同约定的税目开票、上传,校验通过。
这次,商户在 6 月 11 日签了新协议,改了税目,付款方式也从先款后票改成先票后款;6 月 13 日签约平台侧完成签署归档。但本地合同记录一直停在签约中,那条状态变更消息没有在本地生效,建结算规则这一步也就没有执行。商户按新协议开票、在 App 上传时,系统能取到的仍是上一份合同留下的结算规则,税目是旧的「现代服务」,票面却是新协议的「生产生活服务」,两边对不上,上传被拦下,提示税目税率不正确。商户看到的是自己的票被判定填错,实际上票是按新协议开的。最后只能由内部人员线下收票上传。
核查看到:签约平台侧这份合同已是归档状态,签署时间对得上;本地合同状态仍是签约中;商户名下有效的结算规则还绑着旧合同,税目是旧值。消息是在投递环节丢了,还是消费时报错后被确认掉,日志已过保留期,无法再区分。从 6 月签署到 8 月商户反馈,中间没有任何环节把这条合同拉回来。
本质
一句话:合同签完之后该做的收尾动作只挂在一条状态变更消息上,消息没生效,本地状态和结算规则就都停在旧值;发票校验又默认规则一定存在且是新的,于是把「规则没建出来」报成了「税目填错」。
- 收尾动作只有一条触发路径。状态从签约中改成已签署、回写归档时间、按新合同建结算规则,三件事都在同一条消息的消费逻辑里。消息一旦没有被成功消费,三件事一起不发生,也没有第二个入口去补。
- 卡住的状态没有出口。合同停在签约中,系统没有回查签约平台,也没有任何环节在两个多月里重新处理它。商户不反馈,就没人知道它还卡着。
- 校验读的是「最新有效规则」,不是「这份合同的规则」。新规则没建出来,旧规则仍然有效,校验照旧拿旧税目比对。规则与当前合同的对应关系没有被检查,配置缺失就被当成了票面填错。
- 报错把排查方向带偏。提示只说税目税率不正确,没有说清系统取到的是哪份合同、哪个税目、规则是什么时候建的。商户只能反复核对发票,最后转线下。
- 怎么解开。补发一条状态为已签署的消息,消费逻辑重跑,把合同状态改成已签署、回写归档时间、按新合同建结算规则,规则税目变成新值,再让商户重新上传。同期签署的其他合同也可能有同样问题,需要一并排查;这是风险提示,不是已确认的批量影响。
一条消息同时承担「改状态」和「建下游规则」两件事,消息没生效时,没有环节能发现合同一直没到终态,配置缺失最终显示成用户填错。
修复方向是:把「合同已签完但本地仍停在签约中」做成能被自动发现并重放的状态,而不是等商户投诉;发票校验也要区分「规则缺失或仍绑旧合同」和「票面税目填错」,前者不该让商户改票。上面这些代码是按这条链路写的脱敏教学示例,不代表实际项目源码或已上线实现。
错误代码
class ContractSignedHandler {
// 为什么错:改状态、回写归档时间、建结算规则只在这一个入口里,
// 入口由一条状态变更消息触发;消息没生效,三步一起丢,没有第二个入口
public void onSigned(String contractNumber, Date signedAt) {
contractRepository.updateStatus(contractNumber, "SIGNED");
contractRepository.updateFilingTime(contractNumber, signedAt);
settlementRuleService.createCityStlRule(contractNumber);
}
}
class InvoiceValidator {
public void check(InvoiceUploadRequest req) {
// 为什么错:取的是“最新有效规则”,不校验它绑在哪份合同上;
// 新规则没建出来时,旧合同税目被当成标准,报错只说税目税率不正确
SettlementRule rule = ruleRepository.findLatestValid(req.getMerchantId());
if (!rule.getTaxCategory().equals(req.getTaxCategory())) {
throw new BizException("发票税目税率不正确");
}
}
}
修复代码示例
class ContractSignedHandler {
// 修复:两步各自判重,补发或重放都不会重复,也不会只改状态漏建规则
@Transactional
public void onSigned(String contractNumber, Date signedAt) {
if (!"SIGNED".equals(contractRepository.getStatus(contractNumber))) {
contractRepository.updateStatus(contractNumber, "SIGNED");
contractRepository.updateFilingTime(contractNumber, signedAt);
}
if (!settlementRuleRepository.existsByContractNumber(contractNumber)) {
settlementRuleService.createCityStlRule(contractNumber);
}
}
}
class SignedContractReconcileJob {
// 修复:按“停在签约中超过阈值”取数(24 小时为示意值),回查后重放收尾
public void run() {
for (Contract c : contractRepository.findSigningOlderThan(Duration.ofHours(24))) {
RemoteContract remote = signClient.query(c.getContractNumber());
if ("ARCHIVED".equals(remote.getStatusCode())) {
contractSignedHandler.onSigned(c.getContractNumber(), remote.getSignedAt());
}
}
}
}
发票校验沿用同一个类,只把取规则的方式改成按合同取:
class InvoiceValidator {
public void check(InvoiceUploadRequest req) {
Contract contract = contractRepository.getEffective(req.getMerchantId());
SettlementRule rule = ruleRepository.findByContractId(contract.getId());
if (rule == null) {
// 修复:规则缺失时明确报配置问题,不再拿旧合同税目比对
throw new BizException("当前合同的结算规则未生成,请补发签约完成消息");
}
if (!rule.getTaxCategory().equals(req.getTaxCategory())) {
throw new BizException("发票税目与合同不一致:合同=" + rule.getTaxCategory()
+ ",票面=" + req.getTaxCategory());
}
}
}
下次遇到这些场景要警惕
- 给「外部状态变更 → 本地状态 + 下游初始化」接消息时,先只发一次消息并让消费逻辑在中途失败,观察它是否重试、是否进死信、下游规则有没有建。任何一条路径静默确认,就要补回查或重放入口。
- 按状态加时间筛出停在中间态的记录,确认有没有任务回查外部、有没有超时提醒。本例从 6 月签署到 8 月商户反馈,中间没有任何兜底,这个查询能提前暴露它。
- 下游校验依赖「最新有效配置」时,核对它与当前业务对象的绑定关系。规则缺失或还绑在旧合同上,应当在正确的位置报配置问题,而不是继续用旧值比对后归因到用户填写。
- 补数据时把状态和派生数据一起验:合同改成已签署后,确认归档时间已回写、结算规则已按新合同生成、税目已更新,再让商户重传,避免只改状态不建规则。