mama/star-erp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[Merge] Merge demo into main
All checks were successful
ERP-Deploy-Production / deploy-production (push) Successful in 1m11s
Details

Browse Source
This commit is contained in:
sky121113
2026-03-06 11:08:59 +08:00
parent e4c83ebd6d 951005c616
commit 2fd5de96b2
12 changed files with 597 additions and 706 deletions
Download Patch File Download Diff File Expand all files Collapse all files

115
.agents/rules/activity-logging.md
View File

@@ -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`？

9
.agents/rules/framework.md
View File

@@ -80,8 +80,7 @@ trigger: always_on
* **執行 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`。
## 10. 部署與查修環境 (CI/CD & Troubleshooting)
* **自動化部署**：本專案使用 CI/CD 自動化部署，開發者只需 push 程式碼至對應分支即可。
* **Demo 環境 (對應 `demo` 分支)**：若需查修測試站問題（例如查看 Error Log 或資料庫），請連線 `ssh gitea_work`。
* **Production 環境 (對應 `main` 分支)**：若需查修正式站問題，請連線 `ssh erp`。

144
.agents/rules/permission-management.md
View File

@@ -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` 進行顯示控制。

50
.agents/rules/skill-trigger.md Normal file
View File

@@ -0,0 +1,50 @@
---
trigger: always_on
---
# 技能觸發規範 (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、push、合併、部署、`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 文件可能已經更新，且記憶中的內容可能不完整。

105
.agents/rules/ui-consistency.md
View File

@@ -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`

285
.agents/skills/activity-logging/SKILL.md Normal file
View File

@@ -0,0 +1,285 @@
---
name: 操作紀錄實作規範 (Activity Logging Skill)
description: 規範系統內 Activity Log 的實作標準，包含自動名稱解析、複雜單據合併記錄、與前端顯示優化。
---
# 操作紀錄實作規範 (Activity Logging Skill)
本技能定義了 Star ERP 系統中操作紀錄的最高實作標準，旨在確保每筆日誌都具有「高度可讀性」與「單一性」。
---
## 1. 啟用 Activity Log (Model 基本設定)
在 Model 中引用 `LogsActivity` trait 並實作 `getActivitylogOptions` 方法。
```php
use Spatie\Activitylog\Traits\LogsActivity;
use Spatie\Activitylog\LogOptions;
class Product extends Model
{
use LogsActivity;
public function getActivitylogOptions(): LogOptions
{
return LogOptions::defaults()
->logAll()
->logOnlyDirty() // ✅ 關鍵：只記錄有變動的欄位
->dontSubmitEmptyLogs(); // 若無變動則不記錄
}
}
```
---
## 2. `tapActivity` 實作規範 (Backend 核心)
### 2.1 型別宣告：統一使用 `Contracts\Activity`
```php
// ✅ 正確：使用介面
public function tapActivity(\Spatie\Activitylog\Contracts\Activity $activity, string $eventName)
// ❌ 禁止：使用具體類別
public function tapActivity(\Spatie\Activitylog\Models\Activity $activity, string $eventName)
```
### 2.2 必須 `toArray()` 避免 Indirect modification error
```php
// 🚩 核心：轉換為陣列以避免 Indirect modification error
$properties = $activity->properties instanceof \Illuminate\Support\Collection
? $activity->properties->toArray()
: $activity->properties;
// ... 操作 $properties ...
$activity->properties = $properties; // 最後整體回寫
```
### 2.3 Snapshot 快照策略
為確保資料被刪除後仍能辨識操作對象，**必須**在 `properties.snapshot` 中儲存關鍵識別資訊。
```php
$snapshot = $properties['snapshot'] ?? [];
$snapshot['doc_no'] = $this->doc_no; // 單號
$snapshot['name'] = $this->name; // 名稱
$snapshot['warehouse_name'] = $this->warehouse?->name; // 關聯名稱
$properties['snapshot'] = $snapshot;
```
### 2.4 全域 ID 轉名稱邏輯 (ID Resolution)
所有的 ID（如 `warehouse_id`, `created_by`）在記錄時應自動解析為名稱。
#### 模組內 Model：可直接查詢
```php
$resolver = function (&$data) {
if (empty($data) || !is_array($data)) return;
// 同模組內的 Model 可以直接查詢
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;
}
}
};
```
#### 跨模組 Model：必須透過 Service Interface
> [!IMPORTANT]
> 依據跨模組通訊規範，若需解析其他模組的 ID（例如在 `Procurement` 模組中解析 `warehouse_id`），
> **禁止**直接 `Warehouse::find()`，必須透過 Service Interface。
```php
// ✅ 正確：透過 Service Interface 取得跨模組資料
if (isset($data['warehouse_id']) && is_numeric($data['warehouse_id'])) {
$warehouse = app(\App\Modules\Inventory\Contracts\InventoryServiceInterface::class)
->getWarehouse($data['warehouse_id']);
$data['warehouse_id'] = $warehouse?->name ?? $data['warehouse_id'];
}
```
> [!NOTE]
> `Core` 模組的 `User`, `Role`, `Tenant` 屬於全域例外，其他模組可直接查詢。
> 詳見 [跨模組通訊規範](file:///home/mama/projects/star-erp/.agents/skills/cross-module-communication/SKILL.md)。
### 2.5 完整 `tapActivity` 範例（參考 PurchaseOrder）
```php
public function tapActivity(\Spatie\Activitylog\Contracts\Activity $activity, string $eventName)
{
// 🚩 轉換為陣列
$properties = $activity->properties instanceof \Illuminate\Support\Collection
? $activity->properties->toArray()
: $activity->properties;
// 1. Snapshot 快照
$snapshot = $properties['snapshot'] ?? [];
$snapshot['po_number'] = $this->code;
$snapshot['vendor_name'] = $this->vendor?->name;
$properties['snapshot'] = $snapshot;
// 2. ID 轉名稱
$resolver = function (&$data) {
if (empty($data) || !is_array($data)) return;
// 全域例外：User 可直接查
foreach (['user_id', 'created_by', 'updated_by'] as $f) {
if (isset($data[$f]) && is_numeric($data[$f])) {
$data[$f] = \App\Modules\Core\Models\User::find($data[$f])?->name ?? $data[$f];
}
}
// 同模組：可直接查
if (isset($data['vendor_id']) && is_numeric($data['vendor_id'])) {
$data['vendor_id'] = Vendor::find($data['vendor_id'])?->name ?? $data['vendor_id'];
}
// 跨模組：必須透過 Service Interface
if (isset($data['warehouse_id']) && is_numeric($data['warehouse_id'])) {
$warehouse = app(\App\Modules\Inventory\Contracts\InventoryServiceInterface::class)
->getWarehouse($data['warehouse_id']);
$data['warehouse_id'] = $warehouse?->name ?? $data['warehouse_id'];
}
};
if (isset($properties['attributes'])) $resolver($properties['attributes']);
if (isset($properties['old'])) $resolver($properties['old']);
// 3. 合併 activityProperties (手動傳入的 items_diff 等)
if (!empty($this->activityProperties)) {
$properties = array_merge($properties, $this->activityProperties);
}
$activity->properties = $properties;
}
```
---
## 3. 複雜操作的日誌合併 (Log Consolidation)
當一個操作同時涉及「多個品項異動」與「單據狀態變更」時，**嚴禁**產生多筆重複日誌。
### 3.1 手動記錄必須自行過濾差異
```php
// ✅ 正確：自行比對差異，只存變動值
$changedAttributes = [];
$changedOldAttributes = [];
foreach ($newAttributes as $key => $value) {
if ($value != ($oldAttributes[$key] ?? null)) {
$changedAttributes[$key] = $value;
$changedOldAttributes[$key] = $oldAttributes[$key] ?? null;
}
}
if (!empty($changedAttributes)) {
activity()
->withProperties(['attributes' => $changedAttributes, 'old' => $changedOldAttributes])
->log('updated');
}
```
### 3.2 `saveQuietly()` + 手動日誌 合併策略
```php
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');
});
```
> [!WARNING]
> 使用 `saveQuietly()` 會繞過 Model Events（如自動單號產生）。
> 若 Model 有 `creating`/`updating` 事件產生單號，需在 Service 中手動處理。
---
## 4. 後端 Controller 映射 (Subject Map)
新增 Model 時，必須同步在 `ActivityLogController::getSubjectMap()` 加入中文映射。
**位置**: `app/Modules/Core/Controllers/ActivityLogController.php`
```php
private function getSubjectMap()
{
return [
'App\Modules\Inventory\Models\Product' => '商品',
'App\Modules\Finance\Models\UtilityFee' => '公共事業費',
// ... 新增此行
];
}
```
---
## 5. 前端介面規範 (Frontend)
### 5.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: '狀態',
// 新增 Model 的欄位翻譯 ...
};
```
### 5.2 `nameParams` 必須在兩處同步更新
> [!IMPORTANT]
> `nameParams` 在 `LogTable.tsx` 和 `ActivityDetailDialog.tsx` 中各有一份，
> 新增時**必須兩處同步更新**，否則會導致列表與詳情頁顯示不一致。
| 檔案 | 用途 |
|---|---|
| `resources/js/Components/ActivityLog/LogTable.tsx` | 列表頁的描述文字 |
| `resources/js/Components/ActivityLog/ActivityDetailDialog.tsx` | 對話框標題 |
### 5.3 特殊結構顯示
* **品項異動**：前端已能渲染 `items_diff` 結構，以「品項名稱 + 數值變動」方式呈現表格。
* **顯示過濾邏輯**（已內建於 `ActivityDetailDialog`）：
- **Created**: 顯示初始化欄位
- **Updated**: 僅顯示有變動的欄位 (`isChanged` 判斷)
- **Deleted**: 顯示刪除前的完整資料
---
## 6. 開發檢核清單 (Checklist)
- [ ] **Model**: 是否已設定 `logOnlyDirty` + `dontSubmitEmptyLogs`？
- [ ] **Model**: `tapActivity` 型別是否使用 `Contracts\Activity`？
- [ ] **Model**: `tapActivity` 是否已使用 `toArray()` 處理 Collection？
- [ ] **Model**: 是否已實作 Snapshot（關鍵識別資訊）？
- [ ] **Model**: ID 轉名稱是否遵守跨模組規範（Core 例外，其餘需透過 Interface）？
- [ ] **Service**: 是否使用 `saveQuietly()` 搭配手動 `activity()` 避免重複日誌？
- [ ] **Controller**: `ActivityLogController::getSubjectMap()` 是否已新增 Model 中文映射？
- [ ] **UI**: `fieldLabels` 是否已新增欄位中文翻譯？
- [ ] **UI**: `nameParams` 是否已在 `LogTable` 和 `ActivityDetailDialog` 兩處同步？

37
.agents/rules/cross-module-communication.md → .agents/skills/cross-module-communication/SKILL.md
View File

@@ -1,7 +1,3 @@
---
trigger: always_on
---
---
name: 跨模組調用與通訊規範 (Cross-Module Communication)
description: 規範 Laravel Modular Monolith 架構下，不同業務模組中如何彼此調用資料與邏輯，包含禁止項目、Interface 實作、與 Service 綁定規則。
@@ -14,12 +10,8 @@ description: 規範 Laravel 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();`
---
@@ -28,9 +20,9 @@ description: 規範 Laravel Modular Monolith 架構下，不同業務模組中
雖然我們嚴格禁止跨模組直接相依，但為了開發效率與框架機制的完整性，**`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) 的核心基石，底層查詢會頻繁依賴。
1. **`App\Modules\Core\Models\User`**
2. **`App\Modules\Core\Models\Role`**
3. **`App\Modules\Core\Models\Tenant`**
> **⚠️ 注意**：這項例外是單向的。`Core` 模組內的業務邏輯（如 `DashboardController`）**絕對不能**反過來直接 `use` 外部業務模組的 Model，仍必須透過外部模組的 Service Interface 來索取資料。
@@ -45,18 +37,12 @@ description: 規範 Laravel Modular Monolith 架構下，不同業務模組中
如果 `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;
}
```
@@ -66,7 +52,6 @@ interface InventoryServiceInterface
由 `Inventory` 模組自己的 Service 來實作上述介面。
```php
// app/Modules/Inventory/Services/InventoryService.php
namespace App\Modules\Inventory\Services;
use App\Modules\Inventory\Contracts\InventoryServiceInterface;
@@ -77,8 +62,6 @@ class InventoryService implements InventoryServiceInterface
{
public function getActiveWarehouses(): Collection
{
// 建議只取出需要的欄位，或者轉換為 DTO / 陣列
// 避免將完整的 Eloquent Model 實例拋出模組外
return Warehouse::where('is_active', true)
->select(['id', 'name', 'code'])
->get();
@@ -89,7 +72,6 @@ class InventoryService implements InventoryServiceInterface
然後進入 `app/Modules/Inventory/InventoryServiceProvider.php` 完成綁定：
```php
// app/Modules/Inventory/InventoryServiceProvider.php
namespace App\Modules\Inventory;
use Illuminate\Support\ServiceProvider;
@@ -100,7 +82,6 @@ class InventoryServiceProvider extends ServiceProvider
{
public function register(): void
{
// 綁定介面與實體
$this->app->bind(InventoryServiceInterface::class, InventoryService::class);
}
}
@@ -108,10 +89,9 @@ class InventoryServiceProvider extends ServiceProvider
### Step 3: 調用方透過依賴注入 (DI) 使用服務
當 `Procurement` 模組需要取得倉庫資料時，禁止直接 new 服務或呼叫倉庫 Model。必須透過**建構子注入**或**方法注入**取得 `InventoryServiceInterface`。
當 `Procurement` 模組需要取得倉庫資料時，必須透過**建構子注入**或**方法注入**取得 `InventoryServiceInterface`。
```php
// app/Modules/Procurement/Controllers/PurchaseOrderController.php
namespace App\Modules\Procurement\Controllers;
use App\Http\Controllers\Controller;
@@ -120,14 +100,12 @@ 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', [
@@ -141,14 +119,11 @@ class PurchaseOrderController extends Controller
## ⚠️ 跨模組資料回傳的注意事項 (Data Hydration)
* **回傳純粹資料**：為了防止其他模組意外觸發 Lazy Loading (`$item->product->name`)，請盡量在 Service 中就用 `with()` 載入好關聯，或者直接轉為原生的 Array、`stdClass`、或具體的 DTO。
* **手動組合 (Manual Hydration)**：若某個頁面需要合併兩個模組的資料，這也是被允許的，但必須在 Controller 層級呼叫兩個不同的 Service Interface 後，手動合併。
* **回傳純粹資料**：建議在 Service 中用 `with()` 載入好關聯，或者直接轉為原生的 Array 或有具體結構的 DTO，避免依賴 Lazy Loading。
* **手動組合 (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();

5
.agents/rules/git-workflows.md → .agents/skills/git-workflows/SKILL.md
View File

@@ -1,5 +1,6 @@
---
trigger: always_on
name: Git 分支管理與開發規範 (Git Workflow)
description: 規範開發過程中的 Git 分支架構、合併限制、環境部署流程以及提交訊息格式。
---
# Git 分支管理與開發規範 (Git Workflow)
@@ -46,4 +47,4 @@ trigger: always_on
---
> [!IMPORTANT]
> 身為 AI 助手 (Antigravity)，我會監控合併對象與當前時間。若您的命令涉及合併至 `main` 且不在允許時段內，我會優先進行安全提醒。
> 身為 AI 助手 (Antigravity)，我會監控合併對象與當前時間。若您的命令涉及合併至 `main` 且不在允許時段內，我會優先進行安全提醒。

206
.agents/skills/permission-management/SKILL.md Normal file
View File

@@ -0,0 +1,206 @@
---
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 統一規範）。

49
.gemini/antigravity/skills/ui-consistency/SKILL.md → .agents/skills/ui-consistency/SKILL.md
View File

@@ -80,7 +80,7 @@ tooltip
<div style={{ borderColor: 'var(--primary-main)' }}>...</div>
// ❌ 錯誤：寫死色碼 (會導致租戶無法換色)
<div className="text-[#01ab83]">...</div>
<div className="text-primary-main">...</div>
```
### 2.2 灰階 (Grey Scale)
@@ -319,7 +319,7 @@ 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]" />
<Users className="h-6 w-6 text-primary-main" />
使用者管理
</h1>
@@ -584,7 +584,7 @@ export default function ResourceIndex() {
<div className="flex items-center justify-between mb-6">
<div>
<h1 className="text-2xl font-bold text-grey-0 flex items-center gap-2">
<IconComponent className="h-6 w-6 text-[#01ab83]" />
<IconComponent className="h-6 w-6 text-primary-main" />
頁面標題
</h1>
<p className="text-gray-500 mt-1">
@@ -781,7 +781,44 @@ import { SearchableSelect } from "@/Components/ui/searchable-select";
- **Select / SearchableSelect**: 必須確保 Trigger 按鈕高度為 `h-9`
- **禁止使用**: 除非有特殊設計需求，否則避免使用 `h-10` (40px) 或其他非標準高度。
## 11.6 日期輸入框樣式 (Date Input Style)
## 11.6 日期顯示規範 (Date Display)
前端顯示日期時**禁止直接顯示原始 ISO 字串**（如 `2024-03-06T08:30:00.000000Z`），必須使用 `resources/js/lib/date.ts` 提供的工具函式。
### 可用函式
| 函式 | 說明 | 輸出範例 |
|---|---|---|
| `formatDate(dateStr)` | **智慧格式**：自動判斷是否包含時間 | `2024-03-06` 或 `2024-03-06 08:30:00` |
| `formatDate(dateStr, 'yyyy-MM-dd')` | 指定格式輸出 | `2024-03-06` |
| `formatDateOnly(dateStr)` | 強制僅顯示日期 | `2024-03-06` |
### 智慧格式切換邏輯
`formatDate` 會自動判斷原始資料：
- 若時間部分為 `00:00:00`（通常代表後端僅提供日期）→ 僅顯示 `YYYY-MM-DD`
- 若時間部分有值 → 顯示 `YYYY-MM-DD HH:mm:ss`
- 若輸入為 `null` / `undefined` / 無效字串 → 顯示 `"-"`
### 使用範例
```tsx
import { formatDate, formatDateOnly } from "@/lib/date";
// ✅ 正確：使用 formatDate 自動判斷
<span>{formatDate(item.created_at)}</span> // → "2024-03-06 08:30:00"
<span>{formatDate(item.transaction_date)}</span> // → "2024-03-06"（因為時間為 00:00:00）
// ✅ 正確：強制只顯示日期
<span>{formatDateOnly(item.due_date)}</span> // → "2024-03-06"
// ❌ 禁止：直接顯示原始 ISO 字串
<span>{item.created_at}</span> // → "2024-03-06T08:30:00.000000Z" 😱
```
---
## 11.7 日期輸入框樣式 (Date Input Style)
日期輸入框應採用「**左側裝飾圖示 + 右側原生操作**」的配置，以保持視覺一致性並保留瀏覽器原生便利性。
@@ -805,7 +842,7 @@ import { Input } from "@/Components/ui/input";
</div>
```
## 11.7 搜尋選單樣式 (SearchableSelect Style)
## 11.8 搜尋選單樣式 (SearchableSelect Style)
`SearchableSelect` 元件在表單或篩選列中使用時，高度必須設定為 `h-9` 以與輸入框對齊。
@@ -816,7 +853,7 @@ import { Input } from "@/Components/ui/input";
/>
```
## 11.8 篩選列規範 (Filter Bar Norms)
## 11.9 篩選列規範 (Filter Bar Norms)
列表頁面的篩選區域（Filter Bar）應遵循以下規範以節省空間並保持層級清晰：

158
.gemini/antigravity/skills/activity-logging/SKILL.md
View File

@@ -1,158 +0,0 @@
---
name: 操作紀錄實作規範
description: 規範系統內 Activity Log 的實作標準，包含後端資料過濾、快照策略、與前端顯示邏輯。
---
# 操作紀錄實作規範
本文件說明如何在開發新功能時，依據系統規範實作 `spatie/laravel-activitylog` 操作紀錄，確保資料儲存效率與前端顯示一致性。
## 1. 後端實作標準 (Backend)
所有 Model 之操作紀錄應遵循「僅儲存變動資料」與「保留關鍵快照」兩大原則。
### 1.1 啟用 Activity Log
在 Model 中引用 `LogsActivity` trait 並實作 `getActivitylogOptions` 方法。
```php
use Spatie\Activitylog\Traits\LogsActivity;
use Spatie\Activitylog\LogOptions;
class Product extends Model
{
use LogsActivity;
public function getActivitylogOptions(): LogOptions
{
return LogOptions::defaults()
->logAll()
->logOnlyDirty() // ✅ 關鍵：只記錄有變動的欄位
->dontSubmitEmptyLogs(); // 若無變動則不記錄
}
}
```
### 1.2 手動記錄 (Manual Logging)
若需在 Controller 手動記錄（例如需客製化邏輯），**必須**自行實作變動過濾，不可直接儲存所有屬性。
**錯誤範例 (Do NOT do this):**
```php
// ❌ 錯誤：這會導致每次更新都記錄所有欄位，即使它們沒變
activity()
->withProperties(['attributes' => $newAttributes, 'old' => $oldAttributes])
->log('updated');
```
**正確範例 (Do this):**
```php
// ✅ 正確：自行比對差異，只存變動值
$changedAttributes = [];
$changedOldAttributes = [];
foreach ($newAttributes as $key => $value) {
if ($value != ($oldAttributes[$key] ?? null)) {
$changedAttributes[$key] = $value;
$changedOldAttributes[$key] = $oldAttributes[$key] ?? null;
}
}
if (!empty($changedAttributes)) {
activity()
->withProperties(['attributes' => $changedAttributes, 'old' => $changedOldAttributes])
->log('updated');
}
```
### 1.3 快照策略 (Snapshot Strategy)
為確保資料被刪除後仍能辨識操作對象，**必須**在 `properties.snapshot` 中儲存關鍵識別資訊（如名稱、代號、類別名稱）。
**主要方式：使用 `tapActivity` (推薦)**
```php
public function tapActivity(\Spatie\Activitylog\Contracts\Activity $activity, string $eventName)
{
$properties = $activity->properties;
$snapshot = $properties['snapshot'] ?? [];
// 保存關鍵關聯名稱 (避免關聯資料刪除後 ID 失效)
$snapshot['category_name'] = $this->category ? $this->category->name : null;
$snapshot['po_number'] = $this->code; // 儲存單號
// 保存自身名稱 (Context)
$snapshot['name'] = $this->name;
$properties['snapshot'] = $snapshot;
$activity->properties = $properties;
}
```
## 2. 顯示名稱映射 (UI Mapping)
### 2.1 對象名稱映射 (Mapping)
需在 `ActivityLogController.php` 中設定 Model 與中文名稱的對應，讓前端列表能顯示中文對象（如「公共事業費」而非 `UtilityFee`）。
**位置**: `app/Http/Controllers/Admin/ActivityLogController.php`
```php
protected function getSubjectMap()
{
return [
'App\Modules\Inventory\Models\Product' => '商品',
'App\Modules\Finance\Models\UtilityFee' => '公共事業費', // ✅ 新增映射
];
}
```
### 2.2 欄位名稱中文化 (Field Translation)
需在前端 `ActivityDetailDialog` 中設定欄位名稱的中文翻譯。
**位置**: `resources/js/Components/ActivityLog/ActivityDetailDialog.tsx`
```typescript
const fieldLabels: Record<string, string> = {
// ... 既有欄位
'transaction_date': '費用日期',
'category': '費用類別',
'amount': '金額',
};
```
## 3. 前端顯示邏輯 (Frontend)
### 3.1 列表描述生成 (Description Generation)
前端 `LogTable.tsx` 會依據 `properties.snapshot` 中的欄位自動組建描述（例如：「Admin 新增 電話費 公共事業費」）。
若您的 Model 使用了特殊的識別欄位（例如 `category`），**必須**將其加入 `nameParams` 陣列中。
**位置**: `resources/js/Components/ActivityLog/LogTable.tsx`
```typescript
const nameParams = [
'po_number', 'name', 'code',
'category_name',
'category' // ✅ 確保加入此欄位，前端才能抓到 $snapshot['category']
];
```
### 3.2 詳情過濾邏輯
前端 `ActivityDetailDialog` 已內建智慧過濾邏輯：
- **Created**: 顯示初始化欄位。
- **Updated**: **僅顯示有變動的欄位** (由 `isChanged` 判斷)。
- **Deleted**: 顯示刪除前的完整資料。
開發者僅需確保傳入的 `attributes` 與 `old` 資料結構正確，過濾邏輯會自動運作。
## 檢核清單
- [ ] **Backend**: Model 是否已設定 `logOnlyDirty` 或手動實作過濾？
- [ ] **Backend**: 是否已透過 `tapActivity` 或手動方式記錄 Snapshot（關鍵名稱）？
- [ ] **Backend**: 是否已在 `ActivityLogController` 加入 Model 中文名稱映射？
- [ ] **Frontend**: 是否已在 `ActivityDetailDialog` 加入欄位中文翻譯？
- [ ] **Frontend**: 若使用特殊識別欄位，是否已加入 `LogTable` 的 `nameParams`？

140
.gemini/antigravity/skills/permission-management/SKILL.md
View File

@@ -1,140 +0,0 @@
---
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` 進行顯示控制。