<?php

/**
 * 文件功能：用户成就进度模型。
 *
 * 保存用户在每个固定成就上的最新进度快照，解锁状态由 user_achievements 单独记录。
 */

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

/**
 * 类功能：封装用户成就进度字段、类型转换与用户关联。
 */
class UserAchievementProgress extends Model
{
    /** @use HasFactory<\Database\Factories\UserAchievementProgressFactory> */
    use HasFactory;

    /**
     * 对应的数据表名。
     *
     * @var string
     */
    protected $table = 'user_achievement_progress';

    /**
     * 允许批量赋值的字段。
     *
     * @var array<int, string>
     */
    protected $fillable = [
        'user_id',
        'achievement_key',
        'progress_value',
        'threshold_value',
        'last_scanned_at',
    ];

    /**
     * 属性类型转换。
     *
     * @return array<string, string>
     */
    protected function casts(): array
    {
        return [
            'progress_value' => 'integer',
            'threshold_value' => 'integer',
            'last_scanned_at' => 'datetime',
        ];
    }

    /**
     * 关联：进度记录所属用户。
     */
    public function user(): BelongsTo
    {
        return $this->belongsTo(User::class);
    }
}