docs: 整合與優化 Agent Skills 規範及新增技能觸發準則
This commit is contained in:
285
.agents/skills/activity-logging/SKILL.md
Normal file
285
.agents/skills/activity-logging/SKILL.md
Normal 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` 兩處同步？
|
||||
Reference in New Issue
Block a user