hi-server/doc/withdrawal-api-zh.md

提现接口文档

基础信息

项目	值
Base URL	/v1/public/user
认证方式	JWT Token（AuthMiddleware + DeviceMiddleware）
数据表	user_withdrawal

数据模型

user_withdrawal 表

字段	类型	说明
id	int64	主键
user_id	int64	用户 ID
amount	int64	提现金额（单位：分）
content	text	收款信息（账号、姓名等）
status	tinyint	0=待审核, 1=已通过, 2=已拒绝
reason	varchar(500)	拒绝原因（通过时为空）
created_at	datetime	创建时间
updated_at	datetime	更新时间

status 枚举

值	含义	说明
0	Pending（待审核）	用户提交申请后的初始状态
1	Approved（已通过）	管理员审核通过，佣金已扣减
2	Rejected（已拒绝）	管理员拒绝，无需退款（申请时未扣款）

---

用户端接口

1. 申请提现

申请佣金提现，创建一条待审核记录。申请时不扣余额，管理员审核通过后才扣。

POST /v1/public/user/commission_withdraw

请求体

{
  "amount": 1000,
  "content": "支付宝：138xxxx1234 / 张三"
}

字段	类型	必填	说明
amount	int64	是	提现金额（单位：分）
content	string	是	收款信息（支付宝/银行卡等）

成功响应

{
  "data": {
    "id": 1,
    "user_id": 10001,
    "amount": 1000,
    "content": "支付宝：138xxxx1234 / 张三",
    "status": 0,
    "reason": "",
    "created_at": 1716624000000,
    "updated_at": 1716624000000
  }
}

注意：此接口的 created_at / updated_at 返回毫秒级时间戳（.UnixMilli()），与项目其他接口的秒级时间戳不一致。

业务逻辑

1. 查询该用户所有 status=0（待审核）的提现记录，求和得 pendingTotal
2. 校验可用余额：commission >= amount + pendingTotal
3. 创建 user_withdrawal 记录，status=0
4. 不扣减 user.commission，等审核通过才扣

错误码

错误码	常量	说明
20010	UserCommissionNotEnough	可用余额不足（余额 = commission - 所有 pending 提现总额）
40005	InvalidAccess	未登录 / Token 无效

源码位置

• Handler: internal/handler/public/user/commissionWithdrawHandler.go
• Logic: internal/logic/public/user/commissionWithdrawLogic.go

---

2. 查询提现记录

分页查询当前用户的提现记录。

GET /v1/public/user/withdrawal_log

请求参数（Query）

字段	类型	必填	说明
page	int	否	页码
size	int	否	每页数量

成功响应

{
  "data": {
    "list": [
      {
        "id": 1,
        "user_id": 10001,
        "amount": 1000,
        "content": "支付宝：138xxxx1234",
        "status": 0,
        "reason": "",
        "created_at": 1716624000,
        "updated_at": 1716624000
      }
    ],
    "total": 1
  }
}

源码位置

• Handler: internal/handler/public/user/queryWithdrawalLogHandler.go
• Logic: internal/logic/public/user/queryWithdrawalLogLogic.go

Warning

: Logic 层尚未实现（仍为 TODO），调用会返回空响应。

---