integral-shop/backend/docs/前端API-个人奖金积分兑换.md

个人奖金积分兑换 - 前端API接口需求文档

一、概述

本文档描述积分商城前端与寄卖商城（wa_系统）对接所需的API接口，用于实现个人奖金查询、奖金记录查询以及奖金兑换商品功能。

---

二、接口列表

1. 获取寄卖商城用户信息

接口说明：查询寄卖商城用户信息，用于展示个人奖金页面头部数据

请求方式：POST

接口路径：/api/front/wa/user/info

请求参数：

参数名	类型	必填	说明
userId	Integer	是	寄卖商城用户ID

请求示例：

{
  "userId": 100
}

响应参数：

字段名	类型	说明	对应数据库字段
id	Integer	用户ID	wa_users.id
nickname	String	用户昵称	wa_users.nickname
mobile	String	手机号	wa_users.mobile
selfBonus	BigDecimal	个人奖金（我的奖金）	wa_users.self_bonus
money	BigDecimal	可提现余额（奖金）	wa_users.money
score	Integer	易积分（可兑换商品积分）	wa_users.score
shareBonus	BigDecimal	推广奖金	wa_users.share_bonus
coupon	BigDecimal	优惠券余额	wa_users.coupon

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 100,
    "nickname": "用户昵称",
    "mobile": "13800138000",
    "selfBonus": 1077.726,
    "money": 538.86,
    "score": 9999,
    "shareBonus": 200.00,
    "coupon": 50.00
  }
}

---

2. 获取个人奖金记录列表

接口说明：查询寄卖商城个人奖金收支记录，支持分页和类型筛选

请求方式：GET

接口路径：/api/front/wa/selfbonus/list

请求参数：

参数名	类型	必填	说明
userId	Integer	是	寄卖商城用户ID
type	Integer	是	记录类型：1=收入明细，2=支出明细
page	Integer	否	页码，默认1
limit	Integer	否	每页条数，默认20

请求示例：

GET /api/front/wa/selfbonus/list?userId=100&type=2&page=1&limit=20

响应参数：

字段名	类型	说明	对应数据库字段
id	Integer	记录ID	wa_selfbonus_log.id
userId	Integer	用户ID	wa_selfbonus_log.user_id
type	Integer	类型：1=收入，2=支出	wa_selfbonus_log.type
money	BigDecimal	变更金额	wa_selfbonus_log.money
before	BigDecimal	变更前金额	wa_selfbonus_log.before
after	BigDecimal	变更后金额	wa_selfbonus_log.after
memo	String	备注说明	wa_selfbonus_log.memo
createdAt	String	创建时间	wa_selfbonus_log.created_at

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "userId": 100,
        "type": 2,
        "money": -388.119,
        "before": 1465.845,
        "after": 1077.726,
        "memo": "积分兑换：XXX商品名称",
        "createdAt": "2025-12-28 04:09:47"
      },
      {
        "id": 2,
        "userId": 100,
        "type": 2,
        "money": -142.382,
        "before": 1608.227,
        "after": 1465.845,
        "memo": "积分兑换：XXX商品名称",
        "createdAt": "2025-12-20 04:09:47"
      }
    ],
    "total": 50,
    "page": 1,
    "limit": 20,
    "totalPage": 3
  }
}

---

3. 奖金兑换商品下单

接口说明：使用个人奖金在积分商城中兑换商品，成功后扣除寄卖商城对应奖金并新增支出记录

请求方式：POST

接口路径：/api/front/wa/selfbonus/exchange

请求参数：

参数名	类型	必填	说明
userId	Integer	是	寄卖商城用户ID
orderId	String	是	积分商城订单编号
money	BigDecimal	是	兑换使用的奖金金额
memo	String	否	备注说明（如兑换商品名称）

请求示例：

{
  "userId": 100,
  "orderId": "ORDER202512280001",
  "money": 388.119,
  "memo": "积分兑换：XXX商品"
}

响应参数：

字段名	类型	说明
success	Boolean	是否成功
before	BigDecimal	扣除前的奖金余额
after	BigDecimal	扣除后的奖金余额
logId	Integer	生成的支出记录ID

响应示例：

{
  "code": 200,
  "message": "兑换成功",
  "data": {
    "success": true,
    "before": 1077.726,
    "after": 689.607,
    "logId": 123
  }
}

错误响应：

{
  "code": 500,
  "message": "奖金余额不足",
  "data": null
}

---

三、数据表结构（参考 wa_ 数据库）

3.1 wa_users（寄卖服务用户表）

字段名	类型	说明
id	int(10)	主键ID
nickname	varchar(40)	昵称
mobile	varchar(16)	手机号
money	decimal(13,3)	可提现余额（奖金），默认0.000
self_bonus	decimal(13,3)	个人奖金（我的奖金），默认0.000
share_bonus	decimal(13,3)	推广奖金，默认0.000
coupon	decimal(13,3)	优惠券余额，默认0.000
score	int(11)	易积分，默认0
status	tinyint(4)	状态: 0=禁用, 1=启用

3.2 wa_selfbonus_log（个人奖金变动表）

字段名	类型	说明
id	int(10)	主键ID
user_id	int(10)	用户ID
type	tinyint(1)	类型：1=收入，2=支出
money	decimal(13,3)	变更金额
before	decimal(13,3)	变更前金额
after	decimal(13,3)	变更后金额
memo	varchar(255)	备注说明
created_at	datetime	创建时间
updated_at	datetime	更新时间

---

四、业务流程

4.1 页面加载流程

1. 前端获取寄卖商城用户ID（通过手机号或其他关联方式）
2. 调用【获取用户信息】接口（传入userId）→ 展示头部奖金数据
3. 默认加载【收入明细】列表（传入userId, type=1）
4. 切换Tab时重新请求对应类型的记录列表

4.2 奖金兑换流程

1. 用户在积分商城选择商品下单
2. 选择使用"个人奖金"支付
3. 调用【奖金兑换商品下单】接口
   - 传入 userId、orderId、money、memo
4. 后端处理逻辑：
   a. 根据 userId 查询 wa_users 表获取 self_bonus
   b. 校验 self_bonus >= money（奖金余额充足）
   c. 扣除 wa_users.self_bonus（减去 money）
   d. 新增 wa_selfbonus_log 记录：
      - user_id = userId
      - type = 2（支出）
      - money = -money（负数）
      - before = 原余额
      - after = 扣除后余额
      - memo = 备注
5. 返回兑换结果
6. 前端刷新用户奖金信息

4.3 页面数据对应关系

页面元素	数据来源	字段
我的奖金: 1077.726	wa_users	self_bonus
奖金 ¥538.86 可提现	wa_users	money
易积分 9999 可兑换商品	wa_users	score
收入/支出明细列表	wa_selfbonus_log	type区分
积分兑换 -388.119	wa_selfbonus_log	memo + money
2025-12-28 04:09:47	wa_selfbonus_log	created_at

---

五、错误码说明

错误码	说明
200	成功
401	未登录或Token失效
500	服务器错误
40001	用户不存在（wa_users中无此userId）
40002	奖金余额不足（self_bonus < 兑换金额）
40003	订单不存在
40004	重复兑换（订单已处理）
40005	用户已禁用（status=0）

---

六、注意事项

1. 用户ID传递：所有接口都需要传入 userId 参数，表示寄卖商城用户ID
2. 金额精度：
   • 数据库字段 decimal(13,3) 保留3位小数
   • 接口传输和展示时保持3位小数精度
3. 事务处理：奖金扣除操作需要事务保证，确保以下操作原子性：
   • 更新 wa_users.self_bonus
   • 插入 wa_selfbonus_log 记录
4. 金额符号：
   • 收入记录：money 为正数
   • 支出记录：money 为负数
5. 接口限流：建议对兑换接口增加限流，防止重复提交
6. 用户关联：积分商城与寄卖商城用户需要通过手机号或其他方式建立关联