feat(controller): 新增柜机格口操作API控制器
refactor(docs): 删除旧的商品管理和用户余额接口文档 新增CabinetCellOperationApiController控制器，提供柜机格口操作的增删改查功能 同时清理了不再使用的ManageGoodsController和UserBalanceController接口文档
This commit is contained in:
dzq
parent
7cc0674b90
commit
407bdadf6f
|
|
@ -0,0 +1,66 @@
|
||||||
|
package com.agileboot.api.controller.manage;
|
||||||
|
|
||||||
|
import com.agileboot.common.core.dto.ResponseDTO;
|
||||||
|
import com.agileboot.common.core.page.PageDTO;
|
||||||
|
import com.agileboot.domain.common.command.BulkOperationCommand;
|
||||||
|
import com.agileboot.domain.cabinet.operation.CabinetCellOperationApplicationService;
|
||||||
|
import com.agileboot.domain.cabinet.operation.command.AddCabinetCellOperationCommand;
|
||||||
|
import com.agileboot.domain.cabinet.operation.command.UpdateCabinetCellOperationCommand;
|
||||||
|
import com.agileboot.domain.cabinet.operation.db.CabinetCellOperationEntity;
|
||||||
|
import com.agileboot.domain.cabinet.operation.dto.CabinetCellOperationDTO;
|
||||||
|
import com.agileboot.domain.cabinet.operation.query.SearchCabinetCellOperationDetailQuery;
|
||||||
|
import com.agileboot.domain.cabinet.operation.query.SearchCabinetCellOperationQuery;
|
||||||
|
import io.swagger.v3.oas.annotations.Operation;
|
||||||
|
import lombok.RequiredArgsConstructor;
|
||||||
|
import lombok.extern.slf4j.Slf4j;
|
||||||
|
import org.springframework.validation.annotation.Validated;
|
||||||
|
import org.springframework.web.bind.annotation.*;
|
||||||
|
|
||||||
|
import javax.validation.constraints.NotNull;
|
||||||
|
import java.util.List;
|
||||||
|
|
||||||
|
@Slf4j
|
||||||
|
@RestController
|
||||||
|
@CrossOrigin(origins = "*", allowedHeaders = "*")
|
||||||
|
@RequiredArgsConstructor
|
||||||
|
@RequestMapping("/api/manage/cellOperations")
|
||||||
|
public class CabinetCellOperationApiController {
|
||||||
|
|
||||||
|
private final CabinetCellOperationApplicationService cabinetCellOperationService;
|
||||||
|
|
||||||
|
@Operation(summary = "柜机格口操作列表")
|
||||||
|
@GetMapping("/list")
|
||||||
|
public ResponseDTO<PageDTO<CabinetCellOperationDTO>> list(SearchCabinetCellOperationQuery<CabinetCellOperationEntity> query) {
|
||||||
|
PageDTO<CabinetCellOperationDTO> page = cabinetCellOperationService.getCabinetCellOperationList(query);
|
||||||
|
return ResponseDTO.ok(page);
|
||||||
|
}
|
||||||
|
|
||||||
|
@Operation(summary = "柜机格口操作详情列表")
|
||||||
|
@PostMapping("/page")
|
||||||
|
public ResponseDTO<PageDTO<CabinetCellOperationDTO>> listDetail(SearchCabinetCellOperationDetailQuery query) {
|
||||||
|
PageDTO<CabinetCellOperationDTO> page = cabinetCellOperationService.getOperationDetailList(query);
|
||||||
|
return ResponseDTO.ok(page);
|
||||||
|
}
|
||||||
|
|
||||||
|
@Operation(summary = "新增柜机格口操作")
|
||||||
|
@PostMapping
|
||||||
|
public ResponseDTO<Void> add(@Validated @RequestBody AddCabinetCellOperationCommand command) {
|
||||||
|
cabinetCellOperationService.addCabinetCellOperation(command);
|
||||||
|
return ResponseDTO.ok();
|
||||||
|
}
|
||||||
|
|
||||||
|
@Operation(summary = "修改柜机格口操作")
|
||||||
|
@PutMapping("/{operationId}")
|
||||||
|
public ResponseDTO<Void> edit(@PathVariable Long operationId, @Validated @RequestBody UpdateCabinetCellOperationCommand command) {
|
||||||
|
command.setOperationId(operationId);
|
||||||
|
cabinetCellOperationService.updateCabinetCellOperation(command);
|
||||||
|
return ResponseDTO.ok();
|
||||||
|
}
|
||||||
|
|
||||||
|
@Operation(summary = "删除柜机格口操作")
|
||||||
|
@DeleteMapping("/{ids}")
|
||||||
|
public ResponseDTO<Void> remove(@PathVariable @NotNull List<Long> ids) {
|
||||||
|
cabinetCellOperationService.deleteCabinetCellOperation(new BulkOperationCommand<>(ids));
|
||||||
|
return ResponseDTO.ok();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
@ -1,295 +0,0 @@
|
||||||
# ManageGoodsController 接口文档
|
|
||||||
|
|
||||||
## 控制器概述
|
|
||||||
|
|
||||||
**基础路径：** `/api/manage/goods`
|
|
||||||
|
|
||||||
**控制器类：** `com.agileboot.api.controller.manage.ManageGoodsController`
|
|
||||||
|
|
||||||
**功能描述：** 商品管理接口，提供商品的增删改查功能。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 接口列表
|
|
||||||
|
|
||||||
### 1. 获取商品列表
|
|
||||||
|
|
||||||
**接口路径：** `GET /api/manage/goods/list`
|
|
||||||
|
|
||||||
**功能描述：** 分页查询商品列表，支持多条件筛选和排序。
|
|
||||||
|
|
||||||
**请求参数：**
|
|
||||||
|
|
||||||
| 参数名 | 类型 | 必填 | 描述 | 示例 |
|
|
||||||
|--------|------|------|------|------|
|
|
||||||
| `pageNum` | Integer | 否 | 页码，默认1，最大值200 | `1` |
|
|
||||||
| `pageSize` | Integer | 否 | 每页大小，默认10，最大值500 | `10` |
|
|
||||||
| `orderColumn` | String | 否 | 排序字段 | `"createTime"` |
|
|
||||||
| `orderDirection` | String | 否 | 排序方向：`"ascending"`(升序) 或 `"descending"`(降序) | `"descending"` |
|
|
||||||
| `beginTime` | Date | 否 | 开始时间（格式：yyyy-MM-dd） | `"2025-01-01"` |
|
|
||||||
| `endTime` | Date | 否 | 结束时间（格式：yyyy-MM-dd） | `"2025-12-31"` |
|
|
||||||
| `goodsName` | String | 否 | 商品名称（模糊查询） | `"测试商品"` |
|
|
||||||
| `categoryId` | Long | 否 | 商品分类ID | `1` |
|
|
||||||
| `externalGoodsId` | Long | 否 | 外部归属类型的商品ID | `1001` |
|
|
||||||
| `corpid` | String | 否 | 企业微信id | `"wxcorpid123"` |
|
|
||||||
| `status` | Integer | 否 | 商品状态（1上架 2下架） | `1` |
|
|
||||||
| `autoApproval` | Integer | 否 | 免审批（0否 1是） | `1` |
|
|
||||||
| `minPrice` | BigDecimal | 否 | 最低价格 | `10.00` |
|
|
||||||
| `maxPrice` | BigDecimal | 否 | 最高价格 | `100.00` |
|
|
||||||
| `belongType` | Integer | 否 | 归属类型（0-借还柜 1-固资通） | `0` |
|
|
||||||
|
|
||||||
**返回类型：** `ResponseDTO<PageDTO<ShopGoodsDTO>>`
|
|
||||||
|
|
||||||
**响应字段：**
|
|
||||||
|
|
||||||
`ResponseDTO` 通用结构：
|
|
||||||
- `code`: Integer - 响应码
|
|
||||||
- `msg`: String - 响应消息
|
|
||||||
- `data`: `PageDTO<ShopGoodsDTO>` - 分页数据
|
|
||||||
|
|
||||||
`PageDTO` 分页结构：
|
|
||||||
- `total`: Long - 总记录数
|
|
||||||
- `rows`: `List<ShopGoodsDTO>` - 当前页数据列表
|
|
||||||
|
|
||||||
`ShopGoodsDTO` 商品详情字段：
|
|
||||||
|
|
||||||
| 字段名 | 类型 | 描述 |
|
|
||||||
|--------|------|------|
|
|
||||||
| `goodsId` | Long | 商品唯一ID |
|
|
||||||
| `goodsName` | String | 商品名称 |
|
|
||||||
| `categoryId` | Long | 分类ID |
|
|
||||||
| `externalGoodsId` | Long | 外部商品ID |
|
|
||||||
| `corpid` | String | 企业微信id |
|
|
||||||
| `categoryName` | String | 分类名称 |
|
|
||||||
| `belongType` | Long | 归属类型（0-借还柜 1-固资通） |
|
|
||||||
| `price` | BigDecimal | 销售价格 |
|
|
||||||
| `stock` | Integer | 库存数量 |
|
|
||||||
| `status` | Integer | 商品状态（1上架 2下架） |
|
|
||||||
| `autoApproval` | Integer | 免审批（0否 1是） |
|
|
||||||
| `coverImg` | String | 封面图URL |
|
|
||||||
| `creatorId` | Long | 创建者ID |
|
|
||||||
| `creatorName` | String | 创建者名称 |
|
|
||||||
| `createTime` | Date | 创建时间 |
|
|
||||||
| `remark` | String | 备注 |
|
|
||||||
| `cabinetName` | String | 柜机名称 |
|
|
||||||
| `cellNo` | Integer | 格口号 |
|
|
||||||
| `cellNoStr` | String | 格口号（字符串格式） |
|
|
||||||
| `totalStock` | Integer | 已分配库存 |
|
|
||||||
| `shopNameStr` | String | 地址名称 |
|
|
||||||
| `usageInstruction` | String | 商品使用说明 |
|
|
||||||
| `monthlyPurchaseLimit` | Integer | 每人每月限购数量 |
|
|
||||||
|
|
||||||
**示例请求：**
|
|
||||||
```
|
|
||||||
GET /api/manage/goods/list?pageNum=1&pageSize=10&status=1&goodsName=测试
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 2. 新增商品
|
|
||||||
|
|
||||||
**接口路径：** `POST /api/manage/goods`
|
|
||||||
|
|
||||||
**功能描述：** 创建新商品。
|
|
||||||
|
|
||||||
**请求体类型：** `AddGoodsCommand` (继承自 `ShopGoodsEntity`)
|
|
||||||
|
|
||||||
**请求字段：**
|
|
||||||
|
|
||||||
| 字段名 | 类型 | 必填 | 描述 | 示例 |
|
|
||||||
|--------|------|------|------|------|
|
|
||||||
| `goodsName` | String | 是 | 商品名称 | `"测试商品"` |
|
|
||||||
| `categoryId` | Long | 否 | 商品分类ID | `1` |
|
|
||||||
| `externalGoodsId` | Long | 否 | 外部归属类型的商品ID | `1001` |
|
|
||||||
| `corpid` | String | 否 | 企业微信id | `"wxcorpid123"` |
|
|
||||||
| `monthlyPurchaseLimit` | Integer | 否 | 每人每月限购数量 | `5` |
|
|
||||||
| `price` | BigDecimal | 是 | 销售价格 | `99.99` |
|
|
||||||
| `stock` | Integer | 否 | 库存数量 | `100` |
|
|
||||||
| `status` | Integer | 否 | 商品状态（1上架 2下架），默认值需确认 | `1` |
|
|
||||||
| `autoApproval` | Integer | 否 | 免审批（0否 1是），默认值需确认 | `0` |
|
|
||||||
| `coverImg` | String | 否 | 封面图URL | `"https://example.com/image.jpg"` |
|
|
||||||
| `goodsDetail` | String | 否 | 商品详情（支持2000汉字+10个图片链接） | `"<p>商品描述</p>"` |
|
|
||||||
| `remark` | String | 否 | 备注 | `"测试商品备注"` |
|
|
||||||
| `usageInstruction` | String | 否 | 商品使用说明 | `"使用说明内容"` |
|
|
||||||
| `belongType` | Integer | 否 | 归属类型（0-借还柜 1-固资通） | `0` |
|
|
||||||
|
|
||||||
**注意：** `goodsId` 字段为自增主键，请求时无需提供。
|
|
||||||
|
|
||||||
**返回类型：** `ResponseDTO<Void>`
|
|
||||||
|
|
||||||
**响应字段：**
|
|
||||||
- `code`: Integer - 响应码
|
|
||||||
- `msg`: String - 响应消息
|
|
||||||
- `data`: null
|
|
||||||
|
|
||||||
**示例请求：**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"goodsName": "测试商品",
|
|
||||||
"price": 99.99,
|
|
||||||
"stock": 100,
|
|
||||||
"status": 1,
|
|
||||||
"coverImg": "https://example.com/image.jpg"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 3. 删除商品
|
|
||||||
|
|
||||||
**接口路径：** `DELETE /api/manage/goods/{goodsIds}`
|
|
||||||
|
|
||||||
**功能描述：** 批量删除商品。
|
|
||||||
|
|
||||||
**路径参数：**
|
|
||||||
- `goodsIds`: 商品ID列表，多个ID用逗号分隔
|
|
||||||
|
|
||||||
**请求示例：**
|
|
||||||
```
|
|
||||||
DELETE /api/manage/goods/1,2,3
|
|
||||||
```
|
|
||||||
|
|
||||||
**内部处理：** 控制器将路径参数转换为 `BulkOperationCommand<Long>` 对象：
|
|
||||||
```java
|
|
||||||
{
|
|
||||||
"ids": [1, 2, 3] // Set<Long> 类型，自动去重
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**返回类型：** `ResponseDTO<Void>`
|
|
||||||
|
|
||||||
**响应字段：**
|
|
||||||
- `code`: Integer - 响应码
|
|
||||||
- `msg`: String - 响应消息
|
|
||||||
- `data`: null
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 4. 修改商品
|
|
||||||
|
|
||||||
**接口路径：** `PUT /api/manage/goods/{goodsId}`
|
|
||||||
|
|
||||||
**功能描述：** 更新商品信息。
|
|
||||||
|
|
||||||
**路径参数：**
|
|
||||||
- `goodsId`: 商品ID
|
|
||||||
|
|
||||||
**请求体类型：** `UpdateGoodsCommand` (继承自 `AddGoodsCommand`)
|
|
||||||
|
|
||||||
**请求字段：** 与 `AddGoodsCommand` 相同，所有字段均为可选更新。
|
|
||||||
|
|
||||||
**特殊处理：** 接口会自动将路径参数中的 `goodsId` 设置到 command 对象中。
|
|
||||||
|
|
||||||
**返回类型：** `ResponseDTO<Void>`
|
|
||||||
|
|
||||||
**响应字段：**
|
|
||||||
- `code`: Integer - 响应码
|
|
||||||
- `msg`: String - 响应消息
|
|
||||||
- `data`: null
|
|
||||||
|
|
||||||
**示例请求：**
|
|
||||||
```
|
|
||||||
PUT /api/manage/goods/1
|
|
||||||
```
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"goodsName": "更新后的商品名称",
|
|
||||||
"price": 88.88
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 5. 获取单个商品信息
|
|
||||||
|
|
||||||
**接口路径：** `GET /api/manage/goods/getGoodsInfo`
|
|
||||||
|
|
||||||
**功能描述：** 根据商品ID获取单个商品的详细信息。
|
|
||||||
|
|
||||||
**查询参数：**
|
|
||||||
|
|
||||||
| 参数名 | 类型 | 必填 | 描述 | 示例 |
|
|
||||||
|--------|------|------|------|------|
|
|
||||||
| `goodsId` | Long | 是 | 商品ID | `1` |
|
|
||||||
|
|
||||||
**返回类型：** `ResponseDTO<ShopGoodsDTO>`
|
|
||||||
|
|
||||||
**响应字段：**
|
|
||||||
- `code`: Integer - 响应码
|
|
||||||
- `msg`: String - 响应消息
|
|
||||||
- `data`: `ShopGoodsDTO` - 商品详情（字段同接口1）
|
|
||||||
|
|
||||||
**示例请求：**
|
|
||||||
```
|
|
||||||
GET /api/manage/goods/getGoodsInfo?goodsId=1
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 通用数据结构
|
|
||||||
|
|
||||||
### ResponseDTO 通用响应结构
|
|
||||||
```java
|
|
||||||
public class ResponseDTO<T> {
|
|
||||||
private Integer code; // 响应码
|
|
||||||
private String msg; // 响应消息
|
|
||||||
private T data; // 响应数据
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### PageDTO 分页结构
|
|
||||||
```java
|
|
||||||
public class PageDTO<T> {
|
|
||||||
private Long total; // 总记录数
|
|
||||||
private List<T> rows; // 当前页数据列表
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### BulkOperationCommand 批量操作命令
|
|
||||||
```java
|
|
||||||
public class BulkOperationCommand<T> {
|
|
||||||
private Set<T> ids; // 操作ID集合（自动去重）
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 注意事项
|
|
||||||
|
|
||||||
1. **字段默认值：** 部分字段（如 `status`, `autoApproval`）的默认值需查看业务逻辑确认
|
|
||||||
2. **ID 生成：** `goodsId` 为数据库自增字段，创建时无需提供
|
|
||||||
3. **批量删除：** 删除接口支持批量操作，ID列表会自动去重
|
|
||||||
4. **分页限制：** 最大页码200，每页最大大小500
|
|
||||||
5. **时间格式：** 时间参数需使用 `yyyy-MM-dd` 格式
|
|
||||||
6. **企业微信集成：** `corpid` 字段用于企业微信多租户支持
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 相关实体类位置
|
|
||||||
|
|
||||||
| 类名 | 路径 |
|
|
||||||
|------|------|
|
|
||||||
| `ManageGoodsController` | `agileboot-api/src/main/java/com/agileboot/api/controller/manage/` |
|
|
||||||
| `ShopGoodsEntity` | `agileboot-domain/src/main/java/com/agileboot/domain/shop/goods/db/` |
|
|
||||||
| `AddGoodsCommand` | `agileboot-domain/src/main/java/com/agileboot/domain/shop/goods/command/` |
|
|
||||||
| `UpdateGoodsCommand` | `agileboot-domain/src/main/java/com/agileboot/domain/shop/goods/command/` |
|
|
||||||
| `ShopGoodsDTO` | `agileboot-domain/src/main/java/com/agileboot/domain/shop/goods/dto/` |
|
|
||||||
| `SearchShopGoodsQuery` | `agileboot-domain/src/main/java/com/agileboot/domain/shop/goods/query/` |
|
|
||||||
| `BulkOperationCommand` | `agileboot-domain/src/main/java/com/agileboot/domain/common/command/` |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 架构设计说明
|
|
||||||
|
|
||||||
本控制器遵循项目的 **DDD/CQRS 架构**：
|
|
||||||
|
|
||||||
- **查询操作**（GET）：使用 `SearchShopGoodsQuery` 对象，通过 `GoodsApplicationService.getGoodsList()` 处理
|
|
||||||
- **命令操作**（POST/PUT/DELETE）：使用 `AddGoodsCommand`/`UpdateGoodsCommand`/`BulkOperationCommand`，通过 `GoodsApplicationService` 的对应方法处理
|
|
||||||
- **数据流转**：Controller → Command/Query → ApplicationService → Domain Model → DB Entity
|
|
||||||
|
|
||||||
**注意**：`AddGoodsCommand` 和 `UpdateGoodsCommand` 都继承自 `ShopGoodsEntity`，因此共享相同的字段定义。在实际使用中，`goodsId` 字段在新增时由数据库自增生成，在更新时通过路径参数传入。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
*文档生成时间：2025-12-11*
|
|
||||||
*基于代码分析：`agileboot-api/src/main/java/com/agileboot/api/controller/manage/ManageGoodsController.java`*
|
|
||||||
|
|
@ -1,522 +0,0 @@
|
||||||
# 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
|
|
||||||
Loading…
Reference in New Issue