升级节日福利年度调度与批次领取

app/Models/HolidayClaim.php

@@ -15,12 +15,16 @@ namespace App\Models;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
 
+/**
+ * 类功能：记录用户在某个节日福利发放批次中的领取状态。
+ */
 class HolidayClaim extends Model
 {
     public $timestamps = false;
 
     protected $fillable = [
         'event_id',
+        'run_id',
         'user_id',
         'amount',
         'claimed_at',
@@ -45,6 +49,14 @@ class HolidayClaim extends Model
         return $this->belongsTo(HolidayEvent::class, 'event_id');
     }
 
+    /**
+     * 关联所属发放批次。
+     */
+    public function run(): BelongsTo
+    {
+        return $this->belongsTo(HolidayEventRun::class, 'run_id');
+    }
+
     /**
      * 关联领取用户。
      */

app/Models/HolidayEvent.php

@@ -13,11 +13,17 @@
 
 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',
@@ -31,6 +37,12 @@ class HolidayEvent extends Model
         'expire_minutes',
         'repeat_type',
         'cron_expr',
+        'schedule_month',
+        'schedule_day',
+        'schedule_time',
+        'duration_days',
+        'daily_occurrences',
+        'occurrence_interval_minutes',
         'target_type',
         'target_value',
         'status',
@@ -57,6 +69,11 @@ class HolidayEvent extends Model
             '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',
         ];
@@ -71,25 +88,19 @@ class HolidayEvent extends Model
     }
 
     /**
-     * 判断活动是否在领取有效期内。
+     * 本模板对应的所有发放批次。
      */
-    public function isClaimable(): bool
+    public function runs(): HasMany
     {
-        return $this->status === 'active'
-            && $this->expires_at
-            && $this->expires_at->isFuture();
+        return $this->hasMany(HolidayEventRun::class, 'holiday_event_id');
     }
 
     /**
-     * 判断是否还有剩余领取名额。
+     * 判断模板是否使用年度节日调度。
      */
-    public function hasQuota(): bool
+    public function usesYearlySchedule(): bool
     {
-        if ($this->max_claimants === 0) {
-            return true; // 不限人数
-        }
-
-        return $this->claimed_count < $this->max_claimants;
+        return $this->repeat_type === 'yearly';
     }
 
     /**
@@ -100,6 +111,7 @@ class HolidayEvent extends Model
         return static::query()
             ->where('status', 'pending')
             ->where('enabled', true)
+            ->whereNotNull('send_at')
             ->where('send_at', '<=', now())
             ->get();
     }

app/Models/HolidayEventRun.php

@@ -0,0 +1,111 @@
+<?php
+
+/**
+ * 文件功能：节日福利发放批次模型
+ *
+ * 记录节日福利模板的每一次实际发放批次，
+ * 承担领取有效期、批次统计与历史追踪职责。
+ */
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+
+/**
+ * 类功能：封装节日福利单次发放批次的时间、状态和领取统计。
+ */
+class HolidayEventRun extends Model
+{
+    /** @use HasFactory<\Database\Factories\HolidayEventRunFactory> */
+    use HasFactory;
+
+    /**
+     * 允许批量赋值的字段。
+     *
+     * @var array<int, string>
+     */
+    protected $fillable = [
+        'holiday_event_id',
+        'event_name',
+        'event_description',
+        'total_amount',
+        'max_claimants',
+        'distribute_type',
+        'min_amount',
+        'max_amount',
+        'fixed_amount',
+        'target_type',
+        'target_value',
+        'repeat_type',
+        'scheduled_for',
+        'triggered_at',
+        'expires_at',
+        'status',
+        'audience_count',
+        'claimed_count',
+        'claimed_amount',
+    ];
+
+    /**
+     * 属性类型转换。
+     *
+     * @return array<string, string>
+     */
+    protected function casts(): array
+    {
+        return [
+            'scheduled_for' => 'datetime',
+            'triggered_at' => 'datetime',
+            'expires_at' => 'datetime',
+            'total_amount' => 'integer',
+            'max_claimants' => 'integer',
+            'min_amount' => 'integer',
+            'max_amount' => 'integer',
+            'fixed_amount' => 'integer',
+            'audience_count' => 'integer',
+            'claimed_count' => 'integer',
+            'claimed_amount' => 'integer',
+        ];
+    }
+
+    /**
+     * 关联所属节日福利模板。
+     */
+    public function holidayEvent(): BelongsTo
+    {
+        return $this->belongsTo(HolidayEvent::class, 'holiday_event_id');
+    }
+
+    /**
+     * 关联本批次的领取记录。
+     */
+    public function claims(): HasMany
+    {
+        return $this->hasMany(HolidayClaim::class, 'run_id');
+    }
+
+    /**
+     * 判断当前批次是否仍处于可领取状态。
+     */
+    public function isClaimable(): bool
+    {
+        return $this->status === 'active'
+            && $this->expires_at !== null
+            && $this->expires_at->isFuture();
+    }
+
+    /**
+     * 查询需要被自动收尾的批次。
+     */
+    public static function pendingToExpire(): \Illuminate\Database\Eloquent\Collection
+    {
+        return static::query()
+            ->where('status', 'active')
+            ->whereNotNull('expires_at')
+            ->where('expires_at', '<=', now())
+            ->get();
+    }
+}