[FEAT] 重構機台日誌 UI 與增加多語系支援，並整合 IoT API 核心架構
- 機台日誌：對齊 Luxury UI 規範，實作整合式佈局與分頁組件。 - 多語系：完成機台日誌繁、英、日三語系翻譯與動態處理。 - UI 規範：更新 SKILL.md 定義「標準列表 Bible」。 - 後端：完善 TenantScoped 隔離邏輯，修復儀表板死循環與 User Model 缺失。 - IoT：擴展機台、會員 Model 並建立交易、商品、狀態等核心表結構。 - 基礎設施：設置台北時區與 Docker 環境變數同步。
This commit is contained in:
52
.agents/rules/rbac-rules.md
Normal file
52
.agents/rules/rbac-rules.md
Normal file
@@ -0,0 +1,52 @@
|
||||
# 多租戶與權限架構實作規範 (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 必須套用 `TenantScoped` Trait。
|
||||
- 當非系統管理員登入時，所有 Eloquent 查詢必須自動加上 `where('company_id', auth()->user()->company_id)`。
|
||||
- **嚴禁**在 Controller 手動撰寫重複的過濾邏輯，除非是複雜的 Raw SQL。
|
||||
|
||||
### 1.3 寫入安全
|
||||
- 建立新資源時，必須在背景強制綁定 `company_id`，禁止由前端傳參決定。
|
||||
- 範例：`$model->company_id = Auth::user()->company_id;`
|
||||
|
||||
---
|
||||
|
||||
## 2. 權限開發規範 (spatie/laravel-permission)
|
||||
|
||||
### 2.1 租戶感知角色 (Tenant-Aware Roles)
|
||||
- `roles` 資料表已擴充 `company_id` 欄位。
|
||||
- 撈取角色清單供指派時，必須過濾 `company_id` 或為 null 的系統預設角色。
|
||||
|
||||
### 2.2 權限命名
|
||||
- 權限名稱應遵循 `[module].[action]` 格式（例如 `machine.view`, `machine.edit`）。
|
||||
- 所有租戶共用相同的權限定義。
|
||||
|
||||
---
|
||||
|
||||
## 3. 介面安全 (UI/Blade)
|
||||
|
||||
### 3.1 身份判定 Helper
|
||||
使用以下方法進行區分：
|
||||
- `$user->isSystemAdmin()`: 判斷是否為平台營運人員。
|
||||
- `$user->isTenant()`: 判斷是否為租戶帳號。
|
||||
|
||||
### 3.2 Blade 指令
|
||||
- 涉及全站管理或跨租戶功能，必須使用 `@if(auth()->user()->isSystemAdmin())` 包裹。
|
||||
- 確保租戶登入時，不會在 Sidebar 或選單看到不屬於其權限範圍的項目。
|
||||
|
||||
---
|
||||
|
||||
## 4. API 安全
|
||||
- 所有的 API Route 應預設包含 `CheckTenantAccess` Middleware。
|
||||
- 嚴禁透過 URL 修改 ID 存取不屬於該租戶的資料，必須依賴 `company_id` 的 Scope 過濾。
|
||||
@@ -17,6 +17,7 @@ Skills 位於 `.agents/skills/`，採漸進式揭露以節省 Token。
|
||||
| 機台通訊, IoT, 日誌上報, Log Ingestion, 異步隊列, Queue, Heartbeat, 心跳發報 | **IoT 通訊與高併發處理規範** | `.agents/skills/iot-communication/SKILL.md` |
|
||||
| 介面, UI, 佈局, CSS, Tailwind, 奢華, 深色模式, Light Mode, Dark Mode, Blade, 樣式, 間距, 陰影, 動畫 | **極簡奢華風 UI 實作規範** | `.agents/skills/ui-minimal-luxury/SKILL.md` |
|
||||
| 查詢、撈資料、Query、Controller、下拉選單、Eloquent、N+1、`->get()`、select、交易、Transaction、Bulk、分頁、索引 | **資料庫與 ORM 最佳實踐規範** | `/home/mama/.gemini/antigravity/global_skills/database-best-practices/SKILL.md` |
|
||||
| RBAC, 權限, 角色, 租戶, Tenant, Company, Access Control, 多租戶, 權限控管 | **多租戶與權限架構實作規範** | `.agents/rules/rbac-rules.md` |
|
||||
|
||||
---
|
||||
|
||||
@@ -27,6 +28,7 @@ Skills 位於 `.agents/skills/`，採漸進式揭露以節省 Token。
|
||||
### 🔴 新增或修改頁面 (Views/Blade) 時
|
||||
必須讀取：
|
||||
1. **ui-minimal-luxury** — 確保符合極簡奢華風視覺與互動規範
|
||||
2. **rbac-rules** — 確認 UI 區塊的權限顯示控制
|
||||
|
||||
### 🔴 新增機台通訊 API 端點時
|
||||
必須讀取：
|
||||
@@ -39,3 +41,4 @@ Skills 位於 `.agents/skills/`，採漸進式揭露以節省 Token。
|
||||
### 🔴 新增或修改 API 與 Controller 撈取資料庫邏輯時
|
||||
必須讀取：
|
||||
1. **database-best-practices** — 確認查詢優化、交易安全、批量寫入與索引規範
|
||||
2. **rbac-rules** — 確保 `company_id` 隔離邏輯正確套用
|
||||
|
||||
@@ -64,14 +64,9 @@ description: 定義 Star Cloud 管理後台的「極簡奢華風」設計規範
|
||||
- **互動原則**: 點擊觸發下拉選單時，必須使用 `x-transition` 且帶有 `scale` 偏移。
|
||||
- **樣式要求**: 選單背景需使用玻璃擬態 (Glassmorphism) 或帶透明度的深色背景。
|
||||
|
||||
## 4. UI 檢查清單 (AI 助手執行前必讀)
|
||||
- [ ] 是否使用了正確的 `rounded-2xl` (或更圓) 的導角？
|
||||
- [ ] 所有的圖示是否一致使用 `lucide-react` 風格？
|
||||
- [ ] 卡片是否有適當的間距 (通常為 `p-6`)？
|
||||
- [ ] 文字色階是否符合：
|
||||
- **標題**: `text-slate-900` / `dark:text-white`
|
||||
- **副標/標籤**: 最小應為 `text-slate-500` / `dark:text-slate-400`（避免使用 `slate-400` 以下等級，以確保對比度足以閱讀）。
|
||||
- [ ] **字體大小**: 確保所有文字至少為 `text-xs`，重要的標籤建議為 `text-sm`。
|
||||
- [ ] **列表佈局**: 是否採用「整合式卡片」結構且內距設為 `p-8`？
|
||||
- [ ] **分頁與總數**: 列表底部是否正確召喚 `vendor.pagination.luxury`？
|
||||
- [ ] **文字色階**: 符合標題 `slate-900/white` 與標籤 `slate-500` 的對比度。
|
||||
|
||||
## 5. 開發注意事項 (Important Notes)
|
||||
|
||||
@@ -85,6 +80,23 @@ description: 定義 Star Cloud 管理後台的「極簡奢華風」設計規範
|
||||
|
||||
## 6. 頁面佈局規範 (Page Layout)
|
||||
|
||||
### 佈局決策規則 (Layout Decision Rules)
|
||||
|
||||
根據篩選條件的複雜程度，選擇適當的清單頁面佈局：
|
||||
|
||||
#### 1. 整合式佈局 (Integrated Layout) - 【預設推薦】
|
||||
- **適用場景**: 絕大多數 CRUD 列表。
|
||||
- **實作方式**: 篩選器、工具列與資料表格全部封裝在同一個 `luxury-card` 中。
|
||||
- **內距規範**: 強制使用 `p-8` 以獲得最佳空氣感。
|
||||
- **元件間距**: 篩選區與表格之間固定使用 `mb-10`。
|
||||
- **範例**: 帳號管理、角色設定、機台日誌。
|
||||
|
||||
#### 2. 分離式佈局 (Split Layout)
|
||||
- **適用場景**: 複雜查詢 (Filtered Fields >= 3 或多行篩選)。
|
||||
- **實作方式**: 篩選區獨立為一個 `luxury-card`，下方間隔 `mb-6` 後再放置資料清單卡片。
|
||||
- **樣式規範**: 篩選卡片通常使用 `p-6`（緊湊式），清單卡片使用 `p-8`（寬鬆式）。
|
||||
- **範例**: 交易紀錄、機台日誌。
|
||||
|
||||
### 標準寬版佈局 (Wide Layout)
|
||||
|
||||
```html
|
||||
@@ -146,23 +158,21 @@ description: 定義 Star Cloud 管理後台的「極簡奢華風」設計規範
|
||||
|
||||
### 文字大小與權重 (Typography Hierarchy)
|
||||
- **表頭 (Table Header)**:
|
||||
- 類別: `text-[12px] font-black text-slate-400 dark:text-slate-500 uppercase tracking-widest`
|
||||
- 類別: `text-[11px] font-black text-slate-400 dark:text-slate-500 uppercase tracking-[0.2em]`
|
||||
- 作用: 提供清晰的欄位定義而不奪取資料視覺焦點。
|
||||
- **主標題 (Primary Item)**:
|
||||
- 類別: `text-base font-extrabold text-slate-800 dark:text-slate-100`
|
||||
- 範例: 公司名稱、機台標題。
|
||||
- 範例: 公司名稱、機體名稱。
|
||||
- **次要資訊 (Secondary Info)**:
|
||||
- 類別: `text-[11px] font-bold text-slate-400 dark:text-slate-500 tracking-[0.15em]`
|
||||
- 範例: 機台序號 (SN)、公司代碼。
|
||||
- 類別: `text-[11px] font-bold text-slate-400 dark:text-slate-500 tracking-[0.1em]`
|
||||
- 範例: 使用者帳號、備註、權限名稱。
|
||||
- **狀態標籤 (Status Badge)**:
|
||||
- 類別: `text-[11px] font-black tracking-widest`
|
||||
- 樣式: 在線 (`emerald`)、離線 (`rose`)。
|
||||
- **時間訊號 (Signals/Time)**:
|
||||
- 類別: `text-[13px] font-bold font-display tracking-widest`
|
||||
- 作用: 解決數字黏滯感，提升判讀舒適度。
|
||||
- 範例: 啟用 (`emerald`)、禁用 (`rose`) / 角色名稱 (`sky`/`indigo`)。
|
||||
- 特性: `px-2.5 py-1 rounded-lg text-[11px] font-black border tracking-wider`
|
||||
|
||||
- **內距 (Padding)**: 單元格統一使用 `px-6 py-6` 以維持呼吸感。
|
||||
- **懸停 (Hover)**: 表格行需具備 `hover:bg-slate-50/80` (深色: `dark:hover:bg-slate-800/40`) 動態反饋。
|
||||
### 空間與反應 (Spacing & Interaction)
|
||||
- **單元格內距**: 統一使用 `px-6 py-6`。
|
||||
- **懸停反應**: 必須在 `tr` 套用 `group` 且子元素套用 `group-hover:bg-slate-50/80` (深色: `dark:group-hover:bg-slate-800/40`) 以提供高級的互動感知。
|
||||
|
||||
### 分頁與列表控制項 (Pagination & Controls)
|
||||
為了維持操作一致性，所有列表的分頁與切換組件必須遵循以下「Luxury Jump」模式：
|
||||
@@ -177,6 +187,73 @@ description: 定義 Star Cloud 管理後台的「極簡奢華風」設計規範
|
||||
- **指示文字**:
|
||||
- 行動端隱藏多餘詞彙，僅保留「1 - 10 / 50」格式。
|
||||
- 數字顏色對齊 `text-slate-600` (深色: `text-slate-300`)。
|
||||
|
||||
### 底部清單控制項 (Bottom List Controls)
|
||||
為了確保長列表的操作便利，清單底部必須具備以下元素：
|
||||
- **位置**: 卡片底部，內距 `px-8 py-6`，並帶有 `border-t border-slate-100/50 dark:border-slate-800/50`。
|
||||
- **左側：每頁筆數 (Per Page Selector)**:
|
||||
- 樣式: `luxury-select` (緊湊型)，高度固定為 `h-9`。
|
||||
- 規範: 提供 `20, 50, 100` 等選項，並在變更時立即提交。
|
||||
- **中央：資料指示 (Info)**:
|
||||
- 樣式: `text-[11px] font-bold tracking-widest uppercase text-slate-400`。
|
||||
- 內容: `Showing X to Y of Z results`。
|
||||
- **右側：分頁導航 (Pagination)**:
|
||||
- 模式: 優先使用 `Luxury Jump` (跳轉下拉選單) 以節省空間並提升效率。
|
||||
|
||||
### 標準清單萬用模板 (Standard List View Bible)
|
||||
建立新列表頁面時，**必須**以此結構為基底：
|
||||
|
||||
```html
|
||||
<div class="space-y-10 pb-20">
|
||||
<!-- 1. Header Area: 標題與全局按鈕 -->
|
||||
<div class="flex items-center justify-between">
|
||||
<div>
|
||||
<h1 class="text-3xl font-black text-slate-800 dark:text-white tracking-tight font-display">{{ __('Title') }}</h1>
|
||||
<p class="text-xs font-bold text-slate-500 dark:text-slate-400 mt-1 uppercase tracking-widest">{{ __('Subtitle') }}</p>
|
||||
</div>
|
||||
<div>
|
||||
<button class="btn-luxury-primary items-center gap-2">...</button>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- 2. Main Integrated Card -->
|
||||
<div class="luxury-card rounded-3xl p-8 animate-luxury-in">
|
||||
<!-- Toolbar & Filters (mb-10) -->
|
||||
<div class="flex items-center justify-between mb-10">
|
||||
<form class="flex items-center gap-4">
|
||||
<!-- luxury-select & luxury-input -->
|
||||
</form>
|
||||
</div>
|
||||
|
||||
<!-- Scrollable Table Area -->
|
||||
<div class="overflow-x-auto">
|
||||
<table class="w-full text-left border-separate border-spacing-y-0">
|
||||
<thead>
|
||||
<tr class="bg-slate-50/50 dark:bg-slate-900/10">
|
||||
<th class="px-6 py-4 text-[11px] font-black text-slate-400 uppercase tracking-[0.2em] border-b border-slate-100 dark:border-slate-800">{{ __('Name') }}</th>
|
||||
<th class="px-6 py-4 text-[11px] font-black text-slate-400 uppercase tracking-[0.2em] border-b border-slate-100 dark:border-slate-800 text-right">{{ __('Action') }}</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody class="divide-y divide-slate-50 dark:divide-slate-800/80">
|
||||
<tr class="group hover:bg-slate-50/80 dark:hover:bg-slate-800/40 transition-all duration-300">
|
||||
<td class="px-6 py-6 font-extrabold text-slate-800 dark:text-slate-100 italic">Example Name</td>
|
||||
<td class="px-6 py-6 text-right"> <!-- Action row --> </td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
|
||||
<!-- 3. Standard Pagination Footer (mt-8) -->
|
||||
<div class="mt-8 border-t border-slate-100/50 dark:border-slate-800/50 pt-6">
|
||||
{{ $items->links('vendor.pagination.luxury') }}
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
### 清單欄位規範 (Column Visibility & Standards)
|
||||
- **固定欄位**: 第一欄通常為「關鍵標識」（如 ID 或時間），應具備特殊字體樣式。
|
||||
- **操作欄位**: 統一位於表格最右端，並命名為 `Action` (或 `操作`)，標題與內容皆應 `text-right`。
|
||||
## 9. 系統兼容性與標準化 (Compatibility & Standardization)
|
||||
|
||||
為了確保在不同版本的開發環境中（如目前專案使用的 Tailwind CSS v3.1）UI 都能正確呈現，並維持全站操作感一致，必須遵守以下額外規範。
|
||||
|
||||
Reference in New Issue
Block a user