From 7c06ea2330bc3fa7e744c16adc3188bfe39032a4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=90=9D=E5=8D=9C?= <dev@saasshop.local>
Date: Wed, 11 Mar 2026 06:13:54 +0000
Subject: [PATCH] feat: show hint on subscription page when refund inconsistent
 orders exist

---
 .../Admin/SiteSubscriptionController.php      |  2 +-
 .../admin/site_subscriptions/show.blade.php   |  3 +
 ...SubscriptionRefundInconsistentHintTest.php | 91 +++++++++++++++++++
 3 files changed, 95 insertions(+), 1 deletion(-)
 create mode 100644 tests/Feature/AdminSiteSubscriptionRefundInconsistentHintTest.php

diff --git a/app/Http/Controllers/Admin/SiteSubscriptionController.php b/app/Http/Controllers/Admin/SiteSubscriptionController.php
index 45dd7cd..334fd3e 100644
--- a/app/Http/Controllers/Admin/SiteSubscriptionController.php
+++ b/app/Http/Controllers/Admin/SiteSubscriptionController.php
@@ -46,7 +46,7 @@ class SiteSubscriptionController extends Controller
         ];
 
         // 可治理摘要：订阅维度的回执/退款汇总（口径与平台订单列表一致：优先 summary，缺省回退 receipts）
-        $metaOrders = (clone $baseOrdersQuery)->get(['id', 'paid_amount', 'meta']);
+        $metaOrders = (clone $baseOrdersQuery)->get(['id', 'paid_amount', 'payment_status', 'meta']);
 
         $totalReceiptAmount = 0.0;
         $receiptOrders = 0;
diff --git a/resources/views/admin/site_subscriptions/show.blade.php b/resources/views/admin/site_subscriptions/show.blade.php
index 2d33337..6cf0507 100644
--- a/resources/views/admin/site_subscriptions/show.blade.php
+++ b/resources/views/admin/site_subscriptions/show.blade.php
@@ -203,6 +203,9 @@
             退款不一致订单：
             <a class="link" href="{!! $makePlatformOrderUrl(['site_subscription_id' => $subscription->id, 'refund_inconsistent' => '1']) !!}">{{ $summaryStats['refund_inconsistent_orders'] ?? 0 }}</a>
         </div>
+        @if(((int) ($summaryStats['refund_inconsistent_orders'] ?? 0)) > 0)
+            <div class="muted muted-xs text-danger">提示：存在退款状态与退款总额不一致订单。建议先进入列表逐单核对退款轨迹，再在订单详情页使用「退款状态治理」修正状态（仅修口径，不会自动生成回执/退款回执）。</div>
+        @endif
     </div>
 
     <div class="card">
diff --git a/tests/Feature/AdminSiteSubscriptionRefundInconsistentHintTest.php b/tests/Feature/AdminSiteSubscriptionRefundInconsistentHintTest.php
new file mode 100644
index 0000000..e747b9e
--- /dev/null
+++ b/tests/Feature/AdminSiteSubscriptionRefundInconsistentHintTest.php
@@ -0,0 +1,91 @@
+<?php
+
+namespace Tests\Feature;
+
+use App\Models\Merchant;
+use App\Models\Plan;
+use App\Models\PlatformOrder;
+use App\Models\SiteSubscription;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+class AdminSiteSubscriptionRefundInconsistentHintTest 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_show_page_can_render_refund_inconsistent_hint_when_has_inconsistent_orders(): void
+    {
+        $this->loginAsPlatformAdmin();
+
+        $merchant = Merchant::query()->firstOrFail();
+        $plan = Plan::query()->create([
+            'code' => 'sub_refund_inconsistent_hint_01',
+            'name' => '订阅退款不一致提示测试套餐',
+            'billing_cycle' => 'monthly',
+            'price' => 88,
+            'list_price' => 88,
+            'status' => 'active',
+            'sort' => 10,
+            'published_at' => now(),
+        ]);
+
+        $sub = SiteSubscription::query()->create([
+            'merchant_id' => $merchant->id,
+            'plan_id' => $plan->id,
+            'status' => 'activated',
+            'source' => 'manual',
+            'subscription_no' => 'SUB_REFUND_INCONSISTENT_HINT_0001',
+            'plan_name' => $plan->name,
+            'billing_cycle' => 'monthly',
+            'period_months' => 1,
+            'amount' => 88,
+            'starts_at' => now()->subDays(2),
+            'ends_at' => now()->addDays(20),
+            'activated_at' => now()->subDays(2),
+        ]);
+
+        // 构造一个“退款不一致”订单：payment_status=refunded，但退款总额不足（按分取整 + 0.01 容差）
+        PlatformOrder::query()->create([
+            'merchant_id' => $merchant->id,
+            'plan_id' => $plan->id,
+            'site_subscription_id' => $sub->id,
+            'created_by_admin_id' => 1,
+            'order_no' => 'PO_SUB_REFUND_INCONSISTENT_HINT_0001',
+            'order_type' => 'subscription',
+            'status' => 'activated',
+            'payment_status' => 'refunded',
+            'plan_name' => $plan->name,
+            'billing_cycle' => 'monthly',
+            'period_months' => 1,
+            'quantity' => 1,
+            'list_amount' => 88,
+            'discount_amount' => 0,
+            'payable_amount' => 10,
+            'paid_amount' => 10,
+            'placed_at' => now()->subDay(),
+            'paid_at' => now()->subDay(),
+            'activated_at' => now()->subDay(),
+            'meta' => [
+                'refund_summary' => [
+                    'count' => 1,
+                    'total_amount' => 9.98,
+                ],
+            ],
+        ]);
+
+        $this->get('/admin/site-subscriptions/' . $sub->id)
+            ->assertOk()
+            ->assertSee('退款不一致订单：')
+            ->assertSee('提示：存在退款状态与退款总额不一致订单');
+    }
+}