feat(integration): 完善外部 API 對接邏輯與安全性

1. 新增 API Rate Limiting (每分鐘 60 次)
2. 實作 ProductServiceInterface 與 findOrCreateWarehouseByName 解決跨模組耦合問題
3. 強化 OrderSync API 驗證 (price 欄位限制最小 0、payment_method 加上允許白名單)
4. 實作 OrderSync API 冪等性處理，重複訂單直接回傳現有資訊
5. 修正 ProductSync API 同步邏輯，每次同步皆會更新產品分類與單位
6. 完善 integration API 對接手冊內容與 UI 排版

app/Modules/Integration/Controllers/OrderSyncController.php

@@ -6,66 +6,79 @@ use App\Http\Controllers\Controller;
 use Illuminate\Http\Request;
 use App\Modules\Integration\Models\SalesOrder;
 use App\Modules\Integration\Models\SalesOrderItem;
-use App\Modules\Inventory\Services\InventoryService;
-use App\Modules\Inventory\Models\Product;
-use App\Modules\Inventory\Models\Warehouse;
+use App\Modules\Inventory\Contracts\InventoryServiceInterface;
+use App\Modules\Inventory\Contracts\ProductServiceInterface;
 use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Facades\Log;
 
 class OrderSyncController extends Controller
 {
     protected $inventoryService;
+    protected $productService;
 
-    public function __construct(InventoryService $inventoryService)
-    {
+    public function __construct(
+        InventoryServiceInterface $inventoryService,
+        ProductServiceInterface $productService
+    ) {
         $this->inventoryService = $inventoryService;
+        $this->productService = $productService;
     }
 
     public function store(Request $request)
     {
+        // 冪等性處理：若訂單已存在，回傳已建立的訂單資訊
+        $existingOrder = SalesOrder::where('external_order_id', $request->external_order_id)->first();
+        if ($existingOrder) {
+            return response()->json([
+                'message' => 'Order already exists',
+                'order_id' => $existingOrder->id,
+            ], 200);
+        }
+
         $request->validate([
             'external_order_id' => 'required|string|unique:sales_orders,external_order_id',
             'warehouse' => 'nullable|string',
-            'warehouse_id' => 'nullable|exists:warehouses,id',
-            'items' => 'required|array',
+            'warehouse_id' => 'nullable|integer',
+            'payment_method' => 'nullable|string|in:cash,credit_card,line_pay,ecpay,transfer,other',
+            'sold_at' => 'nullable|date',
+            'items' => 'required|array|min:1',
             'items.*.pos_product_id' => 'required|string',
             'items.*.qty' => 'required|numeric|min:0.0001',
-            'items.*.price' => 'required|numeric',
+            'items.*.price' => 'required|numeric|min:0',
         ]);
 
         try {
             return DB::transaction(function () use ($request) {
-                // 1. Create Order
+                // 1. 建立訂單
                 $order = SalesOrder::create([
                     'external_order_id' => $request->external_order_id,
                     'status' => 'completed',
                     'payment_method' => $request->payment_method ?? 'cash',
-                    'total_amount' => 0, // Will calculate
+                    'total_amount' => 0,
                     'sold_at' => $request->sold_at ?? now(),
                     'raw_payload' => $request->all(),
                 ]);
 
-                // Find Warehouse (Default to "銷售倉庫")
+                // 2. 查找或建立倉庫
                 $warehouseId = $request->warehouse_id;
-                
+
                 if (empty($warehouseId)) {
                     $warehouseName = $request->warehouse ?: '銷售倉庫';
-                    $warehouse = Warehouse::firstOrCreate(['name' => $warehouseName], [
-                        'code' => 'SALES-' . strtoupper(bin2hex(random_bytes(4))),
-                        'type' => 'system_sales',
-                        'is_active' => true,
-                    ]);
+                    $warehouse = $this->inventoryService->findOrCreateWarehouseByName($warehouseName);
                     $warehouseId = $warehouse->id;
                 }
 
                 $totalAmount = 0;
 
+                // 3. 處理訂單明細
                 foreach ($request->items as $itemData) {
-                    // Find product by external ID (Strict Check)
-                    $product = Product::where('external_pos_id', $itemData['pos_product_id'])->first();
+                    // 透過介面查找產品
+                    $product = $this->productService->findByExternalPosId($itemData['pos_product_id']);
 
                     if (!$product) {
-                        throw new \Exception("Product not found for POS ID: " . $itemData['pos_product_id'] . ". Please sync product first.");
+                        throw new \Exception(
+                            "Product not found for POS ID: " . $itemData['pos_product_id'] . ". Please sync product first."
+                        );
                     }
 
                     $qty = $itemData['qty'];
@@ -73,23 +86,23 @@ class OrderSyncController extends Controller
                     $lineTotal = $qty * $price;
                     $totalAmount += $lineTotal;
 
-                    // 2. Create Order Item
+                    // 建立訂單明細
                     SalesOrderItem::create([
                         'sales_order_id' => $order->id,
                         'product_id' => $product->id,
-                        'product_name' => $product->name, // Snapshot name
+                        'product_name' => $product->name,
                         'quantity' => $qty,
                         'price' => $price,
                         'total' => $lineTotal,
                     ]);
 
-                    // 3. Deduct Stock (Force negative allowed for POS orders)
+                    // 4. 扣除庫存（強制模式，允許負庫存）
                     $this->inventoryService->decreaseStock(
                         $product->id,
                         $warehouseId,
                         $qty,
                         "POS Order: " . $order->external_order_id,
-                        true // Force = true
+                        true
                     );
                 }