活动模块事件系统

1. 概述

活动模块使用事件系统实现模块间的松耦合通信，通过定义和触发事件，使其他模块能够响应活动系统中的关键行为，而无需直接依赖活动模块的内部实现。

事件系统基于Laravel的事件机制实现，包括事件定义、事件监听器和事件分发。

2. 核心事件

2.1 ActivityCreatedEvent

当新活动被创建时触发此事件。

事件属性：

/**
 * 活动ID
 * @var int
 */
public int $activityId;

/**
 * 活动名称
 * @var string
 */
public string $activityName;

/**
 * 活动类型
 * @var int
 */
public int $activityType;

/**
 * 活动开始时间
 * @var string
 */
public string $startTime;

/**
 * 活动结束时间
 * @var string
 */
public string $endTime;

/**
 * 创建者ID
 * @var int
 */
public int $creatorId;

触发时机：

管理员在后台创建新活动
系统自动创建定期活动

2.2 ActivityStatusChangedEvent

当活动状态发生变化时触发此事件。

事件属性：

/**
 * 活动ID
 * @var int
 */
public int $activityId;

/**
 * 活动名称
 * @var string
 */
public string $activityName;

/**
 * 旧状态
 * @var int
 */
public int $oldStatus;

/**
 * 新状态
 * @var int
 */
public int $newStatus;

/**
 * 状态变更原因
 * @var string
 */
public string $reason;

/**
 * 状态变更时间
 * @var string
 */
public string $changedAt;

触发时机：

活动从未开始变为进行中
活动从进行中变为已结束
管理员手动修改活动状态

2.3 UserParticipatedEvent

当用户参与活动时触发此事件。

事件属性：

/**
 * 用户ID
 * @var int
 */
public int $userId;

/**
 * 活动ID
 * @var int
 */
public int $activityId;

/**
 * 活动类型
 * @var int
 */
public int $activityType;

/**
 * 参与时间
 * @var string
 */
public string $participateTime;

/**
 * 参与渠道
 * @var string
 */
public string $channel;

触发时机：

用户首次参与活动
用户重新参与已重置的活动

2.4 ActivityProgressUpdatedEvent

当用户在活动中的进度更新时触发此事件。

事件属性：

/**
 * 用户ID
 * @var int
 */
public int $userId;

/**
 * 活动ID
 * @var int
 */
public int $activityId;

/**
 * 旧进度
 * @var int
 */
public int $oldProgress;

/**
 * 新进度
 * @var int
 */
public int $newProgress;

/**
 * 进度数据
 * @var array
 */
public array $progressData;

/**
 * 更新时间
 * @var string
 */
public string $updatedAt;

触发时机：

用户完成活动任务
系统自动更新活动进度

2.5 ActivityCompletedEvent

当用户完成活动时触发此事件。

事件属性：

/**
 * 用户ID
 * @var int
 */
public int $userId;

/**
 * 活动ID
 * @var int
 */
public int $activityId;

/**
 * 活动名称
 * @var string
 */
public string $activityName;

/**
 * 活动类型
 * @var int
 */
public int $activityType;

/**
 * 完成时间
 * @var string
 */
public string $completedAt;

/**
 * 可获得的奖励
 * @var array
 */
public array $rewards;

触发时机：

用户达成活动完成条件
管理员手动标记活动为已完成

2.6 ActivityRewardClaimedEvent

当用户领取活动奖励时触发此事件。

事件属性：

/**
 * 用户ID
 * @var int
 */
public int $userId;

/**
 * 活动ID
 * @var int
 */
public int $activityId;

/**
 * 奖励ID列表
 * @var array
 */
public array $rewardIds;

/**
 * 实际发放的奖励
 * @var array
 */
public array $actualRewards;

/**
 * 领取时间
 * @var string
 */
public string $claimedAt;

触发时机：

用户手动领取活动奖励
系统自动发放活动奖励

3. 事件监听器

3.1 ActivityStatusChangeListener

监听活动状态变更事件，执行相关操作。

职责：

当活动开始时，向符合条件的用户发送通知
当活动结束时，处理未领取奖励的情况
记录活动状态变更日志

3.2 UserParticipationListener

监听用户参与活动事件，处理参与逻辑。

职责：

初始化用户活动进度数据
记录用户参与统计信息
触发首次参与奖励（如果有）

3.3 ActivityProgressListener

监听活动进度更新事件，处理进度相关逻辑。

职责：

检查是否达成活动完成条件
更新用户活动统计数据
触发进度里程碑奖励（如果有）

3.4 RewardDistributionListener

监听奖励领取事件，处理奖励发放逻辑。

职责：

将奖励物品添加到用户背包
记录奖励发放日志
更新用户奖励领取状态

4. 事件注册

活动模块通过服务提供者注册事件和监听器：

/**
 * 活动模块服务提供者
 */
class ActivityServiceProvider extends ServiceProvider
{
    /**
     * 事件到监听器的映射
     *
     * @var array
     */
    protected $listen = [
        ActivityCreatedEvent::class => [
            ActivityCreatedListener::class,
        ],
        ActivityStatusChangedEvent::class => [
            ActivityStatusChangeListener::class,
        ],
        UserParticipatedEvent::class => [
            UserParticipationListener::class,
        ],
        ActivityProgressUpdatedEvent::class => [
            ActivityProgressListener::class,
        ],
        ActivityCompletedEvent::class => [
            ActivityCompletedListener::class,
        ],
        ActivityRewardClaimedEvent::class => [
            RewardDistributionListener::class,
        ],

    ];

    /**
     * 注册服务
     */
    public function register()
    {
        // 注册服务...
    }

    /**
     * 启动服务
     */
    public function boot()
    {
        // 注册事件监听器
        parent::boot();
    }
}

5. 事件触发示例

5.1 触发活动创建事件

// 在活动创建逻辑中
public function createActivity(array $data)
{
    // 创建活动记录
    $activity = ActivityConfig::create([
        'name' => $data['name'],
        'type' => $data['type'],
        'start_time' => $data['start_time'],
        'end_time' => $data['end_time'],
        // 其他字段...
    ]);

    // 触发活动创建事件
    event(new ActivityCreatedEvent(
        $activity->id,
        $activity->name,
        $activity->type,
        $activity->start_time,
        $activity->end_time,
        auth()->id()
    ));

    return $activity;
}

5.2 触发用户参与活动事件

// 在用户参与活动逻辑中
public function participateActivity(int $userId, int $activityId)
{
    // 检查参与条件...

    // 记录参与情况
    $participation = ActivityParticipation::create([
        'user_id' => $userId,
        'activity_id' => $activityId,
        'participate_time' => now(),
        'reward_status' => 0,
    ]);

    // 初始化用户活动数据
    UserActivityData::create([
        'user_id' => $userId,
        'activity_id' => $activityId,
        'progress' => 0,
    ]);

    // 获取活动信息
    $activity = ActivityConfig::find($activityId);

    // 触发用户参与活动事件
    event(new UserParticipatedEvent(
        $userId,
        $activityId,
        $activity->type,
        now()->toDateTimeString(),
        'app'
    ));

    return $participation;
}

6. 与其他模块的集成

活动模块的事件系统可以与其他模块集成，实现跨模块功能：

6.1 与通知模块集成

通知模块可以监听活动事件，向用户发送相关通知：

// 在通知模块的服务提供者中
protected $listen = [
    ActivityCreatedEvent::class => [
        SendActivityNotificationListener::class,
    ],
    ActivityStatusChangedEvent::class => [
        SendActivityStatusChangeNotificationListener::class,
    ],
    ActivityRewardClaimedEvent::class => [
        SendRewardClaimNotificationListener::class,
    ],
];

6.2 与任务模块集成

任务模块可以监听活动事件，更新相关任务进度：

// 在任务模块的服务提供者中
protected $listen = [
    UserParticipatedEvent::class => [
        UpdateActivityParticipationTaskListener::class,
    ],
    ActivityCompletedEvent::class => [
        UpdateActivityCompletionTaskListener::class,
    ],

];

6.3 与统计模块集成

统计模块可以监听活动事件，收集活动相关数据：

// 在统计模块的服务提供者中
protected $listen = [
    UserParticipatedEvent::class => [
        RecordActivityParticipationStatListener::class,
    ],
    ActivityRewardClaimedEvent::class => [
        RecordRewardDistributionStatListener::class,
    ],
    ActivityCompletedEvent::class => [
        RecordActivityCompletionStatListener::class,
    ],
];

事件系统.md 8.6 KB History Raw

活动模块事件系统

1. 概述

2. 核心事件

2.1 ActivityCreatedEvent

2.2 ActivityStatusChangedEvent

2.3 UserParticipatedEvent

2.4 ActivityProgressUpdatedEvent

2.5 ActivityCompletedEvent

2.6 ActivityRewardClaimedEvent

3. 事件监听器

3.1 ActivityStatusChangeListener

3.2 UserParticipationListener

3.3 ActivityProgressListener

3.4 RewardDistributionListener

4. 事件注册

5. 事件触发示例

5.1 触发活动创建事件

5.2 触发用户参与活动事件

6. 与其他模块的集成

6.1 与通知模块集成

6.2 与任务模块集成

6.3 与统计模块集成

事件系统.md 8.6 KB

History Raw