docs: 整合與優化 Agent Skills 規範及新增技能觸發準則
This commit is contained in:
@@ -1,115 +0,0 @@
|
||||
---
|
||||
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`？
|
||||
@@ -1,162 +0,0 @@
|
||||
---
|
||||
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;
|
||||
});
|
||||
```
|
||||
@@ -78,10 +78,4 @@ trigger: always_on
|
||||
* **執行 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`。
|
||||
* **執行 Node/NPM**： `./vendor/bin/sail npm run dev`
|
||||
@@ -1,49 +0,0 @@
|
||||
---
|
||||
trigger: always_on
|
||||
---
|
||||
|
||||
# Git 分支管理與開發規範 (Git Workflow)
|
||||
|
||||
為了確保系統穩定性與發布紀律，所有開發者與 AI 助手必須嚴格遵守以下環境發布流程與時段限制。
|
||||
|
||||
## 1. 分支架構與環境定義
|
||||
|
||||
| 分支 | 環境 | 用途描述 | 合併來源 |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **`dev`** | 本機開發 | 日常開發與功能實作。 | `feature/*` |
|
||||
| **`demo`** | 測試/預佈署 | 鏡像生產環境。用於正式上線前的最終驗證。 | `dev` |
|
||||
| **`main`** | 生產環境 | 正式版本分支。僅存放透過 `demo` 驗證後的代碼。 | `demo` |
|
||||
|
||||
## 2. 發布時段與約束 (Release Window)
|
||||
|
||||
### Main 分支發布限制 (Mandatory)
|
||||
1. **標準發布時間**：週一至週四，**12:00 (中午) 之前**。
|
||||
2. **非標準時段提醒**：若於上述時段以外（週五、週末、國定假日或下班時間）欲合併至 `main`：
|
||||
- AI 助手**必須攔截並主動提示風險**（例如：週末災難風險）。
|
||||
- 必須取得使用者明確書面同意（如：「我確定現在要上線」）方可執行。
|
||||
3. **合併鏈路**：一般功能/修正必須先上 `demo` 測試。`main` 的程式原則上應從 `demo` 分支合併而來。
|
||||
|
||||
## 3. 開發與修復流程 (SOP)
|
||||
|
||||
### 標準開發流程
|
||||
1. `feature/*` -> `dev` (隨時合併，主要測試點)。
|
||||
2. `dev` -> `demo` (隨時合併，進行類生產環境測試)。
|
||||
3. `demo` -> `main` (僅限允許時段進行，正式上線)。
|
||||
|
||||
### 緊急修復流程 (Hotfix)
|
||||
1. 直接從 `main` 建立 `hotfix/*` 分支進行修復。
|
||||
2. 修復完成並通過測試後合併回 `main`。
|
||||
3. **重要同步**：修復後的程式碼必須立即合併回 `demo` 與 `dev`，確保各環境修復同步。
|
||||
|
||||
## 4. 提交訊息規範 (Commit Messages)
|
||||
|
||||
提交訊息必須包含以下前綴：
|
||||
- `[FIX]`：修復 Bug。
|
||||
- `[FEAT]`：新增功能。
|
||||
- `[DOCS]`：文件更新。
|
||||
- `[STYLE]`：UI/格式調整。
|
||||
- `[REFACTOR]`：重構。
|
||||
|
||||
---
|
||||
> [!IMPORTANT]
|
||||
> 身為 AI 助手 (Antigravity)，我會監控合併對象與當前時間。若您的命令涉及合併至 `main` 且不在允許時段內，我會優先進行安全提醒。
|
||||
@@ -1,144 +0,0 @@
|
||||
---
|
||||
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` 進行顯示控制。
|
||||
52
.agents/rules/skill-triggers.md
Normal file
52
.agents/rules/skill-triggers.md
Normal file
@@ -0,0 +1,52 @@
|
||||
---
|
||||
trigger: always_on
|
||||
glob:
|
||||
description:
|
||||
---
|
||||
|
||||
# 技能觸發規範 (Skill Trigger Rules)
|
||||
|
||||
本文件確保 AI 助手在對話中能**主動辨識**需要參照技能 (Skill) 的時機。
|
||||
Skills 位於 `.agents/skills/`，採漸進式揭露以節省 Token。
|
||||
**若對話內容命中以下任一觸發條件，必須先使用 `view_file` 讀取對應的 `SKILL.md` 後再進行作業。**
|
||||
|
||||
---
|
||||
|
||||
## 觸發對照表
|
||||
|
||||
| 觸發詞 / 情境 | 對應 Skill | 路徑 |
|
||||
|---|---|---|
|
||||
| 操作紀錄、Activity Log、日誌、`tapActivity`、`LogsActivity`、`saveQuietly`、`activity()`、`items_diff` | **操作紀錄實作規範** | `.agents/skills/activity-logging/SKILL.md` |
|
||||
| 權限、permission、角色、role、`usePermission`、`<Can>`、`PermissionSeeder`、middleware protection | **權限管理與實作規範** | `.agents/skills/permission-management/SKILL.md` |
|
||||
| 跨模組、Service Interface、`Contracts`、模組間通訊、`ServiceProvider` 綁定、禁止跨模組引用 | **跨模組調用與通訊規範** | `.agents/skills/cross-module-communication/SKILL.md` |
|
||||
| 按鈕樣式、表格規範、圖標、分頁、Badge、Toast、表單、UI 統一、頁面佈局、`button-filled-*`、`button-outlined-*`、`lucide-react`、色彩系統 | **客戶端後台 UI 統一規範** | `.agents/skills/ui-consistency/SKILL.md` |
|
||||
| Git 分支、commit、合併、部署、`feature/`、`hotfix/`、`develop`、`main` | **Git 分支管理與開發規範** | `.agents/skills/git-workflows/SKILL.md` |
|
||||
|
||||
---
|
||||
|
||||
## 強制觸發場景
|
||||
|
||||
以下場景**無論對話中是否出現觸發詞**，都必須主動載入對應 Skill：
|
||||
|
||||
### 🔴 新增功能或頁面時
|
||||
必須同時讀取：
|
||||
1. **permission-management** — 設定權限
|
||||
2. **ui-consistency** — 遵循 UI 規範
|
||||
3. **activity-logging** — 若涉及 Model CRUD，需加上操作紀錄
|
||||
|
||||
### 🔴 新增或修改 Model 時
|
||||
必須讀取：
|
||||
1. **activity-logging** — `tapActivity` 實作
|
||||
2. **cross-module-communication** — 確認是否涉及跨模組引用
|
||||
|
||||
### 🔴 Git 操作時
|
||||
必須讀取：
|
||||
1. **git-workflows** — 分支命名與 commit 格式
|
||||
|
||||
---
|
||||
|
||||
## 注意事項
|
||||
|
||||
> [!IMPORTANT]
|
||||
> 即使你「記得」Skill 的大致內容，仍必須重新讀取 `SKILL.md`。
|
||||
> 因為 Skill 文件可能已經更新，且記憶中的內容可能不完整。
|
||||
@@ -1,105 +0,0 @@
|
||||
---
|
||||
trigger: always_on
|
||||
---
|
||||
|
||||
---
|
||||
name: 客戶端後台 UI 統一規範
|
||||
description: 確保 Star ERP 客戶端（租戶端）後台所有頁面的 UI 元件保持統一的樣式與行為
|
||||
---
|
||||
|
||||
## 適用範圍
|
||||
|
||||
本規範適用於租戶端後台（使用 `AuthenticatedLayout` 的頁面），**不適用於**中央管理後台（`LandlordLayout`）。
|
||||
|
||||
## 核心禁止事項
|
||||
|
||||
- ❌ **禁止 Hardcode 色碼**（如 `text-[#01ab83]`），必須使用 `*-primary-main` 等 Tailwind Class 或 CSS 變數
|
||||
- ❌ **禁止使用非 `lucide-react` 的圖標庫**（如 FontAwesome、Material Icons）
|
||||
- ❌ **禁止操作按鈕不包裹 `<Can>` 權限元件**
|
||||
|
||||
---
|
||||
|
||||
## 1. 色彩系統
|
||||
|
||||
### 主題色（動態租戶品牌色，由 `AuthenticatedLayout` 自動注入）
|
||||
|
||||
| Tailwind Class | 用途 |
|
||||
|---|---|
|
||||
| `*-primary-main` | 主色：按鈕、連結、強調 |
|
||||
| `*-primary-dark` | Hover 狀態 |
|
||||
| `*-primary-light` | 次要強調 |
|
||||
| `*-primary-lightest` | 背景底色、Active 狀態 |
|
||||
|
||||
### 灰階與狀態色
|
||||
|
||||
直接參考 `resources/css/app.css` 中定義的 `--grey-0` ~ `--grey-5` 與 `--other-success/error/warning/info` 變數。
|
||||
|
||||
---
|
||||
|
||||
## 2. 按鈕規範
|
||||
|
||||
樣式定義於 `resources/css/app.css`，按鈕必須使用以下類別：
|
||||
|
||||
| 類型 | 類別 | 用途 |
|
||||
|---|---|---|
|
||||
| Filled | `button-filled-primary` | 主要操作（新增、儲存） |
|
||||
| Filled | `button-filled-success/info/warning/error` | 各狀態操作 |
|
||||
| Outlined | `button-outlined-primary` | 次要操作（編輯、檢視） |
|
||||
| Outlined | `button-outlined-error` | 刪除按鈕 |
|
||||
| Text | `button-text-primary` | 文字連結式按鈕 |
|
||||
|
||||
**尺寸**：表格操作列用 `size="sm"`，一般操作用 `size="default"`，主要 CTA 用 `size="lg"`。
|
||||
|
||||
**返回按鈕**：放置於標題上方，使用 `variant="outline"` + `className="gap-2 button-outlined-primary"`，搭配 `<ArrowLeft />` 圖標。
|
||||
|
||||
---
|
||||
|
||||
## 3. 圖標規範
|
||||
|
||||
統一使用 `lucide-react`。
|
||||
|
||||
| 尺寸 | 用途 |
|
||||
|---|---|
|
||||
| `h-4 w-4` | 按鈕內、表格操作 |
|
||||
| `h-5 w-5` | 側邊欄選單 |
|
||||
| `h-6 w-6` | 頁面標題 |
|
||||
|
||||
常用映射：`Plus`(新增)、`Pencil`(編輯)、`Trash2`(刪除)、`Eye`(檢視)、`Search`(搜尋)、`ArrowLeft`(返回)。
|
||||
其餘請參考 `AuthenticatedLayout.tsx` 中的 `allMenuItems` 定義。
|
||||
|
||||
---
|
||||
|
||||
## 4. 頁面佈局規範
|
||||
|
||||
所有頁面遵循以下結構，參考範例：`Pages/Product/Create.tsx`、`Pages/PurchaseOrder/Create.tsx`。
|
||||
|
||||
**關鍵規則**：
|
||||
- **外層容器**：`className="container mx-auto p-6 max-w-7xl"`
|
||||
- **標題樣式**：`text-2xl font-bold text-grey-0 flex items-center gap-2`
|
||||
- **說明文字**：`text-gray-500 mt-1`
|
||||
- **麵包屑**：使用 `BreadcrumbItemType`（屬性為 `label`, `href`, `isPage`），不需要包含「首頁」
|
||||
- **Input 元件**：不額外設定 focus 樣式，直接使用 `@/Components/ui/input` 的內建樣式
|
||||
- **日期顯示**：使用 `resources/js/lib/date.ts` 的 `formatDate` 工具
|
||||
- **數字顯示**：
|
||||
- 所有的金額、數量等數值，應視情境使用千分位格式化（如 `1,234.56`）。
|
||||
- **精確顯示**：數值應按實際數值顯示，避免在小數點後出現多餘的零（例如：應顯示 `10.5` 而非 `10.500`）。
|
||||
- 數值應與單位（如 `元`、`kg`）保持適當間距或清晰呈現。
|
||||
- 負數應視情境明確標示（如使用紅色 `text-other-error` 或負號）。
|
||||
- 列表中的數值建議靠右對齊 (text-right)，以便於視覺比較。
|
||||
|
||||
---
|
||||
|
||||
## 5. 表格規範
|
||||
|
||||
**容器**：`bg-white rounded-xl border border-gray-200 shadow-sm overflow-hidden`
|
||||
**標題列**：`bg-gray-50`，序號欄 `w-[50px] text-center`，操作欄置中
|
||||
**空狀態**：`text-center py-8 text-gray-500`，顯示「無符合條件的資料」
|
||||
**操作欄**：`flex items-center justify-center gap-2`
|
||||
|
||||
### 排序（三態切換）
|
||||
|
||||
- 未排序：`ArrowUpDown`（`text-muted-foreground`）
|
||||
- 升冪：`ArrowUp`（`text-primary`）
|
||||
- 降冪：`ArrowDown`（`text-primary`）
|
||||
- 後端必須處理 `sort_by` 與 `sort_order` 參數
|
||||
- 參考實作：`Pages/Product/Index.tsx` 的 `handleSort`
|
||||
Reference in New Issue
Block a user