Files

sky121113 88415505fb docs(skill): 更新操作紀錄實作規範

整合全域 ID 轉名稱邏輯、日誌合併策略以及針對 Collection 修改錯誤的修復方案。

2026-02-04 15:39:05 +08:00

4.3 KiB

Raw Blame History

name, description

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

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

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

1. 後端實作核心 (Backend)

1.1 全域 ID 轉名稱邏輯 (Global ID Resolution)

為了讓管理者能直覺看懂日誌，所有的 ID（如 warehouse_id, created_by）在記錄時都應自動解析為名稱。此邏輯應統一在 Model 的 tapActivity 中實作。

關鍵實作參考：

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 (單據狀態變更)。

// 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

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？

4.3 KiB Raw Blame History Unescape Escape