feat: 實作 POS API 整合功能，包含商品與銷售訂單同步及韌性機制

app/Modules/Inventory/Services/InventoryService.php

@@ -59,9 +59,9 @@ class InventoryService implements InventoryServiceInterface
         return $stock >= $quantity;
     }
 
-    public function decreaseStock(int $productId, int $warehouseId, float $quantity, ?string $reason = null): void
+    public function decreaseStock(int $productId, int $warehouseId, float $quantity, ?string $reason = null, bool $force = false): void
     {
-        DB::transaction(function () use ($productId, $warehouseId, $quantity, $reason) {
+        DB::transaction(function () use ($productId, $warehouseId, $quantity, $reason, $force) {
             $inventories = Inventory::where('product_id', $productId)
                 ->where('warehouse_id', $warehouseId)
                 ->where('quantity', '>', 0)
@@ -79,8 +79,30 @@ class InventoryService implements InventoryServiceInterface
             }
 
             if ($remainingToDecrease > 0) {
-                // 這裡可以選擇報錯或允許負庫存，目前為了嚴謹拋出異常
-                throw new \Exception("庫存不足，無法扣除所有請求的數量。");
+                if ($force) {
+                    // Find any existing inventory record in this warehouse to subtract from, or create one
+                    $inventory = Inventory::where('product_id', $productId)
+                        ->where('warehouse_id', $warehouseId)
+                        ->first();
+                    
+                    if (!$inventory) {
+                        $inventory = Inventory::create([
+                            'warehouse_id' => $warehouseId,
+                            'product_id' => $productId,
+                            'quantity' => 0,
+                            'unit_cost' => 0,
+                            'total_value' => 0,
+                            'batch_number' => 'POS-AUTO-' . time(),
+                            'arrival_date' => now(),
+                            'origin_country' => 'TW',
+                            'quality_status' => 'normal',
+                        ]);
+                    }
+                    
+                    $this->decreaseInventoryQuantity($inventory->id, $remainingToDecrease, $reason);
+                } else {
+                    throw new \Exception("庫存不足，無法扣除所有請求的數量。");
+                }
             }
         });
     }

app/Modules/Inventory/Services/ProductService.php

@@ -0,0 +1,73 @@
+<?php
+
+namespace App\Modules\Inventory\Services;
+
+use App\Modules\Inventory\Models\Product;
+use App\Modules\Inventory\Models\Category;
+use App\Modules\Inventory\Models\Unit;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+
+class ProductService
+{
+    /**
+     * Upsert product from external POS source.
+     *
+     * @param array $data
+     * @return Product
+     */
+    public function upsertFromPos(array $data)
+    {
+        return DB::transaction(function () use ($data) {
+            $externalId = $data['external_pos_id'] ?? null;
+
+            if (!$externalId) {
+                throw new \Exception("External POS ID is required for syncing.");
+            }
+
+            // Try to find by external_pos_id
+            $product = Product::where('external_pos_id', $externalId)->first();
+
+            if (!$product) {
+                // If not found, create new
+                // Optional: Check SKU conflict if needed, but for now trust POS ID
+                $product = new Product();
+                $product->external_pos_id = $externalId;
+            }
+
+            // Map allowed fields
+            $product->name = $data['name'];
+            $product->barcode = $data['barcode'] ?? $product->barcode;
+            $product->sku = $data['sku'] ?? $product->sku; // Maybe allow SKU update?
+            $product->price = $data['price'] ?? 0;
+            
+            // Generate Code if missing (use sku or external_id)
+            if (empty($product->code)) {
+                $product->code = $data['code'] ?? ($product->sku ?? $product->external_pos_id);
+            }
+            
+            // Handle Category (Default: 未分類)
+            if (empty($product->category_id)) {
+                $categoryName = $data['category'] ?? '未分類';
+                $category = Category::firstOrCreate(
+                    ['name' => $categoryName],
+                    ['code' => 'CAT-' . strtoupper(bin2hex(random_bytes(4)))]
+                );
+                $product->category_id = $category->id;
+            }
+
+            // Handle Base Unit (Default: 個)
+            if (empty($product->base_unit_id)) {
+                $unitName = $data['unit'] ?? '個';
+                $unit = Unit::firstOrCreate(['name' => $unitName]);
+                $product->base_unit_id = $unit->id;
+            }
+            
+            $product->is_active = $data['is_active'] ?? true;
+            
+            $product->save();
+
+            return $product;
+        });
+    }
+}