发生了什么

平台和商户之间的钱,是按结算单结的。结算单把一段时间内某个商户的应收、应付款项算成一张单据,单子上有结算对象商户(这笔钱付给谁)、金额,以及这笔业务属于哪条业务线、哪个业务场景。单据确认后进入打款环节。打款不是平台自己从银行账户转账,而是交给外部支付通道执行;通道要求指明这笔钱走哪个“三方支付商户”,也就是平台在通道侧登记过的收款身份。所以结算单上除了结算对象,还要带上这个三方支付商户。

这份“业务线 + 业务场景 → 三方支付商户”的对应关系,维护在配置中心的一份清单里,不写死在代码中。正常上线一个新场景时,要在这份清单里补一条:哪个业务线的哪个场景,用哪个三方支付商户、商户名称是什么。清单里有了条目,该场景生成的结算单在创建时就能带出三方支付商户,走到打款时直接提交给通道。

这次不一样的地方是:一个按实际用量计费的租赁场景已经投入使用了,结算单能正常生成,金额和结算对象都对,但配置清单里没有这个场景的条目。结算单上的“三方支付商户”因此是空的,单据照常往下流转,直到发起打款时才发现没有可用的支付商户,钱打不出去。业务方是在该场景已经产生待打款结算单之后才反馈的,此时补配置只是第一步,已经生成的那批单据还需要单独处理,不能指望它们自己恢复成可打款状态。

处理方式是在配置清单里补上该场景对应的三方支付商户,让后续该场景的结算单能正常带上收款方;同时把这个靠人工维护的配置迁到数据字典,作为一项改进。修复上线后的验证情况,记录里没有说明。

本质

问题出在“取三方支付商户”这一步,以及这个字段缺失后没有被当成错误。

  1. 新场景上线是业务侧推进的,配置清单的维护是另一条人工流程。代码已经能为这个场景算出金额、生成结算单,配置侧却没有同步登记条目,两件事之间没有任何检查把它们绑在一起。
  2. 打款前按“业务线 + 业务场景”两个条件去清单里精确匹配。清单里没有这个场景的条目,匹配结果就是空,代码把空值原样放进结算单,不抛异常,也不留下能看见的失败记录。
  3. 结算单生成时没有校验收款方信息是否齐全。单据照常落库、照常流转,从队列里的下一个环节看,它和正常单据没有区别,只是“三方支付商户”那一栏是空的。
  4. 直到发起打款,这个字段才第一次被真正使用。打款必须知道走哪个支付身份,空值在这里变成硬失败。此时失败的位置离原因已经很远:要先把单据上的业务线和场景取出来,再去配置里核对有没有这一条,才能定位到是配置漏了。
  5. 影响不止一张单。映射是按场景登记的,清单里没有这个场景,该场景下每一张结算单取到的都是空值,都要在补配置后重新打款。具体多少张,要按场景把待打款单据筛一遍才能确定。

必填的收款方信息靠人工按场景登记,漏一条不会在建单时暴露,要等到打款时才变成“钱付不出去”。

修复方向有三层:配置查询取不到时显式失败,并把业务线、场景两个条件写进错误信息;生成结算单时就校验这个字段并拦截,让缺配置的单据不进入待打款队列;场景上线时对清单做一次完整性检查,缺条目就阻断上线。短期处理是补配置,再对存量单据重新发起打款。

错误代码

// 配置清单按“业务线 + 业务场景”逐条登记收款商户(键名与取值为示意)
public ThirdMerchant resolve(String bizLine, String scene) {
    return merchantConfigList.stream()
            .filter(c -> c.getBizLine().equals(bizLine)
                      && c.getScene().equals(scene))
            .findFirst()
            .map(ThirdMerchant::of)
            // 为什么错:新场景没有登记时这里返回 null,调用方看不出“缺配置”,
            // 空值会一路带进结算单,没有任何异常或失败标记
            .orElse(null);
}

public void createSettlement(Settlement settlement) {
    // 为什么错:生成结算单时不校验收款商户是否取到,空值直接落库
    settlement.setThirdMerchant(
            resolve(settlement.getBizLine(), settlement.getScene()));
    settlementMapper.insert(settlement);   // 单据照常生成、照常流转
}

public void pay(Settlement settlement) {
    // 到打款才取值:这里空指针失败,离真正的错误点已经很远
    paymentChannel.submit(settlement.getThirdMerchant().getMerchantId());
}

修复代码示例

// 取不到就显式失败,并把两个匹配条件写进错误信息,排查不用再猜
public ThirdMerchant resolveRequired(String bizLine, String scene) {
    return merchantConfigList.stream()
            .filter(c -> c.getBizLine().equals(bizLine)
                      && c.getScene().equals(scene))
            .findFirst()
            .map(ThirdMerchant::of)
            .orElseThrow(() -> new MerchantConfigMissingException(
                    "未登记三方支付商户, bizLine=" + bizLine + ", scene=" + scene));
}

public void createSettlement(Settlement settlement) {
    // 生成单据时就校验,缺配置的单据当场被拦住,不进入待打款队列
    settlement.setThirdMerchant(
            resolveRequired(settlement.getBizLine(), settlement.getScene()));
    settlementMapper.insert(settlement);
}

public void pay(Settlement settlement) {
    ThirdMerchant merchant = settlement.getThirdMerchant();
    if (merchant == null) {   // 历史单据可能绕过创建校验,打款前再兜一层
        throw new MerchantConfigMissingException(
                "结算单缺少三方支付商户: " + settlement.getNo());
    }
    paymentChannel.submit(settlement, merchant.getMerchantId());
}

场景上线前的一次性完整性检查(示意):

for (Scene scene : sceneRegistry.all()) {
    boolean registered = merchantConfigList.stream()
            .anyMatch(c -> c.getBizLine().equals(scene.getBizLine())
                        && c.getScene().equals(scene.getCode()));
    if (!registered) {   // 缺条目就让上线检查失败,不再依赖有人记得手工补
        throw new IllegalStateException("场景未登记三方支付商户: " + scene.getCode());
    }
}

下次遇到这些场景要警惕

  • 新业务线或新结算场景上线前:把“按场景登记的必填映射”单独列成检查清单(收款商户、通道、税率),逐项确认配置里已有条目;只验证“结算单能生成”不算通过。
  • 用一个没登记的场景编码造一张结算单:观察系统是当场报错,还是照常生成一张收款方为空的单据。把这个用例写进回归,避免下次换个人又漏。
  • 排查“打不了款”“没有收款方”这类问题:先看单据上的业务线和场景能否在配置里精确匹配到条目,再怀疑支付通道;空字段往往比报错更早出现在页面上。
  • 把人工维护的白名单配置迁到数据字典或配置管理之后:仍然保留“缺失即失败”,不要用默认商户这类兜底把缺失掩盖过去,否则问题会从打款失败变成打给错误对象。