521 lines
14 KiB
Markdown
521 lines
14 KiB
Markdown
# 商品寄卖服务系统管理后台接口实现说明
|
||
|
||
## 实现概述
|
||
|
||
本文档说明了在`crmeb-admin`模块中完成的商品寄卖服务系统管理后台API接口的实现情况。
|
||
|
||
**实现时间**：2025-11-14
|
||
**实现模块**：crmeb-admin
|
||
**API路径前缀**：`/app/admin`
|
||
|
||
---
|
||
|
||
## 一、已创建文件清单
|
||
|
||
### 1.1 Request类（请求对象）
|
||
|
||
位置：`crmeb-common/src/main/java/com/zbkj/common/request/`
|
||
|
||
| 文件名 | 说明 | 用途 |
|
||
|--------|------|------|
|
||
| WaMerchandiseSearchRequest.java | 寄售商品查询请求 | 寄售商品列表查询 |
|
||
| WaMerchandiseUpdateRequest.java | 寄售商品更新请求 | 更新寄售商品信息 |
|
||
| WaOrderSearchRequest.java | 订单查询请求 | 订单列表查询 |
|
||
| WaOrderUpdateRequest.java | 订单更新请求 | 更新订单信息 |
|
||
| WaWithdrawSearchRequest.java | 提现查询请求 | 提现列表查询 |
|
||
| WaWithdrawAuditRequest.java | 提现审核请求 | 审核提现申请 |
|
||
| WaFinanceLogSearchRequest.java | 财务日志查询请求 | 财务日志查询 |
|
||
|
||
### 1.2 Response类（响应对象）
|
||
|
||
位置：`crmeb-common/src/main/java/com/zbkj/common/response/`
|
||
|
||
| 文件名 | 说明 | 用途 |
|
||
|--------|------|------|
|
||
| WaMerchandiseResponse.java | 寄售商品响应 | 返回寄售商品信息 |
|
||
| WaOrderResponse.java | 订单响应 | 返回订单信息 |
|
||
| WaWithdrawResponse.java | 提现响应 | 返回提现信息 |
|
||
| WaFinanceLogResponse.java | 财务日志响应 | 返回财务日志信息 |
|
||
|
||
### 1.3 Service接口
|
||
|
||
位置：`crmeb-service/src/main/java/com/zbkj/service/service/`
|
||
|
||
| 文件名 | 说明 | 方法数 |
|
||
|--------|------|--------|
|
||
| WaMerchandiseService.java | 寄售商品服务接口 | 3个 |
|
||
| WaOrderAdminService.java | 订单管理服务接口 | 3个 |
|
||
| WaWithdrawService.java | 提现服务接口 | 3个 |
|
||
| WaFinanceLogService.java | 财务日志服务接口 | 3个 |
|
||
|
||
### 1.4 Service实现类
|
||
|
||
位置：`crmeb-service/src/main/java/com/zbkj/service/service/impl/`
|
||
|
||
| 文件名 | 说明 |
|
||
|--------|------|
|
||
| WaMerchandiseServiceImpl.java | 寄售商品服务实现 |
|
||
| WaOrderAdminServiceImpl.java | 订单管理服务实现 |
|
||
| WaWithdrawServiceImpl.java | 提现服务实现 |
|
||
| WaFinanceLogServiceImpl.java | 财务日志服务实现 |
|
||
|
||
### 1.5 Controller类（控制器）
|
||
|
||
位置：`crmeb-admin/src/main/java/com/zbkj/admin/controller/`
|
||
|
||
| 文件名 | 说明 | 路由前缀 | 接口数 |
|
||
|--------|------|----------|--------|
|
||
| WaMerchandiseController.java | 寄售商品管理控制器 | /app/admin/merchandise | 2个 |
|
||
| WaOrderAdminController.java | 订单管理控制器 | /app/admin/order | 2个 |
|
||
| WaWithdrawController.java | 提现管理控制器 | /app/admin/withdraw | 2个 |
|
||
| WaFinanceLogController.java | 财务日志管理控制器 | /app/admin/*-log | 3个 |
|
||
|
||
---
|
||
|
||
## 二、API接口详细列表
|
||
|
||
### 2.1 寄售商品管理接口（2个）
|
||
|
||
| 接口 | 路径 | 方法 | 说明 | 权限 |
|
||
|------|------|------|------|------|
|
||
| 寄售商品查询 | /app/admin/merchandise/select | GET | 查询寄售商品（列表/详情） | admin:merchandise:select |
|
||
| 更新寄售商品 | /app/admin/merchandise/update | POST | 更新寄售商品信息（审核、上下架） | admin:merchandise:update |
|
||
|
||
**查询条件支持**：
|
||
- 商品ID（精确查询，传入id参数时返回详情）
|
||
- 卖家用户ID
|
||
- 商品标题（模糊查询）
|
||
- 状态（0=已售，1=未售）
|
||
- 是否显示（0=隐藏，1=显示）
|
||
- 时间范围查询
|
||
|
||
**说明**：列表和详情共用同一个`/select`接口，通过是否传入`id`参数区分。
|
||
|
||
### 2.2 订单管理接口（2个）
|
||
|
||
| 接口 | 路径 | 方法 | 说明 | 权限 |
|
||
|------|------|------|------|------|
|
||
| 订单查询 | /app/admin/order/select | GET | 查询订单（列表/详情） | admin:order:select |
|
||
| 更新订单 | /app/admin/order/update | POST | 更新订单状态 | admin:order:update |
|
||
|
||
**查询条件支持**：
|
||
- 订单ID（精确查询，传入id参数时返回详情）
|
||
- 订单号（模糊查询）
|
||
- 卖家ID
|
||
- 买家ID
|
||
- 订单状态（0=待付款，1=已支付，2=已完成）
|
||
- 是否转拍（0=否，1=是）
|
||
- 是否取消（0=否，1=是）
|
||
- 是否显示（0=隐藏，1=显示）
|
||
- 购买时间范围
|
||
- 确认时间范围
|
||
|
||
**说明**：列表和详情共用同一个`/select`接口，通过是否传入`id`参数区分。
|
||
|
||
### 2.3 提现管理接口（2个）
|
||
|
||
| 接口 | 路径 | 方法 | 说明 | 权限 |
|
||
|------|------|------|------|------|
|
||
| 提现查询 | /app/admin/withdraw/select | GET | 查询提现申请（列表/详情） | admin:withdraw:select |
|
||
| 审核提现 | /app/admin/withdraw/update | POST | 审核提现申请（通过/驳回） | admin:withdraw:update |
|
||
|
||
**查询条件支持**：
|
||
- 提现记录ID（精确查询，传入id参数时返回详情）
|
||
- 提现编号（模糊查询）
|
||
- 用户ID
|
||
- 提现类型（2=优惠券，4=推广奖金）
|
||
- 账号类型（1=银行卡，2=支付宝）
|
||
- 状态（0=待审核，1=通过，2=驳回）
|
||
- 申请时间范围
|
||
- 处理时间范围
|
||
|
||
**说明**：列表和详情共用同一个`/select`接口，通过是否传入`id`参数区分。
|
||
|
||
**审核功能**：
|
||
- 驳回时自动返还金额到用户对应账户
|
||
- 记录审核备注
|
||
|
||
### 2.4 财务日志管理接口（3个）
|
||
|
||
| 接口 | 路径 | 方法 | 说明 | 权限 |
|
||
|------|------|------|------|------|
|
||
| 优惠券日志查询 | /app/admin/coupon-log/select | GET | 查询优惠券变动日志 | admin:coupon-log:select |
|
||
| 个人奖金日志查询 | /app/admin/selfbonus-log/select | GET | 查询个人奖金变动日志 | admin:selfbonus-log:select |
|
||
| 推广奖金日志查询 | /app/admin/sharebonus-log/select | GET | 查询推广奖金变动日志 | admin:sharebonus-log:select |
|
||
|
||
**查询条件支持**：
|
||
- 用户ID
|
||
- 类型（1=收入，2=支出，3=提现驳回）
|
||
- 备注内容（模糊查询）
|
||
- 时间范围查询
|
||
|
||
---
|
||
|
||
## 三、核心业务逻辑说明
|
||
|
||
### 3.1 寄售商品管理
|
||
|
||
**业务流程**：
|
||
1. 用户在前端提交寄售商品申请
|
||
2. 管理员在后台查看寄售商品列表
|
||
3. 管理员审核商品（设置`is_show=1`显示，或`is_show=0`隐藏）
|
||
4. 审核通过后商品上架展示
|
||
5. 管理员可随时上下架商品
|
||
|
||
**关键字段**：
|
||
- `is_show`: 是否显示（0=隐藏，1=显示）
|
||
- `status`: 状态（0=已售，1=未售）
|
||
- `price`: 寄售价格
|
||
|
||
### 3.2 订单管理
|
||
|
||
**业务流程**：
|
||
1. 买家下单抢购商品
|
||
2. 买家支付订单
|
||
3. 卖家发货
|
||
4. 买家确认收货
|
||
5. 订单完成
|
||
|
||
**管理功能**：
|
||
- 查看所有订单（自营+寄售）
|
||
- 查看订单详情
|
||
- 修改订单状态
|
||
- 隐藏/显示订单
|
||
|
||
### 3.3 提现审核
|
||
|
||
**审核流程**：
|
||
1. 用户提交提现申请（系统自动扣除相应账户余额）
|
||
2. 管理员审核提现申请
|
||
3. 审核通过：标记状态为1，资金打款到用户账户
|
||
4. 审核驳回：标记状态为2，系统自动返还金额到用户对应账户
|
||
|
||
**驳回逻辑**：
|
||
- 提现类型为2（优惠券）：返还到`coupon`账户
|
||
- 提现类型为4（推广奖金）：返还到`share_bonus`账户
|
||
- 记录财务日志（type=3，提现驳回）
|
||
|
||
### 3.4 财务日志查询
|
||
|
||
**日志类型**：
|
||
- **优惠券日志**（wa_coupon_log）：记录优惠券的发放、使用、退回
|
||
- **个人奖金日志**（wa_selfbonus_log）：记录个人交易奖励
|
||
- **推广奖金日志**（wa_sharebonus_log）：记录推广返佣
|
||
|
||
**日志字段**：
|
||
- `type`: 1=收入，2=支出，3=提现驳回
|
||
- `money`: 变更金额
|
||
- `before`: 变更前余额
|
||
- `after`: 变更后余额
|
||
- `memo`: 备注说明
|
||
|
||
---
|
||
|
||
## 四、技术实现说明
|
||
|
||
### 4.1 技术栈
|
||
|
||
- **框架**：Spring Boot
|
||
- **ORM**：MyBatis Plus
|
||
- **分页**：PageHelper
|
||
- **安全**：Spring Security
|
||
- **API文档**：Swagger
|
||
- **数据验证**：Hibernate Validator
|
||
|
||
### 4.2 设计模式
|
||
|
||
- 标准三层架构：Controller -> Service -> Dao
|
||
- RESTful API规范
|
||
- 统一响应格式：`CommonResult<T>`
|
||
- 权限注解：`@PreAuthorize`
|
||
- 参数校验：`@Validated`
|
||
|
||
### 4.3 分页查询
|
||
|
||
使用`PageHelper`插件实现分页：
|
||
```java
|
||
PageHelper.startPage(pageParamRequest.getPage(), pageParamRequest.getLimit());
|
||
List<Entity> list = dao.selectList(wrapper);
|
||
return CommonPage.restPage(new PageInfo<>(list));
|
||
```
|
||
|
||
### 4.4 数据关联
|
||
|
||
**用户信息关联**：
|
||
- 寄售商品关联卖家用户信息（`username`）
|
||
- 订单关联买家和卖家信息（`buyer_name`, `seller_name`）
|
||
- 提现记录关联用户信息（`username`, `mobile`）
|
||
- 财务日志关联用户信息（`username`, `mobile`）
|
||
|
||
**实现方式**：
|
||
- 查询列表时通过`WaUsersDao`关联查询用户信息
|
||
- 使用Stream API转换为Response对象
|
||
|
||
---
|
||
|
||
## 五、接口调用示例
|
||
|
||
### 5.1 查询寄售商品列表
|
||
|
||
**请求**：
|
||
```http
|
||
GET /app/admin/merchandise/select?page=1&limit=10&status=1&is_show=1
|
||
```
|
||
|
||
**响应**：
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "ok",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"id": 144753,
|
||
"userId": 92166,
|
||
"username": "用户昵称",
|
||
"title": "商品标题",
|
||
"image": "[\"url1\",\"url2\"]",
|
||
"price": 1000.00,
|
||
"isShow": 1,
|
||
"status": 1,
|
||
"createdAt": "2025-11-13 10:00:00",
|
||
"updatedAt": "2025-11-13 10:00:00"
|
||
}
|
||
],
|
||
"total": 50,
|
||
"pageNum": 1,
|
||
"pageSize": 10
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5.2 查询寄售商品详情
|
||
|
||
**请求**：
|
||
```http
|
||
GET /app/admin/merchandise/select?id=144753
|
||
```
|
||
|
||
**响应**：
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "ok",
|
||
"data": {
|
||
"id": 144753,
|
||
"userId": 92166,
|
||
"username": "用户昵称",
|
||
"title": "商品标题",
|
||
"image": "[\"url1\",\"url2\"]",
|
||
"price": 1000.00,
|
||
"isShow": 1,
|
||
"status": 1,
|
||
"createdAt": "2025-11-13 10:00:00",
|
||
"updatedAt": "2025-11-13 10:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5.3 更新寄售商品（审核通过）
|
||
|
||
**请求**：
|
||
```http
|
||
POST /app/admin/merchandise/update
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"id": 144753,
|
||
"is_show": 1
|
||
}
|
||
```
|
||
|
||
**响应**：
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "ok",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
### 5.4 审核提现申请
|
||
|
||
**请求（通过）**：
|
||
```http
|
||
POST /app/admin/withdraw/update
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"id": 4457,
|
||
"status": 1,
|
||
"remark": "审核通过"
|
||
}
|
||
```
|
||
|
||
**请求（驳回）**：
|
||
```http
|
||
POST /app/admin/withdraw/update
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"id": 4457,
|
||
"status": 2,
|
||
"remark": "账户信息不符"
|
||
}
|
||
```
|
||
|
||
**响应**：
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "审核成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
### 5.5 查询财务日志
|
||
|
||
**请求**：
|
||
```http
|
||
GET /app/admin/coupon-log/select?page=1&limit=10&user_id=92697&type=1
|
||
```
|
||
|
||
**响应**：
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "ok",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"id": 1,
|
||
"userId": 92697,
|
||
"username": "张三",
|
||
"mobile": "13800138000",
|
||
"type": 1,
|
||
"money": 10.000,
|
||
"before": 0.000,
|
||
"after": 10.000,
|
||
"memo": "系统发放",
|
||
"createdAt": "2025-11-13 10:00:00"
|
||
}
|
||
],
|
||
"total": 100,
|
||
"pageNum": 1,
|
||
"pageSize": 10
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 六、权限配置
|
||
|
||
所有管理后台接口都需要管理员权限，权限标识如下：
|
||
|
||
### 6.1 寄售商品管理权限
|
||
- `admin:merchandise:select` - 查询寄售商品（列表/详情）
|
||
- `admin:merchandise:update` - 更新寄售商品
|
||
|
||
### 6.2 订单管理权限
|
||
- `admin:order:select` - 查询订单（列表/详情）
|
||
- `admin:order:update` - 更新订单
|
||
|
||
### 6.3 提现管理权限
|
||
- `admin:withdraw:select` - 查询提现（列表/详情）
|
||
- `admin:withdraw:update` - 审核提现
|
||
|
||
### 6.4 财务日志权限
|
||
- `admin:coupon-log:select` - 查询优惠券日志
|
||
- `admin:selfbonus-log:select` - 查询个人奖金日志
|
||
- `admin:sharebonus-log:select` - 查询推广奖金日志
|
||
|
||
**权限配置位置**：需要在系统权限管理中添加以上权限标识，并分配给相应角色。
|
||
|
||
---
|
||
|
||
## 七、数据统计
|
||
|
||
- **Request类**：7个
|
||
- **Response类**：4个
|
||
- **Service接口**：4个
|
||
- **Service实现类**：4个
|
||
- **Controller类**：4个
|
||
- **API接口总数**：9个（列表和详情共用接口）
|
||
|
||
---
|
||
|
||
## 八、待完善功能
|
||
|
||
### 8.1 提现审核优化
|
||
- [ ] 接入第三方支付API实现自动打款
|
||
- [ ] 增加批量审核功能
|
||
- [ ] 增加审核工作流
|
||
|
||
### 8.2 财务管理增强
|
||
- [ ] 完善财务日志记录（所有金额变动都记录）
|
||
- [ ] 增加财务报表统计
|
||
- [ ] 增加对账功能
|
||
|
||
### 8.3 商品管理优化
|
||
- [ ] 批量审核寄售商品
|
||
- [ ] 商品质量评分系统
|
||
- [ ] 违规商品自动下架
|
||
|
||
### 8.4 订单管理增强
|
||
- [ ] 订单导出功能
|
||
- [ ] 订单统计分析
|
||
- [ ] 异常订单预警
|
||
|
||
---
|
||
|
||
## 九、注意事项
|
||
|
||
### 9.1 安全性
|
||
1. 所有接口都需要管理员身份验证
|
||
2. 敏感操作（提现审核）需要二次确认
|
||
3. 重要操作记录日志
|
||
|
||
### 9.2 数据一致性
|
||
1. 提现驳回时务必返还金额到正确账户
|
||
2. 订单状态变更需要同步更新相关数据
|
||
3. 使用事务保证数据一致性
|
||
|
||
### 9.3 性能优化
|
||
1. 分页查询避免一次性加载大量数据
|
||
2. 关联查询使用批量查询优化
|
||
3. 合理使用缓存
|
||
|
||
### 9.4 代码规范
|
||
1. 遵循统一的代码风格
|
||
2. 添加完善的注释
|
||
3. 合理处理异常
|
||
|
||
---
|
||
|
||
## 十、文档更新日志
|
||
|
||
| 日期 | 版本 | 更新内容 | 更新人 |
|
||
|------|------|----------|--------|
|
||
| 2025-11-14 | V1.0 | 初始创建，完成管理后台API接口封装 | AI Assistant |
|
||
|
||
---
|
||
|
||
**维护人**：AI Assistant
|
||
**最后更新**：2025-11-14
|
||
**文档状态**：已完成接口封装，可进行测试
|
||
|
||
---
|
||
|
||
## 附录A：与PRD文档的对应关系
|
||
|
||
| PRD章节 | 实现内容 | 对应Controller |
|
||
|---------|----------|---------------|
|
||
| 3.2 商品管理模块 | 寄售商品管理 | WaMerchandiseController |
|
||
| 3.3 订单管理模块 | 订单管理 | WaOrderAdminController |
|
||
| 3.4 提现管理模块 | 提现审核 | WaWithdrawController |
|
||
| 3.5 财务日志管理模块 | 财务日志查询 | WaFinanceLogController |
|
||
|
||
本实现完全符合PRD文档的接口规范要求。
|
||
|