服务接口.md 19 KB
活动模块服务接口
1. 概述
活动模块提供了一系列服务接口，供其他模块调用，实现活动相关功能。这些服务接口封装了活动模块的核心功能，提供了清晰的API，使其他模块能够方便地与活动模块交互。
2. 核心服务接口
2.1 ActivityService
活动服务是活动模块的主要对外接口，提供活动查询、参与、进度更新等功能。
2.1.1 获取活动列表
/**
* 获取活动列表
*
* @param int $userId 用户ID
* @param int|null $type 活动类型，null表示所有类型
* @param bool $onlyActive 是否只返回进行中的活动
* @return array 活动列表
*/
public function getActivityList(int $userId, ?int $type = null, bool $onlyActive = true): array;
2.1.2 获取活动详情
/**
* 获取活动详情
*
* @param int $activityId 活动ID
* @param int $userId 用户ID
* @return array|null 活动详情，不存在时返回null
*/
public function getActivityDetail(int $activityId, int $userId): ?array;
2.1.3 参与活动
/**
* 用户参与活动
*
* @param int $userId 用户ID
* @param int $activityId 活动ID
* @return array 参与结果
* @throws ActivityException 参与失败时抛出异常
*/
public function participateActivity(int $userId, int $activityId): array;
2.1.4 更新活动进度
/**
* 更新活动进度
*
* @param int $userId 用户ID
* @param int $activityId 活动ID
* @param int $progress 新进度值
* @param array $progressData 进度详细数据
* @return array 更新结果
* @throws ActivityException 更新失败时抛出异常
*/
public function updateActivityProgress(int $userId, int $activityId, int $progress, array $progressData = []): array;
2.1.5 完成活动
/**
* 标记活动为已完成
*
* @param int $userId 用户ID
* @param int $activityId 活动ID
* @return array 完成结果
* @throws ActivityException 完成失败时抛出异常
*/
public function completeActivity(int $userId, int $activityId): array;
2.1.6 检查活动状态
/**
* 检查活动状态
*
* @param int $activityId 活动ID
* @return int 活动状态
*/
public function checkActivityStatus(int $activityId): int;
2.2 RewardService
奖励服务负责处理活动奖励的查询和领取。
2.2.1 获取活动奖励列表
/**
* 获取活动奖励列表
*
* @param int $activityId 活动ID
* @return array 奖励列表
*/
public function getActivityRewards(int $activityId): array;
2.2.2 获取用户可领取的奖励
/**
* 获取用户可领取的奖励
*
* @param int $userId 用户ID
* @param int $activityId 活动ID
* @return array 可领取的奖励列表
*/
public function getClaimableRewards(int $userId, int $activityId): array;
2.2.3 领取活动奖励
/**
* 领取活动奖励
*
* @param int $userId 用户ID
* @param int $activityId 活动ID
* @param array $rewardIds 要领取的奖励ID列表，为空时领取所有可领取奖励
* @return array 领取结果
* @throws RewardException 领取失败时抛出异常
*/
public function claimRewards(int $userId, int $activityId, array $rewardIds = []): array;
2.2.4 检查奖励领取状态
/**
* 检查奖励领取状态
*
* @param int $userId 用户ID
* @param int $activityId 活动ID
* @return int 奖励领取状态
*/
public function checkRewardStatus(int $userId, int $activityId): int;
2.3 ActivityManagementService
活动管理服务提供活动的创建、更新、发布等管理功能，主要供后台使用。
2.3.1 创建活动
/**
* 创建活动
*
* @param array $data 活动数据
* @return array 创建结果
* @throws ActivityManagementException 创建失败时抛出异常
*/
public function createActivity(array $data): array;
2.3.2 更新活动
/**
* 更新活动
*
* @param int $activityId 活动ID
* @param array $data 更新数据
* @return array 更新结果
* @throws ActivityManagementException 更新失败时抛出异常
*/
public function updateActivity(int $activityId, array $data): array;
2.3.3 发布活动
/**
* 发布活动
*
* @param int $activityId 活动ID
* @return array 发布结果
* @throws ActivityManagementException 发布失败时抛出异常
*/
public function publishActivity(int $activityId): array;
2.3.4 关闭活动
/**
* 关闭活动
*
* @param int $activityId 活动ID
* @param string $reason 关闭原因
* @return array 关闭结果
* @throws ActivityManagementException 关闭失败时抛出异常
*/
public function closeActivity(int $activityId, string $reason): array;
2.3.5 配置活动奖励
/**
* 配置活动奖励
*
* @param int $activityId 活动ID
* @param array $rewards 奖励配置，格式如：[
* [
* 'reward_type' => 1, // 1:物品, 2:物品组, 3:货币, 4:经验
* 'item_id' => 1001, // 当reward_type=1时使用
* 'item_group_id' => 101, // 当reward_type=2时使用
* 'item_count' => 10,
* 'probability' => 100.00,
* 'reward_group' => 'daily_reward'
* ]
* ]
* @return array 配置结果
* @throws ActivityManagementException 配置失败时抛出异常
*/
public function configureRewards(int $activityId, array $rewards): array;
2.3.6 配置活动条件
/**
* 配置活动条件
*
* @param int $activityId 活动ID
* @param array $conditions 条件配置
* @return array 配置结果
* @throws ActivityManagementException 配置失败时抛出异常
*/
public function configureConditions(int $activityId, array $conditions): array;
3. 服务实现示例
3.1 ActivityService实现示例
<?php
namespace App\Module\Activity\Services;
use App\Module\Activity\Events\UserParticipatedEvent;
use App\Module\Activity\Events\ActivityProgressUpdatedEvent;
use App\Module\Activity\Events\ActivityCompletedEvent;
use App\Module\Activity\Exceptions\ActivityException;
use App\Module\Activity\Logics\ActivityLogic;
use App\Module\Activity\Logics\ParticipationLogic;
use App\Module\Activity\Logics\ProgressLogic;
use App\Module\Activity\Models\ActivityConfig;
use App\Module\Activity\Models\ActivityParticipation;
use App\Module\Activity\Models\UserActivityData;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Log;
class ActivityService
{
/**
* 活动逻辑
*
* @var ActivityLogic
*/
protected $activityLogic;
/**
* 参与逻辑
*
* @var ParticipationLogic
*/
protected $participationLogic;
/**
* 进度逻辑
*
* @var ProgressLogic
*/
protected $progressLogic;
/**
* 构造函数
*/
public function __construct(
ActivityLogic $activityLogic,
ParticipationLogic $participationLogic,
ProgressLogic $progressLogic
) {
$this->activityLogic = $activityLogic;
$this->participationLogic = $participationLogic;
$this->progressLogic = $progressLogic;
}
/**
* 获取活动列表
*
* @param int $userId 用户ID
* @param int|null $type 活动类型，null表示所有类型
* @param bool $onlyActive 是否只返回进行中的活动
* @return array 活动列表
*/
public function getActivityList(int $userId, ?int $type = null, bool $onlyActive = true): array
{
try {
return $this->activityLogic->getActivityList($userId, $type, $onlyActive);
} catch (\Exception $e) {
Log::error('获取活动列表失败', [
'user_id' => $userId,
'type' => $type,
'only_active' => $onlyActive,
'error' => $e->getMessage()
]);
return [];
}
}
/**
* 获取活动详情
*
* @param int $activityId 活动ID
* @param int $userId 用户ID
* @return array|null 活动详情，不存在时返回null
*/
public function getActivityDetail(int $activityId, int $userId): ?array
{
try {
return $this->activityLogic->getActivityDetail($activityId, $userId);
} catch (\Exception $e) {
Log::error('获取活动详情失败', [
'activity_id' => $activityId,
'user_id' => $userId,
'error' => $e->getMessage()
]);
return null;
}
}
/**
* 用户参与活动
*
* @param int $userId 用户ID
* @param int $activityId 活动ID
* @return array 参与结果
* @throws ActivityException 参与失败时抛出异常
*/
public function participateActivity(int $userId, int $activityId): array
{
try {
DB::beginTransaction();
// 检查活动状态
$activity = $this->activityLogic->checkActivityAvailable($activityId);
if (!$activity) {
throw new ActivityException('活动不可用');
}
// 检查用户是否已参与
if ($this->participationLogic->hasParticipated($userId, $activityId)) {
throw new ActivityException('已经参与过该活动');
}
// 检查参与条件
$this->participationLogic->checkParticipationConditions($userId, $activityId);
// 记录参与情况
$participation = $this->participationLogic->recordParticipation($userId, $activityId);
// 初始化用户活动数据
$userActivityData = $this->progressLogic->initUserActivityData($userId, $activityId);
// 触发用户参与活动事件
event(new UserParticipatedEvent(
$userId,
$activityId,
$activity->type,
now()->toDateTimeString(),
'app'
));
DB::commit();
return [
'success' => true,
'participation' => $participation,
'user_activity_data' => $userActivityData
];
} catch (ActivityException $e) {
DB::rollBack();
throw $e;
} catch (\Exception $e) {
DB::rollBack();
Log::error('参与活动失败', [
'user_id' => $userId,
'activity_id' => $activityId,
'error' => $e->getMessage()
]);
throw new ActivityException('参与活动失败：' . $e->getMessage());
}
}
/**
* 更新活动进度
*
* @param int $userId 用户ID
* @param int $activityId 活动ID
* @param int $progress 新进度值
* @param array $progressData 进度详细数据
* @return array 更新结果
* @throws ActivityException 更新失败时抛出异常
*/
public function updateActivityProgress(int $userId, int $activityId, int $progress, array $progressData = []): array
{
try {
DB::beginTransaction();
// 检查用户是否已参与活动
if (!$this->participationLogic->hasParticipated($userId, $activityId)) {
throw new ActivityException('未参与该活动');
}
// 获取当前进度
$currentData = $this->progressLogic->getUserActivityData($userId, $activityId);
if (!$currentData) {
throw new ActivityException('活动数据不存在');
}
$oldProgress = $currentData->progress;
// 更新进度
$updatedData = $this->progressLogic->updateProgress($userId, $activityId, $progress, $progressData);
// 触发进度更新事件
event(new ActivityProgressUpdatedEvent(
$userId,
$activityId,
$oldProgress,
$progress,
$progressData,
now()->toDateTimeString()
));
// 检查是否完成活动
$isCompleted = $this->progressLogic->checkActivityCompletion($userId, $activityId);
if ($isCompleted) {
$this->completeActivity($userId, $activityId);
}
DB::commit();
return [
'success' => true,
'old_progress' => $oldProgress,
'new_progress' => $progress,
'is_completed' => $isCompleted
];
} catch (ActivityException $e) {
DB::rollBack();
throw $e;
} catch (\Exception $e) {
DB::rollBack();
Log::error('更新活动进度失败', [
'user_id' => $userId,
'activity_id' => $activityId,
'progress' => $progress,
'error' => $e->getMessage()
]);
throw new ActivityException('更新活动进度失败：' . $e->getMessage());
}
}
/**
* 标记活动为已完成
*
* @param int $userId 用户ID
* @param int $activityId 活动ID
* @return array 完成结果
* @throws ActivityException 完成失败时抛出异常
*/
public function completeActivity(int $userId, int $activityId): array
{
try {
DB::beginTransaction();
// 检查用户是否已参与活动
$participation = $this->participationLogic->getParticipation($userId, $activityId);
if (!$participation) {
throw new ActivityException('未参与该活动');
}
// 检查是否已完成
if ($participation->completion_status == 1) {
throw new ActivityException('活动已完成');
}
// 获取活动信息
$activity = ActivityConfig::find($activityId);
if (!$activity) {
throw new ActivityException('活动不存在');
}
// 更新完成状态
$participation->completion_status = 1;
$participation->completion_time = now();
$participation->save();
// 获取可获得的奖励
$rewards = $this->activityLogic->getActivityRewards($activityId);
// 触发活动完成事件
event(new ActivityCompletedEvent(
$userId,
$activityId,
$activity->name,
$activity->type,
now()->toDateTimeString(),
$rewards
));
DB::commit();
return [
'success' => true,
'completion_time' => $participation->completion_time,
'rewards' => $rewards
];
} catch (ActivityException $e) {
DB::rollBack();
throw $e;
} catch (\Exception $e) {
DB::rollBack();
Log::error('完成活动失败', [
'user_id' => $userId,
'activity_id' => $activityId,
'error' => $e->getMessage()
]);
throw new ActivityException('完成活动失败：' . $e->getMessage());
}
}
/**
* 检查活动状态
*
* @param int $activityId 活动ID
* @return int 活动状态
*/
public function checkActivityStatus(int $activityId): int
{
try {
return $this->activityLogic->getActivityStatus($activityId);
} catch (\Exception $e) {
Log::error('检查活动状态失败', [
'activity_id' => $activityId,
'error' => $e->getMessage()
]);
return -1; // 表示检查失败
}
}
}
4. 服务调用示例
4.1 获取活动列表
// 在其他模块中调用活动服务
$activityService = app(ActivityService::class);
// 获取用户可参与的所有活动
$activities = $activityService->getActivityList($userId);
// 获取用户可参与的签到活动
$signInActivities = $activityService->getActivityList($userId, ActivityType::SIGN_IN);
4.2 用户参与活动
// 在其他模块中调用活动服务
$activityService = app(ActivityService::class);
try {
// 用户参与活动
$result = $activityService->participateActivity($userId, $activityId);
// 处理参与结果
if ($result['success']) {
// 参与成功，可以进行后续操作
}
} catch (ActivityException $e) {
// 处理参与失败的情况
Log::warning('用户参与活动失败', [
'user_id' => $userId,
'activity_id' => $activityId,
'error' => $e->getMessage()
]);
// 向用户返回错误信息
return response()->json([
'success' => false,
'message' => $e->getMessage()
]);
}
4.3 领取活动奖励
// 在其他模块中调用奖励服务
$rewardService = app(RewardService::class);
try {
// 领取活动奖励
$result = $rewardService->claimRewards($userId, $activityId);
// 处理领取结果
if ($result['success']) {
// 领取成功，可以向用户展示获得的奖励
return response()->json([
'success' => true,
'message' => '奖励领取成功',
'rewards' => $result['rewards']
]);
}
} catch (RewardException $e) {
// 处理领取失败的情况
Log::warning('用户领取奖励失败', [
'user_id' => $userId,
'activity_id' => $activityId,
'error' => $e->getMessage()
]);
// 向用户返回错误信息
return response()->json([
'success' => false,
'message' => $e->getMessage()
]);
}
5. 错误处理
活动模块定义了以下异常类型，用于处理各种错误情况：
5.1 ActivityException
活动相关的基础异常类，用于处理活动参与、进度更新等操作中的错误。
5.2 RewardException
奖励相关的异常类，用于处理奖励配置、领取等操作中的错误。
5.3 ActivityManagementException
活动管理相关的异常类，用于处理活动创建、更新、发布等管理操作中的错误。
6. 服务注册
活动模块通过服务提供者注册服务：
/**
* 活动模块服务提供者
*/
class ActivityServiceProvider extends ServiceProvider
{
/**
* 注册服务
*/
public function register()
{
// 注册活动服务
$this->app->singleton(ActivityService::class, function ($app) {
return new ActivityService(
$app->make(ActivityLogic::class),
$app->make(ParticipationLogic::class),
$app->make(ProgressLogic::class)
);
});
// 注册奖励服务
$this->app->singleton(RewardService::class, function ($app) {
return new RewardService(
$app->make(ActivityLogic::class),
$app->make(RewardLogic::class)
);
});
// 注册活动管理服务
$this->app->singleton(ActivityManagementService::class, function ($app) {
return new ActivityManagementService(
$app->make(ActivityLogic::class),
$app->make(RewardLogic::class),
$app->make(ConditionLogic::class)
);
});
}
/**
* 启动服务
*/
public function boot()
{
// 注册事件监听器
// ...
}
}