# 开心农场活动模块

## 1. 模块简介

活动模块是开心农场系统中的核心功能模块之一，负责管理和执行各类游戏活动，包括礼包活动、限时活动等。该模块提供了活动配置、奖励管理、参与记录和进度追踪等功能，为游戏提供丰富多样的活动体验。

## 2. 功能概述

- **礼包活动系统**：支持推荐礼包、补偿礼包、新人礼包、认证礼包等多种类型，支持单个道具或物品组奖励
- **限时活动系统**：支持设置活动开始和结束时间，自动开启和关闭
- **活动管理功能**：支持活动的创建、发布、暂停、结束等状态管理

## 3. 目录结构

```
app/Module/Activity/
├── AdminControllers/        # 后台管理控制器
│   ├── Helper/              # 控制器辅助类
│   ├── Actions/             # 控制器动作类
│   └── LazyRenderable/      # 懒加载渲染类
├── Commands/                # 命令行工具
├── Databases/               # 数据库相关文件
│   └── GenerateSql/         # 数据库创建脚本
├── Dtos/                    # 数据传输对象
├── Enums/                   # 枚举类型定义
├── Events/                  # 事件类
├── Exceptions/              # 异常类
├── Listeners/               # 事件监听器
├── Logics/                  # 业务逻辑类
├── Models/                  # 数据模型
├── Providers/               # 服务提供者
├── Repositorys/             # 数据仓库
├── Services/                # 服务类
└── Docs/                    # 模块文档
```

## 4. 核心组件

- **模型层**：ActivityConfig, ActivityReward, ActivityParticipation, UserActivityData等
- **仓库层**：ActivityConfigRepository, ActivityRewardRepository等
- **逻辑层**：ActivityLogic, RewardLogic, ParticipationLogic, ProgressLogic等
- **服务层**：ActivityService, RewardService, ActivityManagementService等
- **事件系统**：ActivityCreatedEvent, UserParticipatedEvent, ActivityCompletedEvent等

## 5. 文档索引

- [系统概述](./Docs/系统概述.md)：活动模块的整体介绍和功能概述
- [架构设计](./Docs/架构设计.md)：活动模块的架构设计和核心组件
- [数据库设计](./Docs/数据库设计.md)：活动模块的数据库表结构和关系
- [事件系统](./Docs/事件系统.md)：活动模块的事件定义和监听器
- [服务接口](./Docs/服务接口.md)：活动模块对外提供的服务接口
- [开发规划](./Docs/DEV.md)：活动模块的开发计划和里程碑

## 6. 使用示例

### 6.1 获取活动列表

```php
// 在其他模块中调用活动服务
$activityService = app(ActivityService::class);

// 获取用户可参与的所有活动
$activities = $activityService->getActivityList($userId);
```

### 6.2 用户参与活动

```php
// 在其他模块中调用活动服务
$activityService = app(ActivityService::class);

try {
    // 用户参与活动
    $result = $activityService->participateActivity($userId, $activityId);

    // 处理参与结果
    if ($result['success']) {
        // 参与成功，可以进行后续操作
    }
} catch (ActivityException $e) {
    // 处理参与失败的情况
}
```

### 6.3 领取活动奖励

```php
// 在其他模块中调用奖励服务
$rewardService = app(RewardService::class);

try {
    // 领取活动奖励
    $result = $rewardService->claimRewards($userId, $activityId);

    // 处理领取结果
    if ($result['success']) {
        // 领取成功，可以向用户展示获得的奖励
    }
} catch (RewardException $e) {
    // 处理领取失败的情况
}
```

## 7. 开发团队

- 产品经理：待定
- 后端开发：待定
- 前端开发：待定
- 测试工程师：待定

## 8. 版本历史

- v0.1.0 (计划中) - 基础架构搭建
- v0.2.0 (计划中) - 核心功能实现
- v0.3.0 (计划中) - 活动类型实现
- v0.4.0 (计划中) - 后台管理界面
- v1.0.0 (计划中) - 正式版本发布