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

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

## 一、概述

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

---

## 二、接口列表

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

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

**请求方式**：`POST`

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

**请求参数**：

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

**请求示例**：
```json
{
  "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 |

**响应示例**：
```json
{
  "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 |

**响应示例**：
```json
{
  "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 | 否 | 备注说明（如兑换商品名称） |

**请求示例**：
```json
{
  "userId": 100,
  "orderId": "ORDER202512280001",
  "money": 388.119,
  "memo": "积分兑换：XXX商品"
}
```

**响应参数**：

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

**响应示例**：
```json
{
  "code": 200,
  "message": "兑换成功",
  "data": {
    "success": true,
    "before": 1077.726,
    "after": 689.607,
    "logId": 123
  }
}
```

**错误响应**：
```json
{
  "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. **用户关联**：积分商城与寄卖商城用户需要通过手机号或其他方式建立关联