钱包系统

更新时间：2026-03-28

Dujiao-Next 内置钱包系统，用户可以通过多种支付方式充值钱包余额，下单时使用余额支付，也可以通过礼品卡兑换增加余额。管理员可手动调整用户余额或将订单退款至钱包。

---

1. 功能概览

功能	说明
余额充值	用户通过已配置的支付渠道充值钱包
余额支付	下单时可使用钱包余额抵扣全部或部分金额
交易记录	每笔充值、消费、退款均有完整记录
礼品卡兑换	用户输入礼品卡码兑换余额
管理员调整	管理员可增加或扣减用户余额
退款到钱包	管理员可将已支付订单的金额退回用户钱包

---

2. 用户操作

2.1 充值钱包

1. 在前台进入「钱包」页面
2. 输入充值金额（必须大于 0，最多两位小数）
3. 选择支付渠道完成支付
4. 支付成功后余额自动到账

充值未支付将在超时后自动过期（默认 15 分钟，与订单支付超时一致）。

2.2 使用余额支付

下单时系统会自动检测钱包余额：

• 余额 >= 订单金额：可全额使用余额支付，无需在线支付
• 余额 < 订单金额：余额抵扣部分金额，剩余通过在线支付渠道完成
• 游客用户不支持钱包支付

2.3 兑换礼品卡

1. 在前台进入「钱包」页面
2. 输入礼品卡码
3. 兑换成功后面额自动充入钱包

礼品卡码不区分大小写。已使用、已禁用或已过期的礼品卡无法兑换。

2.4 查看交易记录

钱包页面可查看所有历史交易，每笔记录包含：

• 交易类型（充值 / 订单支付 / 退款 / 管理员调整 / 礼品卡兑换）
• 金额与方向（收入 / 支出）
• 交易前后余额
• 关联订单号（如有）
• 时间与备注

---

3. 交易类型

类型标识	说明	方向
recharge	用户充值	收入
order_pay	订单余额支付	支出
admin_refund	管理员退款到钱包	收入
admin_adjust	管理员手动调整	收入/支出
gift_card	礼品卡兑换	收入

---

4. 管理员操作

4.1 调整用户余额

后台「用户管理」中选择用户，可手动增加或扣减余额：

• 正数为增加余额，负数为扣减
• 金额不可为 0
• 操作后余额不可为负

4.2 退款到钱包

后台「订单管理」中，对已支付的订单可执行「退款到钱包」：

• 输入退款金额（不可超过订单可退金额）
• 退款金额自动充入用户钱包
• 支持多次部分退款，累计不超过订单实付金额
• 游客订单不支持退款到钱包
• 若订单关联了分销佣金，退款时会同步处理佣金扣减

---

5. 礼品卡管理

5.1 生成礼品卡

后台「礼品卡」页面可批量生成：

• 名称：批次名称，便于管理
• 面额：每张礼品卡的金额（大于 0，最多两位小数）
• 数量：单次最多生成 10,000 张
• 过期时间：可选，不设则永不过期

生成后每张礼品卡获得唯一卡码（格式：GC + 时间戳 + 序号 + 随机串）。

5.2 礼品卡状态

状态	说明
active	可用，等待兑换
redeemed	已被用户兑换
disabled	已禁用，不可兑换

• 管理员可批量启用/禁用礼品卡
• 已兑换的礼品卡不可修改状态或删除

5.3 导出礼品卡

支持导出为：

• TXT 格式：每行一个卡码
• CSV 格式：包含完整字段（ID、批次号、名称、卡码、面额、状态、兑换信息等）

---

6. 注意事项

• 钱包账户在用户首次访问时自动创建，无需手动开通
• 所有金额操作使用幂等引用（Reference），确保不会重复扣款或充值
• 余额精度为两位小数
• 默认货币跟随系统设置（如 CNY、USD 等）