# 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