523 lines
12 KiB
Markdown
523 lines
12 KiB
Markdown
# UserBalanceController 接口文档
|
||
|
||
## 概述
|
||
|
||
`UserBalanceController` 提供用户余额管理的RESTful接口，包括用户余额的查询、新增、更新、删除以及余额的增减操作。
|
||
|
||
**基础路径**: `/ab98/balance`
|
||
|
||
---
|
||
|
||
## 接口列表
|
||
|
||
### 1. 用户余额列表查询
|
||
|
||
**接口地址**: `GET /ab98/balance`
|
||
|
||
**接口描述**: 分页查询用户余额列表
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 是否必填 | 描述 | 示例 |
|
||
|--------|------|----------|------|------|
|
||
| corpid | String | 否 | 企业微信ID | ww1234567890 |
|
||
| openid | String | 否 | 微信openid | oUpF8uMuAJO_M2pxb1Q9zNjWeS6o |
|
||
| ab98UserId | Long | 否 | 汇邦云用户ID | 10001 |
|
||
| qyUserId | Long | 否 | 企业用户ID | 20001 |
|
||
| pageNum | Integer | 否 | 页码（默认1） | 1 |
|
||
| pageSize | Integer | 否 | 每页条数（默认10） | 10 |
|
||
|
||
**返回结果**: `ResponseDTO<PageDTO<UserBalanceDTO>>`
|
||
|
||
**成功响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"records": [
|
||
{
|
||
"userBalanceId": 1,
|
||
"corpid": "ww1234567890",
|
||
"openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
|
||
"ab98UserId": 10001,
|
||
"qyUserId": 20001,
|
||
"balance": 100000,
|
||
"useBalance": 95000,
|
||
"balanceLimit": 500000,
|
||
"creatorId": 1,
|
||
"updaterId": 1
|
||
}
|
||
],
|
||
"total": 100,
|
||
"pageNum": 1,
|
||
"pageSize": 10,
|
||
"pages": 10
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 用户余额详情
|
||
|
||
**接口地址**: `GET /ab98/balance/{id}`
|
||
|
||
**接口描述**: 根据主键ID查询用户余额详情
|
||
|
||
**路径参数**:
|
||
|
||
| 参数名 | 类型 | 是否必填 | 描述 | 示例 |
|
||
|--------|------|----------|------|------|
|
||
| id | Long | 是 | 主键ID | 1 |
|
||
|
||
**返回结果**: `ResponseDTO<UserBalanceDTO>`
|
||
|
||
**成功响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"userBalanceId": 1,
|
||
"corpid": "ww1234567890",
|
||
"openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
|
||
"ab98UserId": 10001,
|
||
"qyUserId": 20001,
|
||
"balance": 100000,
|
||
"useBalance": 95000,
|
||
"balanceLimit": 500000,
|
||
"creatorId": 1,
|
||
"updaterId": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 根据企业微信ID和汇邦云用户ID查询用户余额
|
||
|
||
**接口地址**: `GET /ab98/balance/byCorpidAb98`
|
||
|
||
**接口描述**: 根据企业微信ID和汇邦云用户ID查询用户余额
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 是否必填 | 描述 | 示例 |
|
||
|--------|------|----------|------|------|
|
||
| corpid | String | 是 | 企业微信ID | ww1234567890 |
|
||
| ab98UserId | Long | 是 | 汇邦云用户ID | 10001 |
|
||
|
||
**返回结果**: `ResponseDTO<UserBalanceDTO>`
|
||
|
||
**成功响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"userBalanceId": 1,
|
||
"corpid": "ww1234567890",
|
||
"openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
|
||
"ab98UserId": 10001,
|
||
"qyUserId": 20001,
|
||
"balance": 100000,
|
||
"useBalance": 95000,
|
||
"balanceLimit": 500000,
|
||
"creatorId": 1,
|
||
"updaterId": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4. 根据openid查询用户余额
|
||
|
||
**接口地址**: `GET /ab98/balance/byOpenid`
|
||
|
||
**接口描述**: 根据微信openid查询用户余额
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 是否必填 | 描述 | 示例 |
|
||
|--------|------|----------|------|------|
|
||
| openid | String | 是 | 微信openid | oUpF8uMuAJO_M2pxb1Q9zNjWeS6o |
|
||
|
||
**返回结果**: `ResponseDTO<UserBalanceDTO>`
|
||
|
||
**成功响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"userBalanceId": 1,
|
||
"corpid": "ww1234567890",
|
||
"openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
|
||
"ab98UserId": 10001,
|
||
"qyUserId": 20001,
|
||
"balance": 100000,
|
||
"useBalance": 95000,
|
||
"balanceLimit": 500000,
|
||
"creatorId": 1,
|
||
"updaterId": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5. 新增用户余额
|
||
|
||
**接口地址**: `POST /ab98/balance`
|
||
|
||
**接口描述**: 新增用户余额记录
|
||
|
||
**请求体** (JSON对象):
|
||
|
||
| 参数名 | 类型 | 是否必填 | 描述 | 备注 |
|
||
|--------|------|----------|------|------|
|
||
| corpid | String | 是 | 企业微信ID | 不能为空 |
|
||
| openid | String | 否 | 微信openid | - |
|
||
| ab98UserId | Long | 是 | 汇邦云用户ID | 不能为空 |
|
||
| qyUserId | Long | 否 | 企业用户ID | - |
|
||
| balance | Long | 否 | 用户余额(分) | 金额单位为分 |
|
||
| useBalance | Long | 否 | 可用余额(分) | 金额单位为分 |
|
||
| balanceLimit | Long | 否 | 余额限制(分) | 金额单位为分 |
|
||
|
||
**请求示例**:
|
||
```json
|
||
{
|
||
"corpid": "ww1234567890",
|
||
"openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
|
||
"ab98UserId": 10001,
|
||
"qyUserId": 20001,
|
||
"balance": 100000,
|
||
"useBalance": 95000,
|
||
"balanceLimit": 500000
|
||
}
|
||
```
|
||
|
||
**返回结果**: `ResponseDTO<UserBalanceDTO>`
|
||
|
||
**成功响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"userBalanceId": 1,
|
||
"corpid": "ww1234567890",
|
||
"openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
|
||
"ab98UserId": 10001,
|
||
"qyUserId": 20001,
|
||
"balance": 100000,
|
||
"useBalance": 95000,
|
||
"balanceLimit": 500000,
|
||
"creatorId": 1,
|
||
"updaterId": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
**操作日志**: 记录新增操作
|
||
|
||
---
|
||
|
||
### 6. 修改用户余额
|
||
|
||
**接口地址**: `PUT /ab98/balance/{id}`
|
||
|
||
**接口描述**: 修改用户余额记录
|
||
|
||
**路径参数**:
|
||
|
||
| 参数名 | 类型 | 是否必填 | 描述 | 示例 |
|
||
|--------|------|----------|------|------|
|
||
| id | Long | 是 | 主键ID | 1 |
|
||
|
||
**请求体** (JSON对象):
|
||
|
||
| 参数名 | 类型 | 是否必填 | 描述 | 备注 |
|
||
|--------|------|----------|------|------|
|
||
| corpid | String | 是 | 企业微信ID | 不能为空 |
|
||
| openid | String | 否 | 微信openid | - |
|
||
| ab98UserId | Long | 是 | 汇邦云用户ID | 不能为空 |
|
||
| qyUserId | Long | 否 | 企业用户ID | - |
|
||
| balance | Long | 否 | 用户余额(分) | 金额单位为分 |
|
||
| useBalance | Long | 否 | 可用余额(分) | 金额单位为分 |
|
||
| balanceLimit | Long | 否 | 余额限制(分) | 金额单位为分 |
|
||
|
||
**请求示例**:
|
||
```json
|
||
{
|
||
"corpid": "ww1234567890",
|
||
"openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
|
||
"ab98UserId": 10001,
|
||
"qyUserId": 20001,
|
||
"balance": 100000,
|
||
"useBalance": 95000,
|
||
"balanceLimit": 500000
|
||
}
|
||
```
|
||
|
||
**返回结果**: `ResponseDTO<UserBalanceDTO>`
|
||
|
||
**成功响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"userBalanceId": 1,
|
||
"corpid": "ww1234567890",
|
||
"openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
|
||
"ab98UserId": 10001,
|
||
"qyUserId": 20001,
|
||
"balance": 100000,
|
||
"useBalance": 95000,
|
||
"balanceLimit": 500000,
|
||
"creatorId": 1,
|
||
"updaterId": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
**操作日志**: 记录修改操作
|
||
|
||
---
|
||
|
||
### 7. 删除用户余额
|
||
|
||
**接口地址**: `DELETE /ab98/balance/{id}`
|
||
|
||
**接口描述**: 删除用户余额记录
|
||
|
||
**路径参数**:
|
||
|
||
| 参数名 | 类型 | 是否必填 | 描述 | 示例 |
|
||
|--------|------|----------|------|------|
|
||
| id | Long | 是 | 主键ID | 1 |
|
||
|
||
**返回结果**: `ResponseDTO<Void>`
|
||
|
||
**操作日志**: 记录删除操作
|
||
|
||
---
|
||
|
||
### 8. 批量删除用户余额
|
||
|
||
**接口地址**: `DELETE /ab98/balance/batch/{ids}`
|
||
|
||
**接口描述**: 批量删除用户余额记录
|
||
|
||
**路径参数**:
|
||
|
||
| 参数名 | 类型 | 是否必填 | 描述 | 示例 |
|
||
|--------|------|----------|------|------|
|
||
| ids | List<Long> | 是 | 主键ID列表 | 1,2,3 |
|
||
|
||
**返回结果**: `ResponseDTO<Void>`
|
||
|
||
**操作日志**: 记录删除操作
|
||
|
||
---
|
||
|
||
### 9. 增加用户余额
|
||
|
||
**接口地址**: `POST /ab98/balance/addBalance`
|
||
|
||
**接口描述**: 增加用户余额
|
||
|
||
**请求体** (JSON对象):
|
||
|
||
| 参数名 | 类型 | 是否必填 | 描述 | 备注 |
|
||
|--------|------|----------|------|------|
|
||
| corpid | String | 是 | 企业微信ID | 不能为空 |
|
||
| ab98UserId | Long | 是 | 汇邦云用户ID | 不能为空 |
|
||
| amount | Long | 是 | 增加金额(分) | 金额单位为分，不能为空 |
|
||
|
||
**请求示例**:
|
||
```json
|
||
{
|
||
"corpid": "ww1234567890",
|
||
"ab98UserId": 10001,
|
||
"amount": 10000
|
||
}
|
||
```
|
||
|
||
**返回结果**: `ResponseDTO<String>`
|
||
|
||
**成功响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "增加用户余额成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**失败响应示例**:
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "增加用户余额失败",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**操作日志**: 记录修改操作
|
||
|
||
---
|
||
|
||
### 10. 减少用户余额
|
||
|
||
**接口地址**: `POST /ab98/balance/subtractBalance`
|
||
|
||
**接口描述**: 减少用户余额
|
||
|
||
**请求体** (JSON对象):
|
||
|
||
| 参数名 | 类型 | 是否必填 | 描述 | 备注 |
|
||
|--------|------|----------|------|------|
|
||
| corpid | String | 是 | 企业微信ID | 不能为空 |
|
||
| ab98UserId | Long | 是 | 汇邦云用户ID | 不能为空 |
|
||
| amount | Long | 是 | 减少金额(分) | 金额单位为分，不能为空 |
|
||
|
||
**请求示例**:
|
||
```json
|
||
{
|
||
"corpid": "ww1234567890",
|
||
"ab98UserId": 10001,
|
||
"amount": 5000
|
||
}
|
||
```
|
||
|
||
**返回结果**: `ResponseDTO<String>`
|
||
|
||
**成功响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "减少用户余额成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**失败响应示例**:
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "减少用户余额失败",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**操作日志**: 记录修改操作
|
||
|
||
---
|
||
|
||
### 11. 插入或更新用户余额
|
||
|
||
**接口地址**: `POST /ab98/balance/insertOrUpdate`
|
||
|
||
**接口描述**: 插入或更新用户余额（如果存在则更新，不存在则新增）
|
||
|
||
**请求体** (JSON对象):
|
||
|
||
| 参数名 | 类型 | 是否必填 | 描述 | 备注 |
|
||
|--------|------|----------|------|------|
|
||
| corpid | String | 是 | 企业微信ID | 不能为空 |
|
||
| openid | String | 否 | 微信openid | - |
|
||
| ab98UserId | Long | 是 | 汇邦云用户ID | 不能为空 |
|
||
| qyUserId | Long | 否 | 企业用户ID | - |
|
||
| balance | Long | 否 | 用户余额(分) | 金额单位为分 |
|
||
| useBalance | Long | 否 | 可用余额(分) | 金额单位为分 |
|
||
| balanceLimit | Long | 否 | 余额限制(分) | 金额单位为分 |
|
||
|
||
**请求示例**:
|
||
```json
|
||
{
|
||
"corpid": "ww1234567890",
|
||
"openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
|
||
"ab98UserId": 10001,
|
||
"qyUserId": 20001,
|
||
"balance": 100000,
|
||
"useBalance": 95000,
|
||
"balanceLimit": 500000
|
||
}
|
||
```
|
||
|
||
**返回结果**: `ResponseDTO<UserBalanceDTO>`
|
||
|
||
**成功响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"userBalanceId": 1,
|
||
"corpid": "ww1234567890",
|
||
"openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
|
||
"ab98UserId": 10001,
|
||
"qyUserId": 20001,
|
||
"balance": 100000,
|
||
"useBalance": 95000,
|
||
"balanceLimit": 500000,
|
||
"creatorId": 1,
|
||
"updaterId": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
**操作日志**: 记录修改操作
|
||
|
||
---
|
||
|
||
## 数据结构
|
||
|
||
### UserBalanceDTO（用户余额DTO）
|
||
|
||
| 字段名 | 类型 | 描述 | 示例 |
|
||
|--------|------|------|------|
|
||
| userBalanceId | Long | 主键ID | 1 |
|
||
| corpid | String | 企业微信ID | ww1234567890 |
|
||
| openid | String | 微信openid | oUpF8uMuAJO_M2pxb1Q9zNjWeS6o |
|
||
| ab98UserId | Long | 汇邦云用户ID | 10001 |
|
||
| qyUserId | Long | 企业用户ID | 20001 |
|
||
| balance | Long | 用户余额(分) | 100000 |
|
||
| useBalance | Long | 可用余额(分) | 95000 |
|
||
| balanceLimit | Long | 余额限制(分) | 500000 |
|
||
| creatorId | Long | 创建者ID | 1 |
|
||
| updaterId | Long | 更新者ID | 1 |
|
||
|
||
**说明**: 余额相关字段单位均为**分**，例如100元 = 10000分
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **金额单位**: 所有余额相关字段（balance、useBalance、balanceLimit、amount）单位均为**分**，而非元
|
||
2. **必填参数**: 标有"不能为空"的参数为必填项，请求时必须提供
|
||
3. **操作日志**: 新增、修改、删除操作会自动记录操作日志
|
||
4. **唯一性**: corpid + ab98UserId 组合应保证唯一性
|
||
5. **分页查询**: list接口支持分页，默认pageNum=1，pageSize=10
|
||
6. **批量操作**: 批量删除支持一次性删除多个记录，ID之间用逗号分隔
|
||
|
||
---
|
||
|
||
## 错误码说明
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 操作成功 |
|
||
| 400 | 请求参数错误 |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
---
|
||
|
||
**生成时间**: 2025-11-24
|
||
**文档版本**: v1.0
|
||
**控制器**: com.agileboot.admin.controller.ab98.UserBalanceController
|