378 lines
12 KiB
Markdown
378 lines
12 KiB
Markdown
# 商品寄卖服务模块 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<T>
|
||
- 请求参数使用 @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) 和 [项目完成总结.md](项目完成总结.md)
|
||
|
||
---
|
||
|
||
## 六、使用示例
|
||
|
||
### 6.1 用户登录
|
||
|
||
**请求**：
|
||
```http
|
||
POST /api/user/login
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"account": "18379637515",
|
||
"password": "123456"
|
||
}
|
||
```
|
||
|
||
**响应**：
|
||
```json
|
||
{
|
||
"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 获取商品列表
|
||
|
||
**请求**：
|
||
```http
|
||
GET /api/goods/list?cateId=1
|
||
```
|
||
|
||
**响应**：
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"title": "商品标题",
|
||
"images": "[\"图片1\", \"图片2\"]",
|
||
"price": 199.00,
|
||
"linePrice": 299.00,
|
||
"salesVolume": 1000
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 6.3 购买商品（需要登录）
|
||
|
||
**请求**：
|
||
```http
|
||
POST /api/order/buy
|
||
Content-Type: application/json
|
||
Authori-zation: Bearer YOUR_TOKEN
|
||
|
||
{
|
||
"id": 143657,
|
||
"sellerId": 92467
|
||
}
|
||
```
|
||
|
||
**响应**：
|
||
```json
|
||
{
|
||
"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
|
||
**文档状态**: 已完成接口定义，待实现业务逻辑
|
||
|