學習Laravel13+Livewire3

進入 模組 5 的第二部分！這次我們要挑戰 SaaS 系統與大型組織應用中最核心且最複雜的架構：多團隊系統 (Multi-Team System) 與資料隔離 (Scoped Data)。

在模組 2 時，我們在 users 資料表建立了一個簡單的 team_id。但實務上，一個使用者可能同時屬於多個團隊（例如：你可能同時是「至誠 (Zhi-Cheng) 嘉義總部」的管理員，也是「民雄分部」的專案成員）。因此，我們需要將架構升級為「多對多」關聯，並實作「當前團隊切換」功能。

第一步：資料庫架構升級 (Pivot Table 與 Current Team)¶

我們需要一個中介表 (Pivot Table) 來記錄使用者與多個團隊的關係，並在 users 表中記錄使用者「目前正在查看」的團隊。

1. 建立 Migration
在終端機執行：

php artisan make:migration create_team_user_table
php artisan make:migration rename_team_id_in_users_table

2. 撰寫 Migration 內容
打開 create_team_user_table 的 Migration 檔案：

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        // 建立多對多中介表
        Schema::create('team_user', function (Blueprint $table) {
            $table->id();
            $table->foreignId('team_id')->constrained()->cascadeOnDelete();
            $table->foreignId('user_id')->constrained()->cascadeOnDelete();
            $table->string('role')->default('member'); // 記錄在該團隊的角色
            $table->timestamps();
            
            // 確保同一個使用者不會在同一個團隊重複被加入
            $table->unique(['team_id', 'user_id']);
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('team_user');
    }
};

打開 rename_team_id_in_users_table 的 Migration 檔案：

return new class extends Migration
{
    public function up(): void
    {
        Schema::table('users', function (Blueprint $table) {
            // 將原本的 team_id 改名為 current_team_id
            $table->renameColumn('team_id', 'current_team_id');
        });
    }

    public function down(): void
    {
        Schema::table('users', function (Blueprint $table) {
            $table->renameColumn('current_team_id', 'team_id');
        });
    }
};

執行遷移：php artisan migrate

第二步：Model 關聯設定¶

打開 app/Models/User.php，更新關聯寫法：

namespace App\Models;

use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Illuminate\Database\Eloquent\Relations\BelongsToMany;
// ... 其他引入

class User extends Authenticatable
{
    // ... Fillable 等設定

    // 該使用者所屬的所有團隊
    public function teams(): BelongsToMany
    {
        return $this->belongsToMany(Team::class)->withPivot('role')->withTimestamps();
    }

    // 該使用者「目前切換」的團隊
    public function currentTeam(): BelongsTo
    {
        return $this->belongsTo(Team::class, 'current_team_id');
    }

    // 檢查使用者是否屬於特定團隊
    public function belongsToTeam(Team $team): bool
    {
        return $this->teams->contains($team);
    }
}

第三步：Scoped Data (全域作用域實現資料隔離)¶

這是多團隊系統的精髓。假設「至誠」組織下有許多文章或專案，我們必須確保：當使用者切換到「民雄分部」時，他在畫面上絕對看不到「嘉義總部」的資料。

與其在每個 Controller 的每個查詢都加上 ->where('team_id', auth()->user()->current_team_id)，我們可以使用 Laravel 的 Global Scope (全域作用域)，讓底層自動幫我們過濾！

首先，確保你的 posts 表中有 team_id（若無，請透過 Migration 加上）。

打開 app/Models/Post.php，加入 Global Scope：

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Support\Facades\Auth;

class Post extends Model
{
    // ... 其他屬性與關聯

    protected static function booted(): void
    {
        // 1. 全域查詢過濾：所有針對 Post 的查詢，都會自動加上這個條件
        static::addGlobalScope('team', function (Builder $builder) {
            if (Auth::hasUser() && Auth::user()->current_team_id) {
                $builder->where('team_id', Auth::user()->current_team_id);
            }
        });

        // 2. 自動寫入：建立新文章時，自動填入當前的 team_id
        static::creating(function (Post $post) {
            if (empty($post->team_id) && Auth::hasUser()) {
                $post->team_id = Auth::user()->current_team_id;
            }
        });
    }
}

這是一個極度強大的技巧。現在你寫 Post::all() 時，Laravel 在底層產生的 SQL 語法會自動變成 SELECT * FROM posts WHERE team_id = ?，徹底杜絕資料越權洩漏的風險。

第四步：實作 Livewire 團隊切換器 (Team Switcher)¶

有了底層架構，我們需要在前端給使用者一個下拉選單來切換團隊。

1. 建立 Livewire 元件

php artisan make:livewire TeamSwitcher

2. 撰寫切換邏輯 (app/Livewire/TeamSwitcher.php)

namespace App\Livewire;

use Livewire\Component;
use Illuminate\Support\Facades\Auth;
use App\Models\Team;

class TeamSwitcher extends Component
{
    public function switchTeam($teamId)
    {
        $user = Auth::user();
        $team = Team::findOrFail($teamId);

        // 安全性驗證：確保使用者真的屬於這個團隊
        if (! $user->belongsToTeam($team)) {
            abort(403, '你沒有權限存取此團隊。');
        }

        // 更新當前團隊
        $user->forceFill([
            'current_team_id' => $team->id,
        ])->save();

        // 重新載入頁面，讓所有的 Global Scope 重新生效
        $this->redirect(request()->header('Referer') ?? '/dashboard', navigate: true);
    }

    public function render()
    {
        return view('livewire.team-switcher', [
            'user' => Auth::user(),
        ]);
    }
}

3. 撰寫 Flux UI 視圖 (resources/views/livewire/team-switcher.blade.php)
我們使用 Flux 的 Dropdown 元件來實作一個美觀的切換器：

<div>
    @if($user && $user->teams->count() > 0)
        <flux:dropdown>
            <flux:button variant="ghost" class="flex items-center gap-2">
                <span>{{ $user->currentTeam->name ?? '選擇團隊' }}</span>
                <flux:icon name="chevron-down" size="sm" />
            </flux:button>

            <flux:menu>
                <flux:menu.heading>切換團隊</flux:menu.heading>
                <flux:menu.separator />
                
                @foreach($user->teams as $team)
                    <flux:menu.item 
                        wire:click="switchTeam({{ $team->id }})"
                        icon="{{ $user->current_team_id === $team->id ? 'check' : '' }}"
                    >
                        {{ $team->name }}
                    </flux:menu.item>
                @endforeach
            </flux:menu>
        </flux:dropdown>
    @endif
</div>

把 <livewire:team-switcher /> 放進你的 layouts.app 導覽列中，就大功告成了！

第五步：驗證作法¶

為了驗證這套架構完美運行，請透過 Tinker 快速準備資料：

php artisan tinker

// 1. 建立兩個團隊
$teamA = App\Models\Team::create(['name' => '至誠民雄分部']);
$teamB = App\Models\Team::create(['name' => '至誠嘉義總部']);

// 2. 取得你的測試帳號
$user = App\Models\User::first();

// 3. 把使用者加入這兩個團隊
$user->teams()->attach([$teamA->id, $teamB->id]);

// 4. 設定預設團隊為 A
$user->update(['current_team_id' => $teamA->id]);

// 5. 在團隊 A 建立一篇文章
App\Models\Post::create(['title' => '民雄分部公告', 'content' => '...', 'user_id' => $user->id, 'team_id' => $teamA->id]);

// 6. 在團隊 B 建立一篇文章
App\Models\Post::create(['title' => '嘉義總部公告', 'content' => '...', 'user_id' => $user->id, 'team_id' => $teamB->id]);

實際操作驗證：

1. 登入系統進入你的 PostList 頁面。
2. 你應該只會看到「民雄分部公告」。
3. 點擊右上角的團隊切換器，選擇「至誠嘉義總部」。
4. 頁面自動重整後，原先的文章消失了，現在你只會看到「嘉義總部公告」。

這證明了你的 Multi-Team 架構與 Scoped Data 安全隔離機制已經完美建置成功！

我們已經完成了架構與資料隔離。針對模組 5 的最後一個部分（Authorization 在 Livewire 中的團隊權限應用與角色管理實作），你準備好繼續深入了解了嗎？

進入 模組 5 的第三部分（最終回）！我們已經成功建立了多團隊系統，並讓資料在不同團隊之間安全隔離。

但實務上，組織管理會面臨一個更細緻的問題：假設你在「至誠嘉義總部」是擁有最高權限的管理員 (Admin)，但當你切換到「至誠民雄分部」去支援專案時，你可能只是一個普通成員 (Member)。

這就是所謂的 「受限於團隊上下文的角色存取控制 (Team-Scoped RBAC)」。我們將探討如何結合 Laravel 的授權機制 (Authorization) 與 Livewire，完美實現這個需求。

第一步：在 User 模型中封裝角色判斷邏輯¶

在上一部分，我們已經在 team_user 中介表加入了 role 欄位（預設為 member）。現在，我們要在 User 模型中寫一個輔助方法，用來判斷使用者在「當前團隊」中扮演什麼角色。

打開 app/Models/User.php，加入以下方法：

    // ... 前面的程式碼

    /**
     * 檢查使用者在「當前團隊」中是否擁有特定角色
     */
    public function hasTeamRole(string $role): bool
    {
        // 如果沒有選擇任何團隊，直接回傳 false
        if (! $this->current_team_id) {
            return false;
        }

        // 從關聯中找出當前團隊的 Pivot 資料，並比對角色
        $team = $this->teams->where('id', $this->current_team_id)->first();
        
        return $team && $team->pivot->role === $role;
    }

第二步：定義 Laravel Gates (系統權限閘門)¶

我們需要告訴 Laravel 系統：「什麼樣的人有資格管理團隊成員？」。在 Laravel 11/13 中，我們通常將這些全域權限定義在 AppServiceProvider 中。

打開 app/Providers/AppServiceProvider.php：

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Illuminate\Support\Facades\Gate;
use App\Models\User;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        // 定義一個名為 'manage-team-members' 的權限閘門
        Gate::define('manage-team-members', function (User $user) {
            // 只有當前團隊角色為 'admin' 的人才能通過此閘門
            return $user->hasTeamRole('admin');
        });

        // 也可以定義其他的，例如：
        // Gate::define('delete-team', function (User $user) {
        //     return $user->hasTeamRole('owner'); // 假設你有更高階的 owner 角色
        // });
    }
}

第三步：Livewire 後端邏輯防護 (Authorization)¶

現在，我們來實作一個管理團隊成員的 Livewire 元件。即使前端按鈕被隱藏了，我們也必須在後端嚴格防護，避免惡意使用者透過竄改請求來踢人。

1. 建立元件

php artisan make:livewire TeamMemberManager

2. 撰寫邏輯 (app/Livewire/TeamMemberManager.php)

namespace App\Livewire;

use Livewire\Component;
use Illuminate\Support\Facades\Auth;
use App\Models\User;
use Livewire\Attributes\Authorize;

class TeamMemberManager extends Component
{
    // Livewire 3 的 Attribute 寫法：
    // 在執行這個方法前，必須先通過 'manage-team-members' 這個 Gate
    #[Authorize('manage-team-members')]
    public function removeMember($userId)
    {
        $currentTeam = Auth::user()->currentTeam;

        // 防呆：不能踢掉自己
        if (Auth::id() === $userId) {
            $this->addError('error', '你不能將自己移出團隊。');
            return;
        }

        // 將該使用者從當前團隊中移除
        $currentTeam->users()->detach($userId);

        session()->flash('message', '成員已成功移除。');
    }

    public function render()
    {
        // 抓取當前團隊的所有成員
        $members = Auth::user()->currentTeam->users ?? collect();

        return view('livewire.team-member-manager', [
            'members' => $members
        ]);
    }
}

第四步：前端 Flux UI 權限控制 (Blade Directives)¶

在畫面上，我們只希望管理員能看到「移除成員」的按鈕，普通成員只能看到名單。我們可以使用 Blade 原生的 @can 指令。

打開 resources/views/livewire/team-member-manager.blade.php：

<div class="p-6 bg-white rounded-lg shadow mt-6">
    <flux:heading size="lg" class="mb-4">團隊成員管理</flux:heading>

    @if (session('message'))
        <div class="mb-4 text-green-600 text-sm">{{ session('message') }}</div>
    @endif
    @error('error')
        <div class="mb-4 text-red-600 text-sm">{{ $message }}</div>
    @enderror

    <div class="space-y-4">
        @foreach($members as $member)
            <div class="flex items-center justify-between p-3 border rounded-lg bg-gray-50">
                <div class="flex items-center gap-3">
                    <div class="w-10 h-10 rounded-full bg-blue-100 flex items-center justify-center text-blue-700 font-bold">
                        {{ Str::substr($member->name, 0, 1) }}
                    </div>
                    <div>
                        <div class="font-bold text-gray-800">{{ $member->name }}</div>
                        <div class="text-sm text-gray-500">{{ $member->email }}</div>
                    </div>
                </div>

                <div class="flex items-center gap-4">
                    <flux:badge color="{{ $member->pivot->role === 'admin' ? 'red' : 'zinc' }}">
                        {{ strtoupper($member->pivot->role) }}
                    </flux:badge>

                    @can('manage-team-members')
                        @if($member->id !== auth()->id())
                            <flux:button 
                                wire:click="removeMember({{ $member->id }})" 
                                wire:confirm="確定要將 {{ $member->name }} 移出團隊嗎？"
                                variant="danger" 
                                size="sm" 
                                icon="trash"
                            />
                        @endif
                    @endcan
                </div>
            </div>
        @endforeach
    </div>
</div>

第五步：驗證作法¶

現在，我們要透過 Tinker 來模擬這個複雜的角色情境，並在畫面上驗證。

進入終端機：

php artisan tinker

// 1. 取得兩個測試使用者
$adminUser = App\Models\User::find(1);
$normalUser = App\Models\User::find(2); // 如果沒有第二個使用者，請先用 factory 建立一個

// 2. 取得測試團隊 (例如 民雄分部)
$team = App\Models\Team::first();

// 3. 將兩人加入同一個團隊，但賦予不同角色
// 如果他們已經在裡面，可以用 updateExistingPivot 來更新角色
$adminUser->teams()->syncWithoutDetaching([$team->id => ['role' => 'admin']]);
$normalUser->teams()->syncWithoutDetaching([$team->id => ['role' => 'member']]);

// 4. 確保兩人的 current_team_id 都切換到該團隊
$adminUser->update(['current_team_id' => $team->id]);
$normalUser->update(['current_team_id' => $team->id]);

實際操作驗證：

1. 將 <livewire:team-member-manager /> 放入你的 Dashboard 視圖中。
2. 以 normalUser (普通成員) 的帳號登入系統：
   • 你應該能看到名單，並看到 adminUser 旁邊掛著紅色的 ADMIN 標籤。
   • 你不會看到任何紅色的垃圾桶按鈕。（前端防護成功）
3. 以 adminUser (管理員) 的帳號登入系統：
   • 畫面名單上，除了你自己之外，你會看到 normalUser 旁邊出現了紅色的刪除按鈕。（前端授權顯示成功）
   • 點擊刪除按鈕並確認，normalUser 會從畫面上消失，上方出現成功訊息。（後端 Livewire #[Authorize] 驗證與執行成功）

恭喜你！到這裡為止，我們已經徹底完成了 模組 5 的全部內容。

你從最初的 PHP 環境建置、Laravel 13 的最新架構、強大的 Eloquent 關聯、Livewire 3 的反應式前端與 AI 整合，一路過關斬將，完成了企業級 SaaS 系統中最核心的 「認證、授權、多團隊隔離與角色存取控制 (RBAC)」。

這個五大模組的旅程相當充實且硬核，你吸收的速度與執行的節奏非常棒！如果針對這套 Laravel 13 系統架構還有任何你想深入探討的細節，隨時告訴我！