feat(integration): 實作並測試 POS 與販賣機訂單同步 API

主要變更： - 實作 POS 與販賣機訂單同步邏輯，支援多租戶與 Sanctum 驗證。 - 修正多租戶識別中間件與 Sanctum 驗證順序問題。 - 切換快取驅動至 Redis 以支援 Tenancy 標籤功能。 - 新增商品同步 API (Upsert) 及相關單元測試。 - 新增手動測試腳本 tests/manual/test_integration_api.sh。 - 前端新增銷售訂單來源篩選與欄位顯示。
2026-02-23 13:27:12 +08:00
parent 904132e460
commit 2f30a78118
23 changed files with 1429 additions and 100 deletions
--- a/app/Modules/Integration/Controllers/OrderSyncController.php
+++ b/app/Modules/Integration/Controllers/OrderSyncController.php
@@ -3,120 +3,58 @@
 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\Contracts\InventoryServiceInterface;
-use App\Modules\Inventory\Contracts\ProductServiceInterface;
-use Illuminate\Support\Facades\DB;
+use App\Modules\Integration\Requests\SyncOrderRequest;
+use App\Modules\Integration\Actions\SyncOrderAction;
+use Illuminate\Http\JsonResponse;
 use Illuminate\Support\Facades\Log;

 class OrderSyncController extends Controller
 {
-    protected $inventoryService;
-    protected $productService;
+    protected $syncOrderAction;

-    public function __construct(
-        InventoryServiceInterface $inventoryService,
-        ProductServiceInterface $productService
-    ) {
-        $this->inventoryService = $inventoryService;
-        $this->productService = $productService;
+    public function __construct(SyncOrderAction $syncOrderAction)
+    {
+        $this->syncOrderAction = $syncOrderAction;
    }

-    public function store(Request $request)
+    /**
+     * 接收並同步外部交易訂單
+     *
+     * @param SyncOrderRequest $request
+     * @return JsonResponse
+     */
+    public function store(SyncOrderRequest $request): JsonResponse
    {
-        // 冪等性處理：若訂單已存在，回傳已建立的訂單資訊
-        $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|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|min:0',
-        ]);
-
        try {
-            return DB::transaction(function () use ($request) {
-                // 1. 建立訂單
-                $order = SalesOrder::create([
-                    'external_order_id' => $request->external_order_id,
-                    'status' => 'completed',
-                    'payment_method' => $request->payment_method ?? 'cash',
-                    'total_amount' => 0,
-                    'sold_at' => $request->sold_at ?? now(),
-                    'raw_payload' => $request->all(),
-                ]);
+            // 所有驗證皆已透過 SyncOrderRequest 自動處理
+            // 將通過驗證的資料交由 Action 處理（包含併發鎖、預先驗證、與資料庫異動）
+            $result = $this->syncOrderAction->execute($request->validated());

-                // 2. 查找或建立倉庫
-                $warehouseId = $request->warehouse_id;
+            $statusCode = ($result['status'] === 'exists') ? 200 : 201;

-                if (empty($warehouseId)) {
-                    $warehouseName = $request->warehouse ?: '銷售倉庫';
-                    $warehouse = $this->inventoryService->findOrCreateWarehouseByName($warehouseName);
-                    $warehouseId = $warehouse->id;
-                }
+            return response()->json([
+                'message' => $result['message'],
+                'order_id' => $result['order_id'] ?? null,
+            ], $statusCode);

-                $totalAmount = 0;
-
-                // 3. 處理訂單明細
-                foreach ($request->items as $itemData) {
-                    // 透過介面查找產品
-                    $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."
-                        );
-                    }
-
-                    $qty = $itemData['qty'];
-                    $price = $itemData['price'];
-                    $lineTotal = $qty * $price;
-                    $totalAmount += $lineTotal;
-
-                    // 建立訂單明細
-                    SalesOrderItem::create([
-                        'sales_order_id' => $order->id,
-                        'product_id' => $product->id,
-                        'product_name' => $product->name,
-                        'quantity' => $qty,
-                        'price' => $price,
-                        'total' => $lineTotal,
-                    ]);
-
-                    // 4. 扣除庫存（強制模式，允許負庫存）
-                    $this->inventoryService->decreaseStock(
-                        $product->id,
-                        $warehouseId,
-                        $qty,
-                        "POS Order: " . $order->external_order_id,
-                        true
-                    );
-                }
-
-                $order->update(['total_amount' => $totalAmount]);
-
-                return response()->json([
-                    'message' => 'Order synced and stock deducted successfully',
-                    'order_id' => $order->id,
-                ], 201);
-            });
+        } catch (\Illuminate\Validation\ValidationException $e) {
+            // 捕捉 Action 中拋出的預先驗證錯誤 (如查無商品、或鎖定逾時)
+            return response()->json([
+                'message' => 'Validation failed',
+                'errors' => $e->errors()
+            ], 422);

        } catch (\Exception $e) {
-            Log::error('Order Sync Failed', ['error' => $e->getMessage(), 'payload' => $request->all()]);
-            return response()->json(['message' => 'Sync failed: ' . $e->getMessage()], 400);
+            // 系統層級的錯誤
+            Log::error('Order Sync Failed', [
+                'error' => $e->getMessage(),
+                'trace' => $e->getTraceAsString(),
+                'payload' => $request->all()
+            ]);
+            
+            return response()->json([
+                'message' => 'Sync failed: An unexpected error occurred.'
+            ], 500);
        }
    }
 }
--- a/app/Modules/Integration/Controllers/SalesOrderController.php
+++ b/app/Modules/Integration/Controllers/SalesOrderController.php
@@ -0,0 +1,52 @@
+<?php
+
+namespace App\Modules\Integration\Controllers;
+
+use App\Http\Controllers\Controller;
+use App\Modules\Integration\Models\SalesOrder;
+use Illuminate\Http\Request;
+use Inertia\Inertia;
+
+class SalesOrderController extends Controller
+{
+    /**
+     * 顯示銷售訂單列表
+     */
+    public function index(Request $request)
+    {
+        $query = SalesOrder::query();
+
+        // 搜尋篩選 (外部訂單號)
+        if ($request->filled('search')) {
+            $query->where('external_order_id', 'like', '%' . $request->search . '%');
+        }
+
+        // 來源篩選
+        if ($request->filled('source')) {
+            $query->where('source', $request->source);
+        }
+
+        // 排序
+        $query->orderBy('sold_at', 'desc');
+
+        $orders = $query->paginate($request->input('per_page', 10))
+            ->withQueryString();
+
+        return Inertia::render('Integration/SalesOrders/Index', [
+            'orders' => $orders,
+            'filters' => $request->only(['search', 'per_page', 'source']),
+        ]);
+    }
+
+    /**
+     * 顯示單一銷售訂單詳情
+     */
+    public function show(SalesOrder $salesOrder)
+    {
+        $salesOrder->load(['items']);
+
+        return Inertia::render('Integration/SalesOrders/Show', [
+            'order' => $salesOrder,
+        ]);
+    }
+}
--- a/app/Modules/Integration/Controllers/VendingOrderSyncController.php
+++ b/app/Modules/Integration/Controllers/VendingOrderSyncController.php
@@ -0,0 +1,56 @@
+<?php
+
+namespace App\Modules\Integration\Controllers;
+
+use App\Http\Controllers\Controller;
+use App\Modules\Integration\Requests\SyncVendingOrderRequest;
+use App\Modules\Integration\Actions\SyncVendingOrderAction;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Support\Facades\Log;
+
+class VendingOrderSyncController extends Controller
+{
+    protected $syncVendingOrderAction;
+
+    public function __construct(SyncVendingOrderAction $syncVendingOrderAction)
+    {
+        $this->syncVendingOrderAction = $syncVendingOrderAction;
+    }
+
+    /**
+     * 接收並同步販賣機交易訂單
+     *
+     * @param SyncVendingOrderRequest $request
+     * @return JsonResponse
+     */
+    public function store(SyncVendingOrderRequest $request): JsonResponse
+    {
+        try {
+            $result = $this->syncVendingOrderAction->execute($request->validated());
+
+            $statusCode = ($result['status'] === 'exists') ? 200 : 201;
+
+            return response()->json([
+                'message' => $result['message'],
+                'order_id' => $result['order_id'] ?? null,
+            ], $statusCode);
+
+        } catch (\Illuminate\Validation\ValidationException $e) {
+            return response()->json([
+                'message' => 'Validation failed',
+                'errors' => $e->errors()
+            ], 422);
+
+        } catch (\Exception $e) {
+            Log::error('Vending Order Sync Failed', [
+                'error' => $e->getMessage(),
+                'trace' => $e->getTraceAsString(),
+                'payload' => $request->all()
+            ]);
+
+            return response()->json([
+                'message' => 'Sync failed: An unexpected error occurred.'
+            ], 500);
+        }
+    }
+}