# 运营活动管理模块

## 功能说明

本模块用于管理商户的运营活动，支持活动的创建、查询、更新和删除操作。活动可以设置参与规则、奖励类型、优惠券等信息。

---

## 数据库表结构

### store_operational_activity 表

```sql
CREATE TABLE `store_operational_activity` (
    `id` int NOT NULL AUTO_INCREMENT COMMENT '主键',
    `store_id` int NULL COMMENT '商户ID',
    `activity_name` VARCHAR(100) NOT NULL COMMENT '活动名称',
    `promotional_image` VARCHAR(500) DEFAULT NULL COMMENT '活动宣传图URL',
    `start_time` DATETIME NOT NULL COMMENT '活动开始时间',
    `end_time` DATETIME NOT NULL COMMENT '活动结束时间',
    `participation_limit` int DEFAULT 0 COMMENT '用户可参与次数，0表示不限制',
    `activity_rule` VARCHAR(50) NOT NULL COMMENT '活动规则：VERIFY_AND_COMMENT-核销并评论, VERIFY-核销, CHECK_IN-打卡',
    `reward_type` VARCHAR(50) DEFAULT NULL COMMENT '奖励类型：COUPON-优惠券, RED_PACKET-红包',
    `coupon_id` int DEFAULT NULL COMMENT '优惠券ID，关联优惠券表',
    `coupon_quantity` int DEFAULT NULL COMMENT '优惠券发放数量',
    `status` int DEFAULT 1 COMMENT '状态：0-禁用, 1-启用',
    `delete_flag` int NOT NULL DEFAULT '0' COMMENT '删除标记, 0:未删除, 1:已删除',
    `created_time` datetime(1) NOT NULL COMMENT '创建时间',
    `created_user_id` int DEFAULT NULL COMMENT '创建人ID',
    `updated_time` datetime DEFAULT NULL COMMENT '修改时间',
    `updated_user_id` int DEFAULT NULL COMMENT '修改人ID',
    PRIMARY KEY (`id`),
    INDEX `idx_activity_time` (`start_time`, `end_time`),
    INDEX `idx_status` (`status`, `delete_flag`),
    INDEX `idx_coupon_id` (`coupon_id`),
    INDEX `idx_create_time` (`created_time`)
) ENGINE=InnoDB AUTO_INCREMENT=1 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='运营活动表';
```

---

## 文件清单

### 1. Entity（实体类）
**路径**: `alien-entity/src/main/java/shop/alien/entity/store/StoreOperationalActivity.java`

**功能**: 运营活动实体类，对应数据库表 `store_operational_activity`

**主要字段**:
- `id`: 主键
- `storeId`: 商户ID
- `activityName`: 活动名称
- `promotionalImage`: 活动宣传图URL
- `startTime`: 活动开始时间
- `endTime`: 活动结束时间
- `participationLimit`: 用户可参与次数（0表示不限制）
- `activityRule`: 活动规则（VERIFY_AND_COMMENT-核销并评论, VERIFY-核销, CHECK_IN-打卡）
- `rewardType`: 奖励类型（COUPON-优惠券, RED_PACKET-红包）
- `couponId`: 优惠券ID
- `couponQuantity`: 优惠券发放数量
- `status`: 状态（0-禁用, 1-启用）
- `deleteFlag`: 删除标记（逻辑删除）
- `createdTime`: 创建时间（自动填充）
- `createdUserId`: 创建人ID
- `updatedTime`: 修改时间（自动填充）
- `updatedUserId`: 修改人ID

---

### 2. DTO（数据传输对象）
**路径**: `alien-entity/src/main/java/shop/alien/entity/store/vo/StoreOperationalActivityDTO.java`

**功能**: 用于接收前端请求参数，包含参数校验

**校验规则**:
- `activityName`: 必填，不能为空
- `startTime`: 必填，不能为空
- `endTime`: 必填，不能为空
- `activityRule`: 必填，不能为空
- 其他字段可选

---

### 3. VO（视图对象）
**路径**: `alien-entity/src/main/java/shop/alien/entity/store/vo/StoreOperationalActivityVO.java`

**功能**: 用于返回给前端的数据对象，继承自实体类并扩展了额外字段

**扩展字段**:
- `statusName`: 状态名称
- `activityRuleName`: 活动规则名称
- `rewardTypeName`: 奖励类型名称
- `couponName`: 优惠券名称
- `storeName`: 商户名称
- `activityStatus`: 活动状态（0-未开始, 1-进行中, 2-已结束）
- `participationCount`: 已参与人数
- `remainingCouponQuantity`: 剩余优惠券数量

---

### 4. Mapper（数据访问层）
**路径**: `alien-entity/src/main/java/shop/alien/mapper/StoreOperationalActivityMapper.java`

**功能**: 继承 MyBatis-Plus 的 `BaseMapper`，提供基础 CRUD 操作

---

### 5. Mapper XML（映射文件）
**路径**: `alien-entity/src/main/resources/mapper/StoreOperationalActivityMapper.xml`

**功能**: MyBatis 映射配置文件，定义结果集映射和通用 SQL

---

### 6. Service（服务接口）
**路径**: `alien-store-platform/src/main/java/shop/alien/storeplatform/service/OperationalActivityService.java`

**功能**: 定义运营活动业务逻辑接口

**方法列表**:
- `createActivity(StoreOperationalActivityDTO dto)`: 创建运营活动
- `updateActivity(StoreOperationalActivityDTO dto)`: 更新运营活动
- `deleteActivity(Integer id)`: 删除运营活动（逻辑删除）
- `getActivityById(Integer id)`: 根据ID获取活动详情
- `getActivityListByStoreId(Integer storeId)`: 根据商户ID获取活动列表
- `getActivityPage(Integer current, Integer size, Integer storeId, Integer status)`: 分页查询活动列表
- `updateActivityStatus(Integer id, Integer status)`: 启用/禁用活动
- `getOngoingActivities(Integer storeId)`: 获取进行中的活动列表

---

### 7. ServiceImpl（服务实现类）
**路径**: `alien-store-platform/src/main/java/shop/alien/storeplatform/service/impl/OperationalActivityServiceImpl.java`

**功能**: 实现运营活动业务逻辑

**核心功能**:
- 活动的增删改查
- 实体与VO对象的转换
- 活动状态的自动判断（未开始/进行中/已结束）
- 活动规则和奖励类型的中文名称转换

---

### 8. Controller（控制器）
**路径**: `alien-store-platform/src/main/java/shop/alien/storeplatform/controller/OperationalActivityController.java`

**功能**: 提供运营活动管理的 REST API 接口

**API 列表**:

#### 8.1 创建运营活动
- **接口**: `POST /operationalActivity/create`
- **参数**: StoreOperationalActivityDTO（JSON）
- **返回**: R<String>

#### 8.2 更新运营活动
- **接口**: `POST /operationalActivity/update`
- **参数**: StoreOperationalActivityDTO（JSON）
- **返回**: R<String>

#### 8.3 删除运营活动
- **接口**: `DELETE /operationalActivity/delete`
- **参数**: id（活动ID）
- **返回**: R<String>

#### 8.4 根据ID获取活动详情
- **接口**: `GET /operationalActivity/detail`
- **参数**: id（活动ID）
- **返回**: R<StoreOperationalActivityVO>

#### 8.5 根据商户ID获取活动列表
- **接口**: `GET /operationalActivity/list`
- **参数**: storeId（商户ID）
- **返回**: R<List<StoreOperationalActivityVO>>

#### 8.6 分页查询活动列表
- **接口**: `GET /operationalActivity/page`
- **参数**: 
  - current（当前页，默认1）
  - size（每页大小，默认10）
  - storeId（商户ID，可选）
  - status（状态，可选）
- **返回**: R<IPage<StoreOperationalActivityVO>>

#### 8.7 启用/禁用活动
- **接口**: `POST /operationalActivity/updateStatus`
- **参数**: 
  - id（活动ID）
  - status（状态：0-禁用, 1-启用）
- **返回**: R<String>

#### 8.8 获取进行中的活动列表
- **接口**: `GET /operationalActivity/ongoing`
- **参数**: storeId（商户ID）
- **返回**: R<List<StoreOperationalActivityVO>>

---

## 使用示例

### 创建活动

```json
POST /operationalActivity/create

{
  "storeId": 1,
  "activityName": "双十一优惠活动",
  "promotionalImage": "https://example.com/image.jpg",
  "startTime": "2025-11-11 00:00:00",
  "endTime": "2025-11-11 23:59:59",
  "participationLimit": 1,
  "activityRule": "VERIFY_AND_COMMENT",
  "rewardType": "COUPON",
  "couponId": 100,
  "couponQuantity": 1000,
  "status": 1
}
```

### 查询活动列表

```
GET /operationalActivity/list?storeId=1
```

### 分页查询

```
GET /operationalActivity/page?current=1&size=10&storeId=1&status=1
```

---

## 数据字典

### 活动规则（activity_rule）
- `VERIFY_AND_COMMENT`: 核销并评论
- `VERIFY`: 核销
- `CHECK_IN`: 打卡

### 奖励类型（reward_type）
- `COUPON`: 优惠券
- `RED_PACKET`: 红包

### 活动状态（status）
- `0`: 禁用
- `1`: 启用

### 活动进行状态（activityStatus）
- `0`: 未开始
- `1`: 进行中
- `2`: 已结束

---

## 注意事项

1. **时间校验**: 创建活动时，需要确保结束时间晚于开始时间
2. **逻辑删除**: 删除操作为逻辑删除，不会真正删除数据
3. **状态管理**: 活动状态由系统根据当前时间自动判断
4. **参数校验**: DTO 中包含必填项校验，需要确保必填字段不为空
5. **优惠券关联**: 如果奖励类型为优惠券，需要填写 couponId 和 couponQuantity

---

## 扩展建议

1. **用户参与记录**: 可以创建用户参与活动记录表，跟踪用户参与情况
2. **活动统计**: 添加活动效果统计功能，如参与人数、发放优惠券数量等
3. **活动审核**: 添加活动审核流程，确保活动内容合规
4. **活动推送**: 集成消息推送功能，在活动开始时通知用户
5. **活动模板**: 提供常用活动模板，简化活动创建流程

---

## 更新日志

### 2025-11-26
- 初始版本发布
- 实现基础的增删改查功能
- 支持活动状态管理
- 支持分页查询