kknongchang_2506/app/Module/GameItems/Models/ItemUser.php

<?php

namespace App\Module\GameItems\Models;

use Illuminate\Database\Eloquent\Relations\BelongsTo;
use UCore\ModelCore;

/**
 * 用户物品关联
 *
 * field start 
 * @property  int  $id  记录ID，主键
 * @property  int  $user_id  用户ID
 * @property  int  $item_id  统一属性物品ID，外键关联kku_item_items表
 * @property  int  $instance_id  单独属性物品ID，外键关联kku_item_instances表（可为空）
 * @property  int  $quantity  数量（对于单独属性物品，该值始终为1）
 * @property  string  $expire_at  用户物品过期时间（可为空）
 * @property  \Carbon\Carbon  $created_at  获取时间
 * @property  \Carbon\Carbon  $updated_at  更新时间
 * @property  bool  $is_frozen  是否冻结（0:未冻结, 1:已冻结）
 * @property  int  $frozen_log_id  冻结日志ID，关联kku_item_freeze_logs表
 * field end
 */
class ItemUser extends ModelCore
{
    /**
     * 与模型关联的表名
     *
     * @var string
     */
    protected $table = 'item_users';

    // attrlist start 
    protected $fillable = [
        'id',
        'user_id',
        'item_id',
        'instance_id',
        'quantity',
        'expire_at',
        'is_frozen',
        'frozen_log_id',
    ];
    // attrlist end

    /**
     * 应该被转换为日期的属性
     *
     * @var array
     */
    protected $dates = [
        'expire_at',
        'created_at',
        'updated_at',
    ];

    /**
     * 应该被转换为原生类型的属性
     *
     * @var array
     */
    protected $casts = [
        'is_frozen' => 'boolean',
        'frozen_log_id' => 'integer',
    ];

    /**
     * 获取关联的物品
     *
     * @return BelongsTo
     */
    public function item(): BelongsTo
    {
        return $this->belongsTo(Item::class, 'item_id');
    }

    /**
     * 获取关联的物品实例（如果有）
     *
     * @return BelongsTo
     */
    public function instance(): BelongsTo
    {
        return $this->belongsTo(ItemInstance::class, 'instance_id');
    }

    /**
     * 获取关联的冻结日志
     *
     * @return BelongsTo
     */
    public function freezeLog(): BelongsTo
    {
        return $this->belongsTo(ItemFreezeLog::class, 'frozen_log_id');
    }




    /**
     * 检查是否为单独属性物品
     *
     * @return bool
     */
    public function isUniqueItem(): bool
    {
        return !empty($this->instance_id);
    }

    /**
     * 检查是否为冻结状态
     *
     * @return bool
     */
    public function isFrozen(): bool
    {
        return $this->is_frozen;
    }

    /**
     * 检查是否可用（未冻结）
     *
     * @return bool
     */
    public function isAvailable(): bool
    {
        return !$this->is_frozen;
    }

    /**
     * 获取用户指定物品的可用数量（排除冻结的堆叠）
     *
     * @param int $userId 用户ID
     * @param int $itemId 物品ID
     * @param int|null $instanceId 实例ID
     * @return int 可用数量
     */
    public static function getAvailableQuantity(int $userId, int $itemId, ?int $instanceId = null): int
    {
        $query = static::where('user_id', $userId)
            ->where('item_id', $itemId)
            ->where('is_frozen', false);

        if ($instanceId) {
            $query->where('instance_id', $instanceId);
        } else {
            $query->whereNull('instance_id');
        }

        return $query->sum('quantity');
    }

    /**
     * 获取用户指定物品的冻结数量
     *
     * @param int $userId 用户ID
     * @param int $itemId 物品ID
     * @param int|null $instanceId 实例ID
     * @return int 冻结数量
     */
    public static function getFrozenQuantity(int $userId, int $itemId, ?int $instanceId = null): int
    {
        $query = static::where('user_id', $userId)
            ->where('item_id', $itemId)
            ->where('is_frozen', true);

        if ($instanceId) {
            $query->where('instance_id', $instanceId);
        } else {
            $query->whereNull('instance_id');
        }

        return $query->sum('quantity');
    }

    /**
     * 获取用户指定物品的总数量（包括冻结的）
     *
     * @param int $userId 用户ID
     * @param int $itemId 物品ID
     * @param int|null $instanceId 实例ID
     * @return int 总数量
     */
    public static function getTotalQuantity(int $userId, int $itemId, ?int $instanceId = null): int
    {
        $query = static::where('user_id', $userId)
            ->where('item_id', $itemId);

        if ($instanceId) {
            $query->where('instance_id', $instanceId);
        } else {
            $query->whereNull('instance_id');
        }

        return $query->sum('quantity');
    }
}