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

app/Http/Controllers/HolidayController.php

@@ -15,14 +15,20 @@ namespace App\Http\Controllers;
 
 use App\Enums\CurrencySource;
 use App\Models\HolidayClaim;
-use App\Models\HolidayEvent;
+use App\Models\HolidayEventRun;
 use App\Services\UserCurrencyService;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\DB;
 
+/**
+ * 类功能：处理节日福利批次的前台领取与状态查询。
+ */
 class HolidayController extends Controller
 {
+    /**
+     * 注入用户金币服务。
+     */
     public function __construct(
         private readonly UserCurrencyService $currency,
     ) {}
@@ -30,56 +36,72 @@ class HolidayController extends Controller
     /**
      * 用户领取节日福利红包。
      *
-     * 从 holiday_claims 中查找当前用户的待领取记录，
-     * 入账金币并更新活动统计数据。
+     * 从 holiday_claims 中查找当前用户在指定批次下的待领取记录，
+     * 入账金币并更新批次统计数据。
      */
-    public function claim(Request $request, HolidayEvent $event): JsonResponse
+    public function claim(Request $request, HolidayEventRun $run): JsonResponse
     {
         $user = $request->user();
 
-        // 活动是否在领取有效期内
-        if (! $event->isClaimable()) {
+        // 批次是否在领取有效期内。
+        if (! $run->isClaimable()) {
             return response()->json(['ok' => false, 'message' => '活动已结束或已过期。']);
         }
 
-        // 查找该用户的领取记录（批量插入时已生成）
-        $claim = HolidayClaim::query()
-            ->where('event_id', $event->id)
-            ->where('user_id', $user->id)
-            ->lockForUpdate()
-            ->first();
+        return DB::transaction(function () use ($run, $user): JsonResponse {
+            /** @var HolidayEventRun|null $lockedRun */
+            $lockedRun = HolidayEventRun::query()
+                ->whereKey($run->id)
+                ->lockForUpdate()
+                ->first();
 
-        if (! $claim) {
-            return response()->json(['ok' => false, 'message' => '您不在本次福利名单内，或活动已结束。']);
-        }
+            if (! $lockedRun || ! $lockedRun->isClaimable()) {
+                return response()->json(['ok' => false, 'message' => '活动已结束或已过期。']);
+            }
 
-        // 防止重复领取（claimed_at 为 null 表示未领取）
-        // 由于批量 insert 时直接写入 claimed_at，需要增加一个 is_claimed 字段
-        // 这里用数据库唯一约束保障幂等性：直接返回已领取的提示
-        return DB::transaction(function () use ($event, $claim, $user): JsonResponse {
-            // 金币入账
+            /** @var HolidayClaim|null $claim */
+            $claim = HolidayClaim::query()
+                ->where('run_id', $lockedRun->id)
+                ->where('user_id', $user->id)
+                ->lockForUpdate()
+                ->first();
+
+            if (! $claim) {
+                return response()->json(['ok' => false, 'message' => '您不在本次福利名单内，或活动已结束。']);
+            }
+
+            // claimed_at 不为空代表本轮已领过，直接返回幂等提示。
+            if ($claim->claimed_at !== null) {
+                return response()->json([
+                    'ok' => false,
+                    'message' => '您已领取过本轮福利。',
+                    'amount' => $claim->amount,
+                ]);
+            }
+
+            // 金币入账。
             $this->currency->change(
                 $user,
                 'gold',
                 $claim->amount,
                 CurrencySource::HOLIDAY_BONUS,
-                "节日福利：{$event->name}",
+                "节日福利：{$lockedRun->event_name}",
             );
 
-            // 更新活动统计（只在首次领取时）
-            HolidayEvent::query()
-                ->where('id', $event->id)
-                ->increment('claimed_amount', $claim->amount);
+            // 领取成功后只更新 claimed_at，不再删除记录，便于幂等和历史追踪。
+            $claim->update(['claimed_at' => now()]);
 
-            // 删除领取记录（以此标记"已领取"，防止重复调用）
-            $claim->delete();
+            // 批次领取统计按成功领取次数累计。
+            $lockedRun->increment('claimed_count');
+            $lockedRun->increment('claimed_amount', $claim->amount);
 
-            // 检查是否已全部领完
-            if ($event->max_claimants > 0) {
-                $remaining = HolidayClaim::where('event_id', $event->id)->count();
-                if ($remaining === 0) {
-                    $event->update(['status' => 'completed']);
-                }
+            $remainingPendingClaims = HolidayClaim::query()
+                ->where('run_id', $lockedRun->id)
+                ->whereNull('claimed_at')
+                ->count();
+
+            if ($remainingPendingClaims === 0) {
+                $lockedRun->update(['status' => 'completed']);
             }
 
             return response()->json([
@@ -91,21 +113,23 @@ class HolidayController extends Controller
     }
 
     /**
-     * 查询当前用户在指定活动中的待领取状态。
+     * 查询当前用户在指定批次中的待领取状态。
      */
-    public function status(Request $request, HolidayEvent $event): JsonResponse
+    public function status(Request $request, HolidayEventRun $run): JsonResponse
     {
         $user = $request->user();
 
         $claim = HolidayClaim::query()
-            ->where('event_id', $event->id)
+            ->where('run_id', $run->id)
             ->where('user_id', $user->id)
             ->first();
 
         return response()->json([
-            'claimable' => $claim !== null && $event->isClaimable(),
+            'claimable' => $claim !== null && $claim->claimed_at === null && $run->isClaimable(),
+            'claimed' => $claim?->claimed_at !== null,
             'amount' => $claim?->amount ?? 0,
-            'expires_at' => $event->expires_at?->toIso8601String(),
+            'status' => $run->status,
+            'expires_at' => $run->expires_at?->toIso8601String(),
         ]);
     }
 }