kknongchang_2506/app/Module/GameItems/Services/ItemService.php

<?php

namespace App\Module\GameItems\Services;

use App\Module\GameItems\Logics\Item as ItemLogic;
use App\Module\GameItems\Models\Item;
use App\Module\GameItems\Models\ItemUser;
use Exception;
use Illuminate\Database\Eloquent\Collection;

/**
 * 物品服务类
 *
 * 提供物品相关的服务，包括获取用户物品、添加物品到用户背包、消耗用户物品等功能。
 * 该类是物品模块对外提供服务的主要入口，封装了物品操作的复杂逻辑，
 * 通过调用ItemLogic类实现具体的业务逻辑处理。
 *
 * 所有方法均为静态方法，可直接通过类名调用。
 */
class ItemService
{
    /**
     * 获取用户物品列表
     *
     * @param int $userId 用户ID
     * @param array $filters 过滤条件
     * @param bool $includeExpired 是否包含已过期物品
     * @return Collection|ItemUser[]
     */
    public static function getUserItems(int $userId, array $filters = [], bool $includeExpired = false): Collection
    {
        $query = ItemUser::where('user_id', $userId)
            ->with(['item', 'instance']);

        // 应用过滤条件
        if (isset($filters['item_id'])) {
            $query->where('item_id', $filters['item_id']);
        }

        if (isset($filters['category_id'])) {
            $query->whereHas('item', function ($q) use ($filters) {
                $q->where('category_id', $filters['category_id']);
            });
        }

        if (isset($filters['type'])) {
            $query->whereHas('item', function ($q) use ($filters) {
                $q->where('type', $filters['type']);
            });
        }

        // 排除过期物品
        if (!$includeExpired) {
            $now = now();
            $query->where(function ($q) use ($now) {
                $q->whereNull('expire_at')
                    ->orWhere('expire_at', '>', $now);
            })->whereHas('item', function ($q) use ($now) {
                $q->where(function ($subQ) use ($now) {
                    $subQ->whereNull('global_expire_at')
                        ->orWhere('global_expire_at', '>', $now);
                });
            });
        }

        return $query->get();
    }

    /**
     * 添加物品到用户背包
     *
     * @param int $userId 用户ID
     * @param int $itemId 物品ID
     * @param int $quantity 数量
     * @param array $options 选项
     * @return array 添加结果
     * @throws Exception
     */
    public static function addItem(int $userId, int $itemId, int $quantity, array $options = []): array
    {
        // 获取物品信息
        $item = Item::findOrFail($itemId);

        // 检查物品是否已过期（全局过期）
        if (ItemLogic::isExpired($item)) {
            throw new Exception("物品 {$itemId} 已全局过期");
        }

        // 处理单独属性物品
        if ($item->is_unique) {
            return ItemLogic::addUniqueItem($userId, $itemId, $options);
        }

        // 处理统一属性物品
        return ItemLogic::addNormalItem($userId, $itemId, $quantity, $options);
    }

    /**
     * 消耗用户物品
     *
     * @param int $userId 用户ID
     * @param int $itemId 物品ID
     * @param int|null $instanceId 物品实例ID（单独属性物品）
     * @param int $quantity 数量
     * @param array $options 选项
     * @return array 消耗结果
     * @throws Exception
     */
    public static function consumeItem(int $userId, int $itemId, ?int $instanceId, int $quantity, array $options = []): array
    {
        // 获取物品信息
        $item = Item::findOrFail($itemId);

        if ($instanceId) {
            // 消耗单独属性物品
            return ItemLogic::consumeUniqueItem($userId, $itemId, $instanceId, $options);
        } else {
            // 消耗统一属性物品
            return ItemLogic::consumeNormalItem($userId, $itemId, $quantity, $options);
        }
    }

    /**
     * 获取物品信息
     *
     * @param int $itemId 物品ID
     * @return Item|null 物品信息
     */
    public static function getItemInfo(int $itemId): ?Item
    {
        return Item::find($itemId);
    }

}