本文档使用 SmartWiki 发布

独立框架卡卷模块

卡券前端兑换接口文档

1. 说明

文档范围：仅包含前端会员侧“卡券兑换”相关接口。
会员中心入口装配文件：/Users/water/Desktop/www/shop/app/common/services/member/center/MemberCenterService.php
前端兑换控制器：/Users/water/Desktop/www/shop/app/frontend/modules/cardVoucher/controllers/RechargeController.php
路由机制：项目走前端模块自动路由，前端请求建议统一传 route 参数。
本模块推荐路由：
- cardVoucher.recharge.index
- cardVoucher.recharge.bind
- cardVoucher.recharge.scanRecharge
鉴权：兑换接口需要会员登录态；会员中心入口接口按现有会员中心逻辑返回。
返回格式：统一调用 successJson() / errorJson()。

2. 通用返回格式

2.1 成功

{
  "result": 1,
  "msg": "获取成功",
  "data": {}
}

2.2 失败

{
  "result": 0,
  "msg": "错误提示文案"
}

3. 会员中心入口

3.1 会员中心数据

路由：member.member.memberData
说明：获取会员中心页面数据，营销互动区域是否返回“卡券兑换”入口，由后端统一装配。

卡券入口出现条件

当前商城 uniacid 下存在卡券数据。
判断逻辑文件：/Users/water/Desktop/www/shop/app/common/services/member/center/MemberCenterService.php
当前判断方式：查询 yz_card_voucher_electronic_order_item.app_id = 当前商城ID 是否存在记录。

返回中的卡券入口结构

当满足条件时，会员中心数据里会附带如下入口：

{
  "name": "card-voucher",
  "title": "卡券兑换",
  "class": "icon-member_changer_centre",
  "url": "xxxxx",
  "image": "member_a(74).png",
  "mini_url": "x'x'xxxxx",
  "type_1": "service",
  "type_2": "market",
  "weight_1": 2700,
  "weight_2": 10800,
  "default_weight": 29
}

前端处理建议

有该入口时显示“卡券兑换”。
无该入口时不显示，不需要额外调开关接口。
小程序跳转地址和 H5需要提供给后端

4. 卡券兑换首页初始化

4.1 获取兑换页基础数据

路由：cardVoucher.recharge.index
说明：进入卡券兑换页时调用，返回当前商城名称、支持的兑换方式、使用规则提示、是否支持扫码。

请求参数

无

返回 data

字段	类型	说明
app_id	int	当前商城 ID
app_name	string	当前商城名称
redeem_method_list	array	当前商城支持的兑换方式列表
default_redeem_method	int	默认兑换方式
tips	array	使用规则提示，来自当前商城启用中的产品档案 `usage_rule` 去重结果
support_scan	int	是否支持扫码，固定返回 `1`

redeem_method_list 单项

字段	类型	说明
value	int	兑换方式值
label	string	兑换方式名称

当前支持的兑换方式

value	说明
1	仅输券密
2	券号 + 券密

成功示例

{
  "result": 1,
  "msg": "获取成功",
  "data": {
    "app_id": 12,
    "app_name": "商城A",
    "redeem_method_list": [
      {
        "value": 1,
        "label": "仅输券密"
      },
      {
        "value": 2,
        "label": "券号+券密"
      }
    ],
    "default_redeem_method": 1,
    "tips": [
      "仅限本商城使用",
      "充值后不可撤销"
    ],
    "support_scan": 1
  }
}

5. 手动兑换

5.1 卡券充值到余额

路由：cardVoucher.recharge.bind
说明：会员手动输入券密或券号+券密后，将卡券充值到当前会员余额。
事务：后端使用事务处理，充值成功后会同时写余额变动和卡券充值状态。

请求参数

字段	类型	必填	说明
redeem_method	int	是	兑换方式：`1` 仅输券密，`2` 券号+券密
voucher_secret	string	是	券密
voucher_code	string	条件必填	当 `redeem_method=2` 时必填

兑换成功后后端处理

给当前登录会员增加余额
余额变动 source 使用 ConstService::SOURCE_RECHARGE_CODE
卡券状态更新为已充值
记录充值会员 ID、昵称、手机号、充值金额、充值时间
同一张卡券不能重复充值

返回 data

字段	类型	说明
member_id	int	当前会员 ID
redeem_amount	string	本次充值金额，保留 2 位小数
voucher_code	string	券号
app_name	string	所属商城名称

成功示例

{
  "result": 1,
  "msg": "充值成功",
  "data": {
    "member_id": 9527,
    "redeem_amount": "100.00",
    "voucher_code": "DZ202606260001",
    "app_name": "商城A"
  }
}

6. 扫码兑换

6.1 扫码充值到余额

路由：cardVoucher.recharge.scanRecharge
说明：前端先识别二维码内容，再把扫码结果原文传给后端，由后端解析卡券参数并完成充值。

请求参数

字段	类型	必填	说明
scan_result	string	是	扫码得到的原始内容，支持完整 URL 或仅 query 参数字符串

后端支持解析的二维码参数

字段	说明
order_no	卡券订单号，可选
stock_no	备券单号，可选
voucher_code	券号，必需
voucher_secret	券密，必需

二维码内容示例

完整链接：

https://xxx.com/app/index.php?i=12&route=cardVoucher/recharge&order_no=EV202606260001&stock_no=BK202606260001&voucher_code=DZ202606260001&voucher_secret=ABC123456

仅参数字符串：

order_no=EV202606260001&stock_no=BK202606260001&voucher_code=DZ202606260001&voucher_secret=ABC123456

返回 data

与手动兑换一致：

字段	类型	说明
member_id	int	当前会员 ID
redeem_amount	string	本次充值金额
voucher_code	string	券号
app_name	string	所属商城名称

7. 后端校验逻辑

以下校验由后端统一处理，前端不需要自行判断业务真伪，但建议按错误提示直接透出。

7.1 基础校验

未登录：请先登录
会员不存在：会员不存在
扫码结果为空：扫码结果不能为空
扫码链接缺少参数：扫码链接缺少卡券参数
兑换方式为空或非法：兑换方式不能为空
券密为空：券密不能为空
券号为空：券号不能为空
卡券不存在或校验失败：卡券不存在或校验失败

7.2 商城归属校验

只允许兑换属于当前商城的卡券
错误提示：当前卡券不属于本商城

7.3 卡券状态校验

禁用：当前卡券已禁用，无法充值
作废：当前卡券已作废，无法充值
未激活：当前卡券未激活，无法充值
未到可用时间：当前卡券未到可用时间
已过期：当前卡券已过期，无法充值
已充值过：当前卡券已充值，不能重复使用

7.4 金额校验

若卡面金额异常或拆分后金额小于等于 0
错误提示：卡券充值金额不正确

8. 充值金额规则

后端金额计算逻辑如下：

如果卡项自身 face_amount > 0，本次充值金额直接取该金额
如果卡项 face_amount <= 0，则按订单总面额 total_face_amount / sale_count 平摊
最终金额保留 2 位小数

9. 前端对接建议

9.1 页面流程

调 member.member.memberData 判断是否显示“卡券兑换”入口
进入兑换页后调 cardVoucher.recharge.index 获取页面配置
用户选择兑换方式
手动输入时调用 cardVoucher.recharge.bind
扫码时前端拿到二维码原文后调用 cardVoucher.recharge.scanRecharge
成功后刷新会员余额信息

9.2 错误处理建议

业务错误直接使用后端 msg 提示
对“当前卡券不属于本商城”“已过期”“未激活”“已充值”这类提示不要二次改写
扫码失败时，前端优先判断是否拿到 scan_result；只要拿到了就交给后端校验

9.3 UI 提示建议

手动兑换页建议展示 tips
support_scan=1 时展示“扫码兑换”入口
兑换成功后展示充值金额和券号

10. 代码参考

会员中心入口装配：/Users/water/Desktop/www/shop/app/common/services/member/center/MemberCenterService.php
会员中心接口：/Users/water/Desktop/www/shop/app/frontend/modules/member/controllers/MemberController.php
卡券兑换控制器：/Users/water/Desktop/www/shop/app/frontend/modules/cardVoucher/controllers/RechargeController.php