kknongchang_2506/app/Module/GameItems/Models/ItemTransactionLog.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  数量（正数表示获取，负数表示消耗）
 * @property   int  $transaction_type  交易类型（1:获取, 2:消耗, 3:交易获得, 4:交易失去, 5:过期失效）
 * @property   string  $source_type  来源类型（如任务奖励、商店购买、宝箱开启等）
 * @property   int  $source_id  来源ID（如任务ID、订单ID、宝箱ID等）
 * @property   object|array  $attributes  额外属性，存储交易相关的详细信息
 * @property   string  $expire_at  物品过期时间（如果有）
 * @property   \Carbon\Carbon  $created_at  创建时间
 * @property   string  $ip_address  操作的IP地址（用于安全审计）
 * @property   string  $device_info  设备信息（用于安全审计）
 * field end
 */
class ItemTransactionLog extends ModelCore
{
    /**
     * 与模型关联的表名
     *
     * @var string
     */
    protected $table = 'item_transaction_logs';

    // attrlist start 
    protected $fillable = [
        'id',
        'user_id',
        'item_id',
        'instance_id',
        'quantity',
        'transaction_type',
        'source_type',
        'source_id',
        'attributes',
        'expire_at',
        'ip_address',
        'device_info',
    ];
    // attrlist end

    /**
     * 可批量赋值的属性
     *
     * @var array
     */
    protected $fillable = [
        'user_id',
        'item_id',
        'instance_id',
        'quantity',
        'transaction_type',
        'source_type',
        'source_id',
        'details',
        'expire_at',
        'ip_address',
        'device_info',
    ];

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

    /**
     * 应该被转换为原生类型的属性
     *
     * @var array
     */
    protected $casts = [
        'details' => \App\Module\GameItems\Casts\TransactionDetailsCast::class,
        'quantity' => 'integer',
        'transaction_type' => 'integer',
    ];

    /**
     * 交易类型常量
     */
    const TYPE_ACQUIRE = 1;    // 获取
    const TYPE_CONSUME = 2;    // 消耗
    const TYPE_TRADE_IN = 3;   // 交易获得
    const TYPE_TRADE_OUT = 4;  // 交易失去
    const TYPE_EXPIRE = 5;     // 过期失效
    const TYPE_DELETE = 6;     // 删除
    const TYPE_CRAFT = 7;      // 合成
    const TYPE_DISMANTLE = 8;  // 分解

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

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

    /**
     * 获取交易类型名称
     *
     * @return string
     */
    public function getTransactionTypeName(): string
    {
        $types = [
            self::TYPE_ACQUIRE => '获取',
            self::TYPE_CONSUME => '消耗',
            self::TYPE_TRADE_IN => '交易获得',
            self::TYPE_TRADE_OUT => '交易失去',
            self::TYPE_EXPIRE => '过期失效',
            self::TYPE_DELETE => '删除',
            self::TYPE_CRAFT => '合成',
            self::TYPE_DISMANTLE => '分解',
        ];

        return $types[$this->transaction_type] ?? '未知';
    }
}