feat(verification): 教練審核流程完整版——狀態機/證照送審/Admin 裁決/通知

實作 openspec change provider-verification-workflow（25/25 tasks）：
- is_verified 升級為 verification_status 四狀態機（unsubmitted/pending/
  approved/rejected），migration 自動轉換既有資料，API 以 accessor 保留
  is_verified 相容輸出
- 教練端：證照上傳（≤3 張、複用 CompressesImages）、送審、駁回原因
  顯示與重送（/coach/verification 新頁面）
- Admin 端：審核佇列、通過/駁回（原因必填）、撤銷 approved；移除
  toggle-verified 端點（防繞過狀態機）；裁決後 flush 課程快取
- 通知：審核通過/駁回（站內+Email，駁回含原因）
- 可見性與預約入口改判 approved（行為等價）
- 測試 +18（ProviderVerificationTest 10、AdminVerificationTest 8），
  既有 4 個測試檔 helper 遷移；Swagger 同步
- 規格同步：provider-verification 全面改寫、admin-user-management
  toggle 段落改為移除聲明

容器內全套件 173 passed / 439 assertions。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

tests/Feature/AdminVerificationTest.php

@@ -0,0 +1,151 @@
+<?php
+
+namespace Tests\Feature;
+
+use App\Models\ProviderProfile;
+use App\Models\User;
+use App\Notifications\ProviderVerificationApprovedNotification;
+use App\Notifications\ProviderVerificationRejectedNotification;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Facades\Notification;
+use Tests\TestCase;
+
+/**
+ * Admin 審核裁決（provider-verification / admin-user-management 規格）。
+ *
+ * 審核是平台對教練資質的把關承諾：駁回必須有原因（教練的申訴與
+ * 補正依據）、裁決必須走狀態機（不可對未送審者直接通過）、
+ * 舊 toggle 後門必須保持關閉。
+ */
+class AdminVerificationTest extends TestCase
+{
+    use RefreshDatabase;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        Notification::fake();
+    }
+
+    private function makeAdmin(): User
+    {
+        return User::factory()->create(['role' => 'admin']);
+    }
+
+    private function makeProvider(string $status): User
+    {
+        $provider = User::factory()->create(['role' => 'provider']);
+        ProviderProfile::create(['user_id' => $provider->id, 'verification_status' => $status]);
+
+        return $provider;
+    }
+
+    // ── 佇列 ─────────────────────────────────────────────────
+
+    public function test_queue_defaults_to_pending_only(): void
+    {
+        $pending = $this->makeProvider('pending');
+        $this->makeProvider('unsubmitted');
+        $this->makeProvider('approved');
+
+        $response = $this->actingAs($this->makeAdmin())->getJson('/api/admin/verifications');
+
+        $response->assertOk();
+        $ids = array_column($response->json('data'), 'user_id');
+        $this->assertSame([$pending->id], $ids);
+    }
+
+    public function test_queue_can_filter_all_statuses(): void
+    {
+        $this->makeProvider('pending');
+        $this->makeProvider('approved');
+
+        $response = $this->actingAs($this->makeAdmin())->getJson('/api/admin/verifications?status=all');
+
+        $this->assertCount(2, $response->json('data'));
+    }
+
+    // ── 裁決狀態機 ───────────────────────────────────────────
+
+    public function test_approve_pending_provider_and_notify(): void
+    {
+        $provider = $this->makeProvider('pending');
+
+        $this->actingAs($this->makeAdmin())
+            ->putJson("/api/admin/verifications/{$provider->id}/approve")
+            ->assertOk();
+
+        $this->assertSame('approved', $provider->providerProfile->fresh()->verification_status->value);
+        Notification::assertSentTo($provider, ProviderVerificationApprovedNotification::class);
+    }
+
+    public function test_reject_requires_reason(): void
+    {
+        $provider = $this->makeProvider('pending');
+
+        $this->actingAs($this->makeAdmin())
+            ->putJson("/api/admin/verifications/{$provider->id}/reject")
+            ->assertStatus(422);
+
+        $this->assertSame('pending', $provider->providerProfile->fresh()->verification_status->value);
+    }
+
+    public function test_reject_pending_provider_stores_reason_and_notifies(): void
+    {
+        $provider = $this->makeProvider('pending');
+
+        $this->actingAs($this->makeAdmin())
+            ->putJson("/api/admin/verifications/{$provider->id}/reject", ['reason' => '證照已過期'])
+            ->assertOk();
+
+        $profile = $provider->providerProfile->fresh();
+        $this->assertSame('rejected', $profile->verification_status->value);
+        $this->assertSame('證照已過期', $profile->rejection_reason);
+        Notification::assertSentTo($provider, ProviderVerificationRejectedNotification::class);
+    }
+
+    public function test_cannot_approve_unsubmitted_provider(): void
+    {
+        $provider = $this->makeProvider('unsubmitted');
+
+        $this->actingAs($this->makeAdmin())
+            ->putJson("/api/admin/verifications/{$provider->id}/approve")
+            ->assertStatus(422);
+    }
+
+    public function test_can_revoke_approved_provider_with_reason(): void
+    {
+        $provider = $this->makeProvider('approved');
+
+        $this->actingAs($this->makeAdmin())
+            ->putJson("/api/admin/verifications/{$provider->id}/reject", ['reason' => '收到檢舉，資料不實'])
+            ->assertOk();
+
+        $this->assertSame('rejected', $provider->providerProfile->fresh()->verification_status->value);
+    }
+
+    // ── 權限邊界與舊端點 ─────────────────────────────────────
+
+    public function test_non_admin_cannot_access_verification_endpoints(): void
+    {
+        $provider = $this->makeProvider('pending');
+        $member   = User::factory()->create(['role' => 'member']);
+
+        $this->actingAs($member)->getJson('/api/admin/verifications')->assertStatus(403);
+        $this->actingAs($member)
+            ->putJson("/api/admin/verifications/{$provider->id}/approve")
+            ->assertStatus(403);
+        $this->actingAs($provider)
+            ->putJson("/api/admin/verifications/{$provider->id}/approve")
+            ->assertStatus(403);
+    }
+
+    public function test_legacy_toggle_verified_endpoint_is_removed(): void
+    {
+        $provider = $this->makeProvider('approved');
+
+        $this->actingAs($this->makeAdmin())
+            ->putJson("/api/admin/providers/{$provider->id}/toggle-verified")
+            ->assertStatus(404);
+    }
+}

tests/Feature/BookingLifecycleTest.php

@@ -44,7 +44,7 @@ class BookingLifecycleTest extends TestCase
 
         ProviderProfile::create([
             'user_id'     => $provider->id,
-            'is_verified' => $isVerified,
+            'verification_status' => $isVerified ? 'approved' : 'unsubmitted',
         ]);
 
         return $provider;
@@ -171,8 +171,8 @@ class BookingLifecycleTest extends TestCase
         $member   = $this->makeMember();
         $booking  = $this->makeBooking($member, $schedule, BookingStatus::Confirmed);
 
-        // 教練在預約成立後被取消驗證：只擋新預約，不毀既有合約
-        $provider->providerProfile->update(['is_verified' => false]);
+        // 教練在預約成立後被撤銷驗證（approved→rejected）：只擋新預約，不毀既有合約
+        $provider->providerProfile->update(['verification_status' => 'rejected', 'rejection_reason' => '測試撤銷']);
 
         $this->actingAs($member)
             ->getJson("/api/bookings/{$booking->id}/messages")

tests/Feature/BookingOversellTest.php

@@ -36,7 +36,7 @@ class BookingOversellTest extends TestCase
 
         ProviderProfile::create([
             'user_id'     => $provider->id,
-            'is_verified' => true,
+            'verification_status' => 'approved',
         ]);
 
         $offer = DivingOffer::create([

tests/Feature/DivingOfferVisibilityTest.php

@@ -24,7 +24,7 @@ class DivingOfferVisibilityTest extends TestCase
 
         ProviderProfile::create([
             'user_id'     => $provider->id,
-            'is_verified' => $isVerified,
+            'verification_status' => $isVerified ? 'approved' : 'unsubmitted',
         ]);
 
         return $provider;
@@ -127,7 +127,7 @@ class DivingOfferVisibilityTest extends TestCase
 
     // ── 驗證狀態切換立即生效（快取失效） ─────────────────────
 
-    public function test_toggle_verified_takes_effect_immediately_despite_cache(): void
+    public function test_revoking_verification_takes_effect_immediately_despite_cache(): void
     {
         $provider = $this->makeProvider(true);
         $this->makeOffer($provider->id, 'Toggle Course');
@@ -139,10 +139,10 @@ class DivingOfferVisibilityTest extends TestCase
             array_column($this->getJson('/api/diving-offers')->json('data'), 'title')
         );
 
+        // 撤銷驗證（approved→rejected）後快取必須立即失效
         $this->actingAs($admin)
-            ->putJson("/api/admin/providers/{$provider->id}/toggle-verified")
-            ->assertOk()
-            ->assertJsonPath('data.is_verified', false);
+            ->putJson("/api/admin/verifications/{$provider->id}/reject", ['reason' => '資料不實'])
+            ->assertOk();
 
         $this->assertNotContains(
             'Toggle Course',

tests/Feature/ProviderVerificationTest.php

@@ -0,0 +1,163 @@
+<?php
+
+namespace Tests\Feature;
+
+use App\Models\ProviderCertification;
+use App\Models\ProviderProfile;
+use App\Models\User;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Http\UploadedFile;
+use Illuminate\Support\Facades\Storage;
+use Tests\TestCase;
+
+/**
+ * 教練端驗證申請流程（provider-verification 規格）。
+ *
+ * 證照是 Admin 的審核依據：pending/approved 期間若可變更，
+ * 等於審核通過後可抽換證照，狀態機與鎖定規則是審核公信力的基礎。
+ */
+class ProviderVerificationTest extends TestCase
+{
+    use RefreshDatabase;
+
+    private function makeProvider(string $status = 'unsubmitted'): User
+    {
+        $provider = User::factory()->create(['role' => 'provider']);
+        ProviderProfile::create(['user_id' => $provider->id, 'verification_status' => $status]);
+
+        return $provider;
+    }
+
+    private function addCertification(User $provider): ProviderCertification
+    {
+        return ProviderCertification::create([
+            'user_id'    => $provider->id,
+            'image_path' => "providers/{$provider->id}/certifications/test.jpg",
+        ]);
+    }
+
+    // ── 查詢 ─────────────────────────────────────────────────
+
+    public function test_provider_can_view_own_verification_state(): void
+    {
+        $provider = $this->makeProvider('rejected');
+        $provider->providerProfile->update(['rejection_reason' => '證照不清晰']);
+        $this->addCertification($provider);
+
+        $this->actingAs($provider)->getJson('/api/provider/verification')
+            ->assertOk()
+            ->assertJsonPath('data.verification_status', 'rejected')
+            ->assertJsonPath('data.rejection_reason', '證照不清晰')
+            ->assertJsonCount(1, 'data.certifications');
+    }
+
+    // ── 證照上傳與鎖定 ───────────────────────────────────────
+
+    public function test_unsubmitted_provider_can_upload_certification(): void
+    {
+        Storage::fake('public');
+        $provider = $this->makeProvider();
+
+        $this->actingAs($provider)
+            ->postJson('/api/provider/verification/certifications', [
+                'image' => UploadedFile::fake()->image('cert.jpg', 800, 600),
+            ])->assertStatus(201);
+
+        $this->assertSame(1, $provider->providerCertifications()->count());
+    }
+
+    public function test_certification_limit_is_three(): void
+    {
+        Storage::fake('public');
+        $provider = $this->makeProvider();
+        foreach (range(1, 3) as $i) {
+            $this->addCertification($provider);
+        }
+
+        $this->actingAs($provider)
+            ->postJson('/api/provider/verification/certifications', [
+                'image' => UploadedFile::fake()->image('cert4.jpg', 800, 600),
+            ])->assertStatus(422);
+    }
+
+    public function test_certifications_are_locked_while_pending(): void
+    {
+        Storage::fake('public');
+        $provider = $this->makeProvider('pending');
+        $cert     = $this->addCertification($provider);
+
+        $this->actingAs($provider)
+            ->postJson('/api/provider/verification/certifications', [
+                'image' => UploadedFile::fake()->image('late.jpg', 800, 600),
+            ])->assertStatus(422);
+
+        $this->actingAs($provider)
+            ->deleteJson("/api/provider/verification/certifications/{$cert->id}")
+            ->assertStatus(422);
+    }
+
+    public function test_provider_cannot_delete_others_certification(): void
+    {
+        $owner    = $this->makeProvider();
+        $cert     = $this->addCertification($owner);
+        $intruder = $this->makeProvider();
+
+        $this->actingAs($intruder)
+            ->deleteJson("/api/provider/verification/certifications/{$cert->id}")
+            ->assertStatus(403);
+    }
+
+    // ── 送審狀態機 ───────────────────────────────────────────
+
+    public function test_submit_requires_at_least_one_certification(): void
+    {
+        $provider = $this->makeProvider();
+
+        $this->actingAs($provider)
+            ->postJson('/api/provider/verification/submit')
+            ->assertStatus(422);
+
+        $this->assertSame('unsubmitted', $provider->providerProfile->fresh()->verification_status->value);
+    }
+
+    public function test_submit_moves_unsubmitted_to_pending(): void
+    {
+        $provider = $this->makeProvider();
+        $this->addCertification($provider);
+
+        $this->actingAs($provider)
+            ->postJson('/api/provider/verification/submit')
+            ->assertOk();
+
+        $this->assertSame('pending', $provider->providerProfile->fresh()->verification_status->value);
+    }
+
+    public function test_rejected_provider_can_resubmit_and_reason_is_cleared(): void
+    {
+        $provider = $this->makeProvider('rejected');
+        $provider->providerProfile->update(['rejection_reason' => '證照過期']);
+        $this->addCertification($provider);
+
+        $this->actingAs($provider)
+            ->postJson('/api/provider/verification/submit')
+            ->assertOk();
+
+        $profile = $provider->providerProfile->fresh();
+        $this->assertSame('pending', $profile->verification_status->value);
+        $this->assertNull($profile->rejection_reason);
+    }
+
+    public function test_pending_or_approved_provider_cannot_submit_again(): void
+    {
+        foreach (['pending', 'approved'] as $status) {
+            $provider = $this->makeProvider($status);
+            $this->addCertification($provider);
+
+            $this->actingAs($provider)
+                ->postJson('/api/provider/verification/submit')
+                ->assertStatus(422);
+
+            $this->assertSame($status, $provider->providerProfile->fresh()->verification_status->value);
+        }
+    }
+}

tests/Feature/ReviewTest.php

@@ -34,7 +34,7 @@ class ReviewTest extends TestCase
     {
         $provider = User::factory()->create(['role' => 'provider']);
         // 公開評價端點僅對已驗證教練的課程開放（provider-verification 規格）
-        ProviderProfile::create(['user_id' => $provider->id, 'is_verified' => true]);
+        ProviderProfile::create(['user_id' => $provider->id, 'verification_status' => 'approved']);
         return DivingOffer::create([
             'provider_id' => $provider->id,
             'title'       => '測試潛水課程',