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

<?php

namespace App\Module\GameItems\Models;

use App\Module\GameItems\Enums\FREEZE_ACTION_TYPE;
use App\Module\GameItems\Enums\FREEZE_REASON_TYPE;
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
 * @property  int  $instance_id  物品实例ID（单独属性物品）
 * @property  int  $quantity  冻结数量
 * @property  \App\Module\GameItems\Enums\FREEZE_ACTION_TYPE  $action_type  操作类型（1:冻结, 2:解冻）
 * @property  string  $reason  操作原因
 * @property  int  $source_id  操作方记录ID
 * @property  string  $source_type  操作类型（如：order, admin, system等）
 * @property  int  $operator_id  操作员ID（系统操作为NULL）
 * @property  \Carbon\Carbon  $created_at  操作时间
 * @property  \Carbon\Carbon  $updated_at  更新时间
 * field end
 */
class ItemFreezeLog extends ModelCore
{
    /**
     * 与模型关联的表名
     *
     * @var string
     */
    protected $table = 'item_freeze_logs';

    // attrlist start 
    protected $fillable = [
        'id',
        'user_id',
        'item_id',
        'instance_id',
        'quantity',
        'action_type',
        'reason',
        'source_id',
        'source_type',
        'operator_id',
    ];
    // attrlist end

    /**
     * 应该被转换为原生类型的属性
     *
     * @var array
     */
    protected $casts = [
        'action_type' => FREEZE_ACTION_TYPE::class,
        'quantity' => 'integer',
        'user_id' => 'integer',
        'item_id' => 'integer',
        'instance_id' => 'integer',
        'source_id' => 'integer',
        'operator_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 itemUser(): BelongsTo
    {
        return $this->hasOne(ItemUser::class, 'frozen_log_id', 'id');
    }

    /**
     * 检查是否为冻结操作
     *
     * @return bool
     */
    public function isFreeze(): bool
    {
        return $this->action_type === FREEZE_ACTION_TYPE::FREEZE;
    }

    /**
     * 检查是否为解冻操作
     *
     * @return bool
     */
    public function isUnfreeze(): bool
    {
        return $this->action_type === FREEZE_ACTION_TYPE::UNFREEZE;
    }

    /**
     * 获取操作类型名称
     *
     * @return string
     */
    public function getActionTypeName(): string
    {
        return $this->action_type->getName($this->action_type->value);
    }

    /**
     * 获取格式化的操作描述
     *
     * @return string
     */
    public function getOperationDescription(): string
    {
        $actionName = $this->getActionTypeName();
        $itemName = $this->item->name ?? "物品ID:{$this->item_id}";
        
        if ($this->instance_id) {
            return "{$actionName}单独属性物品: {$itemName} (实例ID: {$this->instance_id})";
        } else {
            return "{$actionName}统一属性物品: {$itemName} x{$this->quantity}";
        }
    }

    /**
     * 创建冻结记录
     *
     * @param int $userId 用户ID
     * @param int $itemId 物品ID
     * @param int|null $instanceId 物品实例ID
     * @param int $quantity 数量
     * @param FREEZE_ACTION_TYPE $actionType 操作类型
     * @param string $reason 操作原因
     * @param int|null $sourceId 来源ID
     * @param string|null $sourceType 来源类型
     * @param int|null $operatorId 操作员ID
     * @return static
     */
    public static function createLog(
        int $userId,
        int $itemId,
        ?int $instanceId,
        int $quantity,
        FREEZE_ACTION_TYPE $actionType,
        string $reason,
        ?int $sourceId = null,
        ?string $sourceType = null,
        ?int $operatorId = null
    ): self {
        return self::create([
            'user_id' => $userId,
            'item_id' => $itemId,
            'instance_id' => $instanceId,
            'quantity' => $quantity,
            'action_type' => $actionType,
            'reason' => $reason,
            'source_id' => $sourceId,
            'source_type' => $sourceType,
            'operator_id' => $operatorId,
        ]);
    }
}