教程
MPForge
小程序扫码核销教程｜防止重复核销与网络异常处理 – MPForge
直接回答：这是给门店店员与开发两边用的微信小程序扫码核销教程：本方案采用幂等机制（幂等键 = 核销码 + 订单号），防止网络重试、重复扫码导致重复扣卡；配合明确的用户提示与对账流水，保障门店核销数据稳定。MPForge（DEVDIY 旗下）试点项目上线后重复核销为 0。
重复核销 0试点期线上验收结果
4 个模块幂等键、重试、提示、流水
1 分钟内店员完成扫码核销主路径
一单一码核销码与订单号绑定的安全口径
一、场景与痛点：重复扫一下，卡就少一次
先记住一句：防重复不能靠店员「小心点」，要靠系统幂等。
会员到店出示核销码，店员扫码核销，看起来一步动作，线上环境里最容易出三类事故：
- 网络重试导致重复扣卡：店员扫了码，页面转圈，店员再扫一次——两次请求都到达服务端，会员卡被扣两次。
- 用户端重复点击：确认按钮没反馈，用户连点，同样产生多笔扣卡。
- 异常后说不清：扣了没到账、到了没扣掉，门店与用户各执一词，没有流水可查。
二、方案核心：幂等机制怎么防重复核销
「幂等」指同一笔核销无论请求多少次，结果都只生效一次。实现口径拆成四个机制点：
| 机制点 | 实现口径 | 带来什么 |
|---|---|---|
| 幂等键 | 核销码 + 订单号组合成唯一键，服务端以该键判重 | 重复请求直接返回第一次结果，不重复扣卡 |
| 状态机 | 核销单只有「待核销 → 已核销 → 已作废」三个状态 | 已核销的单子不再扣卡，重复请求返回「已核销」提示 |
| 流水先行 | 每次请求先写流水再改余额 | 中途失败有据可查，可重放补账 |
| 客户端重试安全 | 网络超时后客户端可放心重试，服务端按幂等键判重 | 店员不用判断「要不要再扫一次」 |
延伸场景
第三方团购码的场景（一张码在两个系统里核）见 第三方团购码映射核销；核销码本身的防转截与作废口径见 核销码安全要点。
三、操作教程：店员扫码核销四步
店员侧口诀：先核对、再确认、转圈别重扫。主路径四步：
- 出示核销码：会员在小程序里打开会员卡页，核销码一单一码，与订单号绑定。
- 扫码发起核销：店员用店员端扫码，页面显示会员卡余额与本次核销内容，先核对再确认。
- 确认核销：点击确认后等待服务端返回；转圈时不要重复扫码，系统按幂等键处理，重试也只扣一次。
- 看结果提示：成功显示剩余次数；若返回「该码已核销」，说明此前那次已成功，本单不重复扣卡，向会员说明即可。
四、网络异常处理：三种情况怎么办
异常处理的原则：以服务端流水为准，店员照提示操作即可，不需要理解「幂等」这个词。
| 现场情况 | 店员怎么办 | 系统兜底 |
|---|---|---|
| 页面超时转圈 | 等 3 秒后再点一次确认 | 服务端按幂等键判重，重复点击不重复扣卡 |
| 提示「已核销」但会员说没扣 | 在核销记录里查该订单号 | 流水里有就是核销成功，以服务端流水为准 |
| 流水有但余额没变 | 上报走补账流程 | 重放流水补账——「先写流水再改余额」保证任何一步断了都能补 |
五、验收清单与避坑
上线前四条全过才算验收，重点盯「重复请求只扣一次」：
- 重复请求测试：同一核销码连发两次请求，只扣一次、两次请求都返回成功结果。
- 弱网重试测试：断网扫码、恢复网络重试，最终核销记录只有一条。
- 对账口径：每日流水合计与会员扣次合计一致，差异为 0 才算过。
- 提示明确：所有异常都有人话提示，店员不需要理解「幂等」这个词也能按提示处理。
团购券的部分核与退款边界另见 团购券核销流程。
六、常见问题 FAQ
店员重复扫了一次，会扣两次吗？
不会。本方案采用幂等机制：同一核销码 + 订单号只生效一次，重复请求返回第一次的结果，不重复扣卡。
网络断了再重试安全吗？
安全。客户端可以放心重试，服务端按幂等键判重；配合先写流水再改余额，断了也能补账。
会员说没扣卡，但系统说核销了？
以流水为准：查该订单号的核销流水，有记录即核销成功；无记录再排查网络与补账。
核销码被转发给别人用怎么办？
一单一码、扫码时核对会员身份，配合作废机制处理，详见 核销码安全要点。
