Files

sky121113 6b6e840f35 docs: 整合與優化 Agent Skills 規範及新增技能觸發準則

2026-03-06 10:43:23 +08:00

9.5 KiB

Raw Blame History

name, description

name	description
操作紀錄實作規範 (Activity Logging Skill)	規範系統內 Activity Log 的實作標準，包含自動名稱解析、複雜單據合併記錄、與前端顯示優化。

操作紀錄實作規範 (Activity Logging Skill)

本技能定義了 Star ERP 系統中操作紀錄的最高實作標準，旨在確保每筆日誌都具有「高度可讀性」與「單一性」。

1. 啟用 Activity Log (Model 基本設定)

在 Model 中引用 LogsActivity trait 並實作 getActivitylogOptions 方法。

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`

// ✅ 正確：使用介面
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

// 🚩 核心：轉換為陣列以避免 Indirect modification error
$properties = $activity->properties instanceof \Illuminate\Support\Collection 
    ? $activity->properties->toArray() 
    : $activity->properties;

// ... 操作 $properties ...

$activity->properties = $properties; // 最後整體回寫

2.3 Snapshot 快照策略

為確保資料被刪除後仍能辨識操作對象，必須在 properties.snapshot 中儲存關鍵識別資訊。

$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：可直接查詢

$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。

// ✅ 正確：透過 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 屬於全域例外，其他模組可直接查詢。詳見跨模組通訊規範。

2.5 完整 `tapActivity` 範例（參考 PurchaseOrder）

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 手動記錄必須自行過濾差異

// ✅ 正確：自行比對差異，只存變動值
$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()` + 手動日誌合併策略

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

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

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 兩處同步？

9.5 KiB Raw Blame History Unescape Escape