发生了什么
充电网点开业后要按月付电费。系统先从电柜按小时采集的用电数据生成日账单,月初再把上个月的日账单汇总成一张月账单,这张月账单就是商户该付的电费。月账单生成之前,账单程序必须先确定这笔钱由哪个商户付:它拿网点签约时登记的证件号去商户平台查商户,再把查到的商户名称和出账快照里的商户名称比对,一致才认为匹配成功,账单才会落到这个商户名下。快照是签约时留下的商户信息副本,账单生成时读的是它。
4 月,这条匹配链路改过一次。原来的匹配要依次尝试证件号、手机号、快照表里的记录和一段 JSON 字符串,逐段找能对上的商户;改后只按证件号匹配,不再往下走。
出问题的这个网点在 25 年 11 月重新签约,签约时换了证件号。账单程序拿新证件号去商户平台查,查回来的商户名称和快照里的商户名称对不上。按改之前的链路,匹配到这里还会用快照里的房东商户编号回商户平台再查一次,按编号查到的商户名称和快照一致,这类数据以前都能正常出账;改之后不再走这一步,匹配直接判为失败。4 月的日账单都在,按月汇总的那张月账单没有生成,5 月该出的账没出,商户在反馈群里报了出来。
本质
问题不是金额算错,而是这张月账单根本没有被生成:出账前的商户匹配在新链路上被判为失败,账单程序就不出这张账单。
- 出账前,账单程序先解析付款商户。它读快照里的证件号,去商户平台查商户,再比对两边的商户名称,一致才认为匹配成功。
- 这个网点在 25 年 11 月重新签约时变更了证件号。按新证件号查到的商户名称,和快照里保存的商户名称不一致,证件号这一段就断了。
- 改动之前的链路在证件号这段断了以后不会停:它会用快照里的房东商户编号再去商户平台查一次,按编号查到的商户名称和快照一致,所以同一份数据在改动前能正常出账。
- 4 月的改动把链路收窄成只按证件号匹配,证件号对不上就结束,编号这条回退路径不再执行,这次匹配被判为失败。
- 匹配这一步失败,账单程序就不生成这张月账单:4 月的日账单没有汇总成月账单。日账单是按天采集产生的,和商户匹配无关,所以它一直正常,从账面上看就只是月账单少了一张。
- 恢复分两步:先打开这次改动预留的降级开关,让证件号这条走不通时退回原有链路继续查;再按“4 月有电费日账单、3 月正常出过月账单、4 月没有月账单”的条件把受影响的网点捞出来,对指定网点重跑生成账单的任务,把月账单补出。
用会变的业务字段当匹配键,又把稳定编号的回退路径删掉,匹配失败就会被当成“这个网点没有付款商户”,账单静默地不生成。
修复方向是:新链路在证件号匹配不上时继续用快照里的商户编号查,而不是直接判失败;重签这类会改证件号的流程,同步更新快照里的商户信息;出账任务结束后对“有日账单、无月账单”的网点做一次巡检并告警。降级开关和补跑任务是这次的处理手段,代码修复是否上线、补出的账单是否已复核,现有信息没有说明。
下面的 Java 代码为脱敏教学示例,用于说明“匹配链路收窄、回退缺失导致账单不生成”的机制与改法,不代表实际项目源码或已上线实现。
错误代码
// 出账前解析这张月账单的付款商户(示意)
public PayMerchant resolvePayMerchant(BillContext ctx) {
// 为什么错:只用证件号匹配,而证件号会在重新签约时被换掉
String idNo = ctx.getSnapshot().getIdNo();
Merchant remote = merchantClient.getByIdNo(idNo);
if (remote == null || !remote.getName().equals(ctx.getSnapshot().getMerchantName())) {
// 为什么错:名称对不上就直接判定没有付款商户,
// 不再用快照里的商户编号回退查询,这张月账单随后被跳过
return null;
}
return new PayMerchant(remote.getMerchantId(), remote.getName());
}
// 出账入口:拿不到付款商户就跳过这个网点
public void generateMonthlyBill(BillContext ctx) {
PayMerchant payMerchant = resolvePayMerchant(ctx);
if (payMerchant == null) {
// 为什么错:跳过只留一行警告,没有失败告警,账面上只是少了一张账单
log.warn("skip monthly bill, no pay merchant, site={}", ctx.getSiteId());
return;
}
billService.create(ctx, payMerchant);
}
修复代码示例
public PayMerchant resolvePayMerchant(BillContext ctx) {
String idNo = ctx.getSnapshot().getIdNo();
Merchant remote = merchantClient.getByIdNo(idNo);
if (remote != null && remote.getName().equals(ctx.getSnapshot().getMerchantName())) {
return new PayMerchant(remote.getMerchantId(), remote.getName());
}
// 修复:证件号查不到或名称对不上时,继续用快照里的商户编号回退查询,
// 这条路径在改动前就有,不要在新链路里删掉
Merchant byId = merchantClient.getByMerchantId(ctx.getSnapshot().getLandlordMerchantId());
if (byId != null && byId.getName().equals(ctx.getSnapshot().getMerchantName())) {
return new PayMerchant(byId.getMerchantId(), byId.getName());
}
// 两条路都失败才报错,并带上用的键和比对到的名称,便于直接定位
throw new BillBizException("pay merchant not matched, site=" + ctx.getSiteId()
+ ", idNo=" + mask(idNo)
+ ", snapshotName=" + ctx.getSnapshot().getMerchantName());
}
public void generateMonthlyBill(BillContext ctx) {
// 匹配失败即抛异常,交给任务重试与告警,不再静默跳过
billService.create(ctx, resolvePayMerchant(ctx));
}
下次遇到这些场景要警惕
- 收窄匹配链路、删掉回退分支时:先把存量里重签、换证件号、改过名称的数据捞出来,逐个跑一遍新的匹配,观察是否仍能匹配到唯一商户;只要有一类匹配不上,这个回退分支就不能删。
- 用证件号、手机号、名称这类会变的字段做跨系统匹配时:保留稳定编号兜底,并把“哪个键在匹配、查到什么名称、和快照哪一项不一致”写进日志或告警,不要让匹配失败只留一行跳过。
- 账单、对账这类周期任务上线后:每天比一次“有日账单、无月账单”的网点清单,并按上月是否正常出账区分新断档和历史欠账,能在商户来反馈之前发现问题。
- 排查“某个月的账单没出”时:先确认日账单有没有,再看这张账单有没有付款商户,最后看匹配用了哪个键,不要一上来怀疑金额计算。