diff --git a/agileboot-api/src/main/java/com/agileboot/api/controller/manage/CabinetCellOperationApiController.java b/agileboot-api/src/main/java/com/agileboot/api/controller/manage/CabinetCellOperationApiController.java new file mode 100644 index 0000000..66afc56 --- /dev/null +++ b/agileboot-api/src/main/java/com/agileboot/api/controller/manage/CabinetCellOperationApiController.java @@ -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> list(SearchCabinetCellOperationQuery query) { + PageDTO page = cabinetCellOperationService.getCabinetCellOperationList(query); + return ResponseDTO.ok(page); + } + + @Operation(summary = "柜机格口操作详情列表") + @PostMapping("/page") + public ResponseDTO> listDetail(SearchCabinetCellOperationDetailQuery query) { + PageDTO page = cabinetCellOperationService.getOperationDetailList(query); + return ResponseDTO.ok(page); + } + + @Operation(summary = "新增柜机格口操作") + @PostMapping + public ResponseDTO add(@Validated @RequestBody AddCabinetCellOperationCommand command) { + cabinetCellOperationService.addCabinetCellOperation(command); + return ResponseDTO.ok(); + } + + @Operation(summary = "修改柜机格口操作") + @PutMapping("/{operationId}") + public ResponseDTO edit(@PathVariable Long operationId, @Validated @RequestBody UpdateCabinetCellOperationCommand command) { + command.setOperationId(operationId); + cabinetCellOperationService.updateCabinetCellOperation(command); + return ResponseDTO.ok(); + } + + @Operation(summary = "删除柜机格口操作") + @DeleteMapping("/{ids}") + public ResponseDTO remove(@PathVariable @NotNull List ids) { + cabinetCellOperationService.deleteCabinetCellOperation(new BulkOperationCommand<>(ids)); + return ResponseDTO.ok(); + } +} diff --git a/doc/ManageGoodsController接口文档.md b/doc/ManageGoodsController接口文档.md deleted file mode 100644 index a7dfab7..0000000 --- a/doc/ManageGoodsController接口文档.md +++ /dev/null @@ -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>` - -**响应字段：** - -`ResponseDTO` 通用结构： -- `code`: Integer - 响应码 -- `msg`: String - 响应消息 -- `data`: `PageDTO` - 分页数据 - -`PageDTO` 分页结构： -- `total`: Long - 总记录数 -- `rows`: `List` - 当前页数据列表 - -`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个图片链接） | `"

商品描述

"` | -| `remark` | String | 否 | 备注 | `"测试商品备注"` | -| `usageInstruction` | String | 否 | 商品使用说明 | `"使用说明内容"` | -| `belongType` | Integer | 否 | 归属类型（0-借还柜 1-固资通） | `0` | - -**注意：** `goodsId` 字段为自增主键，请求时无需提供。 - -**返回类型：** `ResponseDTO` - -**响应字段：** -- `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` 对象： -```java -{ - "ids": [1, 2, 3] // Set 类型，自动去重 -} -``` - -**返回类型：** `ResponseDTO` - -**响应字段：** -- `code`: Integer - 响应码 -- `msg`: String - 响应消息 -- `data`: null - ---- - -### 4. 修改商品 - -**接口路径：** `PUT /api/manage/goods/{goodsId}` - -**功能描述：** 更新商品信息。 - -**路径参数：** -- `goodsId`: 商品ID - -**请求体类型：** `UpdateGoodsCommand` (继承自 `AddGoodsCommand`) - -**请求字段：** 与 `AddGoodsCommand` 相同，所有字段均为可选更新。 - -**特殊处理：** 接口会自动将路径参数中的 `goodsId` 设置到 command 对象中。 - -**返回类型：** `ResponseDTO` - -**响应字段：** -- `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` - -**响应字段：** -- `code`: Integer - 响应码 -- `msg`: String - 响应消息 -- `data`: `ShopGoodsDTO` - 商品详情（字段同接口1） - -**示例请求：** -``` -GET /api/manage/goods/getGoodsInfo?goodsId=1 -``` - ---- - -## 通用数据结构 - -### ResponseDTO 通用响应结构 -```java -public class ResponseDTO { - private Integer code; // 响应码 - private String msg; // 响应消息 - private T data; // 响应数据 -} -``` - -### PageDTO 分页结构 -```java -public class PageDTO { - private Long total; // 总记录数 - private List rows; // 当前页数据列表 -} -``` - -### BulkOperationCommand 批量操作命令 -```java -public class BulkOperationCommand { - private Set 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`* \ No newline at end of file diff --git a/doc/UserBalanceController接口文档.md b/doc/UserBalanceController接口文档.md deleted file mode 100644 index 69db47f..0000000 --- a/doc/UserBalanceController接口文档.md +++ /dev/null @@ -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>` - -**成功响应示例**: -```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` - -**成功响应示例**: -```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` - -**成功响应示例**: -```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` - -**成功响应示例**: -```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` - -**成功响应示例**: -```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` - -**成功响应示例**: -```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` - -**操作日志**: 记录删除操作 - ---- - -### 8. 批量删除用户余额 - -**接口地址**: `DELETE /ab98/balance/batch/{ids}` - -**接口描述**: 批量删除用户余额记录 - -**路径参数**: - -| 参数名 | 类型 | 是否必填 | 描述 | 示例 | -|--------|------|----------|------|------| -| ids | List | 是 | 主键ID列表 | 1,2,3 | - -**返回结果**: `ResponseDTO` - -**操作日志**: 记录删除操作 - ---- - -### 9. 增加用户余额 - -**接口地址**: `POST /ab98/balance/addBalance` - -**接口描述**: 增加用户余额 - -**请求体** (JSON对象): - -| 参数名 | 类型 | 是否必填 | 描述 | 备注 | -|--------|------|----------|------|------| -| corpid | String | 是 | 企业微信ID | 不能为空 | -| ab98UserId | Long | 是 | 汇邦云用户ID | 不能为空 | -| amount | Long | 是 | 增加金额(分) | 金额单位为分，不能为空 | - -**请求示例**: -```json -{ - "corpid": "ww1234567890", - "ab98UserId": 10001, - "amount": 10000 -} -``` - -**返回结果**: `ResponseDTO` - -**成功响应示例**: -```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` - -**成功响应示例**: -```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` - -**成功响应示例**: -```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