fix: 還原 compose.demo.yaml 的 port 映射為 80:80 + 8080:8080

Demo 主機的 Docker 沒有綁定特權端口 (80) 的權限，
將映射從 80:80 改為 8080:80（主機 8080 → 容器 Nginx 80）。

.env.example

@@ -44,7 +44,7 @@ BROADCAST_CONNECTION=log
 FILESYSTEM_DISK=local
 QUEUE_CONNECTION=database
 
-CACHE_STORE=database
+CACHE_STORE=redis
 # CACHE_PREFIX=
 
 MEMCACHED_HOST=127.0.0.1

.gitea/workflows/deploy-demo.yaml

@@ -0,0 +1,100 @@
+name: ERP-Deploy-Demo
+
+on:
+  push:
+    branches:
+      - demo
+
+jobs:
+  deploy-demo:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v3
+        with:
+          github-server-url: https://gitea.taiwan-star.com.tw
+          repository: ${{ github.repository }}
+
+      - name: Step 1 - Push Code to Demo
+        run: |
+          apt-get update && apt-get install -y rsync openssh-client
+          mkdir -p ~/.ssh
+          echo "${{ secrets.DEMO_SSH_KEY }}" > ~/.ssh/id_rsa_demo
+          chmod 600 ~/.ssh/id_rsa_demo
+          rsync -avz --delete \
+            --exclude='.git' \
+            --exclude='node_modules' \
+            --exclude='vendor' \
+            --exclude='storage' \
+            --exclude='.env' \
+            --exclude='public/build' \
+            -e "ssh -p 2227 -i ~/.ssh/id_rsa_demo -o StrictHostKeyChecking=no" \
+            ./ root@220.132.7.82:/var/www/star-erp-demo/
+          rm ~/.ssh/id_rsa_demo
+
+      - name: Step 2 - Check if Rebuild Needed
+        id: check_rebuild
+        uses: appleboy/ssh-action@master
+        with:
+          host: 220.132.7.82
+          port: 2227
+          username: root
+          key: ${{ secrets.DEMO_SSH_KEY }}
+          script: |
+            cd /var/www/star-erp-demo
+            if git diff --name-only HEAD~1 HEAD 2>/dev/null | grep -qE '(Dockerfile|compose\.yaml|docker-compose\.yaml)'; then
+              echo "REBUILD_NEEDED=true"
+            else
+              echo "REBUILD_NEEDED=false"
+            fi
+
+      - name: Step 3 - Container Up & Health Check
+        uses: appleboy/ssh-action@master
+        with:
+          host: 220.132.7.82
+          port: 2227
+          username: root
+          key: ${{ secrets.DEMO_SSH_KEY }}
+          script: |
+            cd /var/www/star-erp-demo
+            chown -R 1000:1000 .
+            
+            if git diff --name-only HEAD~1 HEAD 2>/dev/null | grep -qE '(Dockerfile|compose\.yaml|compose\.demo\.yaml|docker-compose\.yaml)'; then
+              echo "🔄 偵測到 Docker 相關檔案變更，執行完整重建..."
+              WWWGROUP=1000 WWWUSER=1000 docker compose -f compose.yaml -f compose.demo.yaml up -d --build --wait
+            else
+              echo "⚡ 無 Docker 檔案變更，僅重載服務..."
+              if ! docker ps --format '{{.Names}}' | grep -q 'star-erp-laravel'; then
+                echo "容器未運行，正在啟動..."
+                WWWGROUP=1000 WWWUSER=1000 docker compose -f compose.yaml -f compose.demo.yaml up -d --wait
+              else
+                echo "容器已運行，跳過 docker compose，直接進行程式碼部署..."
+              fi
+            fi
+            
+            echo "容器狀態：" && docker ps --filter "name=star-erp-laravel"
+
+      - name: Step 4 - Composer & NPM Build
+        uses: appleboy/ssh-action@master
+        with:
+          host: 220.132.7.82
+          port: 2227
+          username: root
+          key: ${{ secrets.DEMO_SSH_KEY }}
+          script: |
+           docker exec -u 1000:1000 -w /var/www/html star-erp-laravel sh -c "
+            composer install --no-dev --optimize-autoloader --no-interaction &&
+            npm install &&
+            npm run build &&
+            rm -f public/hot &&
+            php artisan storage:link &&
+            php artisan migrate --force &&
+            php artisan tenants:migrate --force &&
+            php artisan db:seed --force &&
+            php artisan tenants:run db:seed --option=\"class=PermissionSeeder\" --option=\"force=true\" &&
+            php artisan permission:cache-reset &&
+            php artisan optimize:clear &&
+            php artisan optimize &&
+            php artisan view:cache
+           "
+           docker exec star-erp-laravel chmod -R 775 /var/www/html/storage /var/www/html/bootstrap/cache

.gitea/workflows/deploy-prod.yaml

@@ -0,0 +1,93 @@
+name: ERP-Deploy-Production
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy-production:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v3
+        with:
+          repository: ${{ github.repository }}
+
+      - name: Step 1 - Push Code to Production
+        run: |
+          apt-get update && apt-get install -y rsync openssh-client
+          mkdir -p ~/.ssh
+          echo "${{ secrets.PROD_SSH_KEY }}" > ~/.ssh/id_rsa_prod
+          chmod 600 ~/.ssh/id_rsa_prod
+          rsync -avz --delete \
+            --exclude='.git' \
+            --exclude='.env' \
+            --exclude='node_modules' \
+            --exclude='vendor' \
+            --exclude='storage' \
+            --exclude='public/build' \
+            -e "ssh -p 2224 -i ~/.ssh/id_rsa_prod -o StrictHostKeyChecking=no" \
+            ./ root@220.132.7.82:/var/www/star-erp/
+          rm ~/.ssh/id_rsa_prod
+
+      - name: Step 2 - Check if Rebuild Needed
+        id: check_rebuild_prod
+        uses: appleboy/ssh-action@master
+        with:
+          host: 220.132.7.82
+          port: 2224
+          username: root
+          key: ${{ secrets.PROD_SSH_KEY }}
+          script: |
+            cd /var/www/star-erp
+
+            if git diff --name-only HEAD~1 HEAD 2>/dev/null | grep -qE '(Dockerfile|compose\.yaml|docker-compose\.yaml)'; then
+              echo "REBUILD_NEEDED=true"
+            else
+              echo "REBUILD_NEEDED=false"
+            fi
+
+      - name: Step 3 - Container Up & Health Check
+        uses: appleboy/ssh-action@master
+        with:
+          host: 220.132.7.82
+          port: 2224
+          username: root
+          key: ${{ secrets.PROD_SSH_KEY }}
+          script: |
+            cd /var/www/star-erp
+            chown -R 1000:1000 .
+            
+            if git diff --name-only HEAD~1 HEAD 2>/dev/null | grep -qE '(Dockerfile|compose\.yaml|compose\.prod\.yaml|docker-compose\.yaml)'; then
+              echo "🔄 偵測到 Docker 相關檔案變更，執行完整重建..."
+              WWWGROUP=1000 WWWUSER=1000 docker compose -f compose.yaml -f compose.prod.yaml up -d --build --wait
+            else
+              echo "⚡ 無 Docker 檔案變更，僅重載服務..."
+              if ! docker ps --format '{{.Names}}' | grep -q 'star-erp-laravel'; then
+                echo "容器未運行，正在啟動..."
+                WWWGROUP=1000 WWWUSER=1000 docker compose -f compose.yaml -f compose.prod.yaml up -d --wait
+              else
+                echo "容器已運行，跳過 docker compose，直接進行程式碼部署..."
+              fi
+            fi
+            
+            echo "容器狀態：" && docker ps --filter "name=star-erp-laravel"
+
+            docker exec -u 1000:1000 -w /var/www/html star-erp-laravel sh -c "
+              composer install --no-dev --optimize-autoloader &&
+              npm install &&
+              npm run build &&
+              rm -f public/hot
+
+              php artisan storage:link &&
+              php artisan migrate --force &&
+              php artisan tenants:migrate --force &&
+              php artisan db:seed --force &&
+              php artisan tenants:run db:seed --option=\"class=PermissionSeeder\" --option=\"force=true\" &&
+              php artisan permission:cache-reset &&
+              php artisan optimize:clear &&
+              php artisan optimize &&
+              php artisan view:cache
+            "
+            docker exec star-erp-laravel chmod -R 775 /var/www/html/storage /var/www/html/bootstrap/cache

.gitea/workflows/deploy.yaml

@@ -1,201 +0,0 @@
-name: Koori-ERP-Deploy-System
-
-on:
-  push:
-    branches:
-      - demo
-      - main
-
-jobs:
-  # --- 1. Demo 環境部署 (103 本機) ---
-  deploy-demo:
-    if: false
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout Code
-        uses: actions/checkout@v3
-        with:
-          repository: ${{ github.repository }}
-
-      - name: Step 1 - Push Code to Demo
-        run: |
-          apt-get update && apt-get install -y rsync openssh-client
-          mkdir -p ~/.ssh
-          echo "${{ secrets.DEMO_SSH_KEY }}" > ~/.ssh/id_rsa_demo
-          chmod 600 ~/.ssh/id_rsa_demo
-          rsync -avz --delete \
-            --exclude='.git' \
-            --exclude='node_modules' \
-            --exclude='vendor' \
-            --exclude='storage' \
-            --exclude='.env' \
-            --exclude='public/build' \
-            -e "ssh -i ~/.ssh/id_rsa_demo -o StrictHostKeyChecking=no" \
-            ./ amba@192.168.0.103:/home/amba/star-erp/
-          rm ~/.ssh/id_rsa_demo
-
-      - name: Step 2 - Check if Rebuild Needed
-        id: check_rebuild
-        uses: appleboy/ssh-action@master
-        with:
-          host: 192.168.0.103
-          port: 22
-          username: amba
-          key: ${{ secrets.DEMO_SSH_KEY }}
-          script: |
-            cd /home/amba/star-erp
-            if git diff --name-only HEAD~1 HEAD 2>/dev/null | grep -qE '(Dockerfile|compose\.yaml|docker-compose\.yaml)'; then
-              echo "REBUILD_NEEDED=true"
-            else
-              echo "REBUILD_NEEDED=false"
-            fi
-
-      - name: Step 3 - Container Up & Health Check
-        uses: appleboy/ssh-action@master
-        with:
-          host: 192.168.0.103
-          port: 22
-          username: amba
-          key: ${{ secrets.DEMO_SSH_KEY }}
-          script: |
-            cd /home/amba/koori-erp
-            chown -R 1000:1000 .
-            if git diff --name-only HEAD~1 HEAD 2>/dev/null | grep -qE '(Dockerfile|compose\.yaml|docker-compose\.yaml)'; then
-              echo "🔄 偵測到 Docker 相關檔案變更，執行完整重建..."
-              WWWGROUP=1000 WWWUSER=1000 docker compose up -d --build --wait
-            else
-              echo "⚡ 無 Docker 檔案變更，僅重載服務..."
-              if ! docker ps --format '{{.Names}}' | grep -q 'koori-erp-laravel'; then
-                echo "容器未運行，正在啟動..."
-                WWWGROUP=1000 WWWUSER=1000 docker compose up -d --wait
-              else
-                echo "容器已運行，跳過 docker compose，直接進行程式碼部署..."
-              fi
-            fi
-            echo "容器狀態：" && docker ps --filter "name=koori-erp-laravel"
-
-      - name: Step 4 - Composer & NPM Build
-        uses: appleboy/ssh-action@master
-        with:
-          host: 192.168.0.103
-          port: 22
-          username: amba
-          key: ${{ secrets.DEMO_SSH_KEY }}
-          script: |
-            docker exec -u 1000:1000 -w /var/www/html star-erp-laravel sh -c "
-              # 0. 更新版本號 (直接使用 Github Actions 變數注入)
-              VERSION=\"v1.0-$(echo '${{ github.sha }}' | cut -c1-7)\"
-              sed -i \"s/^APP_VERSION=.*/APP_VERSION=\$VERSION/\" .env || echo \"APP_VERSION=\$VERSION\" >> .env
-              
-              composer install --no-dev --optimize-autoloader --no-interaction &&
-              npm install &&
-              npm run build &&
-              php artisan storage:link &&
-              php artisan migrate --force &&
-              php artisan tenants:migrate --force &&
-              php artisan db:seed --force &&
-              php artisan tenants:run db:seed --option=\"class=PermissionSeeder\" --option=\"force=true\" &&
-              php artisan permission:cache-reset &&
-              php artisan optimize:clear &&
-              php artisan optimize &&
-              php artisan view:cache
-            "
-            docker exec star-erp-laravel chmod -R 775 /var/www/html/storage /var/www/html/bootstrap/cache
-
-  # --- 2. 正式環境部署 (erp.koori.tw:2224) ---
-  deploy-production:
-    if: github.ref == 'refs/heads/main'
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout Code
-        uses: actions/checkout@v3
-        with:
-          repository: ${{ github.repository }}
-
-      - name: Step 1 - Push Code to Production
-        run: |
-          apt-get update && apt-get install -y rsync openssh-client
-          mkdir -p ~/.ssh
-          echo "${{ secrets.PROD_SSH_KEY }}" > ~/.ssh/id_rsa_prod
-          chmod 600 ~/.ssh/id_rsa_prod
-          rsync -avz --delete \
-            --exclude='.git' \
-            --exclude='.env' \
-            --exclude='node_modules' \
-            --exclude='vendor' \
-            --exclude='storage' \
-            --exclude='public/build' \
-            -e "ssh -p 2224 -i ~/.ssh/id_rsa_prod -o StrictHostKeyChecking=no" \
-            ./ root@erp.koori.tw:/var/www/star-erp/
-          rm ~/.ssh/id_rsa_prod
-
-
-      # 2. 檢查是否需要重建容器（只有 Dockerfile 或 compose.yaml 變動時才重建）
-      - name: Step 2 - Check if Rebuild Needed
-        id: check_rebuild_prod
-        uses: appleboy/ssh-action@master
-        with:
-          host: erp.koori.tw
-          port: 2224
-          username: root
-          key: ${{ secrets.PROD_SSH_KEY }}
-          script: |
-            cd /var/www/star-erp
-            # [Patch] 修正正式機 Nginx Proxy 配置 (對應外部 SSL/OpenResty)
-            sed -i "s/- '8080:8080'/- '80:80'\n            - '8080:8080'/" compose.yaml
-            sed -i "s/demo-proxy.conf/prod-proxy.conf/" compose.yaml
-
-            # 檢查最近的 commit 是否包含 Dockerfile 或 compose.yaml 的變更
-            if git diff --name-only HEAD~1 HEAD 2>/dev/null | grep -qE '(Dockerfile|compose\.yaml|docker-compose\.yaml)'; then
-              echo "REBUILD_NEEDED=true"
-            else
-              echo "REBUILD_NEEDED=false"
-            fi
-
-      # 3. 啟動或重建容器（根據檢查結果決定是否加 --build）
-      - name: Step 3 - Container Up & Health Check
-        uses: appleboy/ssh-action@master
-        with:
-          host: erp.koori.tw
-          port: 2224
-          username: root
-          key: ${{ secrets.PROD_SSH_KEY }}
-          script: |
-            cd /var/www/star-erp
-            chown -R 1000:1000 .
-            # 檢查是否需要重建
-            if git diff --name-only HEAD~1 HEAD 2>/dev/null | grep -qE '(Dockerfile|compose\.yaml|docker-compose\.yaml)'; then
-              echo "🔄 偵測到 Docker 相關檔案變更，執行完整重建..."
-              WWWGROUP=1000 WWWUSER=1000 docker compose up -d --build --wait
-            else
-              echo "⚡ 無 Docker 檔案變更，僅重載服務..."
-              if ! docker ps --format '{{.Names}}' | grep -q 'star-erp-laravel'; then
-                echo "容器未運行，正在啟動..."
-                WWWGROUP=1000 WWWUSER=1000 docker compose up -d --wait
-              else
-                echo "容器已運行，跳過 docker compose，直接進行程式碼部署..."
-              fi
-            fi
-            
-            echo "容器狀態：" && docker ps --filter "name=star-erp-laravel"
-
-            docker exec -u 1000:1000 -w /var/www/html star-erp-laravel sh -c "
-              # 0. 更新版本號 (直接注入)
-              VERSION=\"v1.0-$(echo '${{ github.sha }}' | cut -c1-7)\"
-              sed -i \"s/^APP_VERSION=.*/APP_VERSION=\$VERSION/\" .env || echo \"APP_VERSION=\$VERSION\" >> .env
-
-              composer install --no-dev --optimize-autoloader &&
-              npm install &&
-              npm run build
-
-              php artisan storage:link &&
-              php artisan migrate --force &&
-              php artisan tenants:migrate --force &&
-              php artisan db:seed --force &&
-              php artisan tenants:run db:seed --option="class=PermissionSeeder" --option="force=true" &&
-              php artisan permission:cache-reset &&
-              php artisan optimize:clear &&
-              php artisan optimize &&
-              php artisan view:cache
-            "
-            docker exec star-erp-laravel chmod -R 775 /var/www/html/storage /var/www/html/bootstrap/cache

app/Modules/Integration/Actions/SyncOrderAction.php

@@ -0,0 +1,156 @@
+<?php
+
+namespace App\Modules\Integration\Actions;
+
+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 Illuminate\Support\Facades\Log;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Validation\ValidationException;
+
+class SyncOrderAction
+{
+    protected $inventoryService;
+    protected $productService;
+
+    public function __construct(
+        InventoryServiceInterface $inventoryService,
+        ProductServiceInterface $productService
+    ) {
+        $this->inventoryService = $inventoryService;
+        $this->productService = $productService;
+    }
+
+    /**
+     * 執行訂單同步
+     *
+     * @param array $data
+     * @return array 包含 orders 建立結果的資訊
+     * @throws ValidationException
+     * @throws \Exception
+     */
+    public function execute(array $data)
+    {
+        $externalOrderId = $data['external_order_id'];
+
+        // 使用 Cache::lock 防護高併發，鎖定該訂單號 10 秒
+        // 此處需要 cache store 支援鎖 (如 memcached, dynamodb, redis, database, file, array)
+        // Laravel 預設的 file/redis 都支援。若無法取得鎖，表示有另一個相同的請求正在處理
+        $lock = Cache::lock("sync_order_{$externalOrderId}", 10);
+
+        if (!$lock->get()) {
+            throw ValidationException::withMessages([
+                'external_order_id' => ["The order {$externalOrderId} is currently being processed by another transaction. Please try again later."]
+            ]);
+        }
+
+        try {
+            // 冪等性處理：若訂單已存在，回傳已建立的訂單資訊
+            $existingOrder = SalesOrder::where('external_order_id', $externalOrderId)->first();
+            if ($existingOrder) {
+                return [
+                    'status' => 'exists',
+                    'message' => 'Order already exists',
+                    'order_id' => $existingOrder->id,
+                ];
+            }
+
+            // --- 預檢 (Pre-flight check) N+1 優化 ---
+            $items = $data['items'];
+            $posProductIds = array_column($items, 'pos_product_id');
+            
+            // 一次性查出所有相關的 Product
+            $products = $this->productService->findByExternalPosIds($posProductIds)->keyBy('external_pos_id');
+            
+            $missingIds = [];
+            foreach ($posProductIds as $id) {
+                if (!$products->has($id)) {
+                    $missingIds[] = $id;
+                }
+            }
+
+            if (!empty($missingIds)) {
+                // 回報所有缺漏的 ID
+                throw ValidationException::withMessages([
+                    'items' => ["The following products are not found: " . implode(', ', $missingIds) . ". Please sync products first."]
+                ]);
+            }
+
+            // --- 執行寫入交易 ---
+            $result = DB::transaction(function () use ($data, $items, $products) {
+                // 1. 建立訂單
+                $order = SalesOrder::create([
+                    'external_order_id' => $data['external_order_id'],
+                    'status' => 'completed',
+                    'payment_method' => $data['payment_method'] ?? 'cash',
+                    'total_amount' => 0,
+                    'sold_at' => $data['sold_at'] ?? now(),
+                    'raw_payload' => $data,
+                    'source' => $data['source'] ?? 'pos',
+                    'source_label' => $data['source_label'] ?? null,
+                ]);
+
+                // 2. 查找或建立倉庫
+                $warehouseId = $data['warehouse_id'] ?? null;
+
+                if (empty($warehouseId)) {
+                    $warehouseName = $data['warehouse'] ?? '銷售倉庫';
+                    $warehouse = $this->inventoryService->findOrCreateWarehouseByName($warehouseName);
+                    $warehouseId = $warehouse->id;
+                }
+
+                $totalAmount = 0;
+
+                // 3. 處理訂單明細
+                $orderItemsData = [];
+                foreach ($items as $itemData) {
+                    $product = $products->get($itemData['pos_product_id']);
+                    
+                    $qty = $itemData['qty'];
+                    $price = $itemData['price'];
+                    $lineTotal = $qty * $price;
+                    $totalAmount += $lineTotal;
+
+                    $orderItemsData[] = [
+                        'sales_order_id' => $order->id,
+                        'product_id' => $product->id,
+                        'product_name' => $product->name,
+                        'quantity' => $qty,
+                        'price' => $price,
+                        'total' => $lineTotal,
+                        'created_at' => now(),
+                        'updated_at' => now(),
+                    ];
+
+                    // 4. 扣除庫存（強制模式，允許負庫存）
+                    $this->inventoryService->decreaseStock(
+                        $product->id,
+                        $warehouseId,
+                        $qty,
+                        "POS Order: " . $order->external_order_id,
+                        true
+                    );
+                }
+
+                // Batch insert order items
+                SalesOrderItem::insert($orderItemsData);
+
+                $order->update(['total_amount' => $totalAmount]);
+
+                return [
+                    'status' => 'created',
+                    'message' => 'Order synced and stock deducted successfully',
+                    'order_id' => $order->id,
+                ];
+            });
+
+            return $result;
+        } finally {
+            // 無論成功失敗，最後釋放鎖定
+            $lock->release();
+        }
+    }
+}

app/Modules/Integration/Actions/SyncVendingOrderAction.php

@@ -0,0 +1,152 @@
+<?php
+
+namespace App\Modules\Integration\Actions;
+
+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 Illuminate\Support\Facades\Log;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Validation\ValidationException;
+
+class SyncVendingOrderAction
+{
+    protected $inventoryService;
+    protected $productService;
+
+    public function __construct(
+        InventoryServiceInterface $inventoryService,
+        ProductServiceInterface $productService
+    ) {
+        $this->inventoryService = $inventoryService;
+        $this->productService = $productService;
+    }
+
+    /**
+     * 執行販賣機訂單同步
+     *
+     * @param array $data
+     * @return array 包含訂單建立結果的資訊
+     * @throws ValidationException
+     * @throws \Exception
+     */
+    public function execute(array $data)
+    {
+        $externalOrderId = $data['external_order_id'];
+
+        // 使用 Cache::lock 防護高併發
+        $lock = Cache::lock("sync_order_{$externalOrderId}", 10);
+
+        if (!$lock->get()) {
+            throw ValidationException::withMessages([
+                'external_order_id' => ["The order {$externalOrderId} is currently being processed by another transaction. Please try again later."]
+            ]);
+        }
+
+        try {
+            // 冪等性處理：若訂單已存在，回傳已建立的訂單資訊
+            $existingOrder = SalesOrder::where('external_order_id', $externalOrderId)->first();
+            if ($existingOrder) {
+                return [
+                    'status' => 'exists',
+                    'message' => 'Order already exists',
+                    'order_id' => $existingOrder->id,
+                ];
+            }
+
+            // --- 預檢：以 ERP 商品代碼查詢 ---
+            $items = $data['items'];
+            $productCodes = array_column($items, 'product_code');
+
+            // 一次性查出所有相關的 Product（以 code 查詢）
+            $products = $this->productService->findByCodes($productCodes)->keyBy('code');
+
+            $missingCodes = [];
+            foreach ($productCodes as $code) {
+                if (!$products->has($code)) {
+                    $missingCodes[] = $code;
+                }
+            }
+
+            if (!empty($missingCodes)) {
+                throw ValidationException::withMessages([
+                    'items' => ["The following products are not found by code: " . implode(', ', $missingCodes) . ". Please ensure these products exist in the system."]
+                ]);
+            }
+
+            // --- 執行寫入交易 ---
+            $result = DB::transaction(function () use ($data, $items, $products) {
+                // 1. 建立訂單
+                $order = SalesOrder::create([
+                    'external_order_id' => $data['external_order_id'],
+                    'status' => 'completed',
+                    'payment_method' => $data['payment_method'] ?? 'electronic',
+                    'total_amount' => 0,
+                    'sold_at' => $data['sold_at'] ?? now(),
+                    'raw_payload' => $data,
+                    'source' => 'vending',
+                    'source_label' => $data['machine_id'] ?? null,
+                ]);
+
+                // 2. 查找或建立倉庫
+                $warehouseId = $data['warehouse_id'] ?? null;
+
+                if (empty($warehouseId)) {
+                    $warehouseName = $data['warehouse'] ?? '販賣機倉庫';
+                    $warehouse = $this->inventoryService->findOrCreateWarehouseByName($warehouseName);
+                    $warehouseId = $warehouse->id;
+                }
+
+                $totalAmount = 0;
+
+                // 3. 處理訂單明細
+                $orderItemsData = [];
+                foreach ($items as $itemData) {
+                    $product = $products->get($itemData['product_code']);
+
+                    $qty = $itemData['qty'];
+                    $price = $itemData['price'];
+                    $lineTotal = $qty * $price;
+                    $totalAmount += $lineTotal;
+
+                    $orderItemsData[] = [
+                        'sales_order_id' => $order->id,
+                        'product_id' => $product->id,
+                        'product_name' => $product->name,
+                        'quantity' => $qty,
+                        'price' => $price,
+                        'total' => $lineTotal,
+                        'created_at' => now(),
+                        'updated_at' => now(),
+                    ];
+
+                    // 4. 扣除庫存（強制模式，允許負庫存）
+                    $this->inventoryService->decreaseStock(
+                        $product->id,
+                        $warehouseId,
+                        $qty,
+                        "Vending Order: " . $order->external_order_id,
+                        true
+                    );
+                }
+
+                // Batch insert order items
+                SalesOrderItem::insert($orderItemsData);
+
+                $order->update(['total_amount' => $totalAmount]);
+
+                return [
+                    'status' => 'created',
+                    'message' => 'Vending order synced and stock deducted successfully',
+                    'order_id' => $order->id,
+                ];
+            });
+
+            return $result;
+        } finally {
+            $lock->release();
+        }
+    }
+}

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);
         }
     }
 }

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,
+        ]);
+    }
+}

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);
+        }
+    }
+}

app/Modules/Integration/IntegrationServiceProvider.php

@@ -14,6 +14,7 @@ class IntegrationServiceProvider extends ServiceProvider
     public function boot()
     {
         $this->loadRoutesFrom(__DIR__ . '/Routes/api.php');
+        $this->loadRoutesFrom(__DIR__ . '/Routes/web.php');
         $this->loadMigrationsFrom(__DIR__ . '/Database/Migrations');
 
         // 註冊 Middleware 別名

app/Modules/Integration/Models/SalesOrder.php

@@ -16,6 +16,8 @@ class SalesOrder extends Model
         'total_amount',
         'sold_at',
         'raw_payload',
+        'source',
+        'source_label',
     ];
 
     protected $casts = [

app/Modules/Integration/Requests/SyncOrderRequest.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace App\Modules\Integration\Requests;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class SyncOrderRequest extends FormRequest
+{
+    /**
+     * Determine if the user is authorized to make this request.
+     */
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Get the validation rules that apply to the request.
+     *
+     * @return array<string, \Illuminate\Contracts\Validation\ValidationRule|array<mixed>|string>
+     */
+    public function rules(): array
+    {
+        return [
+            'external_order_id' => 'required|string',
+            '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',
+        ];
+    }
+}

app/Modules/Integration/Requests/SyncVendingOrderRequest.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace App\Modules\Integration\Requests;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class SyncVendingOrderRequest extends FormRequest
+{
+    /**
+     * Determine if the user is authorized to make this request.
+     */
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * 販賣機訂單同步的驗證規則
+     *
+     * @return array<string, \Illuminate\Contracts\Validation\ValidationRule|array<mixed>|string>
+     */
+    public function rules(): array
+    {
+        return [
+            'external_order_id' => 'required|string',
+            'machine_id'        => 'nullable|string',
+            'warehouse'         => 'nullable|string',
+            'warehouse_id'      => 'nullable|integer',
+            'payment_method'    => 'nullable|string|in:cash,electronic,line_pay,other',
+            'sold_at'           => 'nullable|date',
+            'items'             => 'required|array|min:1',
+            'items.*.product_code' => 'required|string',  // 使用 ERP 商品代碼
+            'items.*.qty'       => 'required|numeric|min:0.0001',
+            'items.*.price'     => 'required|numeric|min:0',
+        ];
+    }
+}

app/Modules/Integration/Routes/api.php

@@ -3,10 +3,12 @@
 use Illuminate\Support\Facades\Route;
 use App\Modules\Integration\Controllers\ProductSyncController;
 use App\Modules\Integration\Controllers\OrderSyncController;
+use App\Modules\Integration\Controllers\VendingOrderSyncController;
 
 Route::prefix('api/v1/integration')
     ->middleware(['api', 'throttle:integration', 'integration.tenant', 'auth:sanctum'])
     ->group(function () {
         Route::post('products/upsert', [ProductSyncController::class, 'upsert']);
         Route::post('orders', [OrderSyncController::class, 'store']);
+        Route::post('vending/orders', [VendingOrderSyncController::class, 'store']);
     });

app/Modules/Integration/Routes/web.php

@@ -0,0 +1,11 @@
+<?php
+
+use App\Modules\Integration\Controllers\SalesOrderController;
+use Illuminate\Support\Facades\Route;
+
+Route::middleware(['web', 'auth', 'verified'])->group(function () {
+    Route::prefix('integration')->name('integration.')->group(function () {
+        Route::get('sales-orders', [SalesOrderController::class, 'index'])->name('sales-orders.index');
+        Route::get('sales-orders/{salesOrder}', [SalesOrderController::class, 'show'])->name('sales-orders.show');
+    });
+});

app/Modules/Inventory/Contracts/ProductServiceInterface.php

@@ -22,4 +22,20 @@ interface ProductServiceInterface
      * @return object|null
      */
     public function findByExternalPosId(string $externalPosId);
+
+    /**
+     * 透過多個外部 POS ID 查找產品。
+     *
+     * @param array $externalPosIds
+     * @return \Illuminate\Database\Eloquent\Collection
+     */
+    public function findByExternalPosIds(array $externalPosIds);
+
+    /**
+     * 透過多個 ERP 商品代碼查找產品（供販賣機 API 使用）。
+     *
+     * @param array $codes
+     * @return \Illuminate\Database\Eloquent\Collection
+     */
+    public function findByCodes(array $codes);
 }

app/Modules/Inventory/Services/InventoryService.php

@@ -599,12 +599,20 @@ class InventoryService implements InventoryServiceInterface
      */
     public function findOrCreateWarehouseByName(string $warehouseName)
     {
+        // 1. 優先查找名稱完全匹配的倉庫（不限類型）
+        $warehouse = Warehouse::where('name', $warehouseName)
+            ->first();
+
+        if ($warehouse) {
+            return $warehouse;
+        }
+
+        // 2. 若找不到對應倉庫，則統一進入「整合銷售倉」(類型：retail)
         return Warehouse::firstOrCreate(
-            ['name' => $warehouseName],
+            ['name' => '整合銷售倉'],
             [
-                'code' => 'SALES-' . strtoupper(bin2hex(random_bytes(4))),
-                'type' => 'system_sales',
-                'is_active' => true,
+                'code' => 'INT-RETAIL-001',
+                'type' => 'retail',
             ]
         );
     }

app/Modules/Inventory/Services/ProductService.php

@@ -88,4 +88,26 @@ class ProductService implements ProductServiceInterface
     {
         return Product::where('external_pos_id', $externalPosId)->first();
     }
+
+    /**
+     * 透過多個外部 POS ID 查找產品。
+     *
+     * @param array $externalPosIds
+     * @return \Illuminate\Database\Eloquent\Collection
+     */
+    public function findByExternalPosIds(array $externalPosIds)
+    {
+        return Product::whereIn('external_pos_id', $externalPosIds)->get();
+    }
+
+    /**
+     * 透過多個 ERP 商品代碼查找產品（供販賣機 API 使用）。
+     *
+     * @param array $codes
+     * @return \Illuminate\Database\Eloquent\Collection
+     */
+    public function findByCodes(array $codes)
+    {
+        return Product::whereIn('code', $codes)->get();
+    }
 }

bootstrap/app.php

@@ -24,6 +24,9 @@ return Application::configure(basePath: dirname(__DIR__))
         $middleware->web(prepend: [
             \App\Http\Middleware\UniversalTenancy::class,
         ]);
+        $middleware->api(prepend: [
+            \App\Http\Middleware\UniversalTenancy::class,
+        ]);
         $middleware->web(append: [
             \App\Http\Middleware\HandleInertiaRequests::class,
         ]);

compose.demo.yaml

@@ -0,0 +1,7 @@
+services:
+  proxy:
+    ports:
+      - '80:80'
+      - '8080:8080'
+    volumes:
+      - './nginx/demo-proxy.conf:/etc/nginx/conf.d/default.conf:ro'

compose.prod.yaml

@@ -0,0 +1,7 @@
+services:
+  proxy:
+    ports:
+      - '80:80'
+      - '8080:8080'
+    volumes:
+      - './nginx/prod-proxy.conf:/etc/nginx/conf.d/default.conf:ro'

compose.yaml

@@ -6,8 +6,8 @@ services:
             args:
                 WWWGROUP: '${WWWGROUP}'
         image: 'sail-8.5/app'
-        container_name: star-erp-laravel
-        hostname: star-erp-laravel
+        container_name: laravel
+        hostname: laravel
         extra_hosts:
             - 'host.docker.internal:host-gateway'
         ports:
@@ -29,8 +29,8 @@ services:
             # - mailpit
     mysql:
         image: 'mysql/mysql-server:8.0'
-        container_name: star-erp-mysql
-        hostname: star-erp-mysql
+        container_name: mysql
+        hostname: mysql
         ports:
             - '${FORWARD_DB_PORT:-3306}:3306'
         environment:
@@ -56,8 +56,8 @@ services:
             timeout: 5s
     redis:
         image: 'redis:alpine'
-        container_name: star-erp-redis
-        hostname: star-erp-redis
+        container_name: redis
+        hostname: redis
         # ports:
         #     - '${FORWARD_REDIS_PORT:-6379}:6379'
         volumes:
@@ -74,11 +74,6 @@ services:
     proxy:
         image: 'nginx:alpine'
         container_name: star-erp-proxy
-        ports:
-            - '8080:8080'
-            - '8081:8081'
-        volumes:
-            - './nginx/demo-proxy.conf:/etc/nginx/conf.d/default.conf:ro'
         networks:
             - sail
         depends_on:

database/migrations/2026_02_23_120000_create_notifications_table.php

@@ -0,0 +1,31 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('notifications', function (Blueprint $table) {
+            $table->uuid('id')->primary();
+            $table->string('type');
+            $table->morphs('notifiable');
+            $table->text('data');
+            $table->timestamp('read_at')->nullable();
+            $table->timestamps();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('notifications');
+    }
+};

database/migrations/tenant/2026_02_23_114909_add_source_to_sales_orders.php

@@ -0,0 +1,31 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * 為 sales_orders 新增來源標記欄位，支援多來源 API 寫入
+     */
+    public function up(): void
+    {
+        Schema::table('sales_orders', function (Blueprint $table) {
+            $table->string('source')->default('pos')->after('raw_payload');
+            $table->string('source_label')->nullable()->after('source');
+            $table->index('source');
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('sales_orders', function (Blueprint $table) {
+            $table->dropIndex(['source']);
+            $table->dropColumn(['source', 'source_label']);
+        });
+    }
+};

database/seeders/PermissionSeeder.php

@@ -139,6 +139,9 @@ class PermissionSeeder extends Seeder
             'store_requisitions.delete' => '刪除',
             'store_requisitions.approve' => '核準',
             'store_requisitions.cancel' => '取消',
+
+            // 銷售訂單管理 (API)
+            'sales_orders.view' => '檢視',
         ];
 
         foreach ($permissions as $name => $displayName) {
@@ -222,6 +225,7 @@ class PermissionSeeder extends Seeder
             'utility_fees.view',
             'inventory_report.view',
             'accounting.view',
+            'sales_orders.view',
         ]);
 
         // 將現有使用者設為 super-admin（如果存在的話）

docker/8.5/Dockerfile

@@ -11,7 +11,7 @@ WORKDIR /var/www/html
 
 ENV DEBIAN_FRONTEND=noninteractive
 ENV TZ=UTC
-ENV SUPERVISOR_PHP_COMMAND="/usr/bin/php -d variables_order=EGPCS /var/www/html/artisan serve --host=0.0.0.0 --port=80"
+ENV SUPERVISOR_PHP_COMMAND="/usr/bin/php -d variables_order=EGPCS /var/www/html/artisan serve --host=0.0.0.0 --port=8080"
 ENV SUPERVISOR_PHP_USER="sail"
 ENV PLAYWRIGHT_BROWSERS_PATH=0
 
@@ -28,32 +28,32 @@ RUN apt-get update && apt-get upgrade -y \
     && echo "deb [signed-by=/etc/apt/keyrings/ppa_ondrej_php.gpg] https://ppa.launchpadcontent.net/ondrej/php/ubuntu noble main" > /etc/apt/sources.list.d/ppa_ondrej_php.list \
     && apt-get update \
     && apt-get install -y \
-        libgd3 \
-        php8.5-cli \
-        php8.5-dev \
-        php8.5-pgsql \
-        php8.5-sqlite3 \
-        php8.5-gd \
-        php8.5-curl \
-        php8.5-mongodb \
-        php8.5-imap \
-        php8.5-mysql \
-        php8.5-mbstring \
-        php8.5-xml \
-        php8.5-zip \
-        php8.5-bcmath \
-        php8.5-soap \
-        php8.5-intl \
-        php8.5-readline \
-        php8.5-ldap \
-        php8.5-msgpack \
-        php8.5-igbinary \
-        php8.5-redis \
-        #php8.5-swoole \
-        php8.5-memcached \
-        php8.5-pcov \
-        php8.5-imagick \
-        php8.5-xdebug \
+    libgd3 \
+    php8.5-cli \
+    php8.5-dev \
+    php8.5-pgsql \
+    php8.5-sqlite3 \
+    php8.5-gd \
+    php8.5-curl \
+    php8.5-mongodb \
+    php8.5-imap \
+    php8.5-mysql \
+    php8.5-mbstring \
+    php8.5-xml \
+    php8.5-zip \
+    php8.5-bcmath \
+    php8.5-soap \
+    php8.5-intl \
+    php8.5-readline \
+    php8.5-ldap \
+    php8.5-msgpack \
+    php8.5-igbinary \
+    php8.5-redis \
+    #php8.5-swoole \
+    php8.5-memcached \
+    php8.5-pcov \
+    php8.5-imagick \
+    php8.5-xdebug \
     && curl -sLS https://getcomposer.org/installer | php -- --install-dir=/usr/bin/ --filename=composer \
     && curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg \
     && echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_VERSION.x nodistro main" > /etc/apt/sources.list.d/nodesource.list \
@@ -75,8 +75,6 @@ RUN apt-get update && apt-get upgrade -y \
     && apt-get clean \
     && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
 
-RUN setcap "cap_net_bind_service=+ep" /usr/bin/php8.5
-
 RUN userdel -r ubuntu
 RUN groupadd --force -g $WWWGROUP sail
 RUN useradd -ms /bin/bash --no-user-group -g $WWWGROUP -u 1337 sail
@@ -87,6 +85,6 @@ COPY supervisord.conf /etc/supervisor/conf.d/supervisord.conf
 COPY php.ini /etc/php/8.5/cli/conf.d/99-sail.ini
 RUN chmod +x /usr/local/bin/start-container
 
-EXPOSE 80/tcp
+EXPOSE 8080/tcp
 
 ENTRYPOINT ["start-container"]

docker/8.5/supervisord.conf

@@ -13,15 +13,3 @@ stdout_logfile_maxbytes=0
 stderr_logfile=/dev/stderr
 stderr_logfile_maxbytes=0
 
-[program:npm]
-command=/usr/bin/npm run dev
-user=%(ENV_SUPERVISOR_PHP_USER)s
-environment=LARAVEL_SAIL="1"
-stdout_logfile=/dev/stdout
-stdout_logfile_maxbytes=0
-stderr_logfile=/dev/stderr
-stderr_logfile_maxbytes=0
-autostart=true
-autorestart=true
-stopasgroup=true
-killasgroup=true

nginx/demo-proxy.conf

@@ -1,29 +1,22 @@
-# 總後台 (landlord) - 端口 8080
-server {
-    listen 8080;
-    server_name 192.168.0.103;
+# Demo 環境 (Demo) - 端口 80
+# 外部 SSL 終止後（如 Cloudflare/NPM）轉發至此端口
 
-    location / {
-        proxy_pass http://star-erp-laravel:80;
-        proxy_set_header Host star-erp.demo;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-        proxy_set_header X-Forwarded-Host $host:$server_port;
-    }
+# 定義 map 以正確處理 X-Forwarded-Proto
+map $http_x_forwarded_proto $proxy_x_forwarded_proto {
+    default $http_x_forwarded_proto;
+    ''      $scheme;
 }
 
-# koori 租戶 - 端口 8081
 server {
-    listen 8081;
-    server_name 192.168.0.103;
+    listen 80;
+    server_name demo-erp.taiwan-star.com.tw;
 
     location / {
-        proxy_pass http://star-erp-laravel:80;
+        proxy_pass http://star-erp-laravel:8080;
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-        proxy_set_header X-Forwarded-Host $host:$server_port;
+        proxy_set_header X-Forwarded-Proto $proxy_x_forwarded_proto;
+        proxy_set_header X-Forwarded-Host $host;
     }
 }

nginx/prod-proxy.conf

@@ -12,7 +12,7 @@ server {
     server_name erp.koori.tw erp.mamaiclub.com;
 
     location / {
-        proxy_pass http://star-erp-laravel:80;
+        proxy_pass http://star-erp-laravel:8080;
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

resources/js/Layouts/AuthenticatedLayout.tsx

@@ -190,6 +190,13 @@ export default function AuthenticatedLayout({
                     route: "/sales/imports",
                     permission: "sales_imports.view",
                 },
+                {
+                    id: "sales-order-list",
+                    label: "銷售訂單管理",
+                    icon: <ShoppingCart className="h-4 w-4" />,
+                    route: "/integration/sales-orders",
+                    permission: "sales_orders.view",
+                },
             ],
         },
         {

resources/js/Pages/Integration/SalesOrders/Index.tsx

@@ -0,0 +1,292 @@
+import { useState } from "react";
+import { Head, Link, router } from "@inertiajs/react";
+import AuthenticatedLayout from "@/Layouts/AuthenticatedLayout";
+import {
+    Search,
+    TrendingUp,
+    Eye,
+} from "lucide-react";
+import {
+    Table,
+    TableBody,
+    TableCell,
+    TableHead,
+    TableHeader,
+    TableRow,
+} from "@/Components/ui/table";
+import { StatusBadge, StatusVariant } from "@/Components/shared/StatusBadge";
+import { Button } from "@/Components/ui/button";
+import { Input } from "@/Components/ui/input";
+import { SearchableSelect } from "@/Components/ui/searchable-select";
+import Pagination from "@/Components/shared/Pagination";
+import { formatDate } from "@/lib/date";
+import { formatNumber } from "@/utils/format";
+import { Can } from "@/Components/Permission/Can";
+
+interface SalesOrder {
+    id: number;
+    external_order_id: string;
+    status: string;
+    payment_method: string;
+    total_amount: string;
+    sold_at: string;
+    created_at: string;
+    source: string;
+    source_label: string | null;
+}
+
+interface PaginationLink {
+    url: string | null;
+    label: string;
+    active: boolean;
+}
+
+interface Props {
+    orders: {
+        data: SalesOrder[];
+        total: number;
+        per_page: number;
+        current_page: number;
+        last_page: number;
+        links: PaginationLink[];
+    };
+    filters: {
+        search?: string;
+        per_page?: string;
+        source?: string;
+    };
+}
+
+// 來源篩選選項
+const sourceOptions = [
+    { label: "全部來源", value: "" },
+    { label: "POS 收銀機", value: "pos" },
+    { label: "販賣機", value: "vending" },
+    { label: "手動匯入", value: "manual_import" },
+];
+
+const getSourceLabel = (source: string): string => {
+    switch (source) {
+        case 'pos': return 'POS';
+        case 'vending': return '販賣機';
+        case 'manual_import': return '手動匯入';
+        default: return source;
+    }
+};
+
+const getSourceVariant = (source: string): StatusVariant => {
+    switch (source) {
+        case 'pos': return 'info';
+        case 'vending': return 'warning';
+        case 'manual_import': return 'neutral';
+        default: return 'neutral';
+    }
+};
+
+const getStatusVariant = (status: string): StatusVariant => {
+    switch (status) {
+        case 'completed': return 'success';
+        case 'pending': return 'warning';
+        case 'cancelled': return 'destructive';
+        default: return 'neutral';
+    }
+};
+
+const getStatusLabel = (status: string): string => {
+    switch (status) {
+        case 'completed': return "已完成";
+        case 'pending': return "待處理";
+        case 'cancelled': return "已取消";
+        default: return status;
+    }
+};
+
+export default function SalesOrderIndex({ orders, filters }: Props) {
+    const [search, setSearch] = useState(filters.search || "");
+    const [perPage, setPerPage] = useState<string>(filters.per_page || "10");
+
+    const handleSearch = () => {
+        router.get(
+            route("integration.sales-orders.index"),
+            { ...filters, search, page: 1 },
+            { preserveState: true, replace: true }
+        );
+    };
+
+    const handlePerPageChange = (value: string) => {
+        setPerPage(value);
+        router.get(
+            route("integration.sales-orders.index"),
+            { ...filters, per_page: value, page: 1 },
+            { preserveState: false, replace: true }
+        );
+    };
+
+    const startIndex = (orders.current_page - 1) * orders.per_page + 1;
+
+    return (
+        <AuthenticatedLayout
+            breadcrumbs={[
+                { label: "銷售管理", href: "#" },
+                {
+                    label: "銷售訂單管理",
+                    href: route("integration.sales-orders.index"),
+                    isPage: true,
+                },
+            ]}
+        >
+            <Head title="銷售訂單管理" />
+
+            <div className="container mx-auto p-6 max-w-7xl">
+                <div className="flex items-center justify-between mb-6">
+                    <div>
+                        <h1 className="text-2xl font-bold text-grey-0 flex items-center gap-2">
+                            <TrendingUp className="h-6 w-6 text-primary-main" />
+                            銷售訂單管理
+                        </h1>
+                        <p className="text-gray-500 mt-1">
+                            檢視從 POS 或販賣機同步進來的銷售訂單紀錄
+                        </p>
+                    </div>
+                </div>
+
+                {/* 篩選列 */}
+                <div className="bg-white rounded-xl border border-gray-200 p-4 mb-4">
+                    <div className="flex flex-wrap items-center gap-3">
+                        <SearchableSelect
+                            value={filters.source || ""}
+                            onValueChange={(v) =>
+                                router.get(
+                                    route("integration.sales-orders.index"),
+                                    { ...filters, source: v || undefined, page: 1 },
+                                    { preserveState: true, replace: true }
+                                )
+                            }
+                            options={sourceOptions}
+                            className="w-[160px] h-9"
+                            showSearch={false}
+                            placeholder="篩選來源"
+                        />
+                        <div className="flex items-center gap-2 flex-1 min-w-[300px]">
+                            <Input
+                                type="text"
+                                value={search}
+                                onChange={(e) => setSearch(e.target.value)}
+                                onKeyDown={(e) => e.key === "Enter" && handleSearch()}
+                                placeholder="搜尋外部訂單號 (External Order ID)..."
+                                className="h-9"
+                            />
+                            <Button
+                                variant="outline"
+                                size="sm"
+                                className="button-outlined-primary h-9"
+                                onClick={handleSearch}
+                            >
+                                <Search className="h-4 w-4" />
+                            </Button>
+                        </div>
+                    </div>
+                </div>
+
+                {/* 表格 */}
+                <div className="bg-white rounded-xl border border-gray-200 shadow-sm overflow-hidden">
+                    <Table>
+                        <TableHeader className="bg-gray-50">
+                            <TableRow>
+                                <TableHead className="w-[50px] text-center">#</TableHead>
+                                <TableHead>外部訂單號</TableHead>
+                                <TableHead className="text-center">來源</TableHead>
+                                <TableHead className="text-center">狀態</TableHead>
+                                <TableHead>付款方式</TableHead>
+                                <TableHead className="text-right">總金額</TableHead>
+                                <TableHead>銷售時間</TableHead>
+                                <TableHead className="text-center">操作</TableHead>
+                            </TableRow>
+                        </TableHeader>
+                        <TableBody>
+                            {orders.data.length === 0 ? (
+                                <TableRow>
+                                    <TableCell colSpan={8} className="text-center py-8 text-gray-500">
+                                        無符合條件的資料
+                                    </TableCell>
+                                </TableRow>
+                            ) : (
+                                orders.data.map((order, index) => (
+                                    <TableRow key={order.id}>
+                                        <TableCell className="text-gray-500 font-medium text-center">
+                                            {startIndex + index}
+                                        </TableCell>
+                                        <TableCell className="font-mono text-sm">
+                                            {order.external_order_id}
+                                        </TableCell>
+                                        <TableCell className="text-center">
+                                            <StatusBadge variant={getSourceVariant(order.source)}>
+                                                {order.source_label || getSourceLabel(order.source)}
+                                            </StatusBadge>
+                                        </TableCell>
+                                        <TableCell className="text-center">
+                                            <StatusBadge variant={getStatusVariant(order.status)}>
+                                                {getStatusLabel(order.status)}
+                                            </StatusBadge>
+                                        </TableCell>
+                                        <TableCell className="text-gray-600">
+                                            {order.payment_method || "—"}
+                                        </TableCell>
+                                        <TableCell className="text-right font-medium">
+                                            ${formatNumber(parseFloat(order.total_amount))}
+                                        </TableCell>
+                                        <TableCell className="text-gray-500 text-sm">
+                                            {formatDate(order.sold_at)}
+                                        </TableCell>
+                                        <TableCell className="text-center">
+                                            <div className="flex items-center justify-center gap-2">
+                                                <Can permission="sales_orders.view">
+                                                    <Link href={route("integration.sales-orders.show", order.id)}>
+                                                        <Button
+                                                            variant="outline"
+                                                            size="sm"
+                                                            className="button-outlined-primary"
+                                                            title="檢視明細"
+                                                        >
+                                                            <Eye className="h-4 w-4" />
+                                                        </Button>
+                                                    </Link>
+                                                </Can>
+                                            </div>
+                                        </TableCell>
+                                    </TableRow>
+                                ))
+                            )}
+                        </TableBody>
+                    </Table>
+                </div>
+
+                {/* 分頁 */}
+                <div className="mt-4 flex flex-col sm:flex-row items-center justify-between gap-4">
+                    <div className="flex items-center gap-4">
+                        <div className="flex items-center gap-2 text-sm text-gray-500">
+                            <span>每頁顯示</span>
+                            <SearchableSelect
+                                value={perPage}
+                                onValueChange={handlePerPageChange}
+                                options={[
+                                    { label: "10", value: "10" },
+                                    { label: "20", value: "20" },
+                                    { label: "50", value: "50" },
+                                    { label: "100", value: "100" },
+                                ]}
+                                className="w-[90px] h-8"
+                                showSearch={false}
+                            />
+                            <span>筆</span>
+                        </div>
+                        <span className="text-sm text-gray-500">
+                            共 {orders.total} 筆紀錄
+                        </span>
+                    </div>
+                    <Pagination links={orders.links} />
+                </div>
+            </div>
+        </AuthenticatedLayout>
+    );
+}

resources/js/Pages/Integration/SalesOrders/Show.tsx

@@ -0,0 +1,215 @@
+import { ArrowLeft, TrendingUp, Package, CreditCard, Calendar, FileJson } from "lucide-react";
+import { Button } from "@/Components/ui/button";
+import AuthenticatedLayout from "@/Layouts/AuthenticatedLayout";
+import { Head, Link } from "@inertiajs/react";
+import {
+    Table,
+    TableBody,
+    TableCell,
+    TableHead,
+    TableHeader,
+    TableRow,
+} from "@/Components/ui/table";
+import { StatusBadge, StatusVariant } from "@/Components/shared/StatusBadge";
+import { formatDate } from "@/lib/date";
+import { formatNumber } from "@/utils/format";
+import CopyButton from "@/Components/shared/CopyButton";
+
+interface SalesOrderItem {
+    id: number;
+    product_name: string;
+    quantity: string;
+    price: string;
+    total: string;
+}
+
+interface SalesOrder {
+    id: number;
+    external_order_id: string;
+    status: string;
+    payment_method: string;
+    total_amount: string;
+    sold_at: string;
+    created_at: string;
+    raw_payload: any;
+    items: SalesOrderItem[];
+    source: string;
+    source_label: string | null;
+}
+
+const getSourceDisplay = (source: string, sourceLabel: string | null): string => {
+    const base = source === 'pos' ? 'POS 收銀機'
+        : source === 'vending' ? '販賣機'
+            : source === 'manual_import' ? '手動匯入'
+                : source;
+    return sourceLabel ? `${base} (${sourceLabel})` : base;
+};
+
+interface Props {
+    order: SalesOrder;
+}
+
+const getStatusVariant = (status: string): StatusVariant => {
+    switch (status) {
+        case 'completed': return 'success';
+        case 'pending': return 'warning';
+        case 'cancelled': return 'destructive';
+        default: return 'neutral';
+    }
+};
+
+const getStatusLabel = (status: string): string => {
+    switch (status) {
+        case 'completed': return "已完成";
+        case 'pending': return "待處理";
+        case 'cancelled': return "已取消";
+        default: return status;
+    }
+};
+
+export default function SalesOrderShow({ order }: Props) {
+    return (
+        <AuthenticatedLayout
+            breadcrumbs={[
+                { label: "銷售管理", href: "#" },
+                { label: "銷售訂單管理", href: route("integration.sales-orders.index") },
+                { label: `訂單詳情 (#${order.external_order_id})`, href: "#", isPage: true },
+            ]}
+        >
+            <Head title={`銷售訂單詳情 - ${order.external_order_id}`} />
+
+            <div className="container mx-auto p-6 max-w-7xl">
+                {/* Header */}
+                <div className="mb-6">
+                    <Link href={route("integration.sales-orders.index")}>
+                        <Button
+                            variant="outline"
+                            className="gap-2 button-outlined-primary mb-6"
+                        >
+                            <ArrowLeft className="h-4 w-4" />
+                            返回銷售訂單列表
+                        </Button>
+                    </Link>
+
+                    <div className="flex items-center justify-between mb-6">
+                        <div>
+                            <h1 className="text-2xl font-bold text-grey-0 flex items-center gap-2">
+                                <TrendingUp className="h-6 w-6 text-primary-main" />
+                                查看銷售訂單
+                            </h1>
+                            <p className="text-gray-500 mt-1">外部單號：{order.external_order_id}</p>
+                        </div>
+                        <StatusBadge variant={getStatusVariant(order.status)}>
+                            {getStatusLabel(order.status)}
+                        </StatusBadge>
+                    </div>
+                </div>
+
+                <div className="grid grid-cols-1 lg:grid-cols-3 gap-6">
+                    {/* 左側：基本資訊與明細 */}
+                    <div className="lg:col-span-2 space-y-6">
+                        {/* 基本資訊卡片 */}
+                        <div className="bg-white rounded-xl border border-gray-200 shadow-sm p-6">
+                            <h2 className="text-lg font-bold text-gray-900 mb-6 flex items-center gap-2">
+                                <Package className="h-5 w-5 text-primary-main" />
+                                基本資訊
+                            </h2>
+                            <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
+                                <div>
+                                    <span className="text-sm text-gray-500 block mb-1">外部訂單編號</span>
+                                    <div className="flex items-center gap-1.5">
+                                        <span className="font-mono font-medium text-gray-900">{order.external_order_id}</span>
+                                        <CopyButton text={order.external_order_id} label="複製單號" />
+                                    </div>
+                                </div>
+                                <div>
+                                    <span className="text-sm text-gray-500 block mb-1">銷售時間</span>
+                                    <div className="flex items-center gap-1.5 font-medium text-gray-900">
+                                        <Calendar className="h-4 w-4 text-gray-400" />
+                                        {formatDate(order.sold_at)}
+                                    </div>
+                                </div>
+                                <div>
+                                    <span className="text-sm text-gray-500 block mb-1">付款方式</span>
+                                    <div className="flex items-center gap-1.5 font-medium text-gray-900">
+                                        <CreditCard className="h-4 w-4 text-gray-400" />
+                                        {order.payment_method || "—"}
+                                    </div>
+                                </div>
+                                <div>
+                                    <span className="text-sm text-gray-500 block mb-1">同步時間</span>
+                                    <span className="font-medium text-gray-900">{formatDate(order.created_at as any)}</span>
+                                </div>
+                                <div>
+                                    <span className="text-sm text-gray-500 block mb-1">訂單來源</span>
+                                    <span className="font-medium text-gray-900">{getSourceDisplay(order.source, order.source_label)}</span>
+                                </div>
+                            </div>
+                        </div>
+
+                        {/* 項目清單卡片 */}
+                        <div className="bg-white rounded-xl border border-gray-200 shadow-sm overflow-hidden">
+                            <div className="p-6 border-b border-gray-100">
+                                <h2 className="text-lg font-bold text-gray-900 mb-0">銷售項目清單</h2>
+                            </div>
+                            <div className="p-6">
+                                <div className="border rounded-lg overflow-hidden">
+                                    <Table>
+                                        <TableHeader>
+                                            <TableRow className="bg-gray-50 hover:bg-gray-50">
+                                                <TableHead className="w-[50px] text-center">#</TableHead>
+                                                <TableHead>商品名稱</TableHead>
+                                                <TableHead className="text-right">數量</TableHead>
+                                                <TableHead className="text-right">單價</TableHead>
+                                                <TableHead className="text-right">小計</TableHead>
+                                            </TableRow>
+                                        </TableHeader>
+                                        <TableBody>
+                                            {order.items.map((item, index) => (
+                                                <TableRow key={item.id}>
+                                                    <TableCell className="text-gray-500 text-center">{index + 1}</TableCell>
+                                                    <TableCell className="font-medium">{item.product_name}</TableCell>
+                                                    <TableCell className="text-right font-medium">{formatNumber(parseFloat(item.quantity))}</TableCell>
+                                                    <TableCell className="text-right text-gray-600">${formatNumber(parseFloat(item.price))}</TableCell>
+                                                    <TableCell className="text-right font-bold text-primary-main">${formatNumber(parseFloat(item.total))}</TableCell>
+                                                </TableRow>
+                                            ))}
+                                        </TableBody>
+                                    </Table>
+                                </div>
+                                <div className="mt-6 flex justify-end">
+                                    <div className="w-full max-w-sm bg-primary-lightest/30 px-6 py-4 rounded-xl border border-primary-light/20 flex flex-col gap-3">
+                                        <div className="flex justify-between items-end w-full">
+                                            <span className="text-sm text-gray-500 font-medium mb-1">訂單總金額</span>
+                                            <span className="text-2xl font-black text-primary-main">
+                                                ${formatNumber(parseFloat(order.total_amount))}
+                                            </span>
+                                        </div>
+                                    </div>
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+
+                    {/* 右側：原始資料 (Raw Payload) */}
+                    <div className="space-y-6">
+                        <div className="bg-white rounded-xl border border-gray-200 shadow-sm p-6">
+                            <h2 className="text-lg font-bold text-gray-900 mb-4 flex items-center gap-2">
+                                <FileJson className="h-5 w-5 text-primary-main" />
+                                API 原始資料
+                            </h2>
+                            <p className="text-sm text-gray-500 mb-4">
+                                此區塊顯示同步時接收到的完整原始 JSON 內容，可用於排查資料問題。
+                            </p>
+                            <div className="bg-slate-900 rounded-lg p-4 overflow-auto max-h-[600px]">
+                                <pre className="text-xs text-slate-300 font-mono">
+                                    {JSON.stringify(order.raw_payload, null, 2)}
+                                </pre>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </AuthenticatedLayout>
+    );
+}

resources/markdown/manual/api-integration.md

@@ -140,6 +140,37 @@ Star ERP 系統提供外部整合 API (Integration API) 供電商前台、POS
 }
 ```
 
+#### 錯誤回應 (HTTP 422 Unprocessable Entity - 驗證失敗)
+
+當傳入資料格式有誤、商品編號不存在，或是該訂單正在處理中被系統鎖定時返回。
+
+- **`message`** (字串): 錯誤摘要。
+- **`errors`** (物件): 具體的錯誤明細列表，能一次性回報多個商品不存在或其它欄位錯誤。
+
+```json
+{
+  "message": "Validation failed",
+  "errors": {
+    "items": [
+      "The following products are not found: POS-999, POS-888. Please sync products first."
+    ],
+    "external_order_id": [
+      "The order ORD-01 is currently being processed by another transaction. Please try again later."
+    ]
+  }
+}
+```
+
+#### 錯誤回應 (HTTP 500 Internal Server Error - 伺服器異常)
+
+當系統發生預期外的錯誤（如資料庫連線失敗）時返回。
+
+```json
+{
+  "message": "Sync failed: An unexpected error occurred."
+}
+```
+
 ---
 
 ## 幂等性說明 (Idempotency)

tests/Feature/Integration/ProductSyncTest.php

@@ -0,0 +1,151 @@
+<?php
+
+namespace Tests\Feature\Integration;
+
+use Tests\TestCase;
+use App\Modules\Core\Models\Tenant;
+use App\Modules\Core\Models\User;
+use App\Modules\Inventory\Models\Product;
+use App\Modules\Inventory\Models\Category;
+use Stancl\Tenancy\Facades\Tenancy;
+use Illuminate\Support\Str;
+
+class ProductSyncTest extends TestCase
+{
+    protected $tenant;
+    protected $user;
+    protected $domain;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        
+        // 每次測試前重置資料庫（在測試環境）
+        \Artisan::call('migrate:fresh');
+        
+        $this->domain = 'product-test-' . Str::random(8) . '.erp.local';
+        $tenantId = 'test_tenant_p_' . Str::random(8);
+
+        // 建立租戶
+        tenancy()->central(function () use ($tenantId) {
+            $this->tenant = Tenant::create([
+                'id' => $tenantId,
+                'name' => 'Product Test Tenant',
+            ]);
+            $this->tenant->domains()->create(['domain' => $this->domain]);
+        });
+
+        // 初始化租戶並遷移
+        tenancy()->initialize($this->tenant);
+        \Artisan::call('tenants:migrate');
+
+        // 建立測試使用者與分類
+        $this->user = User::factory()->create(['name' => 'Test Admin']);
+        Category::create(['name' => '測試分類', 'code' => 'TEST-CAT']);
+        
+        tenancy()->end();
+    }
+
+    protected function tearDown(): void
+    {
+        if ($this->tenant) {
+            $this->tenant->delete();
+        }
+        parent::tearDown();
+    }
+
+    /**
+     * 測試產品同步新增功能
+     */
+    public function test_product_sync_can_create_new_product()
+    {
+        \Laravel\Sanctum\Sanctum::actingAs($this->user, ['*']);
+
+        $payload = [
+            'external_pos_id' => 'POS-NEW-999',
+            'name' => '全新同步商品',
+            'price' => 299,
+            'barcode' => '1234567890123',
+            'category' => '測試分類',
+            'cost_price' => 150
+        ];
+
+        $response = $this->withHeaders([
+            'X-Tenant-Domain' => $this->domain,
+            'Accept' => 'application/json',
+        ])->postJson('/api/v1/integration/products/upsert', $payload);
+
+        $response->assertStatus(200)
+                 ->assertJsonPath('message', 'Product synced successfully');
+
+        // 驗證租戶資料庫
+        tenancy()->initialize($this->tenant);
+        $this->assertDatabaseHas('products', [
+            'external_pos_id' => 'POS-NEW-999',
+            'name' => '全新同步商品',
+            'price' => 299,
+        ]);
+        tenancy()->end();
+    }
+
+    /**
+     * 測試產品同步更新功能 (Upsert)
+     */
+    public function test_product_sync_can_update_existing_product()
+    {
+        // 先建立一個既有商品
+        tenancy()->initialize($this->tenant);
+        Product::create([
+            'name' => '舊商品名稱',
+            'code' => 'OLD-CODE',
+            'external_pos_id' => 'POS-EXIST-001',
+            'price' => 100,
+            'category_id' => Category::first()->id,
+        ]);
+        tenancy()->end();
+
+        \Laravel\Sanctum\Sanctum::actingAs($this->user, ['*']);
+
+        $payload = [
+            'external_pos_id' => 'POS-EXIST-001',
+            'name' => '更新後的商品名稱',
+            'price' => 888,
+        ];
+
+        $response = $this->withHeaders([
+            'X-Tenant-Domain' => $this->domain,
+            'Accept' => 'application/json',
+        ])->postJson('/api/v1/integration/products/upsert', $payload);
+
+        $response->assertStatus(200);
+
+        tenancy()->initialize($this->tenant);
+        $this->assertDatabaseHas('products', [
+            'external_pos_id' => 'POS-EXIST-001',
+            'name' => '更新後的商品名稱',
+            'price' => 888,
+        ]);
+        tenancy()->end();
+    }
+
+    /**
+     * 測試產品同步驗證失敗
+     */
+    public function test_product_sync_validation_fails_without_required_fields()
+    {
+        \Laravel\Sanctum\Sanctum::actingAs($this->user, ['*']);
+
+        $payload = [
+            'external_pos_id' => '', // 缺少此欄位
+            'name' => '',           // 缺少此欄位
+        ];
+
+        $response = $this->withHeaders([
+            'X-Tenant-Domain' => $this->domain,
+            'Accept' => 'application/json',
+        ])->postJson('/api/v1/integration/products/upsert', $payload);
+
+        $response->assertStatus(422)
+                 ->assertJsonValidationErrors(['external_pos_id', 'name']);
+    }
+}

tests/manual/test_integration_api.sh

@@ -0,0 +1,83 @@
+#!/bin/bash
+
+# Star ERP 整合 API 手動測試腳本
+# 用途：手動驗證商品同步、POS 訂單、販賣機訂單 API
+
+# --- 設定區 ---
+BASE_URL=${1:-"http://localhost:8081"}
+TOKEN=${2:-"YOUR_TOKEN_HERE"}
+TENANT_DOMAIN="localhost"
+
+echo "=== Star ERP Integration API Test ==="
+echo "Target URL: $BASE_URL"
+echo "Tenant Domain: $TENANT_DOMAIN"
+echo ""
+
+# 顏色定義
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+NC='\033[0m'
+
+# 輔助函式：執行 curl
+function call_api() {
+    local method=$1
+    local path=$2
+    local data=$3
+    local title=$4
+
+    echo -e "Testing: ${GREEN}$title${NC} ($path)"
+    
+    curl -s -X "$method" "$BASE_URL$path" \
+        -H "X-Tenant-Domain: $TENANT_DOMAIN" \
+        -H "Authorization: Bearer $TOKEN" \
+        -H "Accept: application/json" \
+        -H "Content-Type: application/json" \
+        -d "$data" | jq .
+
+    echo -e "-----------------------------------\n"
+}
+
+# 1. 商品同步 (Upsert)
+PRODUCT_ID="TEST-AUTO-$(date +%s)"
+call_api "POST" "/api/v1/integration/products/upsert" "{
+    \"external_pos_id\": \"$PRODUCT_ID\",
+    \"name\": \"自動測試商品 $(date +%H%M%S)\",
+    \"price\": 150,
+    \"barcode\": \"690123456789\",
+    \"category\": \"飲品\",
+    \"cost_price\": 80
+}" "Product Upsert"
+
+# 2. POS 訂單同步
+call_api "POST" "/api/v1/integration/orders" "{
+    \"external_order_id\": \"POS-AUTO-$(date +%s)\",
+    \"status\": \"completed\",
+    \"payment_method\": \"cash\",
+    \"sold_at\": \"$(date -Iseconds)\",
+    \"warehouse_id\": 2,
+    \"items\": [
+        {
+            \"pos_product_id\": \"TEST-FINAL-VERIFY\",
+            \"qty\": 1,
+            \"price\": 100
+        }
+    ]
+}" "POS Order Sync"
+
+# 3. 販賣機訂單同步
+call_api "POST" "/api/v1/integration/vending/orders" "{
+    \"external_order_id\": \"VEND-AUTO-$(date +%s)\",
+    \"machine_id\": \"Vending-Machine-Test-01\",
+    \"payment_method\": \"line_pay\",
+    \"sold_at\": \"$(date -Iseconds)\",
+    \"warehouse_id\": 2,
+    \"items\": [
+        {
+            \"product_code\": \"FINAL-OK\",
+            \"qty\": 2,
+            \"price\": 50
+        }
+    ]
+}" "Vending Machine Order Sync"
+
+echo "Test Completed."