小程序扫码核销教程｜仅相机与相册识别的取舍与防重放 – MPForge
直接回答：这是写给门店店长与开发两边用的微信小程序扫码核销教程：用 wx.scanCode 扫会员码、券码时，把「仅相机还是可相册、扫码结果怎么校验、怎么防重复核销、失败怎么降级」四件事一次定清楚。MPForge（DEVDIY 旗下）在连锁门店项目里按这套口径交付，扫码环节的重复核销与截屏重放问题基本能压住。
一、先分场景：扫什么码、谁在扫
结论句：扫码功能先定场景再写代码，店员扫顾客的码和顾客扫门店物料的码要用两套交互。
常见场景有三类：店员扫顾客手机上的会员码（码会动、光线复杂）、顾客自助扫台卡或海报上的码（角度固定、码不动）、员工批量扫包裹或工单条码（连续作业、讲究效率）。三类场景对「仅相机」的要求不一样——店员扫动态会员码要关掉相册识别，防止截屏图片重放；台卡码反而可以放开相册识别，因为顾客可能保存过图片，识别失败就走人了。先把场景在纸上列全，再定参数，比写完代码再返工省得多。
二、参数怎么选：仅相机与相册识别的取舍
结论句：涉及权益发放与核销的码一律仅相机调起，纯信息展示的码才开放相册识别。
wx.scanCode 的两个关键参数是 onlyFromCamera（是否只允许相机扫码）和 scanType（码制类型数组）。按场景对号入座：
| 场景 | 建议参数 | 原因与常见错误 |
|---|---|---|
| 店员扫会员码核销 | onlyFromCamera: true，scanType 只留 qrCode | 防截屏图片重放；错误做法是四类码全放开 |
| 顾客扫台卡、海报码 | 相册识别可开，scanType 按物料类型配 | 顾客可能存过图片；错误做法是强制调起相机 |
| 批量扫条码入库 | 仅相机加防抖，连续两次间隔 500ms 以上 | 防一次亮码被识别两次；错误做法是不做间隔控制 |
相机画面本身的曝光与对焦体验，可参考 camera 组件使用注意事项；扫码界面在弱光门店里的可用性，还要结合屏幕亮度一起调。
三、结果校验与防重放：服务端说了算
结论句：前端只负责把码完整送到服务端，格式校验、签名验签、防重放三层全部在服务端做。
第一层格式校验：码内容的前缀、长度对不上业务规则，直接拒绝，不进业务表。第二层签名校验：发码时在码内容里带签名串，服务端验签，防止伪造或改写。第三层防重放：每张码在服务端记「已核销」状态，核销请求带一次性 token，重复提交返回同一个成功结果（幂等口径），而不是报错让店员反复重试。弱网下请求失败时，按 请求重试注意事项 做有限次数重试，重试必须带同一笔单号，避免一次核销变成两次。核销成功后给一次短振动反馈，具体参数见 振动反馈注意事项。
四、上线前自检五步
结论句：正常路径反而不容易出事，自检重点是把异常路径全部走一遍。
- 定参数：按第二节场景表逐个入口确认 onlyFromCamera 与 scanType，不许一套参数到处复制。
- 通校验：拿真码、篡改码、过期码各扫一次，确认三层校验都在服务端拦截，前端只做提示。
- 测重放：同一张码连扫两次、再截屏重扫一次，确认第二次被幂等挡住或明确提示「已核销」。
- 走降级：关掉网络测手输通道，扫码失败能转手输、手输有格式校验、手输失败能转人工登记。
- 调反馈：成功短振动、失败明确报错文案；弱光门店把 屏幕亮度设置注意事项 的口径一并核对。
五、避坑清单
这几条坑都和「把安全当前端的事」有关：
- 别把核销逻辑放前端：前端「扫到就算核销」等于没防重放，截屏、转发图片都能重放，资损由门店承担。
- 别忽略相册识别边界：开了相册识别就等于接受图片重放风险，核销类入口务必仅相机。
- 别只测正常码：篡改码、过期码、已核销码、网络中断四条异常路径各测一次再上线。
- 别让店员面对报错无路可走：每条失败提示都要接下一条出路，手输和转人工是兜底，不是可选项。
六、常见问题 FAQ
二维码和条码能同时支持吗？
能。scanType 传数组即可，如 ['qrCode','barCode']。但核销场景建议收窄到实际用到的码制，范围越小，伪造和误识的空间越小。
同一张码被扫两次会怎样？
按幂等口径处理：服务端识别同一笔核销请求，第二次返回第一次的结果并提示「已核销」，既不重复扣权益，也不给店员一个看不懂的报错。
扫码失败顾客等不及怎么办？
降级链路要提前演练：先重扫一次，不行转手输（输码后同样走服务端校验），再不行转人工登记后补录。三类路径都要在门店培训时过一遍。
这个和 GEO 地理位置配置有关系吗？
扫码核销本身不依赖 GEO。但连锁品牌要做「附近门店」检索时，需在小程序后台配好门店地址、经纬度、服务类目，这属于地理位置配置，不是按城市堆关键词的地域 SEO，两件事别混在一起做。
自己改还是找服务商做？
单店、码制单一，按本页清单自查即可上线；多门店、涉及券与分账的，建议把校验规则和幂等口径写进需求文档再开发，可先 获取报价 评估工作量。
