admin123
/
shop-back-end
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat(user_balance): 添加软删除字段并更新余额计算逻辑 

- 在user_balance表中添加deleted字段实现软删除功能
- 更新UserBalanceServiceImpl中的余额计算逻辑，自动计算balance值
- 统一UserBalanceController接口路径命名风格为驼峰式
- 新增UserBalanceController接口文档
This commit is contained in:
dzq 2025-11-24 17:57:47 +08:00
parent cc78eceda4
commit bf381fcd35
4 changed files with 541 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
agileboot-admin/src/main/java/com/agileboot/admin/controller/ab98/UserBalanceController.java
View File

@ -51,14 +51,14 @@ public class UserBalanceController extends BaseController {
}
@Operation(summary = "根据企业微信ID和汇邦云用户ID查询用户余额")
@GetMapping("/by-corpid-ab98")
@GetMapping("/byCorpidAb98")
public ResponseDTO<UserBalanceDTO> getByCorpidAndAb98UserId(String corpid, Long ab98UserId) {
UserBalanceDTO userBalanceDTO = userBalanceApplicationService.getByCorpidAndAb98UserId(corpid, ab98UserId);
return ResponseDTO.ok(userBalanceDTO);
}
@Operation(summary = "根据openid查询用户余额")
@GetMapping("/by-openid")
@GetMapping("/byOpenid")
public ResponseDTO<UserBalanceDTO> getByOpenid(String openid) {
UserBalanceDTO userBalanceDTO = userBalanceApplicationService.getByOpenid(openid);
return ResponseDTO.ok(userBalanceDTO);
@ -99,7 +99,7 @@ public class UserBalanceController extends BaseController {
@Operation(summary = "增加用户余额")
@AccessLog(title = "用户余额管理", businessType = BusinessTypeEnum.MODIFY)
@PostMapping("/add-balance")
@PostMapping("/addBalance")
public ResponseDTO<String> addBalance(@Validated @RequestBody AddBalanceCommand command) {
boolean success = userBalanceApplicationService.addBalance(command);
return success ? ResponseDTO.ok("增加用户余额成功") : ResponseDTO.fail("增加用户余额失败");
@ -107,7 +107,7 @@ public class UserBalanceController extends BaseController {
@Operation(summary = "减少用户余额")
@AccessLog(title = "用户余额管理", businessType = BusinessTypeEnum.MODIFY)
@PostMapping("/subtract-balance")
@PostMapping("/subtractBalance")
public ResponseDTO<String> subtractBalance(@Validated @RequestBody SubtractBalanceCommand command) {
boolean success = userBalanceApplicationService.subtractBalance(command);
return success ? ResponseDTO.ok("减少用户余额成功") : ResponseDTO.fail("减少用户余额失败");
@ -115,7 +115,7 @@ public class UserBalanceController extends BaseController {
@Operation(summary = "插入或更新用户余额")
@AccessLog(title = "用户余额管理", businessType = BusinessTypeEnum.MODIFY)
@PostMapping("/insert-or-update")
@PostMapping("/insertOrUpdate")
public ResponseDTO<UserBalanceDTO> insertOrUpdate(@Validated @RequestBody AddUserBalanceCommand command) {
UserBalanceDTO userBalanceDTO = userBalanceApplicationService.insertOrUpdate(command);
return ResponseDTO.ok(userBalanceDTO);

10
agileboot-domain/src/main/java/com/agileboot/domain/ab98/user_balance/db/UserBalanceServiceImpl.java
View File

@ -39,9 +39,19 @@ public class UserBalanceServiceImpl extends ServiceImpl<UserBalanceMapper, UserB
if (existing != null) {
// 更新
entity.setUserBalanceId(existing.getUserBalanceId());
if (entity.getBalanceLimit() != null) {
if (entity.getUseBalance() != null) {
entity.setBalance(entity.getBalanceLimit() - entity.getUseBalance());
} else {
entity.setBalance(entity.getBalanceLimit() - existing.getUseBalance());
}
}
return updateById(entity);
} else {
// 插入
if (entity.getBalanceLimit() != null) {
entity.setBalance(entity.getBalanceLimit());
}
return save(entity);
}
}

522
doc/UserBalanceController接口文档.md Normal file
View File

@ -0,0 +1,522 @@
# 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

4
sql/20251124_user_balance.sql
View File

@ -11,9 +11,13 @@ CREATE TABLE `user_balance` (
`create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
`updater_id` bigint NULL DEFAULT 0 COMMENT '更新者ID',
`update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
`deleted` tinyint(1) NOT NULL DEFAULT '0' COMMENT '删除标志（0存在 1删除）',
PRIMARY KEY (`user_balance_id`),
KEY `idx_openid` (`openid`),
KEY `idx_ab98_user_id` (`ab98_user_id`),
KEY `idx_corpid` (`corpid`),
UNIQUE KEY `uk_corpid_user` (`corpid`, `ab98_user_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户余额表';
-- 添加 deleted 字段的 ALTER 语句
ALTER TABLE `user_balance` ADD COLUMN `deleted` tinyint(1) NOT NULL DEFAULT '0' COMMENT '删除标志（0存在 1删除）';