getRewardGroup($groupIdOrCode); } /** * 获取奖励组并转换为Protobuf Reward对象 * * @param int|string $groupIdOrCode 奖励组ID或编码 * @return \Uraus\Kku\Common\Reward|null Protobuf Reward对象,不存在时返回null */ public static function getRewardGroupAsReward($groupIdOrCode): ?\Uraus\Kku\Common\Reward { $rewardGroupDto = self::getRewardGroup($groupIdOrCode); if (!$rewardGroupDto) { return null; } return ProtobufConverter::convertRewardGroupToReward($rewardGroupDto); } /** * 发放奖励 * * @param int $userId 用户ID * @param int|string $groupIdOrCode 奖励组ID或编码 * @param REWARD_SOURCE_TYPE $sourceType 来源类型枚举 * @param int $sourceId 来源ID * @param int $multiplier 倍率 * @return RewardResultDto 奖励结果 */ public static function grantReward(int $userId, $groupIdOrCode, REWARD_SOURCE_TYPE $sourceType, int $sourceId, int $multiplier = 1): RewardResultDto { // 验证来源类型是否有效 if (!REWARD_SOURCE_TYPE::isValid($sourceType->value)) { return RewardResultDto::fail("无效的奖励来源类型: {$sourceType->value}"); } $logic = new RewardLogic(); return $logic->grantReward($userId, $groupIdOrCode, $sourceType->value, $sourceId, $multiplier); } /** * 批量发放奖励 * * @param array $userIds 用户ID数组 * @param int|string $groupIdOrCode 奖励组ID或编码 * @param REWARD_SOURCE_TYPE $sourceType 来源类型枚举 * @param int $sourceId 来源ID * @return array 奖励结果数组,键为用户ID,值为RewardResultDto */ public static function batchGrantReward(array $userIds, $groupIdOrCode, REWARD_SOURCE_TYPE $sourceType, int $sourceId): array { // 验证来源类型是否有效 if (!REWARD_SOURCE_TYPE::isValid($sourceType->value)) { $failResult = RewardResultDto::fail("无效的奖励来源类型: {$sourceType->value}"); return array_fill_keys($userIds, $failResult); } $results = []; $logic = new RewardLogic(); foreach ($userIds as $userId) { $results[$userId] = $logic->grantReward($userId, $groupIdOrCode, $sourceType->value, $sourceId); } return $results; } /** * 检查奖励组是否存在 * * @param int|string $groupIdOrCode 奖励组ID或编码 * @return bool 是否存在 */ public static function rewardGroupExists($groupIdOrCode): bool { return self::getRewardGroup($groupIdOrCode) !== null; } /** * 发放奖励(支持保底机制) * * @param int $userId 用户ID * @param int|string $groupIdOrCode 奖励组ID或编码 * @param REWARD_SOURCE_TYPE $sourceType 来源类型枚举 * @param int $sourceId 来源ID * @param bool $enablePity 是否启用保底机制 * @return RewardResultDto 奖励结果 */ public static function grantRewardWithPity(int $userId, $groupIdOrCode, REWARD_SOURCE_TYPE $sourceType, int $sourceId, bool $enablePity = true): RewardResultDto { // 验证来源类型是否有效 if (!REWARD_SOURCE_TYPE::isValid($sourceType->value)) { return RewardResultDto::fail("无效的奖励来源类型: {$sourceType->value}"); } $logic = new RewardLogic(); return $logic->grantRewardWithPity($userId, $groupIdOrCode, $sourceType->value, $sourceId, $enablePity); } /** * 模拟奖励发放(不实际发放,仅返回奖励结果) * * @param int|string $groupIdOrCode 奖励组ID或编码 * @return RewardResultDto 奖励结果 */ public static function simulateReward($groupIdOrCode): RewardResultDto { $logic = new RewardLogic(); return $logic->simulateReward($groupIdOrCode); } /** * 批量模拟奖励发放(不实际发放,仅返回奖励结果) * * @param int|string $groupIdOrCode 奖励组ID或编码 * @param int $count 模拟次数 * @return array 奖励结果数组 */ public static function batchSimulateReward($groupIdOrCode, int $count): array { $results = []; $logic = new RewardLogic(); for ($i = 0; $i < $count; $i++) { $results[] = $logic->simulateReward($groupIdOrCode); } return $results; } /** * 批量解析奖励项为可读的字符串数组 * * @param RewardItemDto[] $rewardItems 奖励项DTO数组 * @return string[] 可读的奖励描述数组 */ public static function parseRewardItemsToStrings(array $rewardItems): array { $results = []; foreach ($rewardItems as $item) { $results[] = self::parseRewardItemToString($item); } return $results; } /** * 格式化数量文本 * * @param RewardItemDto $rewardItem 奖励项DTO * @return string 格式化后的数量文本 */ private static function formatQuantityText(RewardItemDto $rewardItem): string { // 如果有最小和最大数量,显示范围 if ($rewardItem->minQuantity !== null && $rewardItem->maxQuantity !== null) { if ($rewardItem->minQuantity === $rewardItem->maxQuantity) { return $rewardItem->minQuantity . '个'; } else { return $rewardItem->minQuantity . '-' . $rewardItem->maxQuantity . '个'; } } // 否则使用固定数量 return $rewardItem->quantity . '个'; } /** * 获取用户保底状态 * * @param int $userId 用户ID * @param int|string $groupIdOrCode 奖励组ID或编码 * @return array 保底状态信息 */ public static function getUserPityStatus(int $userId, $groupIdOrCode): array { $rewardGroup = self::getRewardGroup($groupIdOrCode); if (!$rewardGroup) { return []; } return PityService::getPityStatus($userId, $rewardGroup->id); } /** * 重置用户保底计数 * * @param int $userId 用户ID * @param int|string $groupIdOrCode 奖励组ID或编码 * @return bool 是否成功 */ public static function resetUserPity(int $userId, $groupIdOrCode): bool { $rewardGroup = self::getRewardGroup($groupIdOrCode); if (!$rewardGroup) { return false; } PityService::resetAllPityCounts($userId, $rewardGroup->id); return true; } }