chatroom/app/Models/HolidayEvent.php

<?php

/**
 * 文件功能：节日福利活动模型
 *
 * 管理员在后台配置的定时发放金币活动，
 * 支持随机/定额两种分配方式，支持一次性或周期性重复。
 *
 * @author  ChatRoom Laravel
 *
 * @version 1.0.0
 */

namespace App\Models;

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

/**
 * 类功能：定义节日福利模板及其调度配置。
 */
class HolidayEvent extends Model
{
    use HasFactory;

    protected $fillable = [
        'name',
        'description',
        'total_amount',
        'max_claimants',
        'distribute_type',
        'min_amount',
        'max_amount',
        'fixed_amount',
        'send_at',
        'expire_minutes',
        'repeat_type',
        'cron_expr',
        'schedule_month',
        'schedule_day',
        'schedule_time',
        'duration_days',
        'daily_occurrences',
        'occurrence_interval_minutes',
        'target_type',
        'target_value',
        'status',
        'enabled',
        'triggered_at',
        'expires_at',
        'claimed_count',
        'claimed_amount',
    ];

    /**
     * 属性类型转换。
     */
    protected function casts(): array
    {
        return [
            'send_at' => 'datetime',
            'triggered_at' => 'datetime',
            'expires_at' => 'datetime',
            'enabled' => 'boolean',
            'total_amount' => 'integer',
            'max_claimants' => 'integer',
            'min_amount' => 'integer',
            'max_amount' => 'integer',
            'fixed_amount' => 'integer',
            'expire_minutes' => 'integer',
            'schedule_month' => 'integer',
            'schedule_day' => 'integer',
            'duration_days' => 'integer',
            'daily_occurrences' => 'integer',
            'occurrence_interval_minutes' => 'integer',
            'claimed_count' => 'integer',
            'claimed_amount' => 'integer',
        ];
    }

    /**
     * 本次活动的所有领取记录。
     */
    public function claims(): HasMany
    {
        return $this->hasMany(HolidayClaim::class, 'event_id');
    }

    /**
     * 本模板对应的所有发放批次。
     */
    public function runs(): HasMany
    {
        return $this->hasMany(HolidayEventRun::class, 'holiday_event_id');
    }

    /**
     * 判断模板是否使用年度节日调度。
     */
    public function usesYearlySchedule(): bool
    {
        return $this->repeat_type === 'yearly';
    }

    /**
     * 查询待触发的活动（定时任务调用）。
     */
    public static function pendingToTrigger(): \Illuminate\Database\Eloquent\Collection
    {
        return static::query()
            ->where('status', 'pending')
            ->where('enabled', true)
            ->whereNotNull('send_at')
            ->where('send_at', '<=', now())
            ->get();
    }
}