integral-shop/backend/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<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  
**文档状态**: 已完成接口定义，待实现业务逻辑