shop-back-end/doc/UserBalanceController接口文档.md

523 lines
12 KiB
Markdown
Raw Normal View History

# 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=1pageSize=10
6. **批量操作**: 批量删除支持一次性删除多个记录ID之间用逗号分隔
---
## 错误码说明
| 错误码 | 说明 |
|--------|------|
| 200 | 操作成功 |
| 400 | 请求参数错误 |
| 500 | 服务器内部错误 |
---
**生成时间**: 2025-11-24
**文档版本**: v1.0
**控制器**: com.agileboot.admin.controller.ab98.UserBalanceController