活动模块架构设计

1. 目录结构

活动模块采用标准的模块化目录结构，便于代码组织和维护：

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

2. 核心组件

2.1 模型层 (Models)

活动模块的核心数据模型包括：

ActivityConfig：活动基础配置模型，存储活动的基本信息
ActivityReward：活动奖励配置模型，定义活动的奖励内容
ActivityParticipation：活动参与记录模型，记录用户参与活动的情况
UserActivityData：用户活动数据模型，存储用户在活动中的进度

2.2 仓库层 (Repositorys)

仓库层封装数据访问逻辑，提供统一的数据操作接口：

ActivityConfigRepository：活动配置仓库，负责活动基础信息的CRUD操作
ActivityRewardRepository：活动奖励仓库，管理活动奖励配置
ActivityParticipationRepository：活动参与记录仓库，处理用户参与数据
UserActivityDataRepository：用户活动数据仓库，管理用户活动进度

2.3 逻辑层 (Logics)

逻辑层包含核心业务逻辑，仅供模块内部使用：

ActivityLogic：活动核心逻辑，处理活动状态变更、条件检查等
RewardLogic：奖励处理逻辑，负责奖励计算和发放规则
ParticipationLogic：参与逻辑，处理用户参与活动的业务规则
ProgressLogic：进度逻辑，计算和更新用户活动进度

2.4 服务层 (Services)

服务层对外提供功能接口，是模块与外部交互的主要方式：

ActivityService：活动服务，提供活动查询、参与、进度更新等功能
RewardService：奖励服务，处理奖励发放和领取
ActivityManagementService：活动管理服务，提供活动的创建、更新、发布等管理功能

2.5 控制器层 (AdminControllers)

控制器层处理HTTP请求，提供后台管理界面：

ActivityController：活动管理控制器，提供活动的CRUD操作界面
ActivityRewardController：活动奖励管理控制器，管理活动奖励配置
ActivityParticipationController：活动参与记录控制器，查看用户参与情况
UserActivityDataController：用户活动数据控制器，管理用户活动进度

2.6 事件系统 (Events & Listeners)

活动模块定义了以下核心事件：

ActivityCreatedEvent：活动创建事件
ActivityStartedEvent：活动开始事件
ActivityEndedEvent：活动结束事件
UserParticipatedEvent：用户参与活动事件
RewardClaimedEvent：奖励领取事件

3. 设计原则

活动模块的设计遵循以下原则：

3.1 单一职责原则

每个类只负责一个功能领域，如活动配置、奖励管理、参与记录等。

3.2 关注点分离

模型层只负责数据结构定义
仓库层负责数据访问
逻辑层处理业务规则
服务层提供对外接口
控制器层处理HTTP请求

3.3 依赖注入

通过构造函数注入依赖，提高代码的可测试性和灵活性。

3.4 事务完整性

所有涉及多个操作的功能（如奖励发放）都使用数据库事务确保原子性。

3.5 日志记录

关键操作（如活动状态变更、奖励发放）都有详细的日志记录，便于追踪和分析。

4. 交互流程

4.1 活动创建流程

sequenceDiagram
    管理员->>ActivityController: 提交活动创建表单
    ActivityController->>ActivityManagementService: 创建活动
    ActivityManagementService->>ActivityLogic: 处理活动创建逻辑
    ActivityLogic->>ActivityConfigRepository: 保存活动配置
    ActivityConfigRepository->>ActivityConfig: 创建记录
    ActivityLogic->>EventDispatcher: 触发ActivityCreatedEvent
    EventDispatcher->>ActivityCreatedListener: 处理后续操作

4.2 用户参与活动流程

sequenceDiagram
    用户->>ActivityService: 请求参与活动
    ActivityService->>ActivityLogic: 检查参与条件
    ActivityLogic->>ParticipationLogic: 处理参与逻辑
    ParticipationLogic->>ActivityParticipationRepository: 记录参与情况
    ParticipationLogic->>UserActivityDataRepository: 初始化用户进度
    ActivityService->>EventDispatcher: 触发UserParticipatedEvent

4.3 奖励领取流程

sequenceDiagram
    用户->>RewardService: 请求领取奖励
    RewardService->>ActivityLogic: 验证领取条件
    ActivityLogic->>RewardLogic: 计算实际奖励
    RewardLogic->>ItemService: 发放物品奖励
    RewardService->>ActivityParticipationRepository: 更新奖励状态
    RewardService->>EventDispatcher: 触发RewardClaimedEvent

5. 扩展性设计

活动模块设计了良好的扩展机制，支持快速添加新的活动类型：

5.1 活动类型扩展

通过枚举类型定义活动类型，新增活动类型只需添加枚举值并实现对应的处理逻辑。

5.2 奖励类型扩展

奖励系统支持多种奖励类型（物品、货币、经验等），可通过扩展奖励处理器来支持新的奖励类型。

5.3 条件系统扩展

活动参与条件和完成条件采用可配置的条件系统，支持组合多种条件类型，便于扩展新的条件类型。

架构设计.md 6.1 KB 文件歷史 原始文件