From e4156ecf75003dc78c1a4601d40229f74ecd8610 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=90=9D=E5=8D=9C?= <dev@saasshop.local>
Date: Tue, 17 Mar 2026 19:37:09 +0800
Subject: [PATCH] =?UTF-8?q?ui(component):=20metric=5Fexplain=E9=BB=98?=
 =?UTF-8?q?=E8=AE=A4=E6=8A=98=E5=8F=A0(details)=E9=81=BF=E5=85=8DDashboard?=
 =?UTF-8?q?=E5=8F=A3=E5=BE=84=E8=AF=B4=E6=98=8E=E6=92=91=E6=BB=A1?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../admin/components/metric_explain.blade.php | 24 +++++++++----
 ...ComponentShouldUseDetailsByDefaultTest.php | 34 +++++++++++++++++++
 2 files changed, 52 insertions(+), 6 deletions(-)
 create mode 100644 tests/Feature/AdminMetricExplainComponentShouldUseDetailsByDefaultTest.php

diff --git a/resources/views/admin/components/metric_explain.blade.php b/resources/views/admin/components/metric_explain.blade.php
index 5df2875..9fb0ae3 100644
--- a/resources/views/admin/components/metric_explain.blade.php
+++ b/resources/views/admin/components/metric_explain.blade.php
@@ -1,13 +1,25 @@
 @php
     $items = $items ?? [];
     $title = $title ?? '口径说明';
+    $collapsible = (bool) ($collapsible ?? true);
 @endphp
 
 @if(is_array($items) && count($items) > 0)
-    <div class="muted muted-xs">
-        <strong>{{ $title }}：</strong>
-        @foreach($items as $i => $text)
-            <span>{{ $text }}@if($i < count($items) - 1)；@endif</span>
-        @endforeach
-    </div>
+    @if($collapsible)
+        <details class="muted muted-xs" data-role="metric-explain" style="margin-top:4px;">
+            <summary style="cursor:pointer; user-select:none;"><strong>{{ $title }}：</strong><span class="muted">（点击展开）</span></summary>
+            <div class="mt-6">
+                @foreach($items as $i => $text)
+                    <span>{{ $text }}@if($i < count($items) - 1)；@endif</span>
+                @endforeach
+            </div>
+        </details>
+    @else
+        <div class="muted muted-xs" data-role="metric-explain" style="margin-top:4px;">
+            <strong>{{ $title }}：</strong>
+            @foreach($items as $i => $text)
+                <span>{{ $text }}@if($i < count($items) - 1)；@endif</span>
+            @endforeach
+        </div>
+    @endif
 @endif
diff --git a/tests/Feature/AdminMetricExplainComponentShouldUseDetailsByDefaultTest.php b/tests/Feature/AdminMetricExplainComponentShouldUseDetailsByDefaultTest.php
new file mode 100644
index 0000000..2f80b5f
--- /dev/null
+++ b/tests/Feature/AdminMetricExplainComponentShouldUseDetailsByDefaultTest.php
@@ -0,0 +1,34 @@
+<?php
+
+namespace Tests\Feature;
+
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+class AdminMetricExplainComponentShouldUseDetailsByDefaultTest 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_dashboard_should_render_metric_explain_as_details(): void
+    {
+        $this->loginAsPlatformAdmin();
+
+        $res = $this->get('/admin');
+
+        $res->assertOk();
+        // 组件默认应使用 details 折叠，避免口径说明撑满页面。
+        $res->assertSee('data-role="metric-explain"', false);
+        $res->assertSee('<details', false);
+        $res->assertSee('点击展开');
+    }
+}