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

app/Modules/Integration/Controllers/OrderSyncController.php

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

app/Modules/Integration/Controllers/ProductSyncController.php

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

app/Modules/Integration/IntegrationServiceProvider.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace App\Modules\Integration;
+
+use Illuminate\Support\ServiceProvider;
+use Illuminate\Support\Facades\Route;
+use App\Modules\Integration\Middleware\TenantIdentificationMiddleware;
+
+class IntegrationServiceProvider extends ServiceProvider
+{
+    public function boot()
+    {
+        $this->loadRoutesFrom(__DIR__ . '/Routes/api.php');
+        $this->loadMigrationsFrom(__DIR__ . '/Database/Migrations');
+
+        // Register Middleware Alias
+        Route::aliasMiddleware('integration.tenant', TenantIdentificationMiddleware::class);
+    }
+
+    public function register()
+    {
+        //
+    }
+}

app/Modules/Integration/Middleware/TenantIdentificationMiddleware.php

@@ -0,0 +1,58 @@
+<?php
+
+namespace App\Modules\Integration\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+use Stancl\Tenancy\Facades\Tenancy;
+use Symfony\Component\HttpFoundation\Response;
+
+class TenantIdentificationMiddleware
+{
+    /**
+     * Handle an incoming request.
+     *
+     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
+     */
+    public function handle(Request $request, Closure $next): Response
+    {
+        // 1. Check for X-Tenant-Domain header
+        $domain = $request->header('X-Tenant-Domain');
+
+        if (! $domain) {
+            return response()->json([
+                'message' => 'Missing X-Tenant-Domain header.',
+            ], 400);
+        }
+
+        // 2. Find Tenant by domain
+        // Assuming domains are stored in 'domains' table and linked to tenants
+        // Or using Stancl's tenant finder. 
+        // Stancl Tenancy usually finds by domain automatically for web routes, but for API 
+        // we are doing manual identification because we might not be using subdomains for API calls (or maybe we are).
+        // If the API endpoint is centrally hosted (e.g. api.star-erp.com/v1/...), we need this header.
+        
+        // Let's try to initialize tenancy manually.
+        // We need to find the tenant model that has this domain.
+        try {
+             $tenant = \App\Modules\Core\Models\Tenant::whereHas('domains', function ($query) use ($domain) {
+                 $query->where('domain', $domain);
+             })->first();
+
+             if (! $tenant) {
+                 return response()->json([
+                     'message' => 'Tenant not found.',
+                 ], 404);
+             }
+
+             Tenancy::initialize($tenant);
+
+        } catch (\Exception $e) {
+            return response()->json([
+                'message' => 'Tenant initialization failed: ' . $e->getMessage(),
+            ], 500);
+        }
+
+        return $next($request);
+    }
+}

app/Modules/Integration/Models/SalesOrder.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace App\Modules\Integration\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+
+class SalesOrder extends Model
+{
+    protected $table = 'sales_orders';
+
+    protected $fillable = [
+        'external_order_id',
+        'status',
+        'payment_method',
+        'total_amount',
+        'sold_at',
+        'raw_payload',
+    ];
+
+    protected $casts = [
+        'sold_at' => 'datetime',
+        'raw_payload' => 'array',
+        'total_amount' => 'decimal:4',
+    ];
+
+    public function items(): HasMany
+    {
+        return $this->hasMany(SalesOrderItem::class);
+    }
+}

app/Modules/Integration/Models/SalesOrderItem.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace App\Modules\Integration\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+class SalesOrderItem extends Model
+{
+    protected $table = 'sales_order_items';
+
+    protected $fillable = [
+        'sales_order_id',
+        'product_id',
+        'product_name',
+        'quantity',
+        'price',
+        'total',
+    ];
+
+    protected $casts = [
+        'quantity' => 'decimal:4',
+        'price' => 'decimal:4',
+        'total' => 'decimal:4',
+    ];
+
+    public function order(): BelongsTo
+    {
+        return $this->belongsTo(SalesOrder::class, 'sales_order_id');
+    }
+}

app/Modules/Integration/Routes/api.php

@@ -0,0 +1,12 @@
+<?php
+
+use Illuminate\Support\Facades\Route;
+use App\Modules\Integration\Controllers\ProductSyncController;
+use App\Modules\Integration\Controllers\OrderSyncController;
+
+Route::prefix('api/v1/integration')
+    ->middleware(['api', 'integration.tenant', 'auth:sanctum']) // integration.tenant middleware to identify tenant
+    ->group(function () {
+        Route::post('products/upsert', [ProductSyncController::class, 'upsert']);
+        Route::post('orders', [OrderSyncController::class, 'store']);
+    });