发生了什么

商户要在某个场所做经营,系统里先得有一个网点。网点是商户在这个场所的经营档案,记着网点名称、网点类型、详细地址、所属商户这些信息;合同签完之后,系统再按合同里填的内容把这份档案建出来,之后跟这个场所相关的事都按网点来办。

合同本身有一个签约状态。新建时状态是“签约中”,双方在签署平台签完、系统按合同把网点档案建好之后,才推进成“已签约”。所以后台应当同时看到两件事:网点列表里有这个网点,对应的合同显示已签约。

这次这位商户的合同已经在签署平台签完了,回传的结果也是已签;但后台打开还是“签约中”,网点列表里也找不到这个网点。原因不在签署环节:签约完成后那段处理要写网点档案,而这一家的详细地址特别长——门牌、楼栋、楼层、园区或市场名称、怎么走,全被写进了详细地址这一栏,字符数超过了网点档案表里“详细地址”这一列能存下的宽度。写网点这一步被数据库拒绝,整段处理回滚,合同状态的推进也跟着撤销了。于是签署结果停在中间:合同还挂在签约中,网点没有落下来。

本质

问题不在签署结果,也不在回滚本身,而在网点档案那列地址的宽度小于真实要存的地址。

  1. 签署平台把“已签完”的结果回调给系统,处理程序要做两件事:按合同内容插一条网点档案;把这份合同的状态改成已签约。两件事放在同一个事务里,要么都成,要么都不成。
  2. 插网点档案时,详细地址按合同里填的原样写入。这一列在建表时按字符数定了宽度,比这家网点的真实地址短。地址长在业务上是正常的:一栋楼的地址可以写大门牌、楼栋号、楼层、园区或市场名称,再补一句怎么走,录入侧没有按这个宽度做校验,保存前也没有拦下来。
  3. 数据库不接受超长的值,插入这一步抛错,异常越过方法边界,把整个事务标成失败。
  4. 事务回滚,把同一事务里已经执行的合同状态更新一起撤销。回滚是事务该有的行为,可结果是:网点没建出来,合同也没推进到已签约,两个结果一起消失,页面上只剩“签约中”。这段处理之后没有再成功执行过,合同于是一直停在这个中间态。
  5. 结果是合同和网点一起停住:网点列表里没有这条档案,合同也一直显示签约中,这个点位就停在“签了但没生效”的样子,只能由人拿合同逐条核对再补。

一条比列宽长的地址,让整笔签约建档回滚,合同状态和网点记录一起没落库,页面上只剩“签约中”。

修复方向是先把“详细地址”这一列加宽到能存下真实最长的地址,让正常地址不再触发写入失败;同时把长度校验放到保存之前,超长时明确报出字段和长度,而不是等数据库抛错再整笔回滚。已经卡在签约中的合同,要按已签的合同重新建档并把状态推进到已签约。列宽加宽、校验前移是否已经上线、存量怎么订正,现有信息没有说明,上线与验证状态待确认。

下面的 Java 代码为脱敏教学示例,用于解释“地址超过列宽、写入被拒、整笔事务回滚”的机制与改法,不代表实际项目源码或已上线实现。

错误代码

// 签约完成回调:建网点档案 + 推进合同状态(示意)
@Transactional
public void onContractSigned(SignedContract contract) {
    Site site = new Site();
    site.setMerchantId(contract.getMerchantId());
    site.setSiteName(contract.getSiteName());
    // 为什么错:详细地址按合同原样写入,没有按列宽校验,
    // 门牌、楼栋、园区名写全了就超过这一列的宽度
    site.setDetailAddress(contract.getDetailAddress());
    siteMapper.insert(site);   // 为什么错:库在这里拒绝,抛异常
    // 为什么错:状态推进和建档在同一个事务里,
    // 上面插入失败后,下面这行更新会被一起回滚
    contractMapper.updateStatus(contract.getId(), ContractStatus.SIGNED);
}

修复代码示例

// 修复:详细地址列按真实最长地址加宽(DDL 单独执行,宽度为示意)
// ALTER TABLE site MODIFY COLUMN detail_address VARCHAR(255);

@Transactional
public void onContractSigned(SignedContract contract) {
    String address = contract.getDetailAddress();
    if (address != null && address.length() > DETAIL_ADDRESS_MAX) {
        // 修复:保存前按加宽后的列宽校验,超长当场报出字段和长度,
        // 不再等数据库抛错后把状态推进一起回滚
        throw new BizException("网点详细地址超出可保存长度: " + address.length());
    }
    Site site = new Site();
    site.setMerchantId(contract.getMerchantId());
    site.setSiteName(contract.getSiteName());
    site.setDetailAddress(address);
    siteMapper.insert(site);
    contractMapper.updateStatus(contract.getId(), ContractStatus.SIGNED);
}

下次遇到这些场景要警惕

  • 给地址、名称这类字段定列宽时:先按线上真实数据统计最长值,把门牌、楼栋、楼层、园区或市场名、方位描述都算进去,再核对列宽;构造一条刚好超过列宽的地址走完整签约,看它是被明确拒绝,还是整笔处理回滚后什么都没留下。
  • 写档案和推进状态放在同一个事务时:专门让档案写入失败一次,检查合同状态和网点记录是否一致;确认卡在中间态的那笔会被重试或人工重放,而不是只留一条异常日志。
  • 看到数据库写入报错时:确认报错能落到表名和字段名,日志里能看出哪个值有多长;否则只能拿业务编号逐条查,才知道是地址长了。
  • 加宽字段之后:按“合同已签完但网点没建”的条件把存量扫一遍,确认每一份签完的合同都有对应网点,别只修了以后不再发生的那部分。