integral-shop/backend/docs/商品寄卖服务系统管理后台接口实现说明.md

# 商品寄卖服务系统管理后台接口实现说明

## 实现概述

本文档说明了在`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文档的接口规范要求。