发生了什么

平台上的商户分两级:一级商户负责拓展合作,二级商户挂在一级商户名下。两者之间的分润规则按城市逐条约定:一条规则对应一座城市,写明这条合作怎么分润,并带有有效期,快到期时可以续签一年。

规则保存在一级商户这一侧。二级商户要看到这些规则并据此参与分润,需要系统再同步一次:同步程序按一级商户找到它名下的二级商户,把规则写到二级商户名下。正常流程是,一级商户在后台为某座城市的规则续签一年,保存后同步程序遍历下属二级商户,确认这个商户属于应当接收规则的类型,然后写入或更新对应的规则。续签完成后,二级商户后台里这条规则的有效期应该变成新的。

这一次,一个一级商户在某座城市有两条规则一起续签了一年,另外两座城市各有一条规则也做了延期,一共四条规则、三座城市。续签保存后,二级商户后台里只有那条已经过期的规则,四条规则的续签一条都没有出现。续签动作在一级商户这边是成功的,规则却没有到二级商户那边;页面也没有任何失败提示,最后是业务方在值班群里反馈后才被发现的。

本质

问题不在某一条规则的字段上,而在同步程序对二级商户的筛选上。

  1. 同步程序先取出一级商户名下的二级商户列表,再读取一级商户这侧的规则,准备逐条写入。
  2. 写之前要确认这个二级商户是否属于可以接收规则的类型,判断依据是商户记录里的“合作模式”字段。正常二级商户的值应当是“一级下属的二级”。
  3. 这次涉及的二级商户,该字段里存的却是 -1,不在同步逻辑允许的合作模式范围内。
  4. 程序按白名单过滤,遇到不在范围内的值就跳过这个商户,接着处理下一个。被跳过的不是一条规则,而是整个商户,它名下所有规则都不再参与同步,也不会留下失败提示。
  5. 于是四条规则一条都没写过去。二级商户后台查到的还是更早一次同步成功、后来到期的那条规则,所以页面上只剩一条过期规则。

这个值是怎么变成 -1 的,目前没有确认,可能是历史数据迁移留下的,也可能是创建商户时没有赋值成功。这个问题在 2024 年 6 月之前就已存在,属于历史遗留,不是这次续签才出现的。跳过没有产生任何可被察觉的失败信号,问题只能等业务方发现。

处理上把这条商户记录的合作模式改回正确值,让后续同步能识别这个商户;代码侧有没有补兜底或告警,目前没有确认。修复方向是:同步时把“这个商户按业务规则本来就不该接收”和“这个商户的字段值非法、无法判断”区分开,后者要写入异常记录并告警;同时在商户创建和历史数据迁移的入口校验合作模式取值,避免非法值继续进入。

下面用最小示意复现这个过滤:错误版把所有不在白名单里的值一并跳过,修复版先解析取值,再把非法值和正常的不参与区分开。

错误代码

public class ProfitRuleSyncService {

    private static final Set<String> ALLOWED = Set.of("SECOND_BELONG_TO_FIRST_LEVER");

    /** 一级商户续签分润规则后,把规则同步给其下属二级商户 */
    public void syncToSubMerchants(Long firstMerchantId) {
        List<Merchant> subs = merchantMapper.listSubMerchants(firstMerchantId);
        List<ProfitRule> rules = profitRuleMapper.listByMerchant(firstMerchantId);
        for (Merchant sub : subs) {
            // 为什么错:取值无法识别时也被当成“不在白名单”,
            // 整个商户被跳过,名下规则一条都不写,也没有任何记录
            if (!ALLOWED.contains(sub.getCooperationType())) {
                continue;
            }
            for (ProfitRule rule : rules) {
                subRuleMapper.upsert(sub.getId(), rule);
            }
        }
    }
}

修复代码示例

public class ProfitRuleSyncService {

    /** 一级商户续签分润规则后,把规则同步给其下属二级商户 */
    public void syncToSubMerchants(Long firstMerchantId) {
        List<Merchant> subs = merchantMapper.listSubMerchants(firstMerchantId);
        List<ProfitRule> rules = profitRuleMapper.listByMerchant(firstMerchantId);
        for (Merchant sub : subs) {
            CooperationType type = CooperationType.parse(sub.getCooperationType());
            if (type == null) {
                // 非法值属于数据异常,不是“业务上不需要同步”,
                // 留下业务键并告警,修好数据后可以按商户重跑
                log.error("rule sync skipped, merchant={}, type={}",
                        sub.getId(), sub.getCooperationType());
                alert.warn("profit rule sync skipped by invalid cooperation type", sub.getId());
                continue;
            }
            if (!type.canReceiveFromFirstLevel()) {
                continue; // 业务上本来就不参与同步的商户,静默跳过是合理的
            }
            for (ProfitRule rule : rules) {
                subRuleMapper.upsert(sub.getId(), rule);
            }
        }
    }
}

两段代码是脱敏教学示例,用于解释错误与修复思路,不代表实际项目源码或已上线实现。

下次遇到这些场景要警惕

  • 同步任务按枚举字段筛选对象:先造一条字段值为空、-1 或其他非法值的记录,再跑一次同步,观察它是否被静默跳过;检查跳过分支有没有记录业务键、有没有告警。
  • 做续签、延期这类“延长有效期”的操作:不要只看发送方保存成功,要去接收方页面核对有效期是否真的变了,并统计条数与预期一致;本次四条规则一条都没到,按条数对账就能直接发现。
  • 新增或改动商户类型、合作模式等枚举:上线前先盘点数据库里不在枚举范围内的存量值,统一清洗并补上写入校验,否则依赖该字段的过滤逻辑会继续漏掉这些商户。
  • 排查“接收方看不到数据”:先分清是某个对象被整体过滤,还是单条数据没有写入。整体过滤影响该对象名下的全部数据,处理时要连历史规则一起补,不能只补最近一条。