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

app/Modules/Integration/Controllers/OrderSyncController.php

@@ -0,0 +1,109 @@
+<?php
+
+namespace App\Modules\Integration\Controllers;
+
+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 Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+
+class OrderSyncController extends Controller
+{
+    protected $inventoryService;
+
+    public function __construct(InventoryService $inventoryService)
+    {
+        $this->inventoryService = $inventoryService;
+    }
+
+    public function store(Request $request)
+    {
+        $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',
+            'items.*.pos_product_id' => 'required|string',
+            'items.*.qty' => 'required|numeric|min:0.0001',
+            'items.*.price' => 'required|numeric',
+        ]);
+
+        try {
+            return DB::transaction(function () use ($request) {
+                // 1. Create Order
+                $order = SalesOrder::create([
+                    'external_order_id' => $request->external_order_id,
+                    'status' => 'completed',
+                    'payment_method' => $request->payment_method ?? 'cash',
+                    'total_amount' => 0, // Will calculate
+                    'sold_at' => $request->sold_at ?? now(),
+                    'raw_payload' => $request->all(),
+                ]);
+
+                // Find Warehouse (Default to "銷售倉庫")
+                $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,
+                    ]);
+                    $warehouseId = $warehouse->id;
+                }
+
+                $totalAmount = 0;
+
+                foreach ($request->items as $itemData) {
+                    // Find product by external ID (Strict Check)
+                    $product = Product::where('external_pos_id', $itemData['pos_product_id'])->first();
+
+                    if (!$product) {
+                        throw new \Exception("Product not found for POS ID: " . $itemData['pos_product_id'] . ". Please sync product first.");
+                    }
+
+                    $qty = $itemData['qty'];
+                    $price = $itemData['price'];
+                    $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
+                        'quantity' => $qty,
+                        'price' => $price,
+                        'total' => $lineTotal,
+                    ]);
+
+                    // 3. Deduct Stock (Force negative allowed for POS orders)
+                    $this->inventoryService->decreaseStock(
+                        $product->id,
+                        $warehouseId,
+                        $qty,
+                        "POS Order: " . $order->external_order_id,
+                        true // Force = true
+                    );
+                }
+
+                $order->update(['total_amount' => $totalAmount]);
+
+                return response()->json([
+                    'message' => 'Order synced and stock deducted successfully',
+                    'order_id' => $order->id,
+                ], 201);
+            });
+
+        } catch (\Exception $e) {
+            Log::error('Order Sync Failed', ['error' => $e->getMessage(), 'payload' => $request->all()]);
+            return response()->json(['message' => 'Sync failed: ' . $e->getMessage()], 400);
+        }
+    }
+}

app/Modules/Integration/Controllers/ProductSyncController.php

@@ -0,0 +1,47 @@
+<?php
+
+namespace App\Modules\Integration\Controllers;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\Request;
+use App\Modules\Inventory\Services\ProductService;
+use Illuminate\Support\Facades\Log;
+
+class ProductSyncController extends Controller
+{
+    protected $productService;
+
+    public function __construct(ProductService $productService)
+    {
+        $this->productService = $productService;
+    }
+
+    public function upsert(Request $request)
+    {
+        $request->validate([
+            'external_pos_id' => 'required|string',
+            'name' => 'required|string',
+            'price' => 'nullable|numeric',
+            'sku' => 'nullable|string',
+            'barcode' => 'nullable|string',
+            'category' => 'nullable|string',
+            'unit' => 'nullable|string',
+            'updated_at' => 'nullable|date',
+        ]);
+
+        try {
+            $product = $this->productService->upsertFromPos($request->all());
+
+            return response()->json([
+                'message' => 'Product synced successfully',
+                'data' => [
+                    'id' => $product->id,
+                    'external_pos_id' => $product->external_pos_id,
+                ]
+            ]);
+        } catch (\Exception $e) {
+            Log::error('Product Sync Failed', ['error' => $e->getMessage(), 'payload' => $request->all()]);
+            return response()->json(['message' => 'Sync failed'], 500);
+        }
+    }
+}