PoJie/ruoyi-modules/ruoyi-mall/MODULE_STRUCTURE.md

# 商城模块结构说明

## 模块拆分

根据 `MODULE_STRUCTURE_PLAN.md` 的要求，`ruoyi-mall` 模块已按照规划拆分为以下子模块：

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

- **职责**: 商品(SPU)、SKU、分类、品牌、属性管理
- **包名**: `org.dromara.mall.product`
- **状态**: ✅ 核心功能已实现（商品管理✅、分类管理✅、品牌管理✅、属性管理✅）
- **数据库表**: `mall_product`, `mall_sku`, `mall_category`, `mall_brand`, `mall_attribute_template`, `mall_attribute`, `mall_attribute_value`, `mall_product_attribute`

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

- **职责**: 购物车、订单、售后管理
- **包名**: `org.dromara.mall.trade`
- **状态**: ✅ 核心功能已实现（购物车✅、订单✅、售后✅、评价✅）
- **数据库表**: `mall_cart`, `mall_order`, `mall_order_item`, `mall_after_sale`, `mall_order_evaluate`,
  `mall_order_coupon`

### 3. ruoyi-mall-coupon (优惠券中心)

- **职责**: 优惠券发放、核销、过期处理
- **包名**: `org.dromara.mall.coupon`
- **状态**: ✅ 核心功能已实现（优惠券管理✅、用户优惠券✅）
- **数据库表**: `mall_coupon`, `mall_coupon_user`

### 4. ruoyi-mall-promotion (营销中心)

- **职责**: 营销活动、拼团、秒杀、砍价
- **包名**: `org.dromara.mall.promotion`
- **状态**: ✅ 核心功能已实现（活动管理✅、秒杀✅、拼团✅、砍价✅）
- **数据库表**: `mall_promotion`, `mall_group_buy`, `mall_group_buy_order`, `mall_seckill`, `mall_bargain`,
  `mall_bargain_record`, `mall_bargain_help`

### 5. ruoyi-mall-statistics (统计中心)

- **职责**: 交易分析、会员分析、数据统计
- **包名**: `org.dromara.mall.statistics`
- **状态**: ✅ 交易统计功能已实现

## 已完成工作

### 1. 模块结构

- ✅ 创建了所有子模块的目录结构
- ✅ 创建了各子模块的 `pom.xml` 配置文件
- ✅ 配置了模块依赖关系

### 2. 自动配置

- ✅ 创建了各子模块的 `AutoConfiguration` 类
- ✅ 创建了 `spring.factories` 文件
- ✅ 配置了组件扫描

### 3. 数据库

- ✅ 扩展了 `script/sql/ry_mall.sql` 文件
- ✅ 添加了分类、品牌表
- ✅ 添加了优惠券相关表
- ✅ 添加了营销活动相关表（拼团、秒杀等）
- ✅ 添加了商品属性相关表（属性模板、属性、属性值、商品属性关联）

### 4. 文档

- ✅ 创建了各子模块的 README.md 文件
- ✅ 更新了主模块的 README.md 文件

## 代码迁移说明

### 当前状态

- 现有代码位于 `ruoyi-mall/src/main/java/org/dromara/mall/` 目录下
- 现有代码使用 `org.dromara.mall` 作为包名
- 现有代码包含：商品、SKU、购物车、订单等功能

### 迁移建议

由于代码迁移涉及大量文件的包名修改，建议采用渐进式迁移：

1. **保留现有代码**
    - 现有代码继续保留在 `ruoyi-mall/src` 目录
    - 保证现有功能正常运行

2. **新功能开发**
    - 新功能直接在新子模块中开发
    - 使用新的包名结构（如 `org.dromara.mall.product`）

3. **逐步迁移**
    - 商品相关代码 → `ruoyi-mall-product`
    - 交易相关代码 → `ruoyi-mall-trade`
    - 优惠券功能 → `ruoyi-mall-coupon`
    - 营销功能 → `ruoyi-mall-promotion`
    - 统计功能 → `ruoyi-mall-statistics`


## 模块依赖关系

```
ruoyi-mall (聚合模块)
├── ruoyi-mall-product (商品中心)
│   └── 依赖: ruoyi-common-*
├── ruoyi-mall-trade (交易中心)
│   ├── 依赖: ruoyi-mall-product
│   └── 依赖: ruoyi-pay
├── ruoyi-mall-coupon (优惠券中心)
│   └── 依赖: ruoyi-common-*
├── ruoyi-mall-promotion (营销中心)
│   ├── 依赖: ruoyi-mall-product
│   └── 依赖: ruoyi-mall-coupon
└── ruoyi-mall-statistics (统计中心)
    ├── 依赖: ruoyi-mall-product
    └── 依赖: ruoyi-mall-trade
```

## 下一步工作

1. **代码迁移** (可选)
    - 将现有代码迁移到对应的子模块
    - 修改包名以符合新的模块结构

2. **功能实现**
    - 实现各子模块的待实现功能
    - 参考各子模块的 README.md

3. **测试验证**
    - 验证各子模块的自动配置
    - 验证模块间的依赖关系

## 数据库表结构说明

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

#### 商品表 (mall_product)

- **功能**: 存储商品(SPU)基本信息
- **关键字段**: `name`, `category_id`, `brand_id`, `status`, `sales_count`, `view_count`, `cover_url`, `images`,
  `description`, `detail`
- **索引**: `category_id`, `brand_id`, `status`
- **状态说明**:
    - 0: 上架
    - 1: 下架

#### SKU表 (mall_sku)

- **功能**: 存储商品SKU信息，包括价格、库存、规格等
- **关键字段**: `product_id`, `sku_code`, `price`, `stock`, `specs`, `status`
- **索引**: `product_id`, `sku_code`, `status`
- **状态说明**:
    - 0: 启用
    - 1: 禁用

#### 商品分类表 (mall_category)

- **功能**: 商品分类树形结构
- **关键字段**: `name`, `parent_id`, `level`, `sort`, `icon`, `status`
- **索引**: `parent_id`, `status`
- **状态说明**:
    - 0: 启用
    - 1: 禁用
- **级别说明**:
    - 1: 一级分类
    - 2: 二级分类
    - 3: 三级分类
- **说明**: 支持三级分类，通过 `parent_id` 构建树形结构，`parent_id=0` 表示顶级分类

#### 品牌表 (mall_brand)

- **功能**: 商品品牌信息
- **关键字段**: `name`, `logo`, `description`, `sort`, `status`
- **索引**: `status`
- **状态说明**:
    - 0: 启用
    - 1: 禁用

#### 属性模板表 (mall_attribute_template)

- **功能**: 属性模板定义，可绑定到分类
- **关键字段**: `name`, `category_id`, `sort`, `status`
- **索引**: `category_id`, `status`

#### 属性表 (mall_attribute)

- **功能**: 属性定义
- **关键字段**: `template_id`, `name`, `type`, `required`, `sort`, `status`
- **索引**: `template_id`, `status`
- **类型说明**:
    - 0: 文本
    - 1: 数字
    - 2: 日期
    - 3: 枚举

#### 属性值表 (mall_attribute_value)

- **功能**: 属性的值（用于枚举类型属性）
- **关键字段**: `attribute_id`, `value`, `sort`, `status`
- **索引**: `attribute_id`, `status`

#### 商品属性关联表 (mall_product_attribute)

- **功能**: 商品关联的属性值
- **关键字段**: `product_id`, `attribute_id`, `attribute_value_id`, `value`
- **索引**: `product_id`, `attribute_id`, `attribute_value_id`

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

#### 购物车表 (mall_cart)

- **功能**: 用户购物车信息
- **关键字段**: `user_id`, `sku_id`, `quantity`, `selected`
- **索引**: `user_id`, `uk_user_sku` (唯一索引)

#### 订单表 (mall_order)

- **功能**: 订单主表
- **关键字段**: `order_no`, `user_id`, `total_amount`, `pay_amount`, `pay_status`, `order_status`, `delivery_status`,
  `receiver_*`
- **索引**: `order_no` (唯一), `user_id`, `pay_order_no`, `order_status`, `pay_status`
- **状态说明**:
    - `pay_status`:
        - 0: 未支付
        - 1: 已支付
        - 2: 已退款
    - `order_status`:
        - 0: 待付款
        - 1: 待发货
        - 2: 待收货
        - 3: 已完成
        - 4: 已取消
    - `delivery_status`:
        - 0: 未发货
        - 1: 已发货
        - 2: 已收货

#### 订单明细表 (mall_order_item)

- **功能**: 订单商品明细
- **关键字段**: `order_id`, `product_id`, `sku_id`, `price`, `quantity`, `total_amount`
- **索引**: `order_id`, `order_no`, `product_id`, `sku_id`

#### 收货地址表 (mall_address)

- **功能**: 用户收货地址管理
- **关键字段**: `user_id`, `receiver_name`, `receiver_phone`, `province`, `city`, `district`, `address`, `is_default`
- **索引**: `user_id`, `is_default`
- **状态说明**:
    - `is_default`: 0-否，1-是

#### 售后申请表 (mall_after_sale)

- **功能**: 订单售后申请（退款、退货、换货）
- **关键字段**: `after_sale_no`, `order_id`, `type`, `status`, `refund_amount`
- **索引**: `after_sale_no` (唯一), `order_id`, `user_id`, `status`
- **状态说明**:
    - 0: 待审核
    - 1: 已同意
    - 2: 已拒绝
    - 3: 待退货
    - 4: 待收货
    - 5: 已完成
    - 6: 已取消
- **类型说明**:
    - 0: 退款
    - 1: 退货
    - 2: 换货

#### 订单评价表 (mall_order_evaluate)

- **功能**: 订单商品评价
- **关键字段**: `order_id`, `order_item_id`, `product_id`, `user_id`, `score`, `content`, `images`
- **索引**: `order_id`, `order_no`, `order_item_id`, `product_id`, `user_id`

#### 订单优惠券使用记录表 (mall_order_coupon)

- **功能**: 记录订单使用的优惠券信息
- **关键字段**: `order_id`, `coupon_id`, `coupon_user_id`, `discount_amount`
- **索引**: `order_id`, `order_no`, `coupon_id`, `coupon_user_id`

### 3. ruoyi-mall-coupon (优惠券中心)

#### 优惠券表 (mall_coupon)

- **功能**: 优惠券模板定义
- **关键字段**: `name`, `type`, `discount_amount`, `discount_rate`, `min_amount`, `valid_start_time`, `valid_end_time`
- **索引**: `status`, `valid_time`
- **类型说明**:
    - 0: 满减券
    - 1: 折扣券
    - 2: 现金券

#### 用户优惠券表 (mall_coupon_user)

- **功能**: 用户领取的优惠券
- **关键字段**: `user_id`, `coupon_id`, `status`, `used_time`, `order_id`
- **索引**: `user_id`, `coupon_id`, `status`
- **状态说明**:
    - 0: 未使用
    - 1: 已使用
    - 2: 已过期

### 4. ruoyi-mall-promotion (营销中心)

#### 营销活动表 (mall_promotion)

- **功能**: 营销活动主表
- **关键字段**: `name`, `type`, `start_time`, `end_time`, `rules` (JSON)
- **索引**: `type`, `status`, `time`
- **类型说明**:
    - 0: 普通活动
    - 1: 拼团活动
    - 2: 秒杀活动
    - 3: 砍价活动

#### 拼团表 (mall_group_buy)

- **功能**: 拼团活动配置
- **关键字段**: `promotion_id`, `sku_id`, `group_price`, `group_size`, `duration_hours`
- **索引**: `promotion_id`, `sku_id`

#### 拼团订单表 (mall_group_buy_order)

- **功能**: 拼团订单记录
- **关键字段**: `group_buy_id`, `group_no`, `order_id`, `user_id`, `status`, `expire_time`
- **索引**: `group_buy_id`, `group_no`, `order_id`, `status`
- **状态说明**:
    - 0: 拼团中
    - 1: 已成团
    - 2: 已失败

#### 秒杀表 (mall_seckill)

- **功能**: 秒杀活动配置
- **关键字段**: `promotion_id`, `sku_id`, `seckill_price`, `seckill_stock`, `start_time`, `end_time`
- **索引**: `promotion_id`, `sku_id`, `time`

#### 砍价活动表 (mall_bargain)

- **功能**: 砍价活动配置
- **关键字段**: `promotion_id`, `sku_id`, `bargain_price`, `original_price`, `min_price`, `help_count`
- **索引**: `promotion_id`, `sku_id`

#### 砍价记录表 (mall_bargain_record)

- **功能**: 用户发起的砍价记录
- **关键字段**: `bargain_id`, `bargain_no`, `user_id`, `current_price`, `status`, `expire_time`
- **索引**: `bargain_id`, `bargain_no`, `user_id`, `status`
- **状态说明**:
    - 0: 进行中
    - 1: 已成功
    - 2: 已失败
    - 3: 已下单

#### 砍价助力记录表 (mall_bargain_help)

- **功能**: 砍价助力记录
- **关键字段**: `bargain_record_id`, `bargain_no`, `user_id`, `help_price`
- **索引**: `bargain_record_id`, `bargain_no`, `user_id`

### 5. ruoyi-mall-statistics (统计中心)

统计模块主要基于现有业务表进行数据分析和统计，可根据需要创建统计汇总表。

- **主要数据源表**:
  - `mall_order`, `mall_order_item` - 订单和订单明细表（用于交易统计、商品销售统计）
  - `mall_product` - 商品表（用于商品浏览统计，基于`view_count`字段）
  - `mall_promotion`, `mall_group_buy`, `mall_seckill`, `mall_bargain` - 营销活动表（用于活动效果统计）
  - `mall_coupon`, `mall_coupon_user`, `mall_order_coupon` - 优惠券相关表（用于优惠券使用统计）
  - 用户表（通过`mall_order.user_id`关联，用于会员分析，需会员模块支持）

## 功能清单

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

#### 已实现功能 ✅

##### 商品管理 (SPU)

- ✅ 商品CRUD操作
    - 商品列表查询（分页、条件筛选）
    - 商品详情查询
    - 商品新增/修改/删除
    - 商品上架/下架
- ✅ 商品浏览量和销量统计
    - 浏览量自动统计
    - 销量自动累计
- ✅ 商品详情管理
    - 商品描述和详情富文本支持
    - 商品图片管理（封面、轮播图）

##### SKU管理

- ✅ SKU CRUD操作
    - SKU列表查询（支持按商品ID查询）
    - SKU详情查询
    - SKU新增/修改/删除
- ✅ SKU库存管理
    - 库存数量管理
    - 库存扣减和恢复
- ✅ SKU规格属性管理
    - 规格属性JSON格式存储
    - 规格属性查询和展示

##### 商品分类管理 ✅

- ✅ 分类树形结构查询
    - 支持三级分类树形结构
    - 管理端和移动端分类树查询
- ✅ 分类CRUD操作
    - 分类列表查询（分页、条件筛选）
    - 分类详情查询
    - 分类新增/修改/删除
    - 分类导出功能
- ✅ 分类排序
    - 支持自定义排序字段
- ⏳ 分类图标管理
    - 字段已支持，需前端集成文件上传功能

##### 品牌管理 ✅

- ✅ 品牌CRUD操作
    - 品牌列表查询（分页、条件筛选）
    - 品牌详情查询
    - 品牌新增/修改/删除
    - 品牌导出功能
- ✅ 品牌描述管理
    - 品牌描述字段支持
- ✅ 品牌排序
    - 支持自定义排序字段
- ✅ 品牌状态管理
    - 启用/禁用状态控制
- ⏳ 品牌Logo上传
    - 字段已支持，需前端集成文件上传功能

##### 商品属性管理 ✅

- ✅ 属性模板管理
    - ✅ 属性模板CRUD操作
    - ✅ 属性模板绑定分类（可选）
    - ✅ 属性模板导出功能
- ✅ 属性管理
    - ✅ 属性CRUD操作
    - ✅ 属性类型管理（文本、数字、日期、枚举）
    - ✅ 属性绑定模板（可选）
    - ✅ 属性必填设置
    - ✅ 属性导出功能
- ✅ 属性值管理
    - ✅ 属性值CRUD操作
    - ✅ 属性值绑定属性
    - ✅ 属性值排序
    - ✅ 属性值导出功能
- ✅ 商品属性关联
    - ✅ 商品关联属性值
    - ✅ 批量保存商品属性
    - ✅ 根据商品ID查询属性
    - ✅ 支持枚举类型属性值选择
    - ✅ 支持文本/数字/日期类型自定义值

#### 待实现功能 ⏳

- [ ] 商品规格模板系统增强
    - ⏳ 规格模板独立管理（当前规格通过SKU的specs字段JSON存储）
    - ⏳ 规格模板与属性模板区分管理
    - ⏳ 规格值标准化管理
    - ⏳ 规格模板可视化配置
    - **说明**: 当前系统中，SKU规格通过`mall_sku.specs`字段以JSON格式存储。属性模板系统(`mall_attribute_template`)可用于管理商品属性，但规格模板作为独立的规格管理系统，可用于标准化管理商品SKU的规格组合（如颜色+尺寸等），支持规格模板定义、规格值管理和规格模板与商品关联等功能。
- [ ] 商品搜索功能
    - [ ] 全文搜索（集成Elasticsearch或类似方案）
        - 商品名称、描述全文搜索
        - 搜索关键词高亮
        - 搜索排序优化（按相关度、销量、价格等）
    - [ ] 商品筛选（按分类、品牌、价格等）
        - 多条件组合筛选
        - 属性值筛选
        - 价格区间筛选
        - 库存状态筛选
        - 筛选结果统计

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

#### 已实现功能 ✅

##### 购物车管理

- ✅ 购物车添加/删除
    - 添加商品到购物车
    - 删除购物车商品
    - 清空购物车
- ✅ 购物车数量修改
    - 修改购物车商品数量
- ✅ 购物车选中状态管理
    - 单个商品选中/取消选中
    - 批量选中/取消选中
- ✅ 购物车详情查询
    - 购物车列表查询
    - 购物车详情查询（包含商品和SKU完整信息）

##### 订单管理

- ✅ 订单创建
    - 从购物车创建订单
    - 直接购买创建订单
    - 订单明细自动生成
- ✅ 订单查询
    - 订单列表查询（分页、状态筛选）
    - 订单详情查询（包含订单明细）
- ✅ 订单取消
    - 用户主动取消订单
    - 订单取消后库存自动恢复
- ✅ 订单状态管理
    - 订单状态流转（待付款、待发货、待收货、已完成、已取消）
    - 支付状态管理
    - 发货状态管理
- ✅ 订单支付集成
    - 与支付中心（ruoyi-pay）集成
    - 支付回调处理
    - 支付成功后订单状态自动更新
    - 库存自动扣减

#### 待实现功能 ⏳

- [x] 售后管理 ✅
    - [x] 订单退款申请 ✅
    - [x] 退货申请 ✅
    - [x] 换货申请 ✅
    - [x] 售后审核 ✅
    - [x] 售后状态跟踪 ✅
    - [x] 退货物流跟踪 ✅
    - [x] 商家确认收货 ✅
    - [x] 完成售后处理 ✅
    - [x] 取消售后申请 ✅
- [x] 订单评价 ✅
    - [x] 订单评价提交 ✅
    - [x] 评价列表查询 ✅
    - [x] 评价回复（商家） ✅
    - [x] 评价审核 ✅
    - [ ] 评价图片上传（字段已支持，需前端上传功能）
- [x] 地址管理 ✅
    - [x] 收货地址管理（实体类、Mapper、Service、Controller已实现）✅
        - 收货地址CRUD操作
        - 用户地址列表查询
        - 默认地址查询
        - 地址导出功能（管理端）
    - [x] 默认地址设置 ✅
        - 设置默认地址接口
        - 自动取消其他默认地址
- [x] 订单优惠券使用 ✅
    - [x] 订单优惠券记录（实体类、Mapper、Service已实现）✅
    - [x] 优惠券金额计算（已实现CouponCalculator工具类和MallOrderCouponService.calculateAndUseCoupon方法）✅
        - 支持满减券、折扣券、现金券三种类型的金额计算
        - 已实现订单创建时的优惠券计算和使用流程
        - 已实现优惠金额统计方法（按订单ID、订单号、优惠券ID统计）

### 3. ruoyi-mall-coupon (优惠券中心)

#### 待实现功能 ⏳

- [x] 优惠券管理 ✅
    - [x] 优惠券CRUD操作 ✅
    - [x] 优惠券类型管理（满减、折扣、现金） ✅
    - [x] 优惠券发放规则配置 ✅
    - [x] 优惠券有效期管理 ✅
    - [x] 优惠券状态管理 ✅
- [x] 用户优惠券 ✅
    - [x] 用户领券 ✅
    - [x] 用户优惠券列表查询 ✅
    - [x] 优惠券使用（订单结算时） ✅
    - [x] 优惠券退还（订单取消时） ✅
    - [x] 优惠券过期处理（定时任务）✅
        - [x] **实现状态**: `MallCouponJob.processExpiredCoupons()`定时任务已实现，每天凌晨2点执行 ✅
- [x] 优惠券统计 ✅
    - [x] 发放统计（已实现统计接口）✅
    - [x] 使用统计（已实现统计接口）✅
    - [x] 使用率统计（已实现统计接口）✅
    - [ ] 核销金额统计（需集成订单优惠券使用记录表，当前返回0）

### 4. ruoyi-mall-promotion (营销中心)

#### 已实现功能 ✅

- [x] 营销活动管理 ✅
    - [x] 活动CRUD操作 ✅
    - [x] 活动类型管理 ✅
    - [x] 活动规则配置（JSON格式）✅
    - [x] 活动时间管理 ✅
    - [x] 活动状态管理 ✅
- [x] 秒杀功能 ✅
    - [x] 秒杀活动创建 ✅
    - [x] 秒杀库存管理（扣减、恢复）✅
    - [x] 秒杀活动查询 ✅
    - [x] 秒杀活动状态管理 ✅
    - [ ] 秒杀订单处理（需在交易中心集成）
    - [ ] 秒杀库存预扣（需在交易中心集成）
- [x] 拼团功能 ✅
    - [x] 拼团活动创建 ✅
    - [x] 拼团活动查询 ✅
    - [x] 拼团活动状态管理 ✅
    - [ ] 拼团订单创建（需在交易中心集成）
    - [ ] 拼团加入（需在交易中心集成）
    - [ ] 拼团成团处理（需在交易中心集成）
    - [ ] 拼团过期处理（定时任务）
- [x] 砍价功能 ✅
    - [x] 砍价活动创建 ✅
    - [x] 砍价活动查询 ✅
    - [x] 砍价活动状态管理 ✅
    - [ ] 砍价发起（需在交易中心集成）
    - [ ] 砍价助力（需在交易中心集成）
    - [ ] 砍价进度管理（需在交易中心集成）
    - [ ] 砍价订单处理（需在交易中心集成）
    - [ ] 砍价过期处理（定时任务）

#### 待实现功能 ⏳

- [ ] 订单集成（需在交易中心模块实现）
    - [x] 秒杀订单处理（核心逻辑已实现，待订单服务集成）✅
        - [x] **秒杀活动验证**（活动时间、库存、状态校验）✅
            - 验证秒杀活动是否存在且状态为启用（status=0）
            - 验证秒杀活动时间是否在有效期内（当前时间在start_time和end_time之间）
            - 验证秒杀库存是否充足（seckill_stock >= 购买数量）
            - 验证关联的营销活动（mall_promotion）是否启用
        - [x] **秒杀价格计算**（使用秒杀价而非原价）✅
            - 从`mall_seckill`表获取`seckill_price`（秒杀价，单位：分）
            - 订单明细价格使用秒杀价，而非SKU原价
            - 订单总金额基于秒杀价计算
            - **实现状态**: `SeckillOrderService.getSeckillPrice()`方法已实现
        - [x] **秒杀订单标记**（订单表记录活动类型和活动ID）✅
            - 订单表（`mall_order`）需包含字段：`promotion_type`（活动类型，2=秒杀）、`promotion_id`（营销活动ID）、`seckill_id`（秒杀ID）
            - SQL脚本已创建：`script/sql/mall_order_promotion_fields.sql`
            - 订单创建时记录活动信息，便于后续查询和统计
            - 订单明细表（`mall_order_item`）也建议记录活动价格信息
            - **实现状态**: SQL脚本已准备，待订单实体类和服务实现后集成
        - [x] **秒杀限购校验**（同一用户同一商品限购数量）✅
            - 查询用户已购买的秒杀订单数量（同一秒杀活动、同一SKU）
            - 校验是否超过限购数量（可从`mall_promotion.rules` JSON中读取限购规则，或默认每人限购1件）
            - 仅统计已支付的订单，待支付/已取消订单不计入限购
            - **实现状态**: `SeckillOrderService.validatePurchaseLimit()`方法已实现核心逻辑，但由于订单实体类尚未实现，限购查询部分待订单服务实现后完善
        - [ ] **秒杀订单超时处理**（未支付订单自动取消）⏳
            - 订单创建时记录创建时间，设置订单超时时间（如15分钟）
            - 定时任务扫描未支付的秒杀订单（订单状态=待支付，创建时间超过超时时间）
            - 自动取消订单并恢复预扣的秒杀库存
            - 发送订单超时取消通知给用户
            - **实现状态**: 待订单服务实现后添加定时任务
    - [x] 秒杀库存预扣 ✅
        - [x] **下单时预扣秒杀库存**（避免超卖）✅
            - 订单创建时调用`SeckillOrderService.preDeductSeckillStock(seckillId, quantity)`预扣秒杀库存
            - 使用数据库乐观锁（UPDATE ... WHERE seckill_stock >= quantity）确保并发安全
            - 预扣成功后，订单状态为"待支付"，库存已预扣但未最终确认
            - 如果预扣失败（库存不足），订单创建失败，返回库存不足提示
            - **实现状态**: `SeckillOrderService.preDeductSeckillStock()`方法已实现，调用`MallSeckillService.reduceStock()`
        - [x] **支付成功时确认库存扣减**✅
            - 支付回调处理时，订单状态更新为"已支付"
            - 预扣的秒杀库存此时正式扣减（预扣库存已在上一步完成，此处仅状态确认）
            - 如果订单已标记为秒杀订单，确认秒杀库存扣减成功
            - **实现状态**: 预扣逻辑已实现，支付确认需在订单服务的支付回调中调用
        - [x] **订单取消时恢复秒杀库存**✅
            - 用户主动取消订单或系统超时取消时，调用`SeckillOrderService.restoreSeckillStock(seckillId, quantity)`恢复秒杀库存
            - 仅恢复"待支付"状态的订单预扣库存
            - "已支付"订单取消需走退款流程，不恢复秒杀库存（秒杀商品通常不支持退款）
            - **实现状态**: `SeckillOrderService.restoreSeckillStock()`方法已实现，调用`MallSeckillService.restoreStock()`
        - [ ] **库存预扣超时释放机制**⏳
            - 订单创建时记录预扣时间，设置预扣超时时间（如15分钟，与订单超时时间一致）
            - 定时任务扫描预扣超时的订单（订单状态=待支付，创建时间超过超时时间）
            - 自动释放预扣库存并取消订单
            - 确保库存预扣和订单超时处理的一致性
            - **实现状态**: 待订单服务实现后添加定时任务
    - [ ] 拼团订单创建
        - 拼团活动验证（活动时间、库存、状态校验）
        - 创建拼团订单记录（`mall_group_buy_order`表）
        - 生成拼团编号（`group_no`）
        - 计算拼团过期时间（基于`duration_hours`）
        - 拼团价格计算（使用拼团价）
        - 拼团订单状态初始化（状态=0拼团中）
    - [ ] 拼团加入
        - 拼团编号验证（验证拼团是否存在且可加入）
        - 拼团状态校验（仅拼团中状态可加入）
        - 拼团人数校验（未达到成团人数）
        - 拼团过期校验（未超过过期时间）
        - 创建拼团订单记录（关联同一`group_no`）
        - 拼团人数自动累加
        - 自动检测成团条件（达到`group_size`人数）
    - [ ] 拼团成团处理
        - 成团条件判断（达到成团人数）
        - 更新拼团订单状态（状态=1已成团）
        - 记录成团时间（`success_time`）
        - 成团通知（通知所有参与用户）
        - 成团后订单状态流转（待发货等）
    - [ ] 砍价发起
        - 砍价活动验证（活动时间、库存、状态校验）
        - 创建砍价记录（`mall_bargain_record`表）
        - 生成砍价编号（`bargain_no`）
        - 初始化砍价价格（`current_price`=原价，`bargain_price`=0）
        - 计算砍价过期时间（基于`duration_hours`）
        - 砍价状态初始化（状态=0进行中）
        - 用户发起次数限制校验
    - [ ] 砍价助力
        - 砍价编号验证（验证砍价记录是否存在且有效）
        - 砍价状态校验（仅进行中状态可助力）
        - 砍价过期校验（未超过过期时间）
        - 助力用户校验（不能为自己助力、不能重复助力）
        - 计算助力金额（随机或固定算法，需达到最低价限制）
        - 创建助力记录（`mall_bargain_help`表）
        - 更新砍价进度（`current_price`、`bargain_price`、`help_count`）
        - 检测砍价完成条件（达到最低价或完成助力次数）
    - [ ] 砍价进度管理
        - 砍价进度查询（当前价格、已砍金额、助力人数、进度百分比）
        - 砍价列表查询（用户发起的砍价记录）
        - 砍价详情查询（包含助力记录列表）
        - 砍价状态更新（进行中、已成功、已失败、已下单）
        - 砍价完成检测（自动检测是否达到最低价）
    - [ ] 砍价订单处理
        - 砍价完成验证（状态=已成功）
        - 砍价价格使用（使用砍后价创建订单）
        - 订单标记（记录砍价记录ID）
        - 更新砍价状态（状态=3已下单）
        - 砍价订单超时处理（未支付订单释放砍价资格）
    - [x] 定时任务 ✅
        - [x] 秒杀活动状态更新任务 ✅
            - [x] 扫描即将开始的活动（`start_time` <= 当前时间 且 status=1禁用），自动启用（status=0）✅
            - [x] 扫描已结束的活动（`end_time` < 当前时间 且 status=0启用），自动禁用（status=1）✅
            - [x] 执行频率：每5分钟执行一次 ✅
            - [x] **实现状态**: `MallPromotionJob.updateSeckillStatus()`方法已实现
        - [ ] 拼团过期处理（定时任务）
            - 扫描过期拼团（`expire_time` < 当前时间 且 状态=拼团中）
            - 更新拼团状态（状态=2已失败）
            - 取消关联订单（取消所有关联的未支付订单）
            - 恢复库存（恢复拼团商品的库存）
            - 发送失败通知（通知所有参与用户）
            - 执行频率：建议每5-10分钟执行一次
            - **实现状态**: 待创建MallGroupBuyOrderMapper和相关Service方法后实现
        - [ ] 砍价过期处理（定时任务）
            - 扫描过期砍价（`expire_time` < 当前时间 且 状态=进行中）
            - 更新砍价状态（状态=2已失败）
            - 清理未使用的砍价记录
            - 发送失败通知（通知发起用户）
            - 执行频率：建议每10-30分钟执行一次
            - **实现状态**: 待创建MallBargainRecordMapper和相关Service方法后实现

### 5. ruoyi-mall-statistics (统计中心)

#### 已实现功能 ✅

- [x] 交易分析 ✅
    - [x] 订单统计（总订单数、总销售额） ✅
    - [x] 已支付订单统计（已支付订单数、已支付金额） ✅
    - [x] 退款金额统计 ✅
    - [x] 今日统计（今日订单数、今日销售额） ✅
    - [x] 商品销售排行（按销售金额排序） ✅
    - [x] 交易趋势分析（按日期分组统计） ✅

#### 待实现功能 ⏳

- [ ] 会员分析（需会员模块支持，当前系统可通过订单表`mall_order.user_id`实现基础统计）
    - [ ] 会员增长统计
        - 总会员数统计（基于用户表或订单表去重用户数）
        - 每日新增会员数统计（按注册时间或首次下单时间）
        - 会员增长趋势分析（按日期统计新增会员数）
        - 会员增长环比/同比增长分析
    - [ ] 会员消费统计
        - 会员总消费金额统计（按用户ID聚合订单金额）
        - 会员平均消费金额（总消费/会员数）
        - 会员消费排行（按消费金额排序）
        - 会员消费分布分析（消费区间分布）
        - 高价值会员识别（消费金额Top N会员）
    - [ ] 会员活跃度分析
        - 活跃会员数统计（有订单的会员数）
        - 会员活跃度等级划分（根据下单频率、消费金额等）
        - 会员留存率分析（新会员留存、老会员复购）
        - 会员流失分析（长期未下单会员识别）
- [ ] 商品分析（基于现有`mall_product`、`mall_order_item`表实现）
    - [ ] 商品销售统计（部分功能可通过交易统计的商品排行实现）
        - 商品销售金额统计（按商品ID聚合订单明细）
        - 商品销售数量统计（按商品ID聚合订单数量）
        - 商品销售趋势分析（按日期统计商品销售）
        - 商品销售排行（按销售金额、销售数量排序）
        - 商品分类销售统计（按商品分类聚合统计）
        - 商品品牌销售统计（按品牌聚合统计）
    - [ ] 商品浏览统计（商品表已有`view_count`字段，需商品模块支持浏览统计接口）
        - 商品浏览量统计（基于`mall_product.view_count`字段）
        - 商品浏览量排行（按浏览量排序）
        - 商品浏览趋势分析（需记录浏览日志表或通过商品表`view_count`字段）
        - 热门商品识别（浏览量Top N商品）
        - 商品浏览与销售关联分析
    - [ ] 商品转化率分析
        - 商品转化率计算（订单数/浏览量，或销量/浏览量）
        - 商品转化率排行（按转化率排序）
        - 高转化率商品识别
        - 低转化率商品分析（识别需优化商品）
        - 商品浏览到下单转化漏斗分析
- [ ] 营销分析（基于`mall_promotion`、`mall_coupon`、`mall_order`表实现）
    - [ ] 活动效果统计（需营销模块支持，基于`mall_promotion`和订单表关联）
        - 活动参与人数统计（参与活动的订单用户数）
        - 活动订单数统计（按活动ID聚合订单）
        - 活动销售额统计（活动订单的销售金额）
        - 活动转化率分析（活动订单数/活动参与人数）
        - 活动类型效果对比（拼团、秒杀、砍价等活动效果对比）
        - 活动ROI分析（活动投入成本 vs 活动带来的销售额）
        - 活动效果趋势分析（按日期统计活动效果）
    - [ ] 优惠券使用统计（基于`mall_coupon`、`mall_coupon_user`、`mall_order_coupon`表）
        - 优惠券发放统计（优惠券发放数量，基于`mall_coupon_user`表）
        - 优惠券使用统计（优惠券使用数量，`mall_coupon_user.status=1`）
        - 优惠券使用率统计（使用数/发放数）
        - 优惠券核销金额统计（基于`mall_order_coupon.discount_amount`）
        - 优惠券类型使用对比（满减、折扣、现金券使用情况）
        - 优惠券使用趋势分析（按日期统计优惠券使用）
        - 优惠券效果分析（优惠券带来的订单和销售额）
    - [ ] 营销ROI分析
        - 营销活动总投入统计（活动成本计算）
        - 营销活动总产出统计（活动带来的销售额）
        - 营销ROI计算（产出/投入）
        - 各营销渠道ROI对比（活动、优惠券等）
        - 营销效果评估（投入产出比分析）
- [ ] 数据报表
    - [ ] 数据报表导出
        - 交易统计报表导出（Excel格式）
        - 商品销售报表导出
        - 会员统计报表导出
        - 营销活动报表导出
        - 自定义报表配置和导出
    - [ ] 数据可视化接口
        - 图表数据接口（支持折线图、柱状图、饼图等）
        - 实时数据统计接口
        - 数据大屏数据接口
        - 数据导出格式支持（Excel、PDF、CSV等）

## API接口详细说明

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

#### 管理端接口

##### 商品管理 (`/mall/product`)

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

##### 商品分类管理 (`/mall/product/category`)

- `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}` - 删除商品分类
- `POST /mall/product/category/export` - 导出商品分类列表

##### 品牌管理 (`/mall/product/brand`)

- `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` - 导出品牌列表

##### 属性模板管理 (`/mall/product/attribute/template`)

- `GET /mall/product/attribute/template/list` - 查询属性模板列表（分页）
- `GET /mall/product/attribute/template/{id}` - 获取属性模板详情
- `POST /mall/product/attribute/template` - 新增属性模板
- `PUT /mall/product/attribute/template` - 修改属性模板
- `DELETE /mall/product/attribute/template/{ids}` - 删除属性模板
- `POST /mall/product/attribute/template/export` - 导出属性模板列表

##### 属性管理 (`/mall/product/attribute`)

- `GET /mall/product/attribute/list` - 查询属性列表（分页）
- `GET /mall/product/attribute/{id}` - 获取属性详情
- `GET /mall/product/attribute/template/{templateId}` - 根据模板ID查询属性列表
- `POST /mall/product/attribute` - 新增属性
- `PUT /mall/product/attribute` - 修改属性
- `DELETE /mall/product/attribute/{ids}` - 删除属性
- `POST /mall/product/attribute/export` - 导出属性列表

##### 属性值管理 (`/mall/product/attribute/value`)

- `GET /mall/product/attribute/value/list` - 查询属性值列表（分页）
- `GET /mall/product/attribute/value/{id}` - 获取属性值详情
- `GET /mall/product/attribute/value/attribute/{attributeId}` - 根据属性ID查询属性值列表
- `POST /mall/product/attribute/value` - 新增属性值
- `PUT /mall/product/attribute/value` - 修改属性值
- `DELETE /mall/product/attribute/value/{ids}` - 删除属性值
- `POST /mall/product/attribute/value/export` - 导出属性值列表

##### 商品属性关联管理 (`/mall/product/attribute/product`)

- `GET /mall/product/attribute/product/{id}` - 获取商品属性关联详情
- `GET /mall/product/attribute/product/product/{productId}` - 根据商品ID查询商品属性关联列表
- `POST /mall/product/attribute/product` - 新增商品属性关联
- `POST /mall/product/attribute/product/batch` - 批量新增商品属性关联
- `POST /mall/product/attribute/product/product/{productId}` - 保存商品属性关联（先删除旧的，再插入新的）
- `PUT /mall/product/attribute/product` - 修改商品属性关联
- `DELETE /mall/product/attribute/product/{ids}` - 删除商品属性关联
- `DELETE /mall/product/attribute/product/product/{productId}` - 根据商品ID删除商品属性关联

#### 移动端接口

##### 商品分类 (`/app/mall/product/category`)

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

##### 品牌 (`/app/mall/product/brand`)

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

##### 商品 (`/app/mall/product`)

- `GET /app/mall/product/list` - 查询商品列表（仅上架商品）
- `GET /app/mall/product/{id}` - 获取商品详情（仅上架商品）

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

#### 管理端接口

##### 订单管理 (`/mall/order`)

- `GET /mall/order/list` - 查询订单列表（分页、条件筛选）
- `GET /mall/order/{id}` - 获取订单详情
- `PUT /mall/order` - 修改订单
- `DELETE /mall/order/{ids}` - 删除订单
- `PUT /mall/order/delivery/{id}` - 订单发货

##### 售后申请管理 (`/mall/order/after-sale`)

- `GET /mall/order/after-sale/list` - 查询售后申请列表（分页）
- `GET /mall/order/after-sale/{id}` - 获取售后申请详情
- `DELETE /mall/order/after-sale/{ids}` - 删除售后申请
- `POST /mall/order/after-sale/export` - 导出售后申请列表
- `PUT /mall/order/after-sale/audit/{id}` - 审核售后申请（同意/拒绝）
- `PUT /mall/order/after-sale/receive/{id}` - 确认收货（商家确认收到退货）
- `PUT /mall/order/after-sale/complete/{id}` - 完成售后

##### 订单评价管理 (`/mall/order/evaluate`)

- `GET /mall/order/evaluate/list` - 查询订单评价列表（分页）
- `GET /mall/order/evaluate/{id}` - 获取订单评价详情
- `DELETE /mall/order/evaluate/{ids}` - 删除订单评价
- `POST /mall/order/evaluate/export` - 导出订单评价列表
- `PUT /mall/order/evaluate/audit/{id}` - 审核评价（通过/驳回）
- `PUT /mall/order/evaluate/reply/{id}` - 回复评价

#### 移动端接口

##### 购物车 (`/app/mall/cart`)

- `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` - 批量更新选中状态

##### 订单 (`/app/mall/order`)

- `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` - 支付回调（由支付中心调用）

##### 售后申请 (`/app/mall/order/after-sale`)

- `GET /app/mall/order/after-sale/list` - 查询售后申请列表
- `GET /app/mall/order/after-sale/order/{orderId}` - 根据订单ID查询售后申请列表
- `GET /app/mall/order/after-sale/{id}` - 获取售后申请详情
- `POST /app/mall/order/after-sale` - 新增售后申请（退款/退货/换货）
- `PUT /app/mall/order/after-sale/logistics/{id}` - 填写退货物流信息
- `PUT /app/mall/order/after-sale/cancel/{id}` - 取消售后申请

##### 订单评价 (`/app/mall/order/evaluate`)

- `GET /app/mall/order/evaluate/list` - 查询订单评价列表
- `GET /app/mall/order/evaluate/order/{orderId}` - 根据订单ID查询评价列表
- `GET /app/mall/order/evaluate/product/{productId}` - 根据商品ID查询评价列表（仅已审核）
- `GET /app/mall/order/evaluate/{id}` - 获取订单评价详情
- `POST /app/mall/order/evaluate` - 提交订单评价

##### 优惠券 (`/app/mall/coupon`)

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

##### 用户优惠券 (`/app/mall/coupon/user`)

- `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}` - 领取优惠券

### 3. ruoyi-mall-coupon (优惠券中心)

#### 管理端接口

##### 优惠券管理 (`/mall/coupon`)

- `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/statistics` - 获取优惠券统计信息（发放数量、使用数量、使用率）

##### 用户优惠券管理 (`/mall/coupon/user`)

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

### 4. ruoyi-mall-promotion (营销中心)

#### 管理端接口

##### 营销活动管理 (`/mall/promotion`)

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

##### 秒杀活动管理 (`/mall/seckill`)

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

##### 拼团活动管理 (`/mall/groupbuy`)

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

##### 砍价活动管理 (`/mall/bargain`)

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

#### 移动端接口

##### 营销活动 (`/app/mall/promotion`)

- `GET /app/mall/promotion/list` - 查询营销活动列表（可按类型筛选）
- `GET /app/mall/promotion/{id}` - 获取营销活动详情

##### 秒杀活动 (`/app/mall/seckill`)

- `GET /app/mall/seckill/list` - 查询可用秒杀活动列表
- `GET /app/mall/seckill/{id}` - 获取秒杀活动详情
- `GET /app/mall/seckill/sku/{skuId}` - 根据SKU ID查询秒杀活动

##### 拼团活动 (`/app/mall/groupbuy`)

- `GET /app/mall/groupbuy/list` - 查询可用拼团活动列表
- `GET /app/mall/groupbuy/{id}` - 获取拼团活动详情
- `GET /app/mall/groupbuy/sku/{skuId}` - 根据SKU ID查询拼团活动

##### 砍价活动 (`/app/mall/bargain`)

- `GET /app/mall/bargain/list` - 查询可用砍价活动列表
- `GET /app/mall/bargain/{id}` - 获取砍价活动详情
- `GET /app/mall/bargain/sku/{skuId}` - 根据SKU ID查询砍价活动

### 5. ruoyi-mall-statistics (统计中心)

#### 管理端接口

##### 统计数据 (`/mall/statistics`)

- `GET /mall/statistics/transaction` - 获取交易统计数据
  - 支持按日期范围查询（startDate, endDate）
  - 支持设置商品销售排行数量限制（limit，默认10）
  - 返回数据包括：总订单数、总销售额、已支付订单数、已支付金额、退款金额、今日统计、趋势数据、商品销售排行
- `GET /mall/statistics/member` - 获取会员统计数据
  - 支持按日期范围查询（startDate, endDate）
  - 返回数据包括：总会员数、今日新增会员数、活跃会员数、增长趋势、消费统计
  - ⚠️ 注意：会员统计功能需要会员模块支持，当前返回基础结构

## 定时任务规划

### 优惠券模块

- [x] 优惠券过期处理任务 ✅
    - **功能**: 定时扫描过期的用户优惠券，更新状态为已过期
    - **执行频率**: 每天凌晨2点执行一次
    - **实现位置**: `ruoyi-mall-coupon` 模块
    - **方法**: `MallCouponJob.processExpiredCoupons()` (调用 `MallCouponUserService.processExpiredCoupons()`)

### 营销模块

- [ ] 拼团过期处理任务
    - **功能**: 定时扫描过期的拼团订单，更新状态为已失败，处理退款
    - **执行频率**: 每5分钟执行一次
    - **实现位置**: `ruoyi-mall-promotion` 模块
- [ ] 砍价过期处理任务
    - **功能**: 定时扫描过期的砍价记录，更新状态为已失败
    - **执行频率**: 每5分钟执行一次
    - **实现位置**: `ruoyi-mall-promotion` 模块
- [x] 秒杀活动状态更新任务 ✅
    - **功能**: 定时更新秒杀活动状态（开始/结束）
    - **执行频率**: 每5分钟执行一次
    - **实现位置**: `ruoyi-mall-promotion` 模块
    - **方法**: `MallPromotionJob.updateSeckillStatus()`

### 订单模块（可选）

- [ ] 订单自动取消任务
    - **功能**: 定时扫描超时未支付的订单，自动取消并恢复库存
    - **执行频率**: 每10分钟执行一次
    - **实现位置**: `ruoyi-mall-trade` 模块

## 技术栈与开发规范

### 技术栈

- **框架**: Spring Boot 3.x
- **ORM**: MyBatis-Plus
- **数据库**: MySQL 8.0+
- **认证**: Sa-Token
- **API文档**: Swagger/OpenAPI 3.0
- **构建工具**: Maven

### 开发规范

#### 包结构规范

- `controller` - 控制器层（分为 `admin` 和 `app` 两个子包）
- `domain` - 实体类（包含 `bo` 业务对象和 `vo` 视图对象子包）
- `mapper` - MyBatis Mapper 接口
- `service` - 服务接口（实现类放在 `impl` 子包）
- `config` - 配置类（自动配置类）
- `enums` - 枚举类
- `job` - 定时任务（可选）

#### 代码规范

- 统一使用 Lombok 简化代码
- 统一异常处理，使用 `ServiceException` 抛出业务异常
- 统一返回格式，使用 `R<T>` 封装返回结果
- 统一分页查询，使用 `PageQuery` 和 `TableDataInfo<T>`
- 统一日志记录，使用 `@Log` 注解记录操作日志
- 统一权限控制，管理端接口使用 `@SaCheckPermission` 注解

#### 数据库设计规范

- 表名使用 `mall_` 前缀
- 字段命名使用下划线命名法（snake_case）
- 必须包含 `create_by`, `create_time`, `update_by`, `update_time` 字段
- 删除标记使用逻辑删除（`deleted` 字段）
- 状态字段统一使用 `status`，0表示启用/正常，1表示禁用/异常

#### API设计规范

- RESTful 风格设计
- 管理端接口路径：`/mall/{module}/{resource}`
- 移动端接口路径：`/app/mall/{module}/{resource}`
- 使用 HTTP 标准方法：GET（查询）、POST（新增）、PUT（修改）、DELETE（删除）
- 统一使用 JSON 格式进行数据交互
- 使用 Swagger 注解完善接口文档

## 模块集成说明

### 支付中心集成 (ruoyi-pay)

- **集成方式**: 通过 Feign 客户端或本地 Jar 依赖
- **核心功能**:
    - 订单提交时调用支付中心创建支付单
    - 支付中心回调通知支付结果
    - 订单状态与支付状态同步
- **配置要求**: 在 `application.yml` 中配置 `pay-app-id` 和 `pay-notify-url`

### 商品中心依赖关系

- `ruoyi-mall-trade` 依赖 `ruoyi-mall-product`（查询商品和SKU信息）
- `ruoyi-mall-promotion` 依赖 `ruoyi-mall-product`（营销活动关联商品）
- `ruoyi-mall-statistics` 依赖 `ruoyi-mall-product` 和 `ruoyi-mall-trade`（数据统计分析）

## 开发指南

### 新增功能开发步骤

1. **数据库设计**
    - 在 `script/sql/ry_mall.sql` 中设计表结构
    - 确保字段命名规范，包含必要的索引

2. **创建实体类**
    - 在对应模块的 `domain` 包下创建实体类
    - 创建对应的 `Bo`（业务对象）和 `Vo`（视图对象）

3. **创建 Mapper**
    - 在 `mapper` 包下创建 Mapper 接口
    - 如需复杂查询，在 `resources/mapper` 下创建 XML 文件

4. **创建 Service**
    - 在 `service` 包下创建 Service 接口
    - 在 `service/impl` 包下创建 Service 实现类

5. **创建 Controller**
    - 管理端接口：在 `controller/admin` 包下创建
    - 移动端接口：在 `controller/app` 包下创建
    - 添加 Swagger 注解完善接口文档

6. **测试验证**
    - 编写单元测试（可选）
    - 使用 Swagger UI 测试接口
    - 验证业务逻辑正确性

### 代码迁移指南

如果要将现有代码迁移到新模块结构：

1. **创建新模块结构**（如果尚未创建）
2. **复制代码到新模块**
3. **修改包名**（如 `org.dromara.mall.domain` → `org.dromara.mall.product.domain`）
4. **更新导入语句**
5. **更新 Mapper XML 文件中的命名空间**
6. **测试验证功能正常**

## 注意事项

1. **包名冲突**: 如果同时保留现有代码和新模块代码，需要注意包名冲突问题
2. **依赖管理**: 确保模块间的依赖关系正确配置，避免循环依赖
3. **数据库迁移**: 执行 SQL 文件创建新表结构，注意数据迁移（如果需要）
4. **配置管理**: 各子模块的配置通过 `spring.factories` 自动加载
5. **事务管理**: 订单创建、支付回调等核心流程需要确保事务一致性
6. **库存管理**: SKU库存扣减需要考虑并发问题，建议使用分布式锁或数据库锁（悲观锁/乐观锁）
7. **支付集成**: 订单支付需要与 `ruoyi-pay` 模块集成，确保支付流程正确
8. **数据统计**: 统计模块建议使用异步处理，避免影响业务性能
9. **文件上传**: 商品图片、品牌Logo、分类图标等文件上传功能需要集成文件服务（如OSS）
10. **缓存策略**: 商品列表、分类树等热点数据建议使用Redis缓存
11. **幂等性**: 支付回调、订单创建等关键操作需要保证幂等性
12. **数据一致性**: 订单创建、库存扣减等操作需要在同一事务中完成