GogoAI自助健身房团购核销模块设计与开发思路

GogoAI自助健身房团购核销模块设计与开发思路痛点分析自助健身房对接美团、抖音等团购渠道时很容易遇到多种业务问题。团购券和自有会员卡体系隔离券码校验、核销状态分散在第三方后台运营人员需要跨平台核对没有和门禁权限打通核销之后还需要人工给会员开权限不符合无人场馆的运营模式。并发场景下容易出现一码多核销缺少幂等控制团购产品类型多单次体验券、周卡、月卡、私教体验课规则各不相同有效期、使用时段、跨店限制、限购次数配置复杂核销之后课时、入场权限不能自动生效退款、过期退款、验券失败的订单缺少统一状态机管理。连锁模式下团购券要区分单店券和通用券总部统一上架、门店独立核销数据对账工作量大。同时团购回调不稳定存在回调丢失、延迟导致第三方显示已核销但本地系统权益没有发放。GogoAI团购核销模块对接主流团购平台开放接口设计独立的券状态机和会员、卡包、门禁权限、订单异常模块打通实现验券、核销、发权益、门禁自动放行、对账全流程闭环适配24小时无人自助场馆。整体模块设计团购核销模块分为渠道适配层、券核心服务层、权益分发层、对账与回调补偿层。渠道适配层对不同平台的接口、回调格式做适配封装新增渠道只需要新增适配器券核心服务负责券状态流转、幂等校验、核销规则判断权益分发层根据团购商品配置自动发放体验资格、卡包、私教课时对账补偿层处理回调丢失、状态不一致、退款同步。核心数据表group_product团购商品配置表、group_coupon团购券表、group_verify_record核销记录表、group_refund_record退款流水表。券状态定义未使用、已核销、已过期、已退款、核销失败。商品维度支持配置适用门店范围、限购数量、可用时段、是否跨店、核销后发放权益类型、过期自动退款开关。核销校验核心Java代码实现核销入口增加幂等控制先查券状态再通过事务保证核销和权益发放原子性防止重复核销。ServiceSlf4jpublicclassGroupVerifyService{AutowiredprivateGroupCouponMappercouponMapper;AutowiredprivateMemberCardServicememberCardService;AutowiredprivateAccessAuthServiceaccessAuthService;AutowiredprivateRabbitTemplaterabbitTemplate;Transactional(rollbackForException.class)publicResultDTOverifyCoupon(GroupVerifyDTOdto){// 查询团购券GroupCouponcouponcouponMapper.selectByCode(dto.getCouponCode());if(couponnull){returnResultDTO.fail(团购券不存在);}// 状态校验if(!UNUSED.equals(coupon.getStatus())){returnResultDTO.fail(券已核销/已退款不可重复核销);}// 校验门店、有效期、使用限制if(!checkStoreLimit(coupon,dto.getStoreId())){returnResultDTO.fail(该券不支持在当前门店使用);}if(isExpired(coupon)){returnResultDTO.fail(团购券已过期);}// 更新券状态为已核销coupon.setStatus(VERIFIED);coupon.setVerifyTime(newDate());coupon.setVerifyStoreId(dto.getStoreId());couponMapper.updateById(coupon);// 根据商品配置自动发放对应权益GroupProductproductproductMapper.selectById(coupon.getProductId());if(CARD.equals(product.getGiftType())){memberCardService.giveCardToMember(coupon.getMemberId(),product.getCardTemplateId());}elseif(LESSON.equals(product.getGiftType())){lessonService.addLesson(coupon.getMemberId(),product.getLessonNum());}// 同步生成临时通行权限支持门禁扫码入场accessAuthService.createTempAuth(coupon.getMemberId(),dto.getStoreId(),product.getValidDay());// 投递消息记录核销流水通知对账服务rabbitTemplate.convertAndSend(group_exchange,group.verify,coupon);returnResultDTO.success(核销成功);}privatebooleancheckStoreLimit(GroupCouponcoupon,LongstoreId){GroupProductproductproductMapper.selectById(coupon.getProductId());if(ALL.equals(product.getStoreScope())){returntrue;}returnproduct.getStoreIdList().contains(storeId);}}渠道适配器与回调补偿机制不同团购平台的验券接口、回调参数、退款通知格式差异很大使用适配器模式隔离差异统一对外输出标准化券信息。适配器抽象方法包含验券、查询券状态、同步退款、查询商品库存。平台异步回调是不稳定环节很容易出现网络抖动导致回调丢失。方案采用双重保障第一回调接收后先落本地流水返回成功给第三方再异步执行业务逻辑第二定时补偿任务定时拉取第三方平台券状态对比本地库状态不一致时自动修正。例如第三方标记已核销但本地还是未使用自动执行核销流程第三方退款成功而本地券状态未更新自动回收会员权益锁死门禁通行权限。补偿任务做分片处理避免全量拉取拖慢数据库。自助核销的两种使用场景第一种会员端自助核销。会员在小程序输入券码或者跳转团购授权页面完成验券核销成功后自动发放卡包、课时即时获得门禁通行权限直接扫码进场全程不需要店员操作适配无人场馆。第二种店长后台手动核销。店长后台输入券码或者扫码核销适合线下接待场景后台支持查看核销记录、导出核销明细。核销操作记入审计日志总部可以查看全部门店核销数据门店店长只能查看本店核销记录。同时支持预约类团购产品比如私教体验课核销之后自动生成一条待预约记录会员可以直接在约课模块预约教练时段核销记录和排课数据打通。退款、过期与限购控制退款分为用户主动退款、平台超时自动退款。退款触发时同步执行权益回收刚核销还未入场的团购券回收门禁权限已经入场消耗的体验券不支持退款。限购控制在两层拦截平台侧设置限购本地模块二次校验会员历史购买和核销记录防止刷券。过期任务由定时任务扫描过期券更新状态配置了过期自动退款的商品自动调用平台退款接口发起退款。对账与连锁管控连锁场景下商品分为总部通用商品和门店专属商品。总部统一创建团购商品模板下发到门店门店可以单独上架本店团购。核销流水按门店隔离总部后台可以汇总所有门店核销、退款、营收数据生成渠道对账报表统计渠道佣金、核销率、退款率。报表区分已核销、已退款、待补偿数据导出流水用来和平台结算对账。权限复用多门店数据拦截器门店账号不能查看其他门店核销和财务数据。和其他模块联动逻辑和会员卡包模块联动核销自动发卡、发课时和门禁IoT权限模块联动核销成功生成通行凭证支持自助入场和私教排课模块联动私教体验券核销后支持预约私教和订单异常模块联动核销失败、状态不一致的券进入异常工单运营人工处理和消息推送模块联动核销成功、退款成功、券即将过期推送通知给会员。开发落地踩坑总结第一第三方回调一定要先持久化再执行业务不要业务处理失败后给平台返回成功造成两边状态不一致第二核销方法必须加事务和幂等判断不能只依赖第三方平台防重第三自助核销后门禁权限有效期要和商品配置对齐不能永久放行第四补偿拉取不要高频全量同步按券的创建时间分片控制接口调用频率避免触发平台限流第五区分通用券和单店券跨门店核销时提前做好规则拦截避免会员在不支持门店核销。落地效果总结团购核销模块已经对接多个自助健身门店的抖音、美团团购渠道把第三方券码和场馆内部会员体系、门禁权限打通实现无人场景自助验券核销不需要人工介入。适配器模式降低新增渠道的开发成本补偿机制解决回调丢失带来的数据不一致问题。核销流水、退款流水集中汇总大幅降低财务对账成本。整套模块和卡包、排课、IoT门禁、多门店管理系统深度结合形成从引流团购、自助核销、进场体验到数据对账的完整链路是自助场馆线上获客环节的核心支撑。