发生了什么

网点是平台在线下开的经营点位,租场地、放充电设备,对外营业。系统里每个网点有一份档案,记着经营状态、归属商户,还有一个「最新合同状态」。网点要和场地方签合同才能开,合同决定它在什么时间范围内可以经营、结算归到哪个商户。合同签完以后要改条款,不是直接改原合同,而是另起一份变更协议,在外部电子签平台重新签一次。

网点档案上的这个状态由合同程序从合同记录同步过来。商家后台判断网点能不能关闭、也就是终止合作时,读的就是它:签约中说明合同流程没走完,后台直接拦下,避免合同签了一半就把点位关掉。正常情况是双方签完、平台置为已生效、内部把合同记录和网点状态一起改成已签约,后台放行;如果变更协议最后没签成,业务上应当把它作废,让网点回到上一份有效合同的状态。

4 月 20 日,有人为某网点发起了一份变更协议。签署方此后一直没完成电子签:到 8 月查签署平台,合同状态仍是签署中,签署方标记为未完成,也就是它从头到尾没签成过。这份协议自那天起再没有任何更新,网点档案上的最新合同状态也一直是签约中。

8 月下旬,值班人员接到反馈:这个网点在后台一直显示签约中,关闭操作做不了。实际网点早已撤柜停业、电柜全部停用,当前真正有效的是另一份已验签通过的合同,在正常履约。这不影响有效合同的结算和履约,影响就是这个网点关不掉。

本质

一句话:一份发起后再也没人签的变更协议,把网点的最新合同状态固定成了签约中;唯一能自动纠正它的对账任务只回扫最近 62 天更新过的记录,这条记录过了窗口就被漏掉,从此没有任何路径把它改回来。

  1. 发起时写了什么。协议创建后本地合同记录是签约中,同步程序又把这份状态写到网点档案上,网点也变成签约中。这一步本身没错,流程确实开始了。

  2. 业务上没有继续。签署方一直没完成电子签,签署平台如实返回签署中、签署方未完成。这份协议不会自己变成已签约,也不会再有新状态回来。它缺的不是把外部状态同步过来,而是结束它。

  3. 本地没有结束它的规则。系统没有「发起后多少天仍未签完就自动作废、网点状态回退到上一份有效合同」的处理。中间态只有收到新状态才会被改写,没有新状态就一直留着。

  4. 兜底够不到它。定时对账按合同记录的更新时间取数,只回扫最近 62 天内更新过的记录。这条记录的更新时间停在 4 月 20 日,6 月下旬起就不在扫描范围里。

  5. 后台照这个值判断。关闭检查读到签约中,就认定流程没走完,把操作拦下。真正有效的合同在履约,网点状态却停在另一份没签完的协议上。

  6. 这次怎么处理。在签署平台把这份协议作废,把本地合同记录改成已取消,再把网点状态改回已签约并从有效合同回填商户,最后在后台确认可以关闭。这是按单个网点人工订正,机制没改:同样的协议再发起一次、再没人签,还会停在同一个地方。修复方向是给发起后长期没签完的协议加超时作废并回退到有效合同;对账改成按未到终态取数;关闭判断遇到长期停在签约中时先回查签署平台。修复上线状态待确认。

这里最容易看漏:对账只能纠正「外部已经变了、本地没跟上」,纠正不了「外部一直没变、流程根本走不完」。

错误代码

// 合同状态同步、定时对账与网点关闭判断(脱敏教学示例)
class ContractSyncService {
    void onAgreementStarted(Agreement a) {
        contractMapper.updateStatus(a.getContractNo(), "SIGNING");
        // 为什么错:协议刚发起就把签约中写到网点上,之后没有超时作废的出口
        nodeMapper.updateLatestContractStatus(a.getNodeId(), "SIGNING");
    }
    void reconcile() {
        // 为什么错:只回扫最近 62 天内更新过的记录;这份协议停在发起那天,
        // 过了窗口就永远进不了扫描结果,状态再没人改
        for (Contract c : contractMapper.selectUpdatedWithin(62)) {
            String remote = signClient.queryStatus(c.getContractNo());
            if (!remote.equals(c.getStatus())) {
                contractMapper.updateStatus(c.getContractNo(), remote);
                nodeMapper.updateLatestContractStatus(c.getNodeId(), remote);
            }
        }
    }
    void assertClosable(Node n) {
        // 为什么错:只读本地这个值,既不回查签署平台,也不看当前有效合同
        if ("SIGNING".equals(n.getLatestContractStatus())) {
            throw new BizException("网点合同流程中,暂不能关闭");
        }
    }
}

修复代码示例

// 修复:对账不按时间截断,未签完的协议能作废并回退到有效合同(脱敏教学示例)
class ContractSyncService {
    // 修复一:按未到终态取数,历史记录也能被回查
    void reconcile() {
        for (Contract c : contractMapper.selectUnfinished()) {
            applyRemote(c, signClient.queryStatus(c.getContractNo()));
        }
    }
    // 修复二:发起后超过 EXPIRY_DAYS 仍未签完,主动作废并回退网点状态
    void expireUnsigned() {
        for (Contract c : contractMapper.selectSigningOverDays(EXPIRY_DAYS)) {
            signClient.voidContract(c.getContractNo());   // 外部先作废,别让它一直挂着
            contractMapper.updateStatus(c.getContractNo(), "CANCEL");
            Contract valid = contractMapper.selectValidByNode(c.getNodeId());
            applyRemote(c, valid.getStatus());            // 网点状态回到有效合同
            nodeMapper.updateMerchant(c.getNodeId(), valid.getMerchantId(), valid.getMerchantName());
        }
    }
    // 修复三:关闭判断遇到签约中,先回查外部,真没签完才拦
    void assertClosable(Node n) {
        if ("SIGNING".equals(n.getLatestContractStatus())) {
            Contract c = contractMapper.selectSigning(n.getNodeId());
            if ("SIGNING".equals(signClient.queryStatus(c.getContractNo()))) {
                throw new BizException("网点合同流程中,暂不能关闭");
            }
            applyRemote(c, "SIGNED");
        }
    }
}

两段代码对应同一处缺口:错误版让网点状态只跟着最近一次同步走,对账按更新时间截断,关闭判断只读本地值;修复版补上未到终态回查、超期作废回退、关闭前回查。applyRemote 表示把外部状态同时写到合同记录和网点档案上,EXPIRY_DAYS 是示意阈值;上面的改法是从原因推导的方向,未实施也未验证。

下次遇到这些场景要警惕

  • 给合同、协议这类外部签署流程做状态同步时:构造一笔发起后一直没人签的协议,等过了对账窗口再查网点状态,确认它有超时作废或可人工结束的入口,而不是只能改库。
  • 看到网点、订单被某个状态拦住时:顺着值找到来源记录和它最后一次更新时间;如果已早于对账窗口,就别指望定时任务会修好它。
  • 做网点关闭、终止合作这类终态判断时:查清读的是最新那份合同还是当前有效的那份,用一份没签完的变更协议去试,看会不会被判成流程中。
  • 人工订正这类数据时:外部协议、本地合同记录、网点状态、商户信息是四处,按顺序改并逐一核对;只改一处,后台读到的仍是旧值。

代码为脱敏教学示例,用于解释错误与修复思路,不代表实际项目源码或已上线实现;类名、方法名、表名与字段名均为示意。