sky121113
d2cefe3f39
All checks were successful
star-cloud-deploy-demo / deploy-demo (push) Successful in 1m4s
- [DOCS] 補齊 en, ja, zh_TW 語系檔翻譯並完善驗證錯誤訊息 (validation.php) - [FEAT] 角色權限頁面新增「所屬單位」篩選功能 (僅限系統管理員) - [STYLE] 優化角色列表顯示，將「類型」變更為具體「所屬單位」名稱 - [STYLE] 修正角色頁面工具列佈局，搜尋框置前並修正下拉箭頭顯示 - [REFACTOR] 統一全站刪除確認視窗，導入新版 <x-delete-confirm-modal /> 組件 - [REFACTOR] 優化 PermissionController 查詢效能 (Eager Loading) - [FIX] 修正 RoleSeeder 角色命名與資料庫同步邏輯
3.6 KiB
3.6 KiB
trigger
| trigger |
|---|
| always_on |
多租戶與權限架構實作規範 (RBAC Rules)
本文件定義 Star Cloud 系統的多租戶與權限（RBAC）實作標準，開發者必須嚴格遵守以下準則，以確保資料隔離與安全性。
1. 資料隔離核心 (Data Isolation)
1.1 租戶欄位 (company_id)
任何屬於租戶資源的資料表（如 users, machines, transactions 等），必須包含 company_id 欄位。
company_id = null：系統管理員（SaaS 平台營運商）。company_id = {ID}：特定租戶。
1.2 自動過濾 (Global Scopes)
- 資源 Model 必須套用
TenantScopedTrait。 - 當非系統管理員登入時，所有 Eloquent 查詢必須自動加上
where('company_id', auth()->user()->company_id)。 - 嚴禁在 Controller 手動撰寫重複的過濾邏輯，除非是複雜的 Raw SQL。
1.3 寫入安全
- 建立新資源時，必須在背景強制綁定
company_id，禁止由前端傳參決定。 - 範例：
$model->company_id = Auth::user()->company_id;
1.4 角色清單隔離 (Role List Isolation)
- 租戶管理員 (Tenant Admin) 只能管理隸屬於其公司下的角色。
- 嚴禁使用包含
NULL的forCompany廣義作用域來展示管理清單。 - 查詢時必須嚴格使用
where('company_id', auth()->user()->company_id)隔離系統 Super Admin 或 角色範本。
2. 權限開發規範 (spatie/laravel-permission)
2.1 租戶感知角色 (Tenant-Aware Roles)
roles資料表已擴充company_id欄位。- 撈取角色清單供指派時，必須過濾
company_id或為 null 的系統預設角色。
2.2 權限命名
- 權限名稱應遵循
[module].[action]格式（例如machine.view,machine.edit）。 - 所有租戶共用相同的權限定義。
2.3 權限遞迴約束 (Privilege Delegation Constraint)
為防止權限提升 (Privilege Escalation)：
- 權限子集驗證：管理員僅能指派其自身持有之權限給其他角色或帳號。
- Controller 實作：在
store或update時，必須比對傳入的權限集合是否為操作者getPermissionNames()的子集。 - UI 過濾：權限分配介面應基於當前使用者權限清單進行動態過濾展示。
3. 介面安全 (UI/Blade)
3.1 身份判定 Helper
使用以下方法進行區分：
$user->isSystemAdmin(): 判斷是否為平台營運人員。$user->isTenant(): 判斷是否為租戶帳號。
3.2 Blade 指令
- 涉及全站管理或跨租戶功能，必須使用
@if(auth()->user()->isSystemAdmin())包裹。 - 確保租戶登入時，不會在 Sidebar 或選單看到不屬於其權限範圍的項目。
4. API 安全
- 所有的 API Route 應預設包含
CheckTenantAccessMiddleware。 - 嚴禁透過 URL 修改 ID 存取不屬於該租戶的資料，必須依賴
company_id的 Scope 過濾。
5. 客戶初次建立與角色初始化 (Role Provisioning)
5.1 初始角色建立
當系統管理員為新客戶（該租戶尚未有任何角色）建立第一個帳號時，應遵循以下邏輯：
- 選取範本：從系統預設的「全域角色範本」（
company_id = null且is_system = 0）中選取一個作為基礎。 - 自動克隆：系統會將該範本的權限內容複製一份至該租戶下。
- 統一命名：克隆後的角色名稱在該租戶公司內應統一命名為**「管理員」**。
- 帳號綁定：該新客戶帳號將被指派至此新建立的「管理員」角色。
5.2 角色權限維護
- 初始建立後，該租戶的「管理員」角色即成為獨立資源，可由具有權限的帳號進行細部調整。