家政上门预约跨端业务:优惠券、套餐在小程序H5同步核销
在家政上门预约场景,优惠券、次卡套餐是用户下单的常用营销工具。用户可能在H5领取优惠券,切换到小程序下单抵扣;也可以在小程序购买家政次卡套餐,后续从H5预约时扣减次数。小程序和H5存储隔离、渲染组件不同,如果两套端独立维护券和套餐状态,极易出现一端显示可用、另一端已经核销、套餐次数扣减不一致等问题。本文基于SpringBoot,以UnionID作为统一身份,搭建优惠券与套餐次卡的跨端核销体系,统一校验规则、状态流转、扣减逻辑,保证小程序、H5数据实时同步。
一、跨端核销的核心痛点
小程序和H5环境差异,带来几类典型的一致性问题。
第一,券状态不同步:H5核销优惠券后,小程序缓存仍然显示可用,用户再次选择提交,引发重复核销;第二,套餐次卡次数扣减错乱,家政套餐多为多次服务,两端分别缓存剩余次数,并发预约时出现次数超扣;第三,优惠规则分散,前端写死满减门槛、可用品类、使用时段,H5和小程序规则文案不一致;第四,退款返还逻辑割裂,订单取消时,一端自动退回优惠券、恢复套餐次数,另一端没有刷新;第五,并发下单场景,同一用户在两端同时使用同一张券,缺少锁控制,造成一张券绑定多个订单。
前端只能做展示层缓存,核销资格判断、次数扣减、状态变更必须收敛在后端。
二、整体核销架构设计
采用统一营销服务 + 状态机管控 + Redis缓存 + 分布式锁的方案。
用户身份依靠UnionID打通,同一个用户在小程序、H5访问的是同一份用户优惠券、套餐次卡数据。营销服务分为优惠券模块、次卡套餐模块,共用一套校验、核销、退回逻辑。Redis缓存用户券列表、套餐剩余次数,降低数据库查询压力;分布式锁锁定单张券或者单套次卡,防止并发重复核销;状态机约束券和套餐的合法流转,非法状态变更直接拦截。
前端只负责拉取后端返回的优惠列表、渲染选择面板,不维护优惠规则、剩余次数,小程序、H5复用同一套核销接口。状态变更后通过WebSocket推送通知,两端自动刷新优惠面板。
三、后端核销核心代码实现
@Service
public class CouponPackageService {
@Autowired
private StringRedisTemplate redisTemplate;
@Autowired
private RedissonClient redissonClient;
@Autowired
private UserCouponMapper userCouponMapper;
@Autowired
private UserPackageMapper userPackageMapper;
@Autowired
private OrderStateMachine orderStateMachine;
private static final String COUPON_LOCK_KEY = "house:coupon:lock:";
private static final String PACKAGE_LOCK_KEY = "house:package:lock:";
private static final String USER_COUPON_CACHE = "house:user:coupon:";
// 优惠券核销
@Transactional(rollbackFor = Exception.class)
public ResultDTO<String> useCoupon(Long couponId, Long userId, String orderNo) {
RLock lock = redissonClient.getLock(COUPON_LOCK_KEY + couponId);
boolean lockSuccess = lock.tryLock(3, 10, TimeUnit.SECONDS);
if (!lockSuccess) {
return ResultDTO.fail("优惠券正在使用中,请稍后重试");
}
try {
UserCoupon coupon = userCouponMapper.selectById(couponId);
// 状态机校验,仅未使用状态允许核销
if (!orderStateMachine.canCouponUse(coupon.getStatus())) {
return ResultDTO.fail("优惠券不可使用");
}
// 校验适用范围、有效期、订单门槛
boolean checkRule = checkCouponRule(coupon, userId);
if (!checkRule) {
return ResultDTO.fail("不满足优惠券使用条件");
}
// 更新状态,绑定订单号
coupon.setStatus(2);
coupon.setOrderNo(orderNo);
userCouponMapper.updateById(coupon);
// 清理用户券缓存,触发两端刷新
redisTemplate.delete(USER_COUPON_CACHE + userId);
return ResultDTO.success("核销成功");
} finally {
lock.unlock();
}
}
// 家政次卡套餐扣减次数
@Transactional(rollbackFor = Exception.class)
public ResultDTO<String> deductPackage(Long packageId, Long userId, String orderNo) {
RLock lock = redissonClient.getLock(PACKAGE_LOCK_KEY + packageId);
boolean lockSuccess = lock.tryLock(3, 10, TimeUnit.SECONDS);
if (!lockSuccess) {
return ResultDTO.fail("套餐正在使用,请稍后重试");
}
try {
UserPackage userPackage = userPackageMapper.selectById(packageId);
if (userPackage.getRemainCount() <= 0) {
return ResultDTO.fail("套餐次数已用完");
}
// 扣减次数
userPackage.setRemainCount(userPackage.getRemainCount() - 1);
userPackageMapper.updateById(userPackage);
redisTemplate.delete("house:user:package:" + userId);
return ResultDTO.success("套餐次数扣减成功");
} finally {
lock.unlock();
}
}
}
优惠券状态包含:未使用、已核销、已过期、已退回;套餐次卡记录总次数、剩余次数、有效期,订单退款时执行逆向恢复逻辑。
四、预核销与支付回调正式核销
家政下单采用预扣机制,避免用户选券后放弃支付,券被直接消耗。
用户提交预约选择优惠时,先做预核销:锁定优惠券、临时占用套餐次数,设置超时时间;用户支付成功,收到支付回调后执行正式核销;超时未支付,自动释放锁定,优惠券恢复可用、套餐次数回退。
这个机制对双端体验非常关键,用户无论在H5还是小程序下单,预扣逻辑一致,不会出现一端锁定、另一端无感知的情况。
五、前端跨端适配与缓存策略
前端基于UniApp统一封装优惠选择组件,小程序、H5共用一套渲染逻辑:
打开优惠面板,优先请求后端接口拉取最新券、套餐列表,本地缓存仅作为展示兜底;
收到WebSocket推送的券/套餐变更消息,主动清空本地缓存,重新拉取;
禁用状态、优惠文案、可用品类全部由后端返回,前端不写死规则;
提交订单时携带券ID或者套餐ID,由后端统一校验,前端不做抵扣计算。
同时处理跨端跳转场景:H5下单选用套餐,跳转小程序支付,支付完成后,小程序端自动刷新套餐剩余次数。
六、退款逆向处理与过期任务
订单取消、退款是容易出现数据不一致的环节。
退款成功后,后端判断优惠券类型:普通券退回为未使用状态,限时券、一次性券不予退回;套餐次卡自动恢复扣减的次数。退款完成后,删除对应用户缓存并推送变更通知。
定时任务每日扫描,自动把过期优惠券标记为已过期,清理失效缓存,小程序和H5次日打开统一看到过期状态。
所有核销、退回记录写入核销流水表,记录渠道、订单号、操作时间,用于对账排查。
七、并发、监控与异常兜底
同一个用户在小程序、H5同时打开下单页面,选中同一张券提交,分布式锁可以拦截重复核销请求。
监控指标:优惠券核销成功率、套餐扣减次数、退款返还次数、锁冲突失败次数。锁冲突持续上涨,及时告警。
兜底方案:Redis缓存失效时,直接读取数据库作为数据源;WebSocket推送失败,前端在进入优惠面板时增加主动拉取逻辑,保证数据最终一致。
八、测试验证场景
测试场景:H5领取优惠券,小程序下单可抵扣;小程序购买次卡套餐,H5预约扣减次数;两端同时使用同一张券,拦截重复核销;订单退款,券和套餐次数同步恢复;券过期后,小程序、H5同时标记不可用;预扣超时未支付,资源自动释放。
总结
这套优惠券、家政次卡套餐跨端核销方案,核心是依托UnionID打通用户身份,后端营销服务统一承载校验、锁控制、状态流转、次数扣减,前端只做视图渲染,消除小程序和H5的业务规则差异。预核销+支付回调正式核销的模式,兼顾用户体验和资源安全,退款逆向流程、缓存清理、消息推送保障两端状态同步。该模块可以和前面的鉴权、预约排班、并发预约模块组合使用,覆盖家政预约全链路。落地时重点做好分布式锁粒度控制、预扣超时释放、核销流水记录,在营销灵活性和数据一致性之间做好平衡。