integral-shop-mgtv1/crmeb_22miao/docs/商品寄卖服务模块API接口实现说明.md

商品寄卖服务模块 API 接口实现说明

项目概述

本文档说明了在 crmeb-front 模块中新建的"商品寄卖服务模块"移动端 API 接口的实现情况。

实现时间：2025-11-08
实现模块：crmeb-front
API 路径前缀：/api

---

一、已创建文件清单

1.1 实体类（Entity）

位置：crmeb-common/src/main/java/com/zbkj/common/model/consignment/

文件名	说明	对应数据表
WaUsers.java	寄卖服务用户表	wa_users
WaGoods.java	商品表	wa_goods
WaMerchandise.java	寄售商品表	wa_merchandise
WaOrder.java	订单表	wa_order
WaCategory.java	商品分类表	wa_category
WaAddress.java	收货地址表	wa_address
WaMoneyLog.java	余额变动表	wa_money_log
WaCouponLog.java	优惠券变动表	wa_coupon_log
WaSelfbonusLog.java	个人奖金变动表	wa_selfbonus_log
WaSharebonusLog.java	推广奖金变动表	wa_sharebonus_log
WaWithdraw.java	提现表	wa_withdraw
WaAlipay.java	用户支付宝表	wa_alipay
WaBank.java	用户银行卡表	wa_bank
WaBanner.java	轮播图表	wa_banner

1.2 请求对象（Request）

位置：crmeb-common/src/main/java/com/zbkj/common/request/

文件名	说明	用途
WaUserLoginRequest.java	用户登录请求	用户登录
WaUserRegisterRequest.java	用户注册请求	用户注册
WaUserUpdateRequest.java	用户信息更新请求	更新用户信息
WaOrderBuyRequest.java	购买商品请求	抢单购买
WaOrderPayRequest.java	支付订单请求	订单支付
WaAddressRequest.java	地址请求	地址增删改
WaWithdrawRequest.java	提现请求	申请提现
WaAlipayBindRequest.java	绑定支付宝请求	绑定支付宝

1.3 响应对象（Response）

位置：crmeb-common/src/main/java/com/zbkj/common/response/

文件名	说明	用途
WaLoginResponse.java	用户登录响应	返回登录信息
WaUserInfoResponse.java	用户信息响应	返回用户详细信息
WaGoodsDetailResponse.java	商品详情响应	返回商品详细信息
WaMerchandiseListResponse.java	寄售商品列表响应	返回寄售商品列表
WaOrderIndexResponse.java	订单首页响应	返回订单首页数据
WaOrderDetailResponse.java	订单详情响应	返回订单详细信息
WaMoneyLogResponse.java	财务记录响应	返回财务变动记录
WaShareIndexResponse.java	分享首页响应	返回分享推广数据
WaShareFansResponse.java	粉丝列表响应	返回粉丝列表

1.4 控制器（Controller）

位置：crmeb-front/src/main/java/com/zbkj/front/controller/

文件名	说明	路由前缀	接口数量
WaUserController.java	用户认证控制器	/api/user	5个
WaGoodsController.java	商品管理控制器	/api/goods	3个
WaOrderController.java	订单管理控制器	/api/order	9个
WaAddressController.java	地址管理控制器	/api/address	5个
WaMoneyController.java	财务管理控制器	/api/money	3个
WaPayController.java	支付管理控制器	/api/alipay, /api/bank	3个
WaShareController.java	分享推广控制器	/api/share	2个
WaIndexController.java	首页管理控制器	/api/index	2个
WaSmsController.java	短信服务控制器	/api/sms	1个

1.5 服务接口（Service）

位置：crmeb-front/src/main/java/com/zbkj/front/service/

文件名	说明	方法数量
WaUserService.java	用户服务接口	5个
WaGoodsService.java	商品服务接口	3个
WaOrderService.java	订单服务接口	9个
WaAddressService.java	地址服务接口	5个
WaMoneyService.java	财务服务接口	3个
WaPayService.java	支付服务接口	3个
WaShareService.java	分享服务接口	2个
WaIndexService.java	首页服务接口	2个
WaSmsService.java	短信服务接口	1个

---

二、API 接口列表

2.1 用户认证接口（5个）

接口	路径	方法	说明
用户登录	/api/user/login	POST	账号密码登录
用户注册	/api/user/register	POST	手机号注册
获取用户信息	/api/user/info	POST	获取当前用户信息
修改用户昵称	/api/user/nickname	POST	更新昵称
修改密码	/api/user/changepwd	POST	修改密码

2.2 商品相关接口（3个）

接口	路径	方法	说明
获取商品分类	/api/goods/category	GET	获取所有商品分类
获取商品列表	/api/goods/list	GET	根据分类获取商品列表
获取商品详情	/api/goods/detail	GET	获取商品详细信息

2.3 订单相关接口（9个）

接口	路径	方法	说明
订单首页数据	/api/order/index	POST	获取订单首页配置
可购买商品列表	/api/order/goods	GET	获取寄售商品列表
购买商品（抢单）	/api/order/buy	POST	创建订单并抢单
订单列表	/api/order/list	GET	获取买方/卖方订单列表
订单详情	/api/order/detail	GET	获取订单详细信息
支付订单	/api/order/pay	POST	支付订单
确认订单	/api/order/confirm	POST	卖家确认发货
取消订单	/api/order/cancel	POST	取消订单
转卖订单	/api/order/resell	POST	将订单商品转拍

2.4 地址管理接口（5个）

接口	路径	方法	说明
地址列表	/api/address/list	GET	获取用户所有地址
获取默认地址	/api/address/default	POST	获取默认收货地址
新增地址	/api/address/insert	POST	添加新地址
更新地址	/api/address/update	POST	更新地址信息
删除地址	/api/address/delete	POST	删除地址

2.5 财务相关接口（3个）

接口	路径	方法	说明
财务记录列表	/api/money/list	GET	获取财务变动记录
提现记录	/api/money/log	GET	获取提现记录
申请提现	/api/money/withdraw	POST	申请提现

2.6 支付相关接口（3个）

接口	路径	方法	说明
获取支付宝信息	/api/alipay/index	GET	获取绑定的支付宝信息
绑定支付宝	/api/alipay/bind	POST	绑定支付宝账号
获取银行卡信息	/api/bank/index	GET	获取绑定的银行卡信息

2.7 分享推广接口（2个）

接口	路径	方法	说明
分享首页数据	/api/share/index	GET	获取分享推广数据
我的粉丝列表	/api/share/select	GET	获取我的粉丝列表

2.8 首页相关接口（2个）

接口	路径	方法	说明
轮播图	/api/index/banner	GET	获取轮播图列表
首页配置数据	/api/index/get	POST	获取首页配置信息

2.9 短信服务接口（1个）

接口	路径	方法	说明
发送短信验证码	/api/sms/send	POST	发送短信验证码

---

三、数据统计

• 实体类：14 个
• Request 类：8 个
• Response 类：9 个
• Controller 类：9 个
• Service 接口：9 个
• API 接口总数：33 个

---

四、技术说明

4.1 技术栈

• 框架：Spring Boot
• ORM：MyBatis Plus
• 分页：PageHelper
• API 文档：Swagger
• 数据验证：Hibernate Validator

4.2 设计模式

• 采用标准的三层架构：Controller -> Service -> Dao
• 所有接口遵循 RESTful API 规范
• 使用统一的响应格式：CommonResult
• 请求参数使用 @Validated 进行校验

4.3 认证方式

• 使用 Token 认证
• Token 通过 Header: Authori-zation 传递
• 通过 FrontTokenComponent 获取当前登录用户

---

五、后续工作

5.1 ✅ Service 实现类 - 已完成

所有的 Service 实现类已创建完成，位于 crmeb-front/src/main/java/com/zbkj/front/service/impl/ 目录：

• ✅ WaUserServiceImpl.java - 用户服务实现
• ✅ WaGoodsServiceImpl.java - 商品服务实现
• ✅ WaOrderServiceImpl.java - 订单服务实现
• ✅ WaAddressServiceImpl.java - 地址服务实现
• ✅ WaMoneyServiceImpl.java - 财务服务实现
• ✅ WaPayServiceImpl.java - 支付服务实现
• ✅ WaShareServiceImpl.java - 分享服务实现
• ✅ WaIndexServiceImpl.java - 首页服务实现
• ✅ WaSmsServiceImpl.java - 短信服务实现

5.2 ✅ Mapper/Dao 类 - 已完成

所有 Dao 接口和 XML 配置文件已创建完成：

• ✅ 14 个 Dao 接口已创建（位于 crmeb-service/src/main/java/com/zbkj/service/dao/consignment/）
• ✅ 14 个 Mapper XML 已创建（位于 crmeb-service/src/main/resources/mapper/consignment/）

5.3 ✅ 数据库表创建 - 已完成

已根据 数据库设计说明.md 创建完整的建表脚本：

• ✅ 文件位置：sql/wa_consignment_tables.sql
• ✅ 包含 14 张数据表的完整 DDL
• ✅ 包含索引和初始化数据

5.4 ✅ 配置更新 - 已完成

已在 FrontTokenComponent 中配置公开访问路由：

• ✅ /api/user/login - 用户登录
• ✅ /api/user/register - 用户注册
• ✅ /api/goods/* - 商品查询接口
• ✅ /api/index/* - 首页接口
• ✅ /api/sms/send - 短信发送

5.5 ⏳ 待完善功能（可选）

以下功能已预留接口，需根据实际业务需求完善：

• 短信验证码实际发送（接入短信服务商）
• 支付功能实现（接入支付宝/微信支付）
• 财务分红计算逻辑
• 系统配置管理
• 订单超时自动取消

详细说明请查看: 后续工作完成情况.md 和 项目完成总结.md

---

六、使用示例

6.1 用户登录

请求：

POST /api/user/login
Content-Type: application/json

{
  "account": "18379637515",
  "password": "123456"
}

响应：

{
  "code": 0,
  "msg": "success",
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "userInfo": {
      "id": 92564,
      "mobile": "18379637515",
      "nickname": "用户昵称",
      "avatar": "头像URL",
      "shareBonus": "1234.56",
      "selfBonus": "789.12",
      "coupon": "456.78"
    }
  }
}

6.2 获取商品列表

请求：

GET /api/goods/list?cateId=1

响应：

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "id": 1,
      "title": "商品标题",
      "images": "[\"图片1\", \"图片2\"]",
      "price": 199.00,
      "linePrice": 299.00,
      "salesVolume": 1000
    }
  ]
}

6.3 购买商品（需要登录）

请求：

POST /api/order/buy
Content-Type: application/json
Authori-zation: Bearer YOUR_TOKEN

{
  "id": 143657,
  "sellerId": 92467
}

响应：

{
  "code": 0,
  "msg": "success",
  "data": true
}

---

七、注意事项

1. 认证头名称：注意是 Authori-zation 而非标准的 Authorization
2. 参数验证：所有请求参数都已配置验证注解，需要在 Controller 中使用 @Validated
3. 分页参数：使用 PageParamRequest 统一处理分页
4. 时间格式：建议统一使用 yyyy-MM-dd HH:mm:ss 格式
5. 金额类型：使用 BigDecimal 类型处理金额，避免精度丢失
6. 响应格式：统一使用 CommonResult<T> 包装返回数据

---

八、文档更新日志

日期	版本	更新内容	更新人
2025-11-08	V1.0	初始创建，完成所有 API 接口定义	AI Assistant

---

维护: AI Assistant
最后更新: 2025-11-08
文档状态: 已完成接口定义，待实现业务逻辑