refactor: 重構模組通訊與調整儀表板功能
All checks were successful
ERP-Deploy-Demo / deploy-demo (push) Successful in 57s
All checks were successful
ERP-Deploy-Demo / deploy-demo (push) Successful in 57s
- 依循跨模組通訊規範，將 Sales 與 Production 模組中對 Inventory 的直接模型關聯改為透過 InventoryServiceInterface 取得 - 於 InventoryService 實作獲取最高庫存價值、即將過期商品等方法，供儀表板使用 - 確保所有跨模組調用皆採用手動水和（Manual Hydration）方式組合資料 - 移除本地已歸檔的 .agent 規範檔案
This commit is contained in:
115
.agents/rules/activity-logging.md
Normal file
115
.agents/rules/activity-logging.md
Normal file
@@ -0,0 +1,115 @@
|
||||
---
|
||||
trigger: always_on
|
||||
---
|
||||
|
||||
---
|
||||
name: 操作紀錄實作規範
|
||||
description: 規範系統內 Activity Log 的實作標準，包含自動名稱解析、複雜單據合併記錄、與前端顯示優化。
|
||||
---
|
||||
|
||||
# 操作紀錄實作規範 (Activity Logging Skill)
|
||||
|
||||
本文件定義了 Star ERP 系統中操作紀錄的最高實作標準，旨在確保每筆日誌都具有「高度可讀性」與「單一性」。
|
||||
|
||||
---
|
||||
|
||||
## 1. 後端實作核心 (Backend)
|
||||
|
||||
### 1.1 全域 ID 轉名稱邏輯 (Global ID Resolution)
|
||||
為了讓管理者能直覺看懂日誌，所有的 ID（如 `warehouse_id`, `created_by`）在記錄時都應自動解析為名稱。此邏輯應統一在 Model 的 `tapActivity` 中實作。
|
||||
|
||||
#### 關鍵實作參考：
|
||||
```php
|
||||
public function tapActivity(\Spatie\Activitylog\Contracts\Activity $activity, string $eventName)
|
||||
{
|
||||
// 🚩 核心：轉換為陣列以避免 Indirect modification error
|
||||
$properties = $activity->properties instanceof \Illuminate\Support\Collection
|
||||
? $activity->properties->toArray()
|
||||
: $activity->properties;
|
||||
|
||||
// 1. Snapshot 快照：用於主描述的上下文（例如：單號、名稱）
|
||||
$snapshot = $properties['snapshot'] ?? [];
|
||||
$snapshot['doc_no'] = $this->doc_no;
|
||||
$snapshot['warehouse_name'] = $this->warehouse?->name;
|
||||
$properties['snapshot'] = $snapshot;
|
||||
|
||||
// 2. 名稱解析：自動將 attributes 與 old 中的 ID 換成人名/物名
|
||||
$resolver = function (&$data) {
|
||||
if (empty($data) || !is_array($data)) return;
|
||||
|
||||
// 使用者 ID 轉換
|
||||
foreach (['created_by', 'updated_by', 'completed_by'] as $f) {
|
||||
if (isset($data[$f]) && is_numeric($data[$f])) {
|
||||
$data[$f] = \App\Modules\Core\Models\User::find($data[$f])?->name;
|
||||
}
|
||||
}
|
||||
// 倉庫 ID 轉換
|
||||
if (isset($data['warehouse_id']) && is_numeric($data['warehouse_id'])) {
|
||||
$data['warehouse_id'] = \App\Modules\Inventory\Models\Warehouse::find($data['warehouse_id'])?->name;
|
||||
}
|
||||
};
|
||||
|
||||
if (isset($properties['attributes'])) $resolver($properties['attributes']);
|
||||
if (isset($properties['old'])) $resolver($properties['old']);
|
||||
|
||||
$activity->properties = $properties;
|
||||
}
|
||||
```
|
||||
|
||||
### 1.2 複雜操作的日誌合併 (Log Consolidation)
|
||||
當一個操作同時涉及「多個品項異動」與「單據狀態變更」時，**嚴禁**產生多筆重複日誌。
|
||||
|
||||
* **策略**：在 Service 層手動發送主日誌，並使用 `saveQuietly()` 更新單據屬性以抑止 Trait 的自動日誌。
|
||||
* **格式**：主日誌應包含 `items_diff` (品項差異) 與 `attributes/old` (單據狀態變更)。
|
||||
|
||||
```php
|
||||
// Service 中的實作方式
|
||||
DB::transaction(function () use ($doc, $items) {
|
||||
// 1. 更新品項 (記錄變動細節)
|
||||
$updatedItems = $this->getUpdatedItems($doc, $items);
|
||||
|
||||
// 2. 靜默更新單據狀態 (避免 Trait 產生冗餘日誌)
|
||||
$doc->status = 'completed';
|
||||
$doc->saveQuietly();
|
||||
|
||||
// 3. 手動觸發單一合併日誌
|
||||
activity()
|
||||
->performedOn($doc)
|
||||
->withProperties([
|
||||
'items_diff' => ['updated' => $updatedItems],
|
||||
'attributes' => ['status' => 'completed'],
|
||||
'old' => ['status' => 'counting']
|
||||
])
|
||||
->log('updated');
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 前端介面規範 (Frontend)
|
||||
|
||||
### 2.1 標籤命名規範 (Field Labels)
|
||||
前端顯示應完全移除「ID」字眼，提供最友善的閱讀體驗。
|
||||
|
||||
**檔案位置**: `resources/js/Components/ActivityLog/ActivityDetailDialog.tsx`
|
||||
```typescript
|
||||
const fieldLabels: Record<string, string> = {
|
||||
warehouse_id: '倉庫', // ❌ 禁用「倉庫 ID」
|
||||
created_by: '建立者', // ❌ 禁用「建立者 ID」
|
||||
completed_by: '完成者',
|
||||
status: '狀態',
|
||||
};
|
||||
```
|
||||
|
||||
### 2.2 特殊結構顯示
|
||||
* **品項異動**：前端應能渲染 `items_diff` 結構，以「品項名稱 + 數值變動」的方式呈現表格（已在 `ActivityDetailDialog` 實作）。
|
||||
|
||||
---
|
||||
|
||||
## 3. 開發檢核清單 (Checklist)
|
||||
|
||||
- [ ] **Model**: `tapActivity` 是否已處理 Collection 快照？
|
||||
- [ ] **Model**: 是否已實作全域 ID 至名稱的自動解析？
|
||||
- [ ] **Service**: 是否使用 `saveQuietly()` 避免產生重複的「單據已更新」日誌？
|
||||
- [ ] **UI**: `fieldLabels` 是否已移除所有「ID」字樣？
|
||||
- [ ] **UI**: 若有品項異動，是否已正確格式化傳入 `items_diff`？
|
||||
162
.agents/rules/cross-module-communication.md
Normal file
162
.agents/rules/cross-module-communication.md
Normal file
@@ -0,0 +1,162 @@
|
||||
---
|
||||
trigger: always_on
|
||||
---
|
||||
|
||||
---
|
||||
name: 跨模組調用與通訊規範 (Cross-Module Communication)
|
||||
description: 規範 Laravel Modular Monolith 架構下，不同業務模組中如何彼此調用資料與邏輯，包含禁止項目、Interface 實作、與 Service 綁定規則。
|
||||
---
|
||||
|
||||
# 跨模組調用與通訊規範 (Cross-Module Communication)
|
||||
|
||||
為了確保專案的「模組化單體架構 (Modular Monolith)」的獨立性與可維護性，當遇到**需要跨越不同業務模組存取資料或調用功能**的情境時，請嚴格遵守以下規範。
|
||||
|
||||
## 🚫 絕對禁止的行為 (Strict Prohibitions)
|
||||
|
||||
* **禁止跨模組 Eloquent 關聯（例外除外）**
|
||||
* **錯誤**：在 `app/Modules/Sales/Models/Order.php` 中撰寫 `public function product() { return $this->belongsTo(\App\Modules\Inventory\Models\Product::class); }`。
|
||||
* **原因**：這會造成資料庫查詢的強耦合。如果 `Inventory` 模組修改了 Schema，`Sales` 模組會無預警崩壞。
|
||||
* **禁止跨模組直接引入 (use) Model**
|
||||
* **錯誤**：在 `app/Modules/Procurement/Controllers/PurchaseOrderController.php` 頂端寫 `use App\Modules\Inventory\Models\Warehouse;`。
|
||||
* **禁止跨模組直接實例化 (new) Service**
|
||||
* **錯誤**：`$inventoryService = new \App\Modules\Inventory\Services\InventoryService();`
|
||||
|
||||
---
|
||||
|
||||
## 🌟 允許的全域例外 (Global Exceptions)
|
||||
|
||||
雖然我們嚴格禁止跨模組直接相依，但為了開發效率與框架機制的完整性，**`Core` 模組下的特定基礎設施模型 (Infrastructure Models) 被視為全域例外**。
|
||||
|
||||
其他業務模組 **可以** 透過 Eloquent (`belongsTo` / `hasMany`) 直接關聯以下 Model：
|
||||
1. **`App\Modules\Core\Models\User`**：因為幾乎所有表都有 `created_by` / `updated_by`，直接關聯可保留 `with('creator')` 等便利性。
|
||||
2. **`App\Modules\Core\Models\Role`**：權限判定已深度整合至系統底層。
|
||||
3. **`App\Modules\Core\Models\Tenant`**：多租戶架構 (Tenancy) 的核心基石，底層查詢會頻繁依賴。
|
||||
|
||||
> **⚠️ 注意**：這項例外是單向的。`Core` 模組內的業務邏輯（如 `DashboardController`）**絕對不能**反過來直接 `use` 外部業務模組的 Model，仍必須透過外部模組的 Service Interface 來索取資料。
|
||||
|
||||
---
|
||||
|
||||
## ✅ 正確的跨模組調用流程：合約與依賴反轉
|
||||
|
||||
所有的跨模組資料交換與功能調用，必須透過**介面化通訊 (Contracts)** 進行。
|
||||
|
||||
### Step 1: 在被調用的模組定義合約 (Interface)
|
||||
|
||||
如果 `Inventory` 模組需要提供功能給外部使用，請在 `app/Modules/Inventory/Contracts/` 建立 Interface 檔案。
|
||||
|
||||
```php
|
||||
// app/Modules/Inventory/Contracts/InventoryServiceInterface.php
|
||||
namespace App\Modules\Inventory\Contracts;
|
||||
|
||||
use Illuminate\Support\Collection;
|
||||
|
||||
interface InventoryServiceInterface
|
||||
{
|
||||
/**
|
||||
* 取得可用的倉庫清單
|
||||
*
|
||||
* @return Collection 包含每個倉庫的 id, name, code 等基本資料
|
||||
*/
|
||||
public function getActiveWarehouses(): Collection;
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2: 實作介面並在自己模組的 ServiceProvider 註冊
|
||||
|
||||
由 `Inventory` 模組自己的 Service 來實作上述介面。
|
||||
|
||||
```php
|
||||
// app/Modules/Inventory/Services/InventoryService.php
|
||||
namespace App\Modules\Inventory\Services;
|
||||
|
||||
use App\Modules\Inventory\Contracts\InventoryServiceInterface;
|
||||
use App\Modules\Inventory\Models\Warehouse;
|
||||
use Illuminate\Support\Collection;
|
||||
|
||||
class InventoryService implements InventoryServiceInterface
|
||||
{
|
||||
public function getActiveWarehouses(): Collection
|
||||
{
|
||||
// 建議只取出需要的欄位，或者轉換為 DTO / 陣列
|
||||
// 避免將完整的 Eloquent Model 實例拋出模組外
|
||||
return Warehouse::where('is_active', true)
|
||||
->select(['id', 'name', 'code'])
|
||||
->get();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
然後進入 `app/Modules/Inventory/InventoryServiceProvider.php` 完成綁定：
|
||||
|
||||
```php
|
||||
// app/Modules/Inventory/InventoryServiceProvider.php
|
||||
namespace App\Modules\Inventory;
|
||||
|
||||
use Illuminate\Support\ServiceProvider;
|
||||
use App\Modules\Inventory\Contracts\InventoryServiceInterface;
|
||||
use App\Modules\Inventory\Services\InventoryService;
|
||||
|
||||
class InventoryServiceProvider extends ServiceProvider
|
||||
{
|
||||
public function register(): void
|
||||
{
|
||||
// 綁定介面與實體
|
||||
$this->app->bind(InventoryServiceInterface::class, InventoryService::class);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: 調用方透過依賴注入 (DI) 使用服務
|
||||
|
||||
當 `Procurement` 模組需要取得倉庫資料時，禁止直接 new 服務或呼叫倉庫 Model。必須透過**建構子注入**或**方法注入**取得 `InventoryServiceInterface`。
|
||||
|
||||
```php
|
||||
// app/Modules/Procurement/Controllers/PurchaseOrderController.php
|
||||
namespace App\Modules\Procurement\Controllers;
|
||||
|
||||
use App\Http\Controllers\Controller;
|
||||
use App\Modules\Inventory\Contracts\InventoryServiceInterface;
|
||||
use Inertia\Inertia;
|
||||
|
||||
class PurchaseOrderController extends Controller
|
||||
{
|
||||
// 透過建構子注入介面
|
||||
public function __construct(
|
||||
protected InventoryServiceInterface $inventoryService
|
||||
) {}
|
||||
|
||||
public function create()
|
||||
{
|
||||
// 僅能呼叫介面有定義的方法
|
||||
$warehouses = $this->inventoryService->getActiveWarehouses();
|
||||
|
||||
return Inertia::render('Procurement/PurchaseOrder/Create', [
|
||||
'warehouses' => $warehouses
|
||||
]);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 跨模組資料回傳的注意事項 (Data Hydration)
|
||||
|
||||
* **回傳純粹資料**：為了防止其他模組意外觸發 Lazy Loading (`$item->product->name`)，請盡量在 Service 中就用 `with()` 載入好關聯，或者直接轉為原生的 Array、`stdClass`、或具體的 DTO。
|
||||
* **手動組合 (Manual Hydration)**：若某個頁面需要合併兩個模組的資料，這也是被允許的，但必須在 Controller 層級呼叫兩個不同的 Service Interface 後，手動合併。
|
||||
|
||||
### 範例：手動合併資料
|
||||
```php
|
||||
// 錯誤示範（禁止在 OrderService 中去查使用者的關聯）
|
||||
$orders = Order::with('user')->get(); // 如果 user 表在 Core 模組，這是不允許的
|
||||
|
||||
// 正確示範：在各自模組取資料，並手動組裝
|
||||
$orders = $this->orderService->getOrders();
|
||||
$userIds = $orders->pluck('user_id')->unique()->toArray();
|
||||
$users = $this->coreUserService->getUsersByIds($userIds)->keyBy('id');
|
||||
|
||||
$mergedData = $orders->map(function ($order) use ($users) {
|
||||
// 將使用者資料手動附加上去
|
||||
$order->user_name = $users->get($order->user_id)->name ?? 'Unknown';
|
||||
return $order;
|
||||
});
|
||||
```
|
||||
87
.agents/rules/framework.md
Normal file
87
.agents/rules/framework.md
Normal file
@@ -0,0 +1,87 @@
|
||||
---
|
||||
trigger: always_on
|
||||
---
|
||||
|
||||
# 開發框架規範說明書：ERP 系統 (star-erp)
|
||||
|
||||
## 1. 專案概述
|
||||
* **目標**： 打造一個強大且穩定的 ERP 後台管理系統。
|
||||
* **核心架構**： 採用 **模組化單體式架構 (Modular Monolith)** 配現代化前端。使用 Laravel、Inertia.js 及 React。
|
||||
* **工作流程**： 將 UI/UX 設計師提供的 React 原始碼，透過 Inertia.js 整合進 Laravel 環境中。後端邏輯依據「業務領域」拆分為獨立模組。
|
||||
|
||||
## 2. 技術棧 (Tech Stack)
|
||||
* **後端**： PHP 8.5 / Laravel 12
|
||||
* **前端橋樑**： Inertia.js (不使用傳統 RESTful API 串接頁面，改用 Inertia 協議)
|
||||
* **前端庫**： React (以 Functional Components 與 Hooks 為主)
|
||||
* **樣式處理**： Tailwind CSS (確保與 UI/UX 設計稿完全一致)
|
||||
* **資料庫**： MySQL 8.0
|
||||
* **開發環境**： Laravel Sail (Docker / WSL2)
|
||||
* **未來擴充**： 針對高併發或跨平台模組，預留 Golang 微服務接口。
|
||||
|
||||
## 3. 目錄結構與慣例
|
||||
|
||||
### 3.1 後端 (Laravel - Modular Monolith)
|
||||
系統採用模組化架構，核心邏輯位於 `app/Modules/` 下：
|
||||
|
||||
* **Modules**： 位於 `app/Modules/{ModuleName}/`。
|
||||
* **Controllers**： `app/Modules/{ModuleName}/Controllers/`。必須回傳 `Inertia::render()`。
|
||||
* **Models**： `app/Modules/{ModuleName}/Models/`。
|
||||
* **Routes**： `app/Modules/{ModuleName}/Routes/web.php`。各模組獨立管理路由。
|
||||
* **Global Routes**： `routes/web.php` 僅保留全域通用路由或作為模組路由的載入點。
|
||||
|
||||
### 3.2 前端 (React)
|
||||
* **Pages (頁面)**： 位於 `resources/js/Pages/`。每個檔案代表一個完整的路由視圖。
|
||||
* **Components (組件)**： 位於 `resources/js/Components/`。存放由 UI/UX 團隊提供的可重複使用 UI 元件。
|
||||
* **Layouts (版面)**： 位於 `resources/js/Layouts/`。定義 ERP 的通用版面。
|
||||
|
||||
## 4. 整合指南 (UI/UX 轉換至 Laravel)
|
||||
* **組件遷移**： 將 UI/UX 的 React 原始碼移入 `resources/js/` 時，應進行「原子化」拆解，提高元件複用率。
|
||||
* **資料傳遞**： 透過 Laravel Controller 的 props 傳送動態資料給 React。優先使用 Inertia 資料流，避免初次渲染時使用 axios。
|
||||
* **狀態管理**： 優先使用 Inertia 內建的狀態管理與 useForm hook 處理表單提交。
|
||||
|
||||
## 5. 開發標準 (Coding Standards)
|
||||
* **命名規範**：
|
||||
* Controllers: `PascalCaseController.php`
|
||||
* React Components: `PascalCase.jsx`
|
||||
* Routes: `kebab-case` (小寫橫線分隔)
|
||||
* **回傳格式**： 所有的前後端溝通需維持一致的 JSON 結構，特別是驗證錯誤 (Validation Errors) 與閃存訊息 (Flash Messages)。
|
||||
|
||||
## 6. 嚴格模組化通訊規範 (Strict Modular Communication)
|
||||
為了確保系統的可維護性與獨立性，所有模組必須遵守以下「實體解耦」規範：
|
||||
|
||||
* **禁止跨模組 Eloquent 關聯**：禁止在 Model 中定義指向其他模組的 `belongsTo`, `hasMany` 等關聯。
|
||||
* **介面化通訊 (Contracts)**：模組間的資料交換與功能調用必須透過 `app/Modules/{ModuleName}/Contracts/` 下定義的介面進行。
|
||||
* **禁止跨模組 Model 引用**：Controller 與 Service 禁止 `use` 其他模組的 Model (除非是該模組自身的 Contracts)。
|
||||
* **手動資料水和 (Manual Hydration)**：若頁面需要顯示跨模組資料（例：訂單顯示使用者名稱），Controller 應透過 Service 獲取基本資料，再手動組合成前端所需的 JSON/Props 結構。
|
||||
* **資料一致性**：跨模組的資料操作應由各模組的 Service 處理其內部的 transaction 完整性。
|
||||
|
||||
## 7. AI 協作規則 (給 Antigravity AI)
|
||||
* **角色設定**： 你是一位專業的全端開發工程師助手。
|
||||
* **代碼生成指令**：
|
||||
* 所有的解釋說明請使用 **繁體中文**。
|
||||
* 生成 React 組件時，必須符合專案現有的 Tailwind CSS 配置。
|
||||
* 必須考慮 ERP 邏輯（例如：權限判斷、操作日誌、資料完整性）。
|
||||
* 新增功能時，請先判斷應歸屬於哪個 Module，並建立在 `app/Modules/` 對應目錄下。
|
||||
|
||||
## 8. 多租戶開發規範 (Multi-tenancy Standards)
|
||||
本專案採用多租戶隔離架構，開發時必須遵守以下資料同步規則：
|
||||
* **權限與選單同步**：新增 Permission 或修改系統設定時，必須確保中央資料庫 (Central) 與所有租戶資料庫 (Tenants) 均已同步。
|
||||
* **指令執行**：
|
||||
* **Seeders**: 必須執行 `./vendor/bin/sail php artisan tenants:run db:seed` 以確保所有租戶均獲得更新。
|
||||
* **Tinker**: 檢查租戶資料時應使用 `./vendor/bin/sail php artisan tenants:run tinker`。
|
||||
* **Migrations**: 租戶相關的 Schema 異動應放在 `database/migrations/tenant/` 並執行 `./vendor/bin/sail artisan tenants:migrate`。
|
||||
|
||||
## 9. 運行機制 (Docker / Sail)
|
||||
由於專案運行在 Docker 容器環境中，請勿直接在宿主機 (Host) 執行 php 或 composer 指令。請使用專案內建的 `sail` 指令：
|
||||
|
||||
* **啟動環境**： `./vendor/bin/sail up -d`
|
||||
* **執行 PHP 指令**： `./vendor/bin/sail php -v`
|
||||
* **執行 Artisan 指令**： `./vendor/bin/sail artisan route:list`
|
||||
* **執行 Composer**： `./vendor/bin/sail composer install`
|
||||
* **執行 Node/NPM**： `./vendor/bin/sail npm run dev`
|
||||
|
||||
## 10. 日期處理 (Date Handling)
|
||||
|
||||
- 前端顯示日期時預設使用 `resources/js/lib/date.ts` 提供的 `formatDate` 工具。
|
||||
- 避免直接顯示原始 ISO 字串（如 `...Z` 結尾的格式）。
|
||||
- **智慧格式切換**：`formatDate` 會自動判斷原始資料，若時間部分為 `00:00:00` 則僅顯示 `YYYY-MM-DD`，否則顯示 `YYYY-MM-DD HH:mm:ss`。
|
||||
144
.agents/rules/permission-management.md
Normal file
144
.agents/rules/permission-management.md
Normal file
@@ -0,0 +1,144 @@
|
||||
---
|
||||
trigger: always_on
|
||||
---
|
||||
|
||||
---
|
||||
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` 進行顯示控制。
|
||||
512
.agents/rules/ui-consistency.md
Normal file
512
.agents/rules/ui-consistency.md
Normal file
@@ -0,0 +1,512 @@
|
||||
---
|
||||
trigger: always_on
|
||||
---
|
||||
|
||||
---
|
||||
name: 客戶端後台 UI 統一規範
|
||||
description: 確保 Star ERP 客戶端（租戶端）後台所有頁面的 UI 元件保持統一的樣式與行為
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
本技能提供 Star ERP 系統**客戶端（租戶端）後台**的 UI 統一性規範，確保所有頁面使用一致的元件、樣式類別、圖標和佈局模式。
|
||||
|
||||
> **適用範圍**：本規範適用於租戶端後台（使用 `AuthenticatedLayout` 的頁面），**不適用於**中央管理後台（`LandlordLayout`）。
|
||||
|
||||
## 核心原則
|
||||
|
||||
1. **使用統一的 UI 組件庫**：優先使用 `@/Components/ui/` 中的 47 個元件
|
||||
2. **遵循既定的樣式類別**：使用 `app.css` 中定義的自定義按鈕類別
|
||||
3. **統一的圖標系統**：全面使用 `lucide-react` 圖標
|
||||
4. **一致的佈局模式**：表格、分頁、操作按鈕等保持相同結構
|
||||
5. **權限控制**：所有操作按鈕必須使用 `<Can>` 元件包裹
|
||||
|
||||
---
|
||||
|
||||
## 1. 專案結構
|
||||
|
||||
### 1.1 關鍵目錄
|
||||
|
||||
```
|
||||
resources/
|
||||
├── css/
|
||||
│ └── app.css # 全域樣式與設計 Token
|
||||
├── js/
|
||||
│ ├── Components/
|
||||
│ │ ├── ui/ # 47 個基礎 UI 元件 (shadcn/ui)
|
||||
│ │ ├── shared/ # 共用業務元件 (Pagination, BreadcrumbNav 等)
|
||||
│ │ └── Permission/ # 權限控制元件 (Can, HasRole, CanAll)
|
||||
│ ├── Layouts/
|
||||
│ │ ├── AuthenticatedLayout.tsx # 客戶端後台佈局 ⬅️ 本規範適用
|
||||
│ │ └── LandlordLayout.tsx # 中央管理後台佈局
|
||||
│ └── Pages/ # 頁面元件
|
||||
```
|
||||
|
||||
### 1.2 可用 UI 元件清單
|
||||
|
||||
```
|
||||
accordion, alert, alert-dialog, avatar, badge, breadcrumb, button,
|
||||
calendar, card, carousel, chart, checkbox, collapsible, command,
|
||||
context-menu, dialog, drawer, dropdown-menu, form, hover-card,
|
||||
input, input-otp, label, menubar, navigation-menu, pagination,
|
||||
popover, progress, radio-group, resizable, scroll-area,
|
||||
searchable-select, select, separator, sheet, sidebar, skeleton,
|
||||
slider, sonner, switch, table, tabs, textarea, toggle, toggle-group,
|
||||
tooltip
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 色彩系統
|
||||
|
||||
### 2.1 主題色 (Primary) - **動態租戶品牌色**
|
||||
|
||||
> **注意**：主題色會根據租戶設定（Branding）動態改變，**嚴禁**在程式碼中 Hardcode 色碼（如 `#01ab83`）。
|
||||
> 請務必使用 Tailwind Utility Class 或 CSS 變數。
|
||||
|
||||
| Tailwind Class | CSS Variable | 說明 |
|
||||
|----------------|--------------|------|
|
||||
| `*-primary-main` | `--primary-main` | **主色**：與租戶設定一致（預設綠色），用於主要按鈕、連結、強調文字 |
|
||||
| `*-primary-dark` | `--primary-dark` | **深色**：系統自動計算，用於 Hover 狀態 |
|
||||
| `*-primary-light` | `--primary-light` | **淺色**：系統自動計算，用於次要強調 |
|
||||
| `*-primary-lightest` | `--primary-lightest` | **最淺色**：系統自動計算，用於背景底色、Active 狀態 |
|
||||
|
||||
**運作機制**：
|
||||
`AuthenticatedLayout` 會根據後端回傳的 `branding` 資料，自動注入 CSS 變數覆寫預設值。
|
||||
|
||||
```tsx
|
||||
// ✅ 正確：使用 Tailwind Class
|
||||
<div className="text-primary-main">...</div>
|
||||
|
||||
// ✅ 正確：使用 CSS 變數 (自定義樣式時)
|
||||
<div style={{ borderColor: 'var(--primary-main)' }}>...</div>
|
||||
|
||||
// ❌ 錯誤：寫死色碼 (會導致租戶無法換色)
|
||||
<div className="text-[#01ab83]">...</div>
|
||||
```
|
||||
|
||||
### 2.2 灰階 (Grey Scale)
|
||||
|
||||
```css
|
||||
--grey-0: #1a1a1a; /* 深黑 - 標題文字 */
|
||||
--grey-1: #4a4a4a; /* 深灰 - 主要內文 */
|
||||
--grey-2: #6b6b6b; /* 中灰 - 次要內文、Placeholder */
|
||||
--grey-3: #9e9e9e; /* 淺灰 - 禁用文字、輔助說明 */
|
||||
--grey-4: #e0e0e0; /* 極淺灰 - 邊框、分隔線 */
|
||||
--grey-5: #fff; /* 白色 - 背景、按鈕文字 */
|
||||
```
|
||||
|
||||
### 2.3 狀態色 (State Colors)
|
||||
|
||||
```css
|
||||
--other-success: #01ab83; /* 成功 - 同主題色 */
|
||||
--other-error: #dc2626; /* 錯誤 - 刪除、警示 */
|
||||
--other-warning: #f59e0b; /* 警告 - 提醒、注意 */
|
||||
--other-info: #3b82f6; /* 資訊 - 說明、提示 */
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 按鈕規範
|
||||
|
||||
### 3.1 按鈕樣式類別
|
||||
|
||||
專案在 `resources/css/app.css` 中定義了統一的按鈕樣式，**必須**使用這些類別：
|
||||
|
||||
#### Filled 按鈕（實心按鈕）— 用於主要操作
|
||||
|
||||
```tsx
|
||||
// ✅ 主要操作按鈕（綠色主題色）- 新增、儲存、確認
|
||||
<Button className="button-filled-primary">
|
||||
<Plus className="h-4 w-4 mr-2" />
|
||||
新增項目
|
||||
</Button>
|
||||
|
||||
// ✅ 成功操作
|
||||
<Button className="button-filled-success">確認</Button>
|
||||
|
||||
// ✅ 資訊操作（用於系統提示、說明等非業務主流程）
|
||||
<Button className="button-filled-info">系統資訊</Button>
|
||||
|
||||
// ✅ 警告操作
|
||||
<Button className="button-filled-warning">警告</Button>
|
||||
|
||||
// ✅ 錯誤/刪除操作（AlertDialog 內確認按鈕）
|
||||
<Button className="button-filled-error">刪除</Button>
|
||||
```
|
||||
|
||||
#### Outlined 按鈕（邊框按鈕）— 用於次要操作
|
||||
|
||||
```tsx
|
||||
// ✅ 編輯按鈕（表格操作列）
|
||||
<Button variant="outline" size="sm" className="button-outlined-primary">
|
||||
<Pencil className="h-4 w-4" />
|
||||
</Button>
|
||||
|
||||
// ✅ 刪除按鈕（表格操作列）
|
||||
<Button variant="outline" size="sm" className="button-outlined-error">
|
||||
<Trash2 className="h-4 w-4" />
|
||||
</Button>
|
||||
```
|
||||
|
||||
#### Text 按鈕（文字按鈕）
|
||||
|
||||
```tsx
|
||||
<Button className="button-text-primary">查看更多</Button>
|
||||
```
|
||||
|
||||
### 3.2 按鈕大小
|
||||
|
||||
| Size | 高度 | 使用情境 |
|
||||
|------|------|----------|
|
||||
| `size="sm"` | h-8 | 表格操作列、緊湊佈局 |
|
||||
| `size="default"` | h-9 | 一般操作、表單提交 |
|
||||
| `size="lg"` | h-10 | 主要 CTA、頁面主操作 |
|
||||
| `size="icon"` | 9×9 | 純圖標按鈕 |
|
||||
|
||||
### 3.3 常見操作按鈕模式
|
||||
|
||||
#### 頁面頂部新增按鈕
|
||||
|
||||
```tsx
|
||||
<Can permission="resource.create">
|
||||
<Link href={route('resource.create')}>
|
||||
<Button className="button-filled-primary">
|
||||
<Plus className="h-4 w-4 mr-2" />
|
||||
新增XXX
|
||||
</Button>
|
||||
</Link>
|
||||
</Can>
|
||||
```
|
||||
|
||||
#### 表格操作列檢視按鈕
|
||||
|
||||
```tsx
|
||||
<Can permission="resource.view">
|
||||
<Link href={route('resource.show', item.id)}>
|
||||
<Button
|
||||
variant="outline"
|
||||
size="sm"
|
||||
className="button-outlined-primary"
|
||||
title="檢視"
|
||||
>
|
||||
<Eye className="h-4 w-4" />
|
||||
</Button>
|
||||
</Link>
|
||||
</Can>
|
||||
```
|
||||
|
||||
#### 表格操作列編輯按鈕
|
||||
|
||||
```tsx
|
||||
<Can permission="resource.edit">
|
||||
<Link href={route('resource.edit', item.id)}>
|
||||
<Button
|
||||
variant="outline"
|
||||
size="sm"
|
||||
className="button-outlined-primary"
|
||||
title="編輯"
|
||||
>
|
||||
<Pencil className="h-4 w-4" />
|
||||
</Button>
|
||||
</Link>
|
||||
</Can>
|
||||
```
|
||||
|
||||
#### 表格操作列刪除按鈕（帶確認對話框）
|
||||
|
||||
```tsx
|
||||
<Can permission="resource.delete">
|
||||
<AlertDialog>
|
||||
<AlertDialogTrigger asChild>
|
||||
<Button
|
||||
variant="outline"
|
||||
size="sm"
|
||||
className="button-outlined-error"
|
||||
title="刪除"
|
||||
>
|
||||
<Trash2 className="h-4 w-4" />
|
||||
</Button>
|
||||
</AlertDialogTrigger>
|
||||
<AlertDialogContent>
|
||||
<AlertDialogHeader>
|
||||
<AlertDialogTitle>確認刪除</AlertDialogTitle>
|
||||
<AlertDialogDescription>
|
||||
確定要刪除「{item.name}」嗎？此操作無法復原。
|
||||
</AlertDialogDescription>
|
||||
</AlertDialogHeader>
|
||||
<AlertDialogFooter>
|
||||
<AlertDialogCancel>取消</AlertDialogCancel>
|
||||
<AlertDialogAction
|
||||
onClick={() => handleDelete(item.id)}
|
||||
className="bg-red-600 hover:bg-red-700"
|
||||
>
|
||||
刪除
|
||||
</AlertDialogAction>
|
||||
</AlertDialogFooter>
|
||||
</AlertDialogContent>
|
||||
</AlertDialog>
|
||||
</Can>
|
||||
```
|
||||
|
||||
### 3.4 返回按鈕規範
|
||||
|
||||
詳情頁面（如：查看庫存、進貨單詳情）的返回按鈕應統一放置於 **頁面標題上方**，並採用「**圖標 + 文字**」的 Outlined 樣式。
|
||||
|
||||
**樣式規格**：
|
||||
- **位置**：標題區域上方 (`mb-6`)，獨立於標題列
|
||||
- **樣式**：`variant="outline"` + `className="gap-2 button-outlined-primary"`
|
||||
- **圖標**：`<ArrowLeft className="h-4 w-4" />`
|
||||
- **文字**：清楚說明返回目的地，例如「返回倉庫管理」、「返回列表」
|
||||
|
||||
```tsx
|
||||
<div className="mb-6">
|
||||
<Link href={route('resource.index')}>
|
||||
<Button
|
||||
variant="outline"
|
||||
className="gap-2 button-outlined-primary"
|
||||
>
|
||||
<ArrowLeft className="h-4 w-4" />
|
||||
返回列表
|
||||
</Button>
|
||||
</Link>
|
||||
</div>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3.5 頁面佈局規範（新增/編輯頁面）
|
||||
|
||||
### 標準結構
|
||||
|
||||
新增/編輯頁面（如：商品新增、採購單建立）應遵循以下標準結構：
|
||||
|
||||
```tsx
|
||||
<AuthenticatedLayout breadcrumbs={...}>
|
||||
<Head title="..." />
|
||||
|
||||
<div className="container mx-auto p-6 max-w-7xl">
|
||||
{/* Header */}
|
||||
<div className="mb-6">
|
||||
{/* 返回按鈕 */}
|
||||
<Link href={route('resource.index')}>
|
||||
<Button
|
||||
variant="outline"
|
||||
className="gap-2 button-outlined-primary mb-4"
|
||||
>
|
||||
<ArrowLeft className="h-4 w-4" />
|
||||
返回列表
|
||||
</Button>
|
||||
</Link>
|
||||
|
||||
{/* 頁面標題區塊 */}
|
||||
<div className="mb-4">
|
||||
<h1 className="text-2xl font-bold text-grey-0 flex items-center gap-2">
|
||||
<Icon className="h-6 w-6 text-primary-main" />
|
||||
頁面標題
|
||||
</h1>
|
||||
<p className="text-gray-500 mt-1">
|
||||
頁面說明文字
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{/* 表單或內容區塊 */}
|
||||
<FormComponent ... />
|
||||
</div>
|
||||
</AuthenticatedLayout>
|
||||
```
|
||||
|
||||
### 關鍵規範
|
||||
|
||||
1. **外層容器**：使用 `className="container mx-auto p-6 max-w-7xl"` 確保寬度與間距一致
|
||||
2. **Header 包裹**：使用 `<div className="mb-6">` 包裹返回按鈕與標題區塊
|
||||
3. **返回按鈕**：加上 `mb-4` 與標題區塊分隔
|
||||
4. **標題區塊**：使用 `<div className="mb-4">` 包裹 h1 和 p 標籤
|
||||
5. **標題樣式**：`text-2xl font-bold text-grey-0 flex items-center gap-2`
|
||||
6. **說明文字**：`text-gray-500 mt-1`
|
||||
|
||||
### 範例頁面
|
||||
|
||||
- ✅ `/resources/js/Pages/PurchaseOrder/Create.tsx`（建立採購單）
|
||||
- ✅ `/resources/js/Pages/Product/Create.tsx`（新增商品）
|
||||
- ✅ `/resources/js/Pages/Product/Edit.tsx`（編輯商品）
|
||||
|
||||
---
|
||||
|
||||
## 4. 圖標規範
|
||||
|
||||
### 4.1 統一使用 lucide-react
|
||||
|
||||
**統一使用 `lucide-react`**，禁止使用其他圖標庫（如 FontAwesome、Material Icons、react-icons 等）。
|
||||
|
||||
### 4.2 圖標尺寸標準
|
||||
|
||||
| 尺寸 | 類別 | 使用情境 |
|
||||
|------|------|----------|
|
||||
| 小型 | `h-3 w-3` | Badge 內、小文字旁 |
|
||||
| 標準 | `h-4 w-4` | 按鈕內、表格操作 |
|
||||
| 標題 | `h-5 w-5` | 側邊欄選單 |
|
||||
| 大型 | `h-6 w-6` | 頁面標題 |
|
||||
|
||||
### 4.3 常用操作圖標映射
|
||||
|
||||
| 操作 | 圖標組件 | 使用情境 |
|
||||
|------|----------|----------|
|
||||
| 新增 | `<Plus />` | 新增按鈕 |
|
||||
| 編輯 | `<Pencil />` | 編輯按鈕 |
|
||||
| 刪除 | `<Trash2 />` | 刪除按鈕 |
|
||||
| 查看 | `<Eye />` | 查看詳情 |
|
||||
| 搜尋 | `<Search />` | 搜尋欄位 |
|
||||
| 篩選 | `<Filter />` | 篩選功能 |
|
||||
| 下載 | `<Download />` | 下載/匯出 |
|
||||
| 上傳 | `<Upload />` | 上傳/匯入 |
|
||||
| 設定 | `<Settings />` | 設定功能 |
|
||||
| 複製 | `<Copy />` | 複製內容 |
|
||||
| 郵件 | `<Mail />` | Email 顯示 |
|
||||
| 使用者 | `<Users />`, `<User />` | 使用者管理 |
|
||||
| 權限 | `<Shield />` | 角色/權限 |
|
||||
| 排序 | `<ArrowUpDown />`, `<ArrowUp />`, `<ArrowDown />` | 表格排序 |
|
||||
| 儀表板 | `<LayoutDashboard />` | 首頁/總覽 |
|
||||
| 商品 | `<Package />` | 商品管理 |
|
||||
| 倉庫 | `<Warehouse />` | 倉庫管理 |
|
||||
| 廠商 | `<Truck />`, `<Contact2 />` | 廠商管理 |
|
||||
| 採購 | `<ShoppingCart />` | 採購管理 |
|
||||
|
||||
### 4.4 圖標使用範例
|
||||
|
||||
```tsx
|
||||
import { Plus, Pencil, Trash2, Users } from 'lucide-react';
|
||||
|
||||
// 頁面標題
|
||||
<h1 className="text-2xl font-bold text-grey-0 flex items-center gap-2">
|
||||
<Users className="h-6 w-6 text-[#01ab83]" />
|
||||
使用者管理
|
||||
</h1>
|
||||
|
||||
// 按鈕內圖標（圖標在左，帶文字）
|
||||
<Button className="button-filled-primary">
|
||||
<Plus className="h-4 w-4 mr-2" />
|
||||
新增使用者
|
||||
</Button>
|
||||
|
||||
// 純圖標按鈕（表格操作列）
|
||||
<Button variant="outline" size="sm" className="button-outlined-primary">
|
||||
<Pencil className="h-4 w-4" />
|
||||
</Button>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 表格規範
|
||||
|
||||
### 5.1 表格容器
|
||||
|
||||
```tsx
|
||||
<div className="bg-white rounded-xl border border-gray-200 shadow-sm overflow-hidden">
|
||||
<Table>
|
||||
{/* 表格內容 */}
|
||||
</Table>
|
||||
</div>
|
||||
```
|
||||
|
||||
### 5.2 表格標題列
|
||||
|
||||
```tsx
|
||||
<TableHeader className="bg-gray-50">
|
||||
<TableRow>
|
||||
<TableHead className="w-[50px] text-center">#</TableHead>
|
||||
<TableHead>名稱</TableHead>
|
||||
<TableHead className="text-center">操作</TableHead>
|
||||
</TableRow>
|
||||
</TableHeader>
|
||||
```
|
||||
|
||||
**關鍵要點**：
|
||||
- 使用 `bg-gray-50` 背景色
|
||||
- 序號欄位固定寬度 `w-[50px]` 並置中
|
||||
- 操作欄位置中顯示
|
||||
|
||||
### 5.3 表格主體
|
||||
|
||||
```tsx
|
||||
<TableBody>
|
||||
{items.length === 0 ? (
|
||||
<TableRow>
|
||||
<TableCell colSpan={5} className="text-center py-8 text-gray-500">
|
||||
無符合條件的資料
|
||||
</TableCell>
|
||||
</TableRow>
|
||||
) : (
|
||||
items.map((item, index) => (
|
||||
<TableRow key={item.id}>
|
||||
<TableCell className="text-gray-500 font-medium text-center">
|
||||
{startIndex + index}
|
||||
</TableCell>
|
||||
{/* 其他欄位 */}
|
||||
<TableCell className="text-center">
|
||||
<div className="flex items-center justify-center gap-2">
|
||||
{/* 操作按鈕 */}
|
||||
</div>
|
||||
</TableCell>
|
||||
</TableRow>
|
||||
))
|
||||
)}
|
||||
</TableBody>
|
||||
```
|
||||
|
||||
**關鍵要點**：
|
||||
- 空狀態訊息使用置中、灰色文字
|
||||
- 序號欄使用 `text-gray-500 font-medium text-center`
|
||||
- 操作欄使用 `flex items-center justify-center gap-2` 排列按鈕
|
||||
|
||||
### 5.4 欄位排序規範
|
||||
|
||||
當表格需要支援排序時，請遵循以下模式：
|
||||
|
||||
1. **圖標邏輯**：
|
||||
* 未排序：`ArrowUpDown` (class: `text-muted-foreground`)
|
||||
* 升冪 (asc)：`ArrowUp` (class: `text-primary`)
|
||||
* 降冪 (desc)：`ArrowDown` (class: `text-primary`)
|
||||
2. **結構**：在 `TableHead` 內使用 `button` 元素。
|
||||
3. **後端配合**：後端 Controller **必須** 處理 `sort_by` 與 `sort_order` 參數。
|
||||
|
||||
```tsx
|
||||
// 1. 定義 Helper Component (在元件內部)
|
||||
const SortIcon = ({ field }: { field: string }) => {
|
||||
if (filters.sort_by !== field) {
|
||||
return <ArrowUpDown className="h-4 w-4 text-muted-foreground ml-1" />;
|
||||
}
|
||||
if (filters.sort_order === "asc") {
|
||||
return <ArrowUp className="h-4 w-4 text-primary ml-1" />;
|
||||
}
|
||||
return <ArrowDown className="h-4 w-4 text-primary ml-1" />;
|
||||
};
|
||||
|
||||
// 2. 表格標題應用
|
||||
<TableHead>
|
||||
<button
|
||||
onClick={() => handleSort('created_at')}
|
||||
className="flex items-center hover:text-gray-900"
|
||||
>
|
||||
建立時間 <SortIcon field="created_at" />
|
||||
</button>
|
||||
</TableHead>
|
||||
|
||||
// 3. 排序處理函式 (三態切換：未排序 -> 升冪 -> 降冪 -> 未排序)
|
||||
const handleSort = (field: string) => {
|
||||
let newSortBy: string | undefined = field;
|
||||
let newSortOrder: 'asc' | 'desc' | undefined = 'asc';
|
||||
|
||||
if (filters.sort_by === field) {
|
||||
if (filters.sort_order === 'asc') {
|
||||
newSortOrder = 'desc';
|
||||
} else {
|
||||
// desc -> reset (回到預設排序)
|
||||
newSortBy = undefined;
|
||||
newSortOrder = undefined;
|
||||
}
|
||||
}
|
||||
|
||||
router.get(
|
||||
route(route().curr
|
||||
Reference in New Issue
Block a user