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

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>>

成功响应示例:

{
  "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>

成功响应示例:

{
  "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>

成功响应示例:

{
  "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>

成功响应示例:

{
  "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	否	余额限制(分)	金额单位为分

请求示例:

{
  "corpid": "ww1234567890",
  "openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
  "ab98UserId": 10001,
  "qyUserId": 20001,
  "balance": 100000,
  "useBalance": 95000,
  "balanceLimit": 500000
}

返回结果: ResponseDTO<UserBalanceDTO>

成功响应示例:

{
  "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	否	余额限制(分)	金额单位为分

请求示例:

{
  "corpid": "ww1234567890",
  "openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
  "ab98UserId": 10001,
  "qyUserId": 20001,
  "balance": 100000,
  "useBalance": 95000,
  "balanceLimit": 500000
}

返回结果: ResponseDTO<UserBalanceDTO>

成功响应示例:

{
  "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	是	主键ID列表	1,2,3

返回结果: ResponseDTO<Void>

操作日志: 记录删除操作

---

9. 增加用户余额

接口地址: POST /ab98/balance/addBalance

接口描述: 增加用户余额

请求体 (JSON对象):

参数名	类型	是否必填	描述	备注
corpid	String	是	企业微信ID	不能为空
ab98UserId	Long	是	汇邦云用户ID	不能为空
amount	Long	是	增加金额(分)	金额单位为分，不能为空

请求示例:

{
  "corpid": "ww1234567890",
  "ab98UserId": 10001,
  "amount": 10000
}

返回结果: ResponseDTO<String>

成功响应示例:

{
  "code": 200,
  "msg": "增加用户余额成功",
  "data": null
}

失败响应示例:

{
  "code": 500,
  "msg": "增加用户余额失败",
  "data": null
}

操作日志: 记录修改操作

---

10. 减少用户余额

接口地址: POST /ab98/balance/subtractBalance

接口描述: 减少用户余额

请求体 (JSON对象):

参数名	类型	是否必填	描述	备注
corpid	String	是	企业微信ID	不能为空
ab98UserId	Long	是	汇邦云用户ID	不能为空
amount	Long	是	减少金额(分)	金额单位为分，不能为空

请求示例:

{
  "corpid": "ww1234567890",
  "ab98UserId": 10001,
  "amount": 5000
}

返回结果: ResponseDTO<String>

成功响应示例:

{
  "code": 200,
  "msg": "减少用户余额成功",
  "data": null
}

失败响应示例:

{
  "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	否	余额限制(分)	金额单位为分

请求示例:

{
  "corpid": "ww1234567890",
  "openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
  "ab98UserId": 10001,
  "qyUserId": 20001,
  "balance": 100000,
  "useBalance": 95000,
  "balanceLimit": 500000
}

返回结果: ResponseDTO<UserBalanceDTO>

成功响应示例:

{
  "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