加载中…
首页打印分享
余额 money

模块说明

money 覆盖会员余额体系：余额总览、充值套餐、明细流水、付款码刷新；工作端（money/work，要求员工身份）提供按付款码/手机号查询会员余额与核销扣款。

鉴权级别：会员侧必须登录；工作端必须员工身份。

接口一览

方法 URL 鉴权 说明
GET /api/money 必须 余额首页（余额总额）
GET /api/money/recharge 必须 充值页（套餐列表）
GET /api/user/money 必须 我的余额明细
GET /api/user/money/pay_code 必须 刷新会员付款码
GET /api/money/work 员工 工作端余额核销入口
POST /api/money/work/search 员工 查询会员余额与流水
POST /api/money/work/use 员工 核销扣款

余额首页 GET /api/money

{
  "code": "OK",
  "message": "",
  "data": {
    "title": "余额支付",
    "total": "¥100.00"
  },
  "errors": {},
  "request_id": "9f2a5c8e1b3d7f40"
}

充值页 GET /api/money/recharge

参数 必填 说明
current_id 否 当前选中套餐 ID，默认第一个 
{
  "code": "OK",
  "message": "",
  "data": {
    "title": "余额充值",
    "package_list": [ { "id": 1, "name": "...", "money": "...", "give": "..." } ],
    "current_id": 1,
    "current": { "...": "当前套餐对象" },
    "total": "¥100.00"
  },
  "errors": {},
  "request_id": "9f2a5c8e1b3d7f40"
}

我的余额明细 GET /api/user/money

参数 必填 说明
page 否 页码，默认 1 
{
  "code": "OK",
  "message": "",
  "data": {
    "title": "余额明细",
    "log_list": [ { "id": 1, "money": "...", "add_time": "...", "...": "" } ],
    "pager": { "...": "分页信息" },
    "total": "¥100.00"
  },
  "errors": {},
  "request_id": "9f2a5c8e1b3d7f40"
}

付款码 GET /api/user/money/pay_code

刷新并返回当前会员付款码（供工作端扫码/输入核销）：

{
  "code": "OK",
  "message": "",
  "data": {
    "pay_code": "123456",
    "user": { "...": "会员信息格式化数据" },
    "total": "¥100.00"
  },
  "errors": {},
  "request_id": "9f2a5c8e1b3d7f40"
}

工作端接口（work_required）

入口 GET /api/money/work

返回 title 与 pay_code_mode（true 时用付款码核销、false 时用手机号核销，由站点参数 money_pay_code 决定）。

查询余额 POST /api/money/work/search

参数 必填 说明
number 是 付款码（pay_code_mode=true）或手机号（false）
money 否 本次拟扣金额（仅回显）
page 否 流水页码，默认 1 
{
  "code": "OK",
  "message": "",
  "data": {
    "pay_code_mode": true,
    "log_list": [ { "...": "该会员余额流水" } ],
    "pager": { "...": "分页信息" },
    "work": { "number": "123456", "money": "¥10.00", "total": "¥100.00" },
    "user": { "...": "会员信息" }
  },
  "errors": {},
  "request_id": "9f2a5c8e1b3d7f40"
}
场景 响应
未找到匹配会员 404 NOT_FOUND（money_not_user）
非员工 / 未登录 403 FORBIDDEN（未登录时由鉴权层先返回 401）

核销扣款 POST /api/money/work/use

参数 必填 说明
number 是 付款码或手机号
money 是 扣款金额（必须大于 0）

成功返回 data.money（本次扣款金额）。

场景 响应
会员不存在或金额非法 422 INVALID_PARAMS（money_not_user）
余额不足等业务失败 由余额服务判定（通常 422 BUSINESS_RULE_VIOLATION）

注意事项

  • 工作端鉴权为员工权限（work 功能 + money 模块权限）；非员工统一 403 work_no_permission；
  • 付款码模式由站点参数 money_pay_code 决定：开启时 number 传付款码（纯数字），关闭时传手机号；客户端应以 GET /api/money/work 返回的 pay_code_mode 为准动态切换输入形态；
  • 金额字段（total 等）为格式化字符串（如 ¥100.00），非数值。
添加日期：2026-10-06