207 lines
6.7 KiB
Markdown
207 lines
6.7 KiB
Markdown
---
|
||
name: 權限管理與實作規範
|
||
description: 為新功能實作權限控制的完整流程規範，包含後端 Seeder 設定、Middleware 路由保護與前端權限判斷。
|
||
---
|
||
|
||
# 權限管理與實作規範
|
||
|
||
本文件說明如何在新增功能時，一併實作完整的權限控制機制。專案採用 `spatie/laravel-permission` 套件進行權限管理。
|
||
|
||
---
|
||
|
||
## 1. 定義權限 (Backend Seeder)
|
||
|
||
所有權限皆定義於 `database/seeders/PermissionSeeder.php`。
|
||
|
||
### 步驟：
|
||
|
||
1. 開啟 `database/seeders/PermissionSeeder.php`。
|
||
2. 在 `$permissions` 關聯陣列中新增功能對應的權限。
|
||
* **命名慣例**：`{resource}.{action}`（例如：`system.view_logs`, `products.create`）
|
||
* **格式**：`'權限字串' => '中文動作名稱'`
|
||
* 常用動作：`view`, `create`, `edit`, `delete`, `approve`, `cancel`, `export`
|
||
3. 在下方「角色分配」區段，將新權限分配給適合的角色。
|
||
|
||
### 範例：
|
||
|
||
```php
|
||
// 1. 新增權限（注意：是 key => value 格式）
|
||
$permissions = [
|
||
// ... 現有權限
|
||
'utility_fees.view' => '檢視',
|
||
'utility_fees.create' => '建立',
|
||
'utility_fees.edit' => '編輯',
|
||
'utility_fees.delete' => '刪除',
|
||
];
|
||
|
||
// 2. 分配給角色
|
||
$admin->givePermissionTo([
|
||
// ... 現有權限
|
||
'utility_fees.view', 'utility_fees.create', 'utility_fees.edit', 'utility_fees.delete',
|
||
]);
|
||
```
|
||
|
||
### 現有角色定義：
|
||
|
||
| 角色 | 說明 | 權限範圍 |
|
||
|---|---|---|
|
||
| `super-admin` | 系統管理員 | 自動擁有所有權限（`Permission::all()`） |
|
||
| `admin` | 一般管理員 | 大部分權限（除角色管理外） |
|
||
| `warehouse-manager` | 倉庫管理員 | 庫存、盤點、調撥、進貨、門市叫貨 |
|
||
| `purchaser` | 採購人員 | 商品檢視、採購單、退貨、供應商、進貨 |
|
||
| `viewer` | 檢視人員 | 僅限各模組的 `.view` 權限 |
|
||
|
||
---
|
||
|
||
## 2. 套用資料庫變更 (Multi-tenancy)
|
||
|
||
修改 Seeder 後，必須在**中央與所有租戶**同步執行。
|
||
|
||
```bash
|
||
# 對所有租戶執行 Seeder
|
||
./vendor/bin/sail php artisan tenants:seed --class=PermissionSeeder
|
||
```
|
||
|
||
> [!WARNING]
|
||
> 僅執行 `db:seed` 只會更新中央資料庫。務必使用 `tenants:seed` 確保所有租戶同步。
|
||
|
||
---
|
||
|
||
## 3. 路由保護 (Backend Middleware)
|
||
|
||
路由保護定義在各模組自己的 `app/Modules/{ModuleName}/Routes/web.php` 中。
|
||
|
||
> [!IMPORTANT]
|
||
> 路由檔在各模組內（如 `app/Modules/Finance/Routes/web.php`），**不是**全域的 `routes/web.php`。
|
||
|
||
### 範例：
|
||
|
||
```php
|
||
// 單一權限保護
|
||
Route::middleware('permission:utility_fees.view')->group(function () {
|
||
Route::get('/utility-fees', [UtilityFeeController::class, 'index'])->name('utility-fees.index');
|
||
Route::get('/utility-fees/{utilityFee}', [UtilityFeeController::class, 'show'])->name('utility-fees.show');
|
||
});
|
||
|
||
// 巢狀權限群組
|
||
Route::middleware('permission:utility_fees.create')->group(function () {
|
||
Route::get('/utility-fees/create', [UtilityFeeController::class, 'create'])->name('utility-fees.create');
|
||
Route::post('/utility-fees', [UtilityFeeController::class, 'store'])->name('utility-fees.store');
|
||
});
|
||
|
||
// 單行 middleware
|
||
Route::delete('/utility-fees/{utilityFee}', [UtilityFeeController::class, 'destroy'])
|
||
->middleware('permission:utility_fees.delete')
|
||
->name('utility-fees.destroy');
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 配置權限群組名稱 (Backend UI Config)
|
||
|
||
為了讓新權限在「角色與權限」管理介面中正確分組並顯示中文標題，需修改 Controller。
|
||
|
||
**位置**: `app/Modules/Core/Controllers/RoleController.php` → `getGroupedPermissions()`
|
||
|
||
```php
|
||
$groupDefinitions = [
|
||
'products' => '商品資料管理',
|
||
'warehouses' => '倉庫管理',
|
||
'inventory' => '庫存資料管理',
|
||
// ...
|
||
'utility_fees' => '公共事業費管理', // ✅ 新增此行
|
||
];
|
||
```
|
||
|
||
> [!NOTE]
|
||
> 未加入 `$groupDefinitions` 的權限群組仍會顯示，但標題會以原始 key（英文）呈現。
|
||
|
||
---
|
||
|
||
## 5. 前端權限判斷 (React)
|
||
|
||
### 5.1 方式一：`usePermission` Hook（在邏輯中判斷）
|
||
|
||
**位置**: `resources/js/hooks/usePermission.ts`
|
||
|
||
```tsx
|
||
import { usePermission } from "@/hooks/usePermission";
|
||
|
||
export default function ProductIndex() {
|
||
const { can, canAny, isSuperAdmin } = usePermission();
|
||
|
||
return (
|
||
<div>
|
||
{can('products.create') && <Button>新增商品</Button>}
|
||
{canAny(['products.edit', 'products.delete']) && <ManageDropdown />}
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
#### Hook 完整介面：
|
||
|
||
| 方法 | 說明 |
|
||
|---|---|
|
||
| `can(permission)` | 檢查是否擁有**指定**權限 |
|
||
| `canAny(permissions[])` | 檢查是否擁有**任一**權限 |
|
||
| `canAll(permissions[])` | 檢查是否擁有**所有**權限 |
|
||
| `hasRole(role)` | 檢查是否擁有**指定**角色 |
|
||
| `hasAnyRole(roles[])` | 檢查是否擁有**任一**角色 |
|
||
| `hasAllRoles(roles[])` | 檢查是否擁有**所有**角色 |
|
||
| `isSuperAdmin()` | 是否為超級管理員 |
|
||
|
||
> 所有方法對 `super-admin` 角色自動回傳 `true`。
|
||
|
||
### 5.2 方式二：`<Can>` / `<HasRole>` / `<CanAll>` 元件（在 JSX 中包裹）
|
||
|
||
**位置**: `resources/js/Components/Permission/Can.tsx`
|
||
|
||
```tsx
|
||
import { Can, HasRole, CanAll } from '@/Components/Permission/Can';
|
||
|
||
// 單一權限
|
||
<Can permission="products.create">
|
||
<Button>新增商品</Button>
|
||
</Can>
|
||
|
||
// 任一權限（OR 邏輯）
|
||
<Can permission={['products.edit', 'products.delete']}>
|
||
<ManageDropdown />
|
||
</Can>
|
||
|
||
// 所有權限都必須有（AND 邏輯）
|
||
<CanAll permissions={['products.edit', 'products.delete']}>
|
||
<Button>完整管理</Button>
|
||
</CanAll>
|
||
|
||
// 角色判斷
|
||
<HasRole role="admin">
|
||
<Link href="/admin">管理後台</Link>
|
||
</HasRole>
|
||
|
||
// Fallback 支援
|
||
<Can permission="products.delete" fallback={<span className="text-gray-400">無權限</span>}>
|
||
<Button variant="destructive">刪除</Button>
|
||
</Can>
|
||
```
|
||
|
||
> [!IMPORTANT]
|
||
> UI 規範要求：所有可操作按鈕（新增、編輯、刪除）**必須**包裹 `<Can>` 元件或使用 `can()` 判斷。
|
||
> 詳見 [UI 統一規範](file:///home/mama/projects/star-erp/.agents/skills/ui-consistency/SKILL.md)。
|
||
|
||
---
|
||
|
||
## 6. 開發檢核清單 (Checklist)
|
||
|
||
### 後端
|
||
- [ ] `PermissionSeeder.php` 已新增權限字串（`'key' => '中文動作名稱'` 格式）。
|
||
- [ ] `PermissionSeeder.php` 已將新權限分配給 `admin` 及其他適用角色。
|
||
- [ ] 已執行 `./vendor/bin/sail php artisan tenants:seed --class=PermissionSeeder` 同步所有租戶。
|
||
- [ ] `RoleController.php` 的 `$groupDefinitions` 已新增權限群組中文名稱。
|
||
- [ ] 模組路由 (`app/Modules/{ModuleName}/Routes/web.php`) 已加上 `middleware('permission:...')` 保護。
|
||
|
||
### 前端
|
||
- [ ] 頁面按鈕已使用 `usePermission` Hook 或 `<Can>` 元件進行權限控制。
|
||
- [ ] 所有可操作按鈕都包裹於權限判斷中（符合 UI 統一規範）。
|