发生了什么
商户是在线下经营点位、使用这套服务的一方,商户端是他们自己登录、查看经营情况的手机应用。收益页上有三样东西:昨日收益(前一天已结算进来的合计)、月收益(当月累计)、历史已结算账单(逐笔结算记录,每一条除了商户,还写明这笔结算属于哪个城市)。
每天结算程序按商户产生的使用记录算出应得的部分,写入一条已结算账单;账单在结算完成时就已经确定,不会再变。收益页上的三个数都由这些账单汇总得出:昨日收益是昨天那批账单之和,月收益是当月账单之和,明细列表就是账单本身。所以账单和页面必须对得上,页面上少了多少条,商户就少看到多少笔结算。
正常流程是商户打开收益页,商户端向收益接口发一次请求,请求里带商户身份和月份;接口到账单表里取出这段时间内该商户的账单,汇总出昨日、当月两个数,再把账单逐条列出来。
三月十三号,商户把商户端更新到新版本之后,昨日收益每天都显示 0;同期,历史已结算账单也少了很多条,商户对不上哪天结了多少。之后又一次更新,月收益从四万多变成三万多。商户的疑问很直接:钱到底结没结。
本质
问题不在算钱,而在“按哪个范围取账单”这一步。
- 账单按商户和城市一起归属:同一个商户在不同城市都有点位,每笔结算单独落在某个城市下面。
- 新版本商户端把收益页改成按城市取数,一个城市一个数,商户才能对得上自己那一摊的收益。请求里带的是商户身份和月份,城市这一项没有带。
- 收益接口的入参里也没有 cityGuid:接口定义里没有这个参数,服务端的城市条件只能传空。
- 服务端拿空的城市值去匹配按城市存放的账单,等值条件一条也命中不了,取回来的账单是空集;昨日收益和月收益都由这份结果汇总,空集合汇总出来就是 0,页面照原样显示。历史账单列表也没有全空,但同样缺了一批——具体缺在哪一步,记录里没有说清,能确认的只是列表和汇总同时变得不可信。
账单是按城市分开存的,取数却拿一个空城市去做过滤条件,条件永远不成立,页面只能显示 0。
- 再往上一层是方案缺口:历史功能从来没有要求按城市展示收益,需求里也没有城市这个维度;新版本想把收益拆到城市,接口、取数条件、页面三处没有一起定义。单看哪一处都算不上写错,合起来就是取不到数,所以这条记录给出的处置是转需求,不是改一句 SQL。
- 两个版本取到的账单范围不一样,页面数字就跟着版本变,月收益从四万多变成三万多就是这种不一致的表现;哪个数才对,要按城市明细逐笔核对才能定,现阶段只能确认它不稳定。
修复方向是:收益接口入参补上 cityGuid,前端请求同步带上;老版本不带城市时按商户全量兜底汇总,不能把空城市带进查询条件;同时把“按城市展示收益”的口径写进需求,明确昨日、当月、明细三处用同一份账单结果。修复是否已经上线、页面最终以哪个数字为准,截至这条记录仍待确认。
代码为脱敏教学示例,用于解释错误与修复思路,不代表实际项目源码或已上线实现。
错误代码
// 商户端收益页请求:改成按城市展示,请求里却没有城市
public class RevenueQuery {
private String merchantId;
private String month;
// 为什么错:页面按城市取数,这里没有城市字段,服务端收不到
}
@PostMapping("/merchant/revenue/query")
public RevenueVO query(@RequestBody RevenueQuery q) {
// 为什么错:接口入参未定义 cityGuid,城市条件只能传 null
List<Bill> bills = billMapper.selectByMerchant(q.getMerchantId(), q.getMonth(), null);
// 为什么错:合计和明细用同一份空结果,页面昨日收益显示 0、账单只剩零星几条
return RevenueVO.of(sumByDay(bills, yesterday()), sumByMonth(bills), bills);
}
<!-- 账单表按 (商户, 城市) 归属,城市传 null 时等值条件一条也不成立 -->
<select id="selectByMerchant" resultType="Bill">
SELECT id, city_guid, settle_amount, settle_time
FROM bill
WHERE merchant_id = #{merchantId}
AND city_guid = #{cityGuid}
AND settle_time >= #{monthStart}
</select>
修复代码示例
public class RevenueQuery {
private String merchantId;
private String month;
private String cityGuid; // 新增:收益页按城市取数
}
@PostMapping("/merchant/revenue/query")
public RevenueVO query(@RequestBody RevenueQuery q) {
List<Bill> bills;
if (StringUtils.isBlank(q.getCityGuid())) {
// 老版本不带城市:按商户全量汇总兜底,返回空会把收益显示成 0
bills = billMapper.selectByMerchantAll(q.getMerchantId(), q.getMonth());
} else {
bills = billMapper.selectByMerchant(q.getMerchantId(), q.getMonth(), q.getCityGuid());
}
// 合计与明细来自同一份结果,总数和列表不会再对不上
return RevenueVO.of(sumByDay(bills, yesterday()), sumByMonth(bills), bills);
}
下次遇到这些场景要警惕
- 把某个页面改成按新维度(城市、网点、门店)展示时:先打开接口定义确认入参里真有这个维度,再用带该维度和不带该维度两种请求各调一次,看返回是全量还是空。
- 查询条件里出现必填维度时:专门造一条该维度为空的数据调接口,观察返回是 0、是报错还是全量;返回 0 最危险,页面会把它当成“真没有收益”,没有人会去查。
- 客户端发新版、服务端改接口时:拿旧版本包对新接口跑一遍,再拿新版本对旧接口跑一遍;两端发布不同步时,兼容要双向验,只测自己刚装的那台等于没测。
- 接到“收益显示 0、账单少了”的反馈时:先按城市把账单明细逐笔拉出来,用明细之和去对昨日和当月两个数;先分清是取数范围错了,还是结算真的没跑,再决定找哪一侧。