退款治理：手动修正状态增加安全阀并补测试

app/Http/Controllers/Admin/PlatformOrderController.php

@@ -584,7 +584,8 @@ class PlatformOrderController extends Controller
     {
         $admin = $this->ensurePlatformAdmin($request);
 
-        if ((float) ($order->paid_amount ?? 0) <= 0) {
+        $paidAmount = (float) ($order->paid_amount ?? 0);
+        if ($paidAmount <= 0) {
             return redirect()->back()->with('warning', '当前订单已付金额为 0，无法标记为已退款。');
         }
 
@@ -592,6 +593,12 @@ class PlatformOrderController extends Controller
             return redirect()->back()->with('warning', '当前订单已是已退款状态，无需重复操作。');
         }
 
+        // 安全阀：仅允许在“退款总额已达到/超过已付金额”时标记为已退款
+        $refundTotal = (float) $this->refundTotalForOrder($order);
+        if (round($refundTotal * 100) + 1 < round($paidAmount * 100)) {
+            return redirect()->back()->with('warning', '退款总额尚未达到已付金额，无法标记为已退款。请先核对/补齐退款记录。');
+        }
+
         $now = now();
         $order->payment_status = 'refunded';
         $order->refunded_at = $order->refunded_at ?: $now;
@@ -617,7 +624,8 @@ class PlatformOrderController extends Controller
     {
         $admin = $this->ensurePlatformAdmin($request);
 
-        if ((float) ($order->paid_amount ?? 0) <= 0) {
+        $paidAmount = (float) ($order->paid_amount ?? 0);
+        if ($paidAmount <= 0) {
             return redirect()->back()->with('warning', '当前订单已付金额为 0，无法标记为部分退款。');
         }
 
@@ -625,6 +633,15 @@ class PlatformOrderController extends Controller
             return redirect()->back()->with('warning', '当前订单已是部分退款状态，无需重复操作。');
         }
 
+        // 安全阀：部分退款需要“退款总额>0 且未达到已付金额”
+        $refundTotal = (float) $this->refundTotalForOrder($order);
+        if (round($refundTotal * 100) <= 0) {
+            return redirect()->back()->with('warning', '退款总额为 0，无法标记为部分退款。');
+        }
+        if (round($refundTotal * 100) + 1 >= round($paidAmount * 100)) {
+            return redirect()->back()->with('warning', '退款总额已达到/超过已付金额，建议标记为已退款。');
+        }
+
         $now = now();
         $order->payment_status = 'partially_refunded';
         $order->refunded_at = $order->refunded_at ?: $now;
@@ -650,10 +667,15 @@ class PlatformOrderController extends Controller
     {
         $admin = $this->ensurePlatformAdmin($request);
 
-        if ((float) ($order->paid_amount ?? 0) <= 0) {
+        $paidAmount = (float) ($order->paid_amount ?? 0);
+        if ($paidAmount <= 0) {
             return redirect()->back()->with('warning', '当前订单已付金额为 0，无法标记为已支付。');
         }
 
+        if ((string) $order->payment_status === 'unpaid') {
+            return redirect()->back()->with('warning', '当前订单为未支付状态，不允许直接标记为已支付，请使用「标记支付并生效」或补回执/金额后再处理。');
+        }
+
         if ((string) $order->payment_status === 'paid') {
             return redirect()->back()->with('warning', '当前订单已是已支付状态，无需重复操作。');
         }
@@ -1451,6 +1473,25 @@ class PlatformOrderController extends Controller
 
         return $sum;
     }
+
+    private function refundTotalForOrder(PlatformOrder $order): float
+    {
+        // 优先读扁平字段 refund_summary.total_amount
+        $total = data_get($order->meta, 'refund_summary.total_amount');
+        if ($total !== null) {
+            return (float) $total;
+        }
+
+        // 回退：遍历 refund_receipts[].amount
+        $refunds = (array) (data_get($order->meta, 'refund_receipts', []) ?? []);
+        $sum = 0.0;
+        foreach ($refunds as $r) {
+            $sum += (float) (data_get($r, 'amount') ?? 0);
+        }
+
+        return $sum;
+    }
+
     protected function sumReceiptAmount($orders): float
     {
         $total = 0.0;

tests/Feature/AdminPlatformOrderMarkRefundStatusSafetyValveTest.php

@@ -0,0 +1,153 @@
+<?php
+
+namespace Tests\Feature;
+
+use App\Models\Merchant;
+use App\Models\Plan;
+use App\Models\PlatformOrder;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+class AdminPlatformOrderMarkRefundStatusSafetyValveTest extends TestCase
+{
+    use RefreshDatabase;
+
+    protected function loginAsPlatformAdmin(): void
+    {
+        $this->seed();
+
+        $this->post('/admin/login', [
+            'email' => 'platform.admin@demo.local',
+            'password' => 'Platform@123456',
+        ])->assertRedirect('/admin');
+    }
+
+    public function test_mark_refunded_should_be_blocked_when_refund_total_not_enough(): void
+    {
+        $this->loginAsPlatformAdmin();
+
+        $merchant = Merchant::query()->firstOrFail();
+        $plan = Plan::query()->create([
+            'code' => 'refund_safety_valve_plan_01',
+            'name' => '退款状态安全阀测试套餐',
+            'billing_cycle' => 'monthly',
+            'price' => 10,
+            'list_price' => 10,
+            'status' => 'active',
+            'sort' => 10,
+            'published_at' => now(),
+        ]);
+
+        $order = PlatformOrder::query()->create([
+            'merchant_id' => $merchant->id,
+            'plan_id' => $plan->id,
+            'order_no' => 'PO_REFUND_SAFETY_0001',
+            'order_type' => 'new_purchase',
+            'status' => 'activated',
+            'payment_status' => 'paid',
+            'plan_name' => $plan->name,
+            'billing_cycle' => $plan->billing_cycle,
+            'period_months' => 1,
+            'quantity' => 1,
+            'payable_amount' => 10,
+            'paid_amount' => 10,
+            'placed_at' => now(),
+            'paid_at' => now(),
+            'activated_at' => now(),
+            'meta' => [
+                'refund_summary' => [
+                    'count' => 1,
+                    'total_amount' => 1.00,
+                ],
+            ],
+        ]);
+
+        $this->post('/admin/platform-orders/' . $order->id . '/mark-refunded')
+            ->assertRedirect();
+
+        $order->refresh();
+        $this->assertSame('paid', $order->payment_status);
+    }
+
+    public function test_mark_partially_refunded_should_be_blocked_when_refund_total_is_zero(): void
+    {
+        $this->loginAsPlatformAdmin();
+
+        $merchant = Merchant::query()->firstOrFail();
+        $plan = Plan::query()->create([
+            'code' => 'refund_safety_valve_plan_02',
+            'name' => '退款状态安全阀测试套餐2',
+            'billing_cycle' => 'monthly',
+            'price' => 10,
+            'list_price' => 10,
+            'status' => 'active',
+            'sort' => 10,
+            'published_at' => now(),
+        ]);
+
+        $order = PlatformOrder::query()->create([
+            'merchant_id' => $merchant->id,
+            'plan_id' => $plan->id,
+            'order_no' => 'PO_REFUND_SAFETY_0002',
+            'order_type' => 'new_purchase',
+            'status' => 'activated',
+            'payment_status' => 'paid',
+            'plan_name' => $plan->name,
+            'billing_cycle' => $plan->billing_cycle,
+            'period_months' => 1,
+            'quantity' => 1,
+            'payable_amount' => 10,
+            'paid_amount' => 10,
+            'placed_at' => now(),
+            'paid_at' => now(),
+            'activated_at' => now(),
+            'meta' => [],
+        ]);
+
+        $this->post('/admin/platform-orders/' . $order->id . '/mark-partially-refunded')
+            ->assertRedirect();
+
+        $order->refresh();
+        $this->assertSame('paid', $order->payment_status);
+    }
+
+    public function test_mark_paid_status_should_be_blocked_when_current_status_is_unpaid(): void
+    {
+        $this->loginAsPlatformAdmin();
+
+        $merchant = Merchant::query()->firstOrFail();
+        $plan = Plan::query()->create([
+            'code' => 'refund_safety_valve_plan_03',
+            'name' => '退款状态安全阀测试套餐3',
+            'billing_cycle' => 'monthly',
+            'price' => 10,
+            'list_price' => 10,
+            'status' => 'active',
+            'sort' => 10,
+            'published_at' => now(),
+        ]);
+
+        $order = PlatformOrder::query()->create([
+            'merchant_id' => $merchant->id,
+            'plan_id' => $plan->id,
+            'order_no' => 'PO_REFUND_SAFETY_0003',
+            'order_type' => 'new_purchase',
+            'status' => 'pending',
+            'payment_status' => 'unpaid',
+            'plan_name' => $plan->name,
+            'billing_cycle' => $plan->billing_cycle,
+            'period_months' => 1,
+            'quantity' => 1,
+            'payable_amount' => 10,
+            'paid_amount' => 10,
+            'placed_at' => now(),
+            'meta' => [],
+        ]);
+
+        $this->post('/admin/platform-orders/' . $order->id . '/mark-paid-status')
+            ->assertRedirect();
+
+        $order->refresh();
+        $this->assertSame('unpaid', $order->payment_status);
+    }
+}