新增 POS 庫存查詢 API：實作 InventorySyncController 與相關 Service 邏輯，並更新 API 整合手冊

app/Modules/Inventory/Models/InventoryTransaction.php

@@ -10,6 +10,7 @@ class InventoryTransaction extends Model
 {
     /** @use HasFactory<\Database\Factories\InventoryTransactionFactory> */
     use HasFactory;
+    use \Spatie\Activitylog\Traits\LogsActivity;
 
     protected $fillable = [
         'inventory_id',
@@ -41,4 +42,49 @@ class InventoryTransaction extends Model
     {
         return $this->morphTo();
     }
+
+    public function getActivitylogOptions(): \Spatie\Activitylog\LogOptions
+    {
+        return \Spatie\Activitylog\LogOptions::defaults()
+            ->logAll()
+            ->dontLogIfAttributesChangedOnly(['updated_at'])
+            // 取消 logOnlyDirty，代表新增時(created)也要留紀錄
+            ->dontSubmitEmptyLogs();
+    }
+
+    public function tapActivity(\Spatie\Activitylog\Contracts\Activity $activity, string $eventName)
+    {
+        $properties = $activity->properties instanceof \Illuminate\Support\Collection 
+            ? $activity->properties->toArray() 
+            : $activity->properties;
+
+        $snapshot = $properties['snapshot'] ?? [];
+
+        // 試著取得商品與倉庫名稱來作為主要顯示依據
+        $inventory = $this->inventory;
+        if ($inventory) {
+            $snapshot['warehouse_name'] = $inventory->warehouse ? $inventory->warehouse->name : null;
+            $snapshot['product_name'] = $inventory->product ? $inventory->product->name : null;
+            $snapshot['batch_number'] = $inventory->batch_number;
+        }
+
+        // 把異動類型與數量也拉到 snapshot
+        $snapshot['type'] = $this->type;
+        $snapshot['quantity'] = $this->quantity;
+        $snapshot['reason'] = $this->reason;
+        
+        // 替換使用者名稱
+        $resolver = function (&$data) {
+            if (empty($data) || !is_array($data)) return;
+            if (isset($data['user_id']) && is_numeric($data['user_id'])) {
+                $data['user_id'] = \App\Modules\Core\Models\User::find($data['user_id'])?->name;
+            }
+        };
+
+        if (isset($properties['attributes'])) $resolver($properties['attributes']);
+        if (isset($properties['old'])) $resolver($properties['old']);
+
+        $properties['snapshot'] = $snapshot;
+        $activity->properties = $properties;
+    }
 }