integral-shop-mgtv1/crmeb_22miao/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插件实现分页：

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 查询寄售商品列表

请求：

GET /app/admin/merchandise/select?page=1&limit=10&status=1&is_show=1

响应：

{
  "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 查询寄售商品详情

请求：

GET /app/admin/merchandise/select?id=144753

响应：

{
  "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 更新寄售商品（审核通过）

请求：

POST /app/admin/merchandise/update
Content-Type: application/json

{
  "id": 144753,
  "is_show": 1
}

响应：

{
  "code": 0,
  "msg": "ok",
  "data": null
}

5.4 审核提现申请

请求（通过）：

POST /app/admin/withdraw/update
Content-Type: application/json

{
  "id": 4457,
  "status": 1,
  "remark": "审核通过"
}

请求（驳回）：

POST /app/admin/withdraw/update
Content-Type: application/json

{
  "id": 4457,
  "status": 2,
  "remark": "账户信息不符"
}

响应：

{
  "code": 0,
  "msg": "审核成功",
  "data": null
}

5.5 查询财务日志

请求：

GET /app/admin/coupon-log/select?page=1&limit=10&user_id=92697&type=1

响应：

{
  "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文档的接口规范要求。