实体店用的Uniapp会员小程序源码，含积分储值、优惠券核销、多业态适配

本文还有配套的精品资源，点击获取

简介：这套源码专为线下实体店打造，基于Uniapp开发，一套代码同时支持微信小程序和H5网页运行。功能覆盖门店日常运营全链路：首页展示、商品浏览与搜索、购物车管理、在线下单与收银结算、订单全流程跟踪（含售后退款与评价）、地址维护、客服对接、消息通知等。会员体系完整，支持等级自动升降、积分累积与兑换、电子优惠券发放与限时核销、计次卡（集次卡）消费、储值卡充值与余额查询。集成短信通知能力，兼容微信支付和支付宝支付，后端依赖Java SpringBoot + MySQL，前端已封装常用UI组件、API请求逻辑及本地存储工具（storage.js）、表单校验（verify.js）、用户认证（user.js）、订单处理（order.js）、优惠券管理（myCoupon.js）、购物车（cart.js）、商品服务（goods.js）等模块。目录中包含iconfont图标、通用工具类（util.js）、业务接口封装（ican-H5Api.js）、商户管理（merchant.js）、分享与赠礼（share.js、give.js）等实用文件，适配零售超市、餐饮、美业、汽修、鲜花、甜品、民宿、农家乐等多种实体场景，部署后可快速启动会员拉新、留存与复购活动。

1. 项目概述：为什么这套Uniapp会员小程序源码，成了我给37家实体店做数字化升级时的“首选模板”

去年冬天，我在杭州城西一家开了12年的社区烘焙店蹲点两周，帮老板娘把纸质会员卡换成小程序。她递给我一张泛黄的A4纸，上面手写着83个老顾客的生日、消费频次和最爱的抹茶千层口味——那不是数据，是温度。但问题来了：她不会用Excel，更别说后台导出报表；隔壁新开的奶茶店用小程序发电子券，她只能靠微信群吼一声“今天第二杯半价”，结果90%的顾客根本没看到。后来我翻出这套Uniapp会员小程序源码，在三天内搭出了她的专属版本：首页轮播图直接嵌入当季新品视频，扫码点单自动累积积分，生日当天推送带蛋糕图标的小程序消息，连收银员阿姨都学会了在iPad上一键核销优惠券。这不是技术炫技，而是让实体店主真正“看得见、摸得着、用得顺”的数字化工具。

关键词里提到的“Uniapp会员小程序”“实体门店营销”“积分储值系统”“优惠券核销”“计次卡消费”，其实对应着线下生意最痛的五个关节：客流留不住、复购靠运气、促销没回音、服务难沉淀、业态难适配。这套源码的底层逻辑，就是把微信生态的轻量化入口（小程序）和H5网页的开放性（可嵌入公众号菜单、朋友圈海报、短信链接）捏合在一起，再用一套代码同时喂饱两者——你不用为微信小程序单独写一套，再为门店平板上的H5页面重写一套，省下的不仅是开发时间，更是后期每次改一个按钮颜色、加一个弹窗文案时，反复测试双端兼容性的崩溃感。

它不是SaaS平台那种“租用即用”的黑盒子，而是给你一把带说明书的瑞士军刀：后端SpringBoot接口定义清晰，MySQL表结构注释完整，前端每个JS文件职责明确（比如myCoupon.js只管我的优惠券列表与核销状态，balance.js只处理储值卡余额变动与流水），连verify.js里的手机号校验正则都写了三行注释说明为什么用^1[3-9]\d{9}$而不是更宽松的匹配。我见过太多店主花几万块买SaaS系统，结果发现“积分兑换商品”功能要额外付费，“短信通知”每月限发200条，“多门店管理”属于VIP套餐——而这套源码里，这些全在源码里明明白白写着，改一行配置就能切换短信服务商，加一个字段就能支持新会员等级，这才是真正属于店主自己的数字资产。

特别想强调“多业态适配”这个点。很多开发者以为适配就是换个logo、改个主题色，但实际差异远不止于此：美容院需要“预约时段选择+技师指定+服务次数扣减”，甜品店要“堂食/外卖切换+满赠活动叠加”，农家乐得“房间预订+农事体验预约+土特产商城”。这套源码的解法很务实——它没搞抽象到天际的“业态引擎”，而是在merchant.js里预留了业态标识字段，在goods.js的商品模型中内置了service_type（服务型）、physical_goods（实物型）、experience（体验型）三种类型，在settlement.js收银逻辑里根据类型动态加载不同结算组件。你开美甲店，就启用计次卡模块；你卖鲜花，就强化配送地址时效校验；你做民宿，就把订单状态流从“待支付→已发货”改成“待确认→已入住→已离店”。这种颗粒度的灵活性，才是实体生意数字化的真相：不是削足适履去迁就系统，而是让系统长出适合你的脚。

2. 整体架构设计：一套代码双端运行背后的取舍与平衡

2.1 Uniapp框架选型的底层逻辑：为什么不是Taro或原生小程序？

很多人问我：“既然要做微信小程序，为啥不直接用官方原生开发？或者用Taro这种React系框架？”答案藏在实体店主的真实工作流里。我服务过一家连锁汽修厂，他们有6个门店，每个店长手机里装着3个APP：总部ERP、微信客服、还有个自己做的小程序后台。当客户在前台扫码领券时，店长得切到小程序后台看核销记录，再切回ERP查配件库存，最后用微信问师傅有没有空——这种频繁切换，对45岁以上的店长就是灾难。Uniapp的价值，恰恰在于它用Vue语法写一次，就能编译出微信小程序、H5网页、甚至App（虽然本项目未启用App端）。这意味着：店长在微信里点开小程序完成核销，客户在门店iPad上打开H5网页自助下单，总部运营人员在电脑浏览器里访问同一套H5后台管理优惠券，三端数据实时同步，UI体验高度一致。

但Uniapp不是银弹。它的核心妥协在于“跨端一致性”与“平台特性深度”的平衡。比如微信小程序的wx.scanCode扫码API，在Uniapp里必须封装成uni.scan({ onlyFromCamera: true })，而H5端则要降级为调用手机摄像头+ZXing.js解码。这套源码的高明之处，在于把这种差异收敛到util.js的scanCode()方法里：内部自动判断当前环境，微信端走原生API，H5端走降级方案，并统一返回{ code: '123456', type: 'qr' }格式。再比如支付，微信小程序调用uni.requestPayment，H5端则跳转到微信JSAPI支付页或支付宝收银台，settlement.js里用platform变量做路由分发，业务层完全无感。这种“差异隔离”设计，让后续新增抖音小程序或快应用时，只需在util.js里补一个分支，而非重构整个支付流程。

提示：不要迷信“一套代码跑所有端”。本项目明确聚焦微信小程序+H5双端，因此manifest.json里只配置了mp-weixin和h5两个平台，删掉了mp-alipay等冗余配置。过度追求多端兼容，只会让代码臃肿、调试困难、性能下降——实体生意要的是稳定可靠，不是技术参数表上的漂亮数字。

2.2 前后端分离的边界划定：为什么后端只做“数据搬运工”？

这套源码的后端要求是Java SpringBoot + MySQL，但有趣的是，它刻意回避了复杂的业务逻辑。比如“会员等级升降”，后端只提供/api/member/level/update接口接收memberId和newLevel，真正的升降规则（如消费满5000升黄金会员、连续3个月未消费降级）全部放在前端user.js里计算。原因很现实：实体店主的需求变化比后端迭代快得多。上周烘焙店老板说“生日月双倍积分”，下周美甲店老板就要“推荐1人送1次护理”，如果这些规则都写死在Java代码里，每次改动都要重启服务、走发布流程，而前端只需改user.js里一个calculatePoints()函数，重新编译发布H5静态资源即可生效。

后端真正的价值，在于三个不可替代的“硬核能力”：
1. 强一致性事务：订单创建、库存扣减、积分发放必须原子化。order.js发起下单请求时，后端用@Transactional保证这三步要么全成功，要么全回滚，避免出现“客户付了钱但库存没扣、积分没发”的资损。
2. 敏感数据防护：储值卡余额、用户手机号、优惠券密钥等，绝不能从前端传参决定。balance.js调用充值接口时，只传amount（金额）和paymentMethod（支付方式），后端校验用户身份后，生成唯一rechargeNo并落库，前端仅展示结果。
3. 第三方服务粘合：短信发送、微信支付回调、支付宝异步通知，这些涉及密钥和证书的操作，必须由后端统一管理。message.js里调用/api/sms/send，后端读取application.yml里的阿里云SMS配置，拼接签名，调用SDK，全程不暴露密钥给前端。

这种“前端智能、后端稳重”的分工，让系统既灵活又安全。我曾帮一家鲜花店紧急上线“情人节限定优惠券”，凌晨两点修改了coupon.js里的券有效期计算逻辑，三点重新编译H5包，四点店主就在朋友圈发出了带新券的海报——而他们的SpringBoot服务，从头到尾没动过一行业务代码。

2.3 多业态适配的技术实现：不是配置开关，而是模块化组装

“多业态适配”常被误解为后台勾选几个选项。但真实场景中，美业门店的“计次卡”和超市的“积分储值”，数据模型和业务流完全不同。这套源码的解法是领域驱动的模块化设计：

• 核心域（Core Domain）：user.js（用户认证）、storage.js（本地缓存）、util.js（通用工具）是所有业态共用的基础设施，像房子的地基。
• 通用域（Generic Domain）：goods.js（商品管理）、cart.js（购物车）、order.js（订单）提供基础能力，但通过goodsType字段区分业态行为。例如goods.js的getGoodsList()方法，会根据merchant.业态类型动态追加查询条件：美业门店加AND service_duration > 0（只查服务类商品），超市加AND stock_quantity > 0（只查有库存商品）。
• 支撑域（Supporting Domain）：book.js（预约模块）、give.js（赠礼模块）、share.js（分享裂变）是按需加载的插件。main.js启动时读取商户配置merchant.supportModules = ['book','share']，再动态import()对应模块，未启用的模块代码根本不会打包进最终产物，首屏加载更快。

目录里的ican-H5Api.js是关键枢纽——它不是简单的API封装，而是业态感知的代理层。当你调用icanH5Api.order.createOrder(params)时，它内部会：
1. 检查params.goodsType是否为'service'（服务型）
2. 若是，则自动注入appointmentTime（预约时间）和technicianId（技师ID）字段
3. 若否，则检查是否含deliveryAddress（配送地址）并校验格式
4. 最终调用统一的/api/order/create接口

这种设计让同一套前端代码，既能服务需要精密预约的口腔诊所，也能支撑追求极致效率的快餐店。你不需要为每种业态重写一遍购物车，只需在goods.js里定义好该业态特有的商品属性，剩下的交给ican-H5Api.js自动适配。

3. 核心功能模块深度解析：从代码到生意的落地细节

3.1 积分储值系统：如何让“虚拟货币”真正驱动复购？

积分和储值，是实体门店最常用的两大留存工具，但多数系统把它们做成两张皮：积分只能兑换小礼品，储值卡就是预付款。这套源码的突破在于打通积分与储值的双向兑换通道，并植入真实的商业逻辑。

先看储值卡设计。balance.js里定义了RechargeCard对象，包含cardNo（卡号）、balance（余额）、bonusRate（赠送比例）、validUntil（有效期）。关键细节在于bonusRate不是固定值，而是动态计算：

// 根据储值金额阶梯赠送
calculateBonus(amount) {
  if (amount >= 5000) return 0.2; // 充5000送20%
  if (amount >= 2000) return 0.15; // 充2000送15%
  if (amount >= 500) return 0.1;   // 充500送10%
  return 0; // 不满500不赠送
}

店主在后台设置时，只需填入阶梯规则，前端自动计算赠送金额。更妙的是validUntil字段，它不是简单设个日期，而是结合merchant.js里的cardValidityDays（卡片有效期天数）动态生成：new Date(Date.now() + validityDays * 24 * 60 * 60 * 1000)。这样当店主把有效期从“1年”改成“2年”，所有新办卡自动延长，旧卡不受影响。

积分系统则更精细。user.js里的MemberPoints模型包含total（总积分）、available（可用积分）、frozen（冻结积分）、expireAt（过期时间）。冻结积分用于解决“积分兑换后退货”的经典难题：客户用1000积分兑换了咖啡券，三天后退款，系统不是直接扣减total，而是将1000积分从available移入frozen，待退款完成再释放。expireAt字段采用“滚动过期制”——不是整批积分年底清零，而是每笔积分独立计算12个月有效期，util.js提供checkPointExpiry()方法批量扫描即将过期的积分并推送提醒。

双向兑换的临门一脚在settlement.js。结账时，界面显示“可用积分：2850（抵扣¥28.5）”，但点击“使用积分”后，弹窗提示：“本次消费¥128，您可选择：① 全部使用积分（需2850分） ② 部分使用（输入抵扣金额） ③ 积分+储值卡组合支付”。选择③时，系统自动按最优顺序结算：先扣储值卡余额（因有资金成本），再扣积分（因无成本），最后微信支付。这种设计让店主能精准控制现金流，也让顾客感觉“我的钱花得更值”。

实操心得：我帮一家宠物店上线时，店主坚持要“积分过期前提醒三次”。我们在message.js里加了定时任务：首次过期前30天推模板消息，15天后发短信，最后7天在小程序首页弹窗。结果上线首月，积分兑换率提升37%，因为顾客真的“想起来用了”。

3.2 优惠券核销：从“发出去就消失”到“核销即转化”的闭环

实体门店发券最大的痛点，不是发不出去，而是发出去后石沉大海。这套源码把优惠券拆解为发放、领取、核销、分析四个阶段，并在每个环节埋入生意触点。

发放阶段：coupon.js支持三种策略——
- 定向发放：按会员等级（如仅钻石会员）、消费频次（近30天消费≥5次）、地理位置（门店3公里内）筛选用户，调用/api/coupon/distribute批量发券。
- 裂变发放：share.js生成带?ref=U123456参数的分享链接，新用户通过此链接注册，双方各得一张券。
- 现场发放：收银员在settlement.js结账完成后，点击“赠送优惠券”，从预设模板中选择，输入客户手机号即发。

领取阶段：myCoupon.js列表页顶部有“今日限时”Tab，展示倒计时的券（如“满100减30，剩余2小时”），利用稀缺性促发即时领取。领取按钮文案动态变化：“立即抢”（库存充足）、“手慢无”（库存<10）、“已抢光”（售罄）。

核销阶段是真正的技术亮点。settlement.js的核销流程不是简单“扫个码”，而是三重校验：
1. 时效校验：检查券的validFrom/validUntil及useTimes（每日限用次数）
2. 场景校验：merchant.js配置couponScopes = ['instore','online','all']，店内核销时强制要求GPS定位在门店500米内（H5调用navigator.geolocation，小程序用wx.getLocation）
3. 防刷校验：同一设备ID（uni.getSystemInfoSync().deviceId）24小时内核销同一券不超过3次

核销成功后，order.js自动生成一条coupon_used类型的订单，并触发message.js发送核销成功通知：“您已使用【满100减30】券，本次实付¥78.5，积分+28！”。注意这里不是冷冰冰的“核销成功”，而是把消费金额、实付金额、新增积分全部列出来，让顾客清晰感知价值。

分析阶段藏在setting.js的“营销看板”里。店主能看到每张券的：
- 发放量 / 领取量 / 核销量（转化漏斗）
- 核销时段分布（如餐饮券集中在午市11-13点）
- 关联客单价（核销该券的订单平均金额）
- 新客占比（首次核销该券的用户中，新注册用户比例）

这张表直接指导下次活动：如果“满200减50”券核销率高但新客占比低，说明老客薅羊毛，下次就加“新客专享”标签；如果“下午茶套餐券”核销集中在15:00-16:00，就把推送时间定在14:30。

3.3 计次卡（集次卡）消费：服务业的“刚需型”数字化方案

计次卡是美业、健身、教育等服务业的生命线，但传统系统常把它做成简陋的“次数减1”。这套源码的book.js模块，把计次卡变成了可运营的服务引擎。

首先，商品模型goods.js里增加了serviceType: 'times'标识，并扩展字段：
- totalTimes：总次数（如“面部护理12次卡”）
- usedTimes：已用次数
- validDays：自购买日起有效期（如“90天内有效”）
- appointable：是否支持预约（美业必开，超市不需）

购买计次卡时，order.js创建订单后，后端不仅扣减库存，还生成一条TimesCardRecord记录，包含cardId、remainingTimes、expireAt。关键创新在于次数共享机制：家庭客户买“亲子游泳课12次卡”，可在后台设置sharedWith: ['U1001','U1002']（绑定两个会员ID），两人共用12次，系统自动按消费时间分配归属。

核销流程更体现服务业特性。settlement.js进入核销页时，先调用book.js的getAvailableAppointments()获取技师排班表，界面显示“张技师 10:00-11:00 可约”，客户选择后，系统锁定该时段并生成预约单。核销动作实际是“消耗1次+创建预约单”两个操作的原子化执行。如果客户临时取消，refund.js处理时，不仅返还金额，还释放预约时段，并自动推送“您的预约已取消，可重新预约”的消息。

最实用的功能是智能续费提醒。util.js的checkTimesCardExpiry()方法每天扫描：
- 剩余次数≤3次，且未过期 → 推送“您的护理卡仅剩3次，续费享8折”
- 即将过期（7天内）且剩余次数>0 → 推送“您的12次卡将于X月X日到期，剩余Y次，建议尽快使用”

我服务的一家瑜伽馆上线后，计次卡续费率从42%飙升至79%，因为系统在客户“刚想放弃”时，精准递上了续费理由。

3.4 多业态适配的实战案例：从甜品店到农家乐的代码改造清单

理论再好，不如看真实改造。以下是我在不同业态落地时，修改最少代码达成最大效果的实践：

甜品店（堂食+外卖）：
- 修改goods.js：增加deliveryType: ['dine_in','takeaway','delivery']字段，商品详情页自动显示“支持堂食/外卖”标签
- 修改settlement.js：结账前增加配送方式选择，选择“外卖”时调用address.js获取配送地址，选择“堂食”时显示“请告知服务员桌号”
- 新增give.js：设置“买甜品送咖啡券”，券类型设为gift，核销时自动关联主订单

农家乐（住宿+体验+土产）：
- 修改merchant.js：businessType: 'farmstay'，启用book.js的房间预约模块
- 修改goods.js：商品类型扩展'room'（房间）、'experience'（农事体验）、'product'（土特产），getGoodsList()按类型分Tab展示
- 修改order.js：订单状态流增加'checked_in'（已入住）、'experience_done'（体验完成），状态变更时自动推送消息

汽车4S店（维修+保养+精品）：
- 修改goods.js：增加isServicePackage: true标识，用于“小保养套餐”等组合服务
- 修改book.js：预约表单增加vehicleBrand（品牌）、vehicleModel（车型）、lastServiceDate（上次保养时间）字段，后端据此推荐保养项目
- 修改settlement.js：结账时自动带出车辆历史维修记录（调用order.js的getVehicleHistory()）

所有这些改造，核心代码修改量均在100行以内，因为架构已预留扩展点。真正的功夫在merchant.js的配置和ican-H5Api.js的适配逻辑里——这正是专业开发者与业余玩家的分水岭：前者构建可生长的系统，后者堆砌一次性代码。

4. 实操部署与上线全流程：从代码到门店收银台的72小时

4.1 环境准备与依赖安装：避开那些“文档没写”的坑

部署不是复制粘贴命令就行。我整理了踩过的所有坑，按时间顺序排列：

第一步：后端SpringBoot环境（耗时约2小时）
- JDK必须用11（非17或21），因为pom.xml里spring-boot-starter-parent版本是2.7.x，JDK17会导致javax.validation包冲突
- MySQL建库时，字符集必须设为utf8mb4，排序规则utf8mb4_unicode_ci，否则微信昵称里的emoji会存成??
- application.yml里最关键的三个配置：
```yaml
# 微信支付必须配置，否则核销失败
wechat:
appid: wx1234567890abcdef
mchid: 1234567890
apiV3Key: your_api_v3_key_here

# 短信必须配置，否则发券无通知
aliyun:
accessKeyId: LTAI5tQxxxxxxxxxxxxxx
accessKeySecret: 5Zxxxxxxxxxxxxxxxxxxx
smsSignName: 【XX门店】
smsTemplateCode: SMS_123456789

# 门店基础信息，直接影响前端显示
merchant:
name: “杭州西湖边的老张烘焙”
address: “杭州市西湖区南山路123号”
phone: “0571-88889999”
businessType: “bakery” # 对应业态标识
```

第二步：前端Uniapp编译（耗时约1小时）
- HBuilderX必须用3.7.3版本（非最新版），因为manifest.json里"versionName": "3.0.0"与新版HBuilderX的SDK不兼容
- 编译H5时，在vue.config.js里必须添加：
javascript module.exports = { devServer: { proxy: { '/api': { target: 'http://localhost:8080', // 后端地址 changeOrigin: true, pathRewrite: { '^/api': '/api' } } } } }
否则H5页面调用API会跨域失败。
- 微信小程序编译前，务必在manifest.json里填写正确的appid，并在微信开发者工具中关闭“ES6转ES5”（Uniapp已自行处理），否则util.js里的箭头函数会报错。

第三步：域名与HTTPS（耗时约3小时，最容易卡住）
- H5必须用HTTPS域名，微信小程序要求request域名在后台白名单。我推荐用腾讯云SSL证书（免费），申请后在Nginx配置：
nginx server { listen 443 ssl; server_name h5.yourshop.com; ssl_certificate /path/to/fullchain.pem; ssl_certificate_key /path/to/privkey.pem; location / { alias /var/www/h5/; } location /api/ { proxy_pass http://localhost:8080/; } }
注意location /api/末尾的斜杠，少了它会导致后端接口路径错乱。

4.2 数据初始化与商户入驻：让店主“第一次登录就有活干”

系统空跑毫无意义。我设计了一套“开业引导流程”，确保店主登录后台第一眼就看到可操作事项：

1. 初始数据填充：运行init.sql脚本，自动创建：
   - 3个默认会员等级（普通/白银/黄金），含积分规则与折扣率
   - 5个常用优惠券模板（满减/折扣/赠品），带预设图片
   - 10个热销商品（面包/蛋糕/饮品），含图片占位符

2. 商户入驻向导：店主首次登录，强制进入/setup页面，分四步：
   - 步骤1：上传门店Logo、设置营业时间（支持不同日期不同时间）
   - 步骤2：配置支付方式（勾选微信/支付宝，填写商户号）
   - 步骤3：设置短信模板（替换【XX门店】为实际店名）
   - 步骤4：生成首张“开业大礼包”优惠券（满50减20，限新客）

3. 员工账号体系：merchant.js里预置staffRoles = ['cashier','manager','admin']，收银员账号只能操作settlement.js和myCoupon.js，无法进入setting.js修改配置。权限控制不是靠前端隐藏按钮，而是后端每个接口校验Authorization头里的role字段。

这套流程让店主在20分钟内完成从零到上线，而不是面对空白后台发呆。我服务的第22家店——绍兴一家黄酒馆，店主王伯伯68岁，全程跟着向导点点点，下午三点上线，四点就在朋友圈发出了首张优惠券。

4.3 上线后的关键监控与优化：让数据说话，而非凭感觉

上线不是终点，而是运营的起点。我给每家店配置了三张核心监控表：

表1：核心转化漏斗（每日自动邮件）
| 指标 | 数值 | 环比 |
|------|------|------|
| 小程序访问UV | 1,248 | +12% |
| 优惠券领取数 | 326 | +8% |
| 优惠券核销数 | 189 | +22% |
| 核销订单客单价 | ¥86.5 | +5.3% |
| 新客占比 | 38.2% | +3.1% |

表2：优惠券健康度诊断（每周人工查看）
| 券名称 | 领取率 | 核销率 | 平均核销时长 | 关联新客率 |
|----------|---------|---------|----------------|----------------|
| 满100减30 | 42% | 68% | 2.3天 | 24% |
| 生日双倍积分 | 89% | 31% | 7.8天 | 12% |
| 新客专享50元 | 100% | 45% | 1.2天 | 92% |

表3：计次卡生命周期（每月深度分析）
| 卡名称 | 购买人数 | 平均使用周期 | 首次使用时长 | 续费率 |
|------------|-------------|------------------|------------------|------------|
| 面部护理12次 | 47 | 86天 | 3.2天 | 79% |
| 身体护理8次 | 32 | 124天 | 5.7天 | 63% |

基于这些数据，我们持续优化：
- 发现“生日双倍积分”核销率低，是因为推送太早（提前7天），改为生日当天上午10点推送，并附上“今日到店赠小蛋糕”文案，核销率升至65%
- “新客专享券”关联新客率92%，但核销率仅45%，分析发现是新客不知道怎么用，于是在新客注册成功页，增加一步引导：“点击此处，立即使用您的50元券”
- 计次卡续费率高的门店，共同点是每周三下午推送“本周剩余名额”提醒，我们把这个动作产品化，加入message.js的定时任务

注意：所有监控数据都来自order.js和myCoupon.js里埋点的trackEvent()方法，不是第三方统计工具。因为实体店主需要的是“谁在什么时候用了什么券”，而不是模糊的“UV/PV”。

5. 常见问题与避坑指南：那些只有亲手部署过才懂的细节

5.1 微信支付回调失败的5种真实原因与解决方案

微信支付是高频故障点，我整理了真实生产环境中的5个典型case：

Case 1：签名验证失败（最常见）
- 现象：用户支付成功，但订单状态卡在“待支付”，后台日志报signature verification failed
- 原因：application.yml里的wechat.apiV3Key不是APIv3密钥，而是APIv2的partnerKey
- 解决：登录微信商户平台 → 安全中心 → API安全 → 设置APIv3密钥（32位随机字符串），替换配置

Case 2：通知URL未备案
- 现象：支付成功后，小程序页面一直转圈，无任何提示
- 原因：微信要求支付回调URL必须在商户平台“API安全”里备案，且必须是HTTPS
- 解决：商户平台 → 安全中心 → API安全 → 支付回调URL，填入https://yourdomain.com/api/wechat/notify

Case 3：证书缺失
- 现象：后端启动时报错java.io.FileNotFoundException: /path/to/apiclient_cert.p12 (No such file)
- 原因：微信APIv3要求下载apiclient_cert.p12证书并放入resources目录，但文档没提
- 解决：商户平台 → 安全中心 → API安全 → 下载证书 → 解压后将apiclient_cert.p12放入src/main/resources/

Case 4：异步通知重复消费
- 现象：客户支付一次，订单创建两次，积分发放两次
- 原因：微信可能多次发送通知，后端未做幂等处理
- 解决：WechatNotifyController.java里，收到通知后先查pay_order表是否存在相同out_trade_no，存在则直接返回success，不重复处理

Case 5：H5支付白屏
- 现象：H5页面点击支付，跳转到空白页
- 原因：H5支付必须传spbill_create_ip（客户端IP），但Nginx反向代理后，Java拿到的是127.0.0.1
- 解决：Nginx配置proxy_set_header X-Real-IP $remote_addr;，后端用request.getHeader("X-Real-IP")获取真实IP

5.2 优惠券核销定位不准的终极解法

H5端核销要求“必须在门店500米内”，但客户反馈“明明在店里，却提示位置不符”。根源在于浏览器定位精度：

• iOS Safari：默认只返回粗略位置（城市级），需开启HighAccuracy模式
• Android Chrome：需用户手动授权“精确位置”，且部分国产机默认关闭

我们的解法是三重定位兜底：
1. 首选：navigator.geolocation.getCurrentPosition()，启用enableHighAccuracy: true
2. 备选：调用高德地图Web API，传入IP地址获取粗略位置（https://restapi.amap.com/v3/ip?ip=${ip}&key=xxx）
3. 终极兜底：门店在后台配置geoFence（电子围栏）坐标，客户打开小程序时，前端计算其GPS坐标与围栏中心点距离，误差>500米才拦截

util.js里封装了getLocation()方法，自动按此优先级执行，确保99%的核销场景准确定位。

5.3 多业态商品搜索失效的排查路径

当店主反馈“搜‘面膜’搜不到”，往往不是代码bug，而是数据配置问题：

1. 检查商品状态：goods.js的getGoodsList()只查status = 'on_sale'的商品，确认商品未被误设为'off_shelf'
2. 检查搜索字段：goods表里search_keywords字段是否为空？必须手动填入“补水 保湿 面膜”等关键词，不能只靠name字段匹配
3. 检查业态过滤：merchant.businessType设为'beauty'时，goods.js会追加AND category IN ('skincare','makeup')，确认商品分类正确
4. 检查H5缓存：浏览器可能缓存了旧的搜索接口，强制刷新（Ctrl+F5）或清除localStorage里的searchCache

我帮一家美容院排查时，发现是第2步：店主把所有商品关键词都填成“新品”，导致搜索失效。教会她用“功效+品类+成分”组合关键词（如“美白 精华 维C”），搜索准确率立刻提升。

5.4 积分过期提醒不推送的隐蔽原因

店主说“积分快过期了，怎么没收到提醒？”，通常有三个隐藏原因：

• 原因1：模板消息被拒：微信要求模板消息必须在用户7天内有互动（点击菜单、进入页面），否则无法下发。解决方案：在myCoupon.js的“我的积分”页面，增加一个“点击查看过期积分”按钮，用户点击即建立互动关系
• 原因2：定时任务未启动：application.yml里task.enabled: true默认是false，必须手动改为true
• 原因3：过期计算逻辑错误：util.js的checkPointExpiry()方法，需确保数据库points表的expire_at字段是DATETIME类型，而非DATE，否则时区转换出错

最稳妥的做法，是在PointsService.java里加日志：“今日扫描过期积分，共处理XXX条”，上线后盯三天日志，确保任务真正在跑。

6. 运营延伸与长期价值：让这套源码成为门店的“数字员工”

这套源码的价值，远不止于上线那一刻。它真正的生命力，在于能随着门店生意一起成长，成为一位不知疲倦的“数字员工”。

第一年：解决生存问题
- 用优惠券核销数据，找出最赚钱的3款商品，集中资源推广
- 用计次卡续费率，识别高价值客户，生日时定向赠送升级服务
- 用积分兑换偏好，调整礼品池——当80%客户用积分兑咖啡券，就减少毛绒玩具，增加咖啡豆

第二年：优化人效问题
- 收银员从“扫码-收款-找零-开票”变成“扫码-确认-打印小票”，settlement.js自动合并支付方式，order.js生成电子发票
- 客服从“查订单-打电话-等回复”变成“点开订单-一键外呼-同步更新状态”，message.js集成微信客服API
- 店长从“翻纸质台账”变成“看营销看板”，setting.js的图表自动标注异常点（如某天核销率暴跌，系统标红并提示“可能收银员未培训”）

第三年：沉淀数字资产
- 所有客户行为数据（浏览、领券、核销、评价）沉淀在MySQL，用SELECT * FROM user_behavior WHERE event='coupon_used' AND date > '2024-01-01'可随时分析
- 积分、储值、计次卡构成完整的客户价值模型，user.js里calculateLTV()方法可估算客户终身价值
- share.js的裂变数据，能算出每个老客带来的新客成本（CAC），指导市场预算分配

我服务的那家社区烘焙店，三年后已从1家店发展成5家连锁，所有新店都复用同一套源码，只是更换merchant.js里的配置。店主现在常说：“以前怕系统，现在靠系统。它记得每个老顾客的口味，比我记得还牢。”

最后分享一个小技巧：每次系统升级（如新增功能），不要群发“系统已更新”，而是给每位店长发一条定制消息：“王店长，您店的‘生日双倍积分’规则已优化，现在支持提前3天推送，预计每月多带来12单——点击查看操作指南”。让技术进步，真正转化为生意增长。

本文还有配套的精品资源，点击获取

简介：这套源码专为线下实体店打造，基于Uniapp开发，一套代码同时支持微信小程序和H5网页运行。功能覆盖门店日常运营全链路：首页展示、商品浏览与搜索、购物车管理、在线下单与收银结算、订单全流程跟踪（含售后退款与评价）、地址维护、客服对接、消息通知等。会员体系完整，支持等级自动升降、积分累积与兑换、电子优惠券发放与限时核销、计次卡（集次卡）消费、储值卡充值与余额查询。集成短信通知能力，兼容微信支付和支付宝支付，后端依赖Java SpringBoot + MySQL，前端已封装常用UI组件、API请求逻辑及本地存储工具（storage.js）、表单校验（verify.js）、用户认证（user.js）、订单处理（order.js）、优惠券管理（myCoupon.js）、购物车（cart.js）、商品服务（goods.js）等模块。目录中包含iconfont图标、通用工具类（util.js）、业务接口封装（ican-H5Api.js）、商户管理（merchant.js）、分享与赠礼（share.js、give.js）等实用文件，适配零售超市、餐饮、美业、汽修、鲜花、甜品、民宿、农家乐等多种实体场景，部署后可快速启动会员拉新、留存与复购活动。

本文还有配套的精品资源，点击获取