发生了什么

换电业务在线下铺开靠的是一批“网点”:门店或场地里放置换电柜,用户把没电的电池放进柜子,换一块满电的带走。网点正式上线前要先签约,系统里会先建一条“潜在网点”记录——点位已经选好,但合同还没签,所以暂时不能对外运营。

签约由运营在后台发起:在签约页面填写签约主体、收款账户等信息,系统据此生成合同,发送到电子签平台由对方签署。签署完成后,电子签平台回调后台。后台收到回调要做两件事:把这份合同的签约状态改为“已签约”,再调用商户系统的接口,为这个签约主体绑定银行卡。两步都完成,网点才能继续上线流程。

这次的问题出在填写环节。运营填写的一项文本信息末尾带进了一个换行符,提交页面没有清理首尾空白,接口也没有再校验,这个值就原样存进了合同记录。合同本身在 7 月 20 日正常签署完成,但后台一直显示“签约中”。

排查发现,回调其实已经到达。后台拿着这条带换行的信息去商户系统绑卡,商户接口校验不通过,直接报错;回调处理在这里抛出异常退出,更新合同状态那一步没有执行,合同记录就停在“签约中”。确认的影响是:合同真实已经签完,系统里的状态却没有跟上,运营在页面上只看到一个不再变化的“签约中”,也看不出是绑卡这一步失败的。这类记录不会自己恢复,需要对这一单刷数处理,把库里带换行的值清掉。

本质

一句话:入口没有去掉换行符,这个脏值一路传到商户接口;回调又把绑卡和改状态串成一条必须全部成功的顺序流程,绑卡一报错,状态就再也不会前进。

  1. 原流程。运营提交签约信息后,后台把它写进合同记录并发起电子签。对方签完,电子签平台回调后台,后台用合同记录里的信息调商户接口绑卡,绑卡成功后把合同状态改为已签约。整条流程默认“提交上来的值就是可用的值”。
  2. 这次不同的数据。运营提交时,文本末尾多了换行符。前端没做 trim,后端也没有再清洗一次,换行符跟着这条记录进了库,成为这份合同的一部分。
  3. 出错的一步。回调到达后,后台把这条信息原样传给商户系统。商户接口对传入的值做校验,带换行的值过不了校验,接口返回错误。这是整条回调里第一个失败的地方。
  4. 为什么状态没变。回调代码把绑卡和状态更新写在一条顺序流程里,绑卡抛异常后流程直接退出,更新合同状态、记录回调结果这些后续动作都没有执行。于是外部合同已经生效,系统内的记录还停在“签约中”,两个状态就此分叉。
  5. 结果和处置。这条记录既没有变成已签约,也没有留下可重试的失败态。修复方向有两处:前端针对输入内容增加 trim 校验,挡住首尾空白;已经卡住的这一单需要刷数据处理,清掉库里带换行的值,再把状态补正。刷数的具体做法和修复的上线状态都待确认。

修复范围只到入口校验和存量刷数两处:回调里绑卡失败之后状态如何推进,目前还没有对应处置,后续再遇到同类外部失败,合同仍可能被留在中间态。

入口没有清掉的换行符会一路带到下游接口,在那里才第一次报错;此时本地状态已经停在中间态,靠重试回不来。

错误代码

// 提交签约:表单值原样落库并发起电子签(脱敏教学示例)
public void submitSign(SignForm form) {
    ContractRecord record = new ContractRecord();
    // 为什么错:文本没做归一化,末尾的换行、制表符、全角空格都会原样进库
    record.setSubjectName(form.getSubjectName());
    record.setBankCardNo(form.getBankCardNo());
    contractMapper.insert(record);
    eSignClient.create(record);
}

// 签约完成回调:绑卡和状态更新串在一条顺序流程里
public void onSigned(ContractSignedEvent event) {
    ContractRecord record = contractMapper.selectByNo(event.getContractNo());
    // 为什么错:带换行的值被原样传给商户接口,接口校验不通过直接报错
    BindResult result = merchantClient.bindCard(record.getSubjectName(), record.getBankCardNo());
    if (!result.isSuccess()) {
        // 为什么错:抛异常让整个回调退出,后面的状态更新再也执行不到
        throw new BizException("绑卡失败:" + result.getMsg());
    }
    record.setStatus(SIGNED);
    contractMapper.updateStatus(record);
}

修复代码示例

// 修复:提交时统一归一化,换行、制表符和首尾空白都在入口清掉(脱敏教学示例)
public void submitSign(SignForm form) {
    String subjectName = normalize(form.getSubjectName());
    if (subjectName.isEmpty()) {
        throw new BizException("请填写签约主体信息");
    }
    ContractRecord record = new ContractRecord();
    record.setSubjectName(subjectName);
    // 修复:卡号这类字段不允许任何空白字符
    record.setBankCardNo(normalize(form.getBankCardNo()).replace(" ", ""));
    contractMapper.insert(record);
    eSignClient.create(record);
}

private static String normalize(String raw) {
    if (raw == null) {
        return "";
    }
    // 修复:连续空白压成一个空格,再去掉首尾空白,换行不会再跟着进库
    return raw.replace('\u00A0', ' ').replaceAll("\\s+", " ").trim();
}

存量记录要单独处理:把库里带回车、换行或首尾空白的值清掉,再把这一单的签约状态补正。只改入口校验不会纠正已经入脏的数据,这部分必须刷数,具体范围和操作方式待确认。

下次遇到这些场景要警惕

  • 签约、建户这类要把用户填写内容传给下游系统的表单:提交前先列出这些字段会经过哪些接口,在入口统一去掉首尾空白和换行,再落库和外发,不要指望下游容忍脏值。
  • 回调处理里同时有外部调用和本地状态更新时:构造下游接口失败的分支,观察本地状态会不会停在中间态、有没有可重试的失败态和错误记录;会停住就说明这两步需要拆开或补上重试。
  • 测试签约链路时:用例里放一条首尾带空格、带换行、带全角空格的输入,完整走一遍签署完成回调,确认状态能推进到已签约、绑卡能成功;这类数据用正常输入永远测不出来。
  • 排查“合同签了但系统没签”的问题时:先看回调有没有到达、卡在回调的哪一步,再核对入库的值和外部系统拿到的值是否一字不差,不要一上来就怀疑回调丢失。

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