<?php

namespace App\Module\GameItems\Events;

use Illuminate\Broadcasting\InteractsWithSockets;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;

/**
 * 物品数量变更事件
 *
 * 当用户物品数量发生变化时触发此事件，包括增加和减少。
 * 此事件可用于监控物品数量变化，更新相关任务进度，
 * 触发成就解锁，以及其他需要响应物品数量变化的系统功能。
 */
class ItemQuantityChanged
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    /**
     * 用户ID
     *
     * 物品所属用户的唯一标识符
     *
     * @var int
     */
    public $userId;

    /**
     * 物品ID
     *
     * 物品的唯一标识符，对应item_items表中的id
     *
     * @var int
     */
    public $itemId;

    /**
     * 物品实例ID（单独属性物品）
     *
     * 单独属性物品的实例ID，对应item_instances表中的id
     * 对于统一属性物品，此值为null
     *
     * @var int|null
     */
    public $instanceId;

    /**
     * 旧数量
     *
     * 变更前的物品数量
     *
     * @var int
     */
    public $oldQuantity;

    /**
     * 新数量
     *
     * 变更后的物品数量
     *
     * @var int
     */
    public $newQuantity;

    /**
     * 变化量（正数表示增加，负数表示减少）
     *
     * 物品数量的变化值，等于newQuantity - oldQuantity
     *
     * @var int
     */
    public $changeAmount;

    /**
     * 用户物品记录ID
     *
     * 对应item_users表中的记录ID
     *
     * @var int
     */
    public $userItemId;

    /**
     * 旧冻结状态
     *
     * 变更前的冻结状态，null表示冻结状态未变更
     *
     * @var bool|null
     */
    public $oldFrozenStatus;

    /**
     * 新冻结状态
     *
     * 变更后的冻结状态，null表示冻结状态未变更
     *
     * @var bool|null
     */
    public $newFrozenStatus;

    /**
     * 选项
     *
     * 包含物品变更的额外信息，如来源类型、来源ID等
     *
     * @var array
     */
    public $options;

    /**
     * 创建一个新的事件实例
     *
     * 初始化物品数量变更事件，记录变更前后的数量信息及相关上下文
     *
     * @param int $userId 用户ID - 物品所属用户的唯一标识符
     * @param int $itemId 物品ID - 物品的唯一标识符
     * @param int|null $instanceId 物品实例ID - 单独属性物品的实例ID，统一属性物品为null
     * @param int $oldQuantity 旧数量 - 变更前的物品数量
     * @param int $newQuantity 新数量 - 变更后的物品数量
     * @param int $userItemId 用户物品记录ID - 对应item_users表中的记录ID
     * @param bool|null $oldFrozenStatus 旧冻结状态 - 变更前的冻结状态，null表示冻结状态未变更
     * @param bool|null $newFrozenStatus 新冻结状态 - 变更后的冻结状态，null表示冻结状态未变更
     * @param array $options 选项 - 包含物品变更的额外信息，如来源类型、来源ID等
     * @return void
     */
    public function __construct(
        int $userId,
        int $itemId,
        ?int $instanceId,
        int $oldQuantity,
        int $newQuantity,
        int $userItemId,
        ?bool $oldFrozenStatus = null,
        ?bool $newFrozenStatus = null,
        array $options = []
    ) {
        $this->userId = $userId;
        $this->itemId = $itemId;
        $this->instanceId = $instanceId;
        $this->oldQuantity = $oldQuantity;
        $this->newQuantity = $newQuantity;
        $this->changeAmount = $newQuantity - $oldQuantity; // 自动计算变化量
        $this->userItemId = $userItemId;
        $this->oldFrozenStatus = $oldFrozenStatus;
        $this->newFrozenStatus = $newFrozenStatus;
        $this->options = $options;
    }
}