# 电商模块 (ruoyi-mall)

## 模块简介

`ruoyi-mall` 是 PoJie 项目的电商核心业务模块，提供完整的电商功能，包括商品管理、购物车、订单管理、支付集成等。

## 模块结构

根据模块结构规划，`ruoyi-mall` 采用子模块拆分的方式，包含以下子模块：

- `ruoyi-mall-product` - 商品中心 (SPU, SKU, 分类, 品牌, 属性)
- `ruoyi-mall-trade` - 交易中心 (购物车, 订单, 售后)
- `ruoyi-mall-promotion` - 营销中心 (活动, 拼团, 秒杀, 砍价)
- `ruoyi-mall-coupon` - 优惠券中心 (独立拆分，便于复用)
- `ruoyi-mall-statistics` - 统计中心 (交易分析, 会员分析)

各子模块详细说明请参考对应的 README.md 文件。

## 功能特性

### 1. 商品管理

- ✅ 商品CRUD操作
- ✅ 商品上架/下架
- ✅ 商品浏览量和销量统计
- ✅ 商品详情管理

### 2. SKU管理

- ✅ SKU CRUD操作
- ✅ 库存管理
- ✅ 库存扣减和恢复
- ✅ 规格属性管理

### 3. 购物车管理

- ✅ 添加/删除购物车
- ✅ 购物车数量修改
- ✅ 购物车选中状态管理
- ✅ 购物车详情查询（包含商品和SKU信息）

### 4. 订单管理

- ✅ 订单创建
- ✅ 订单查询（列表、详情）
- ✅ 订单取消
- ✅ 订单状态管理
- ✅ 订单支付集成

### 5. 支付集成

- ✅ 与支付中心（ruoyi-pay）集成
- ✅ 支付回调处理
- ✅ 支付状态同步

## 数据库表

### 商品中心 (ruoyi-mall-product)

- `mall_product` - 商品表
- `mall_sku` - SKU表
- `mall_category` - 商品分类表
- `mall_brand` - 品牌表

### 交易中心 (ruoyi-mall-trade)

- `mall_cart` - 购物车表
- `mall_order` - 订单表
- `mall_order_item` - 订单明细表
- `mall_after_sale` - 售后申请表
- `mall_order_evaluate` - 订单评价表
- `mall_order_coupon` - 订单优惠券使用记录表

详细表结构请参考：`script/sql/ry_mall.sql`

## 配置说明

在 `application.yml` 中添加以下配置：

```yaml
ruoyi:
  mall:
    pay-app-id: 1  # 支付应用ID
    pay-notify-url: https://your-domain.com/app/mall/pay/notify  # 支付回调地址
```

## API接口

### 移动端接口

#### 商品接口

- `GET /app/mall/product/list` - 查询商品列表
- `GET /app/mall/product/{id}` - 查询商品详情
- `GET /app/mall/product/{productId}/skus` - 查询商品SKU列表

#### 商品分类接口

- `GET /app/mall/product/category/tree` - 查询商品分类树形列表（仅启用分类）

#### 品牌接口

- `GET /app/mall/product/brand/list` - 查询品牌列表（仅启用品牌）

#### 购物车接口

- `GET /app/mall/cart/list` - 查询购物车列表
- `GET /app/mall/cart/detail/list` - 查询购物车详情列表（包含商品信息）
- `POST /app/mall/cart` - 添加购物车
- `PUT /app/mall/cart` - 修改购物车
- `DELETE /app/mall/cart/{ids}` - 删除购物车
- `DELETE /app/mall/cart/clear` - 清空购物车
- `PUT /app/mall/cart/selected/{id}` - 更新选中状态
- `PUT /app/mall/cart/selected/batch` - 批量更新选中状态

#### 订单接口

- `POST /app/mall/order/submit` - 提交订单并发起支付
- `GET /app/mall/order/list` - 查询订单列表
- `GET /app/mall/order/{id}` - 查询订单详情
- `PUT /app/mall/order/cancel/{id}` - 取消订单
- `POST /app/mall/order/pay/notify` - 支付回调（由支付中心调用）

#### 优惠券接口

- `GET /app/mall/coupon/available/list` - 查询可领取的优惠券列表
- `GET /app/mall/coupon/{id}` - 获取优惠券详情
- `GET /app/mall/coupon/user/list` - 查询用户优惠券列表
- `GET /app/mall/coupon/user/available/list` - 查询用户可用优惠券列表
- `GET /app/mall/coupon/user/{id}` - 获取用户优惠券详情
- `POST /app/mall/coupon/user/receive/{couponId}` - 领取优惠券

### 管理端接口

#### 商品管理

- `GET /mall/product/list` - 查询商品列表
- `GET /mall/product/{id}` - 查询商品详情
- `POST /mall/product` - 新增商品
- `PUT /mall/product` - 修改商品
- `DELETE /mall/product/{ids}` - 删除商品
- `PUT /mall/product/status/{id}` - 上架/下架商品

#### 商品分类管理

- `GET /mall/product/category/list` - 查询商品分类列表（分页）
- `GET /mall/product/category/tree` - 查询商品分类树形列表
- `GET /mall/product/category/{id}` - 获取商品分类详情
- `POST /mall/product/category` - 新增商品分类
- `PUT /mall/product/category` - 修改商品分类
- `DELETE /mall/product/category/{ids}` - 删除商品分类

#### 优惠券管理

- `GET /mall/coupon/list` - 查询优惠券列表（分页）
- `GET /mall/coupon/{id}` - 获取优惠券详情
- `POST /mall/coupon` - 新增优惠券
- `PUT /mall/coupon` - 修改优惠券
- `DELETE /mall/coupon/{ids}` - 删除优惠券
- `POST /mall/coupon/export` - 导出优惠券列表
- `PUT /mall/coupon/changeStatus/{id}` - 启用/禁用优惠券

#### 用户优惠券管理

- `GET /mall/coupon/user/list` - 查询用户优惠券列表（分页）
- `GET /mall/coupon/user/{id}` - 获取用户优惠券详情
- `DELETE /mall/coupon/user/{ids}` - 删除用户优惠券
- `POST /mall/coupon/user/export` - 导出用户优惠券列表
- `POST /mall/product/category/export` - 导出商品分类列表

#### 品牌管理

- `GET /mall/product/brand/list` - 查询品牌列表（分页）
- `GET /mall/product/brand/{id}` - 获取品牌详情
- `POST /mall/product/brand` - 新增品牌
- `PUT /mall/product/brand` - 修改品牌
- `DELETE /mall/product/brand/{ids}` - 删除品牌
- `POST /mall/product/brand/export` - 导出品牌列表

#### SKU管理

- `GET /mall/sku/list` - 查询SKU列表
- `GET /mall/sku/{id}` - 查询SKU详情
- `GET /mall/sku/product/{productId}` - 根据商品ID查询SKU列表
- `POST /mall/sku` - 新增SKU
- `PUT /mall/sku` - 修改SKU
- `DELETE /mall/sku/{ids}` - 删除SKU

#### 订单管理

- `GET /mall/order/list` - 查询订单列表
- `GET /mall/order/{id}` - 查询订单详情
- `PUT /mall/order` - 修改订单
- `DELETE /mall/order/{ids}` - 删除订单
- `PUT /mall/order/delivery/{id}` - 订单发货

## 业务流程

### 订单提交流程

1. 用户选择商品（从购物车或直接购买）
2. 调用 `/app/mall/order/submit` 提交订单
3. 系统创建订单和订单明细
4. 调用支付中心创建支付单
5. 返回支付参数给前端
6. 前端调起支付
7. 支付成功后，支付中心回调 `/app/mall/order/pay/notify`
8. 系统更新订单状态并扣减库存

### 购物车流程

1. 用户浏览商品，选择SKU
2. 调用 `/app/mall/cart` 添加到购物车
3. 如果购物车中已存在该SKU，则更新数量
4. 用户可以在购物车中修改数量、选中状态
5. 提交订单时，从购物车获取商品信息
6. 订单创建成功后，删除购物车中的商品

## 依赖模块

- `ruoyi-pay` - 支付中心模块
- `ruoyi-common-*` - 通用工具模块

## 注意事项

1. **库存管理**：订单支付成功后才扣减库存，避免超卖
2. **幂等性**：支付回调需要保证幂等处理
3. **地址管理**：当前版本地址信息简化处理，后续可扩展地址表
4. **订单号生成**：使用时间戳+随机字符串生成唯一订单号

## 待完善功能

### 商品中心

- [ ] 商品属性管理
- [ ] 商品规格模板
- [ ] 商品搜索功能

### 交易中心

- ✅ 订单评价功能
- ✅ 售后管理功能（退款、退货、换货）
- [ ] 地址管理模块（可考虑集成到会员模块）
- [ ] 订单优惠券使用记录

### 营销中心

- [ ] 营销活动管理
- [ ] 拼团功能
- [ ] 秒杀功能
- [ ] 砍价功能

### 优惠券中心

- [ ] 优惠券管理
- [ ] 用户优惠券功能
- [ ] 优惠券统计

### 统计中心

- [ ] 交易分析
- [ ] 会员分析
- [ ] 商品分析
- [ ] 营销分析