141 lines
4.0 KiB
Markdown
141 lines
4.0 KiB
Markdown
|
---
|
|||
|
|
name: 權限管理與實作規範
|
|||
|
|
description: 為新功能實作權限控制的完整流程規範，包含後端 Seeder 設定、Middleware 路由保護與前端權限判斷。
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 權限管理與實作規範
|
|||
|
|
|
|||
|
|
本文件說明如何在新增功能時，一併實作完整的權限控制機制。專案採用 `spatie/laravel-permission` 套件進行權限管理。
|
|||
|
|
|
|||
|
|
## 1. 定義權限 (Backend)
|
|||
|
|
|
|||
|
|
所有權限皆定義於 `database/seeders/PermissionSeeder.php`。
|
|||
|
|
|
|||
|
|
### 步驟：
|
|||
|
|
|
|||
|
|
1. 開啟 `database/seeders/PermissionSeeder.php`。
|
|||
|
|
2. 在 `$permissions` 陣列中新增功能對應的權限字串。
|
|||
|
|
* **命名慣例**：`{resource}.{action}` (例如：`system.view_logs`, `products.create`)
|
|||
|
|
* 常用動作：`view`, `create`, `edit`, `delete`, `publish`, `export`
|
|||
|
|
3. 在下方「角色分配」區段，將新權限分配給適合的角色。
|
|||
|
|
* `super-admin`：通常擁有所有權限（程式碼中 `Permission::all()` 自動涵蓋，無需手動新增）。
|
|||
|
|
* `admin`：通常擁有大部分權限。
|
|||
|
|
* 其他角色 (`warehouse-manager`, `purchaser`, `viewer`)：依業務邏輯分配。
|
|||
|
|
|
|||
|
|
### 範例：
|
|||
|
|
|
|||
|
|
```php
|
|||
|
|
// 1. 新增權限字串
|
|||
|
|
$permissions = [
|
|||
|
|
// ... 現有權限
|
|||
|
|
'system.view_logs', // 新增：檢視系統日誌
|
|||
|
|
];
|
|||
|
|
|
|||
|
|
// ...
|
|||
|
|
|
|||
|
|
// 2. 分配給角色
|
|||
|
|
$admin->givePermissionTo([
|
|||
|
|
// ... 現有權限
|
|||
|
|
'system.view_logs',
|
|||
|
|
]);
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 2. 套用資料庫變更
|
|||
|
|
|
|||
|
|
修改 Seeder 後，必須重新執行 Seeder 以將權限寫入資料庫。
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 對於所有租戶執行 Seeder (開發環境)
|
|||
|
|
php artisan tenants:seed --class=PermissionSeeder
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 3. 路由保護 (Backend Middleware)
|
|||
|
|
|
|||
|
|
在 `routes/web.php` 中，使用 `permission:{name}` middleware 保護路由。
|
|||
|
|
|
|||
|
|
### 範例：
|
|||
|
|
|
|||
|
|
```php
|
|||
|
|
// 單一權限保護
|
|||
|
|
Route::get('/logs', [LogController::class, 'index'])
|
|||
|
|
->middleware('permission:system.view_logs')
|
|||
|
|
->name('logs.index');
|
|||
|
|
|
|||
|
|
// 路由群組保護
|
|||
|
|
Route::middleware('permission:products.view')->group(function () {
|
|||
|
|
// ...
|
|||
|
|
});
|
|||
|
|
|
|||
|
|
// 多重權限 (OR 邏輯：有其一即可)
|
|||
|
|
Route::middleware('permission:products.create|products.edit')->group(function () {
|
|||
|
|
// ...
|
|||
|
|
});
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 4. 前端權限判斷 (React Component)
|
|||
|
|
|
|||
|
|
使用自訂 Hook `usePermission` 來控制 UI 元素的顯示（例如：隱藏沒有權限的按鈕）。
|
|||
|
|
|
|||
|
|
### 引入 Hook：
|
|||
|
|
|
|||
|
|
```tsx
|
|||
|
|
import { usePermission } from "@/hooks/usePermission";
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 使用方式：
|
|||
|
|
|
|||
|
|
```tsx
|
|||
|
|
export default function ProductIndex() {
|
|||
|
|
const { can } = usePermission();
|
|||
|
|
|
|||
|
|
return (
|
|||
|
|
<div>
|
|||
|
|
<h1>商品列表</h1>
|
|||
|
|
|
|||
|
|
{/* 只有擁有 create 權限才顯示按鈕 */}
|
|||
|
|
{can('products.create') && (
|
|||
|
|
<Button>新增商品</Button>
|
|||
|
|
)}
|
|||
|
|
|
|||
|
|
{/* 組合判斷 */}
|
|||
|
|
{can('products.edit') && <EditButton />}
|
|||
|
|
</div>
|
|||
|
|
);
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 權限 Hook 介面說明：
|
|||
|
|
|
|||
|
|
- `can(permission: string)`: 檢查當前使用者是否擁有指定權限。
|
|||
|
|
- `canAny(permissions: string[])`: 檢查當前使用者是否擁有陣列中**任一**權限。
|
|||
|
|
- `hasRole(role: string)`: 檢查當前使用者是否擁有指定角色。
|
|||
|
|
|
|||
|
|
## 5. 配置權限群組名稱 (Backend UI Config)
|
|||
|
|
|
|||
|
|
為了讓新權限在「角色與權限」管理介面中顯示正確的中文分組標題，需修改 Controller 設定。
|
|||
|
|
|
|||
|
|
### 步驟：
|
|||
|
|
|
|||
|
|
1. 開啟 `app/Http/Controllers/Admin/RoleController.php`。
|
|||
|
|
2. 找到 `getGroupedPermissions` 方法。
|
|||
|
|
3. 在 `$groupDefinitions` 陣列中，新增 `{resource}` 對應的中文名稱。
|
|||
|
|
|
|||
|
|
### 範例：
|
|||
|
|
|
|||
|
|
```php
|
|||
|
|
$groupDefinitions = [
|
|||
|
|
'products' => '商品資料管理',
|
|||
|
|
// ...
|
|||
|
|
'utility_fees' => '公共事業費管理', // 新增此行
|
|||
|
|
];
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 檢核清單
|
|||
|
|
|
|||
|
|
- [ ] `PermissionSeeder.php` 已新增權限字串。
|
|||
|
|
- [ ] `PermissionSeeder.php` 已將新權限分配給對應角色。
|
|||
|
|
- [ ] 已執行 `php artisan tenants:seed --class=PermissionSeeder` 更新資料庫。
|
|||
|
|
- [ ] `RoleController.php` 已新增權限群組的中文名稱映射。
|
|||
|
|
- [ ] 後端路由 (`routes/web.php`) 已加上 middleware 保護。
|
|||
|
|
- [ ] 前端頁面/按鈕已使用 `usePermission` 進行顯示控制。
|