079076a70e
- 从 main 获取 single_uniapp22miao 子项目 - dart-sass: /deep/ -> ::v-deep，calc 运算符加空格 - DEPLOY.md 采用 shccd159 版本（4 子项目架构说明） Made-with: Cursor
304 lines
8.2 KiB
Markdown
304 lines
8.2 KiB
Markdown
# 个人奖金积分兑换 - 前端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. **用户关联**：积分商城与寄卖商城用户需要通过手机号或其他方式建立关联
|