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

app/Modules/Core/Models/User.php

@@ -10,10 +10,12 @@ use Spatie\Permission\Traits\HasRoles;
 use Spatie\Activitylog\Traits\LogsActivity;
 use Spatie\Activitylog\LogOptions;
 
+use Laravel\Sanctum\HasApiTokens;
+
 class User extends Authenticatable
 {
     /** @use HasFactory<\Database\Factories\UserFactory> */
-    use HasFactory, Notifiable, HasRoles, LogsActivity;
+    use HasFactory, Notifiable, HasRoles, LogsActivity, HasApiTokens;
 
     /**
      * 可批量賦值的屬性。

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

app/Modules/Inventory/Contracts/InventoryServiceInterface.php

@@ -21,9 +21,10 @@ interface InventoryServiceInterface
      * @param int $warehouseId
      * @param float $quantity
      * @param string|null $reason
+     * @param bool $force
      * @return void
      */
-    public function decreaseStock(int $productId, int $warehouseId, float $quantity, ?string $reason = null): void;
+    public function decreaseStock(int $productId, int $warehouseId, float $quantity, ?string $reason = null, bool $force = false): void;
 
     /**
      * Get all active warehouses.

app/Modules/Inventory/Models/Product.php

@@ -18,7 +18,9 @@ class Product extends Model
     protected $fillable = [
         'code',
         'barcode',
+        'sku',
         'name',
+        'external_pos_id',
         'category_id',
         'brand',
         'specification',

app/Modules/Inventory/Services/InventoryService.php

@@ -59,9 +59,9 @@ class InventoryService implements InventoryServiceInterface
         return $stock >= $quantity;
     }
 
-    public function decreaseStock(int $productId, int $warehouseId, float $quantity, ?string $reason = null): void
+    public function decreaseStock(int $productId, int $warehouseId, float $quantity, ?string $reason = null, bool $force = false): void
     {
-        DB::transaction(function () use ($productId, $warehouseId, $quantity, $reason) {
+        DB::transaction(function () use ($productId, $warehouseId, $quantity, $reason, $force) {
             $inventories = Inventory::where('product_id', $productId)
                 ->where('warehouse_id', $warehouseId)
                 ->where('quantity', '>', 0)
@@ -79,8 +79,30 @@ class InventoryService implements InventoryServiceInterface
             }
 
             if ($remainingToDecrease > 0) {
-                // 這裡可以選擇報錯或允許負庫存，目前為了嚴謹拋出異常
-                throw new \Exception("庫存不足，無法扣除所有請求的數量。");
+                if ($force) {
+                    // Find any existing inventory record in this warehouse to subtract from, or create one
+                    $inventory = Inventory::where('product_id', $productId)
+                        ->where('warehouse_id', $warehouseId)
+                        ->first();
+                    
+                    if (!$inventory) {
+                        $inventory = Inventory::create([
+                            'warehouse_id' => $warehouseId,
+                            'product_id' => $productId,
+                            'quantity' => 0,
+                            'unit_cost' => 0,
+                            'total_value' => 0,
+                            'batch_number' => 'POS-AUTO-' . time(),
+                            'arrival_date' => now(),
+                            'origin_country' => 'TW',
+                            'quality_status' => 'normal',
+                        ]);
+                    }
+                    
+                    $this->decreaseInventoryQuantity($inventory->id, $remainingToDecrease, $reason);
+                } else {
+                    throw new \Exception("庫存不足，無法扣除所有請求的數量。");
+                }
             }
         });
     }

app/Modules/Inventory/Services/ProductService.php

@@ -0,0 +1,73 @@
+<?php
+
+namespace App\Modules\Inventory\Services;
+
+use App\Modules\Inventory\Models\Product;
+use App\Modules\Inventory\Models\Category;
+use App\Modules\Inventory\Models\Unit;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+
+class ProductService
+{
+    /**
+     * Upsert product from external POS source.
+     *
+     * @param array $data
+     * @return Product
+     */
+    public function upsertFromPos(array $data)
+    {
+        return DB::transaction(function () use ($data) {
+            $externalId = $data['external_pos_id'] ?? null;
+
+            if (!$externalId) {
+                throw new \Exception("External POS ID is required for syncing.");
+            }
+
+            // Try to find by external_pos_id
+            $product = Product::where('external_pos_id', $externalId)->first();
+
+            if (!$product) {
+                // If not found, create new
+                // Optional: Check SKU conflict if needed, but for now trust POS ID
+                $product = new Product();
+                $product->external_pos_id = $externalId;
+            }
+
+            // Map allowed fields
+            $product->name = $data['name'];
+            $product->barcode = $data['barcode'] ?? $product->barcode;
+            $product->sku = $data['sku'] ?? $product->sku; // Maybe allow SKU update?
+            $product->price = $data['price'] ?? 0;
+            
+            // Generate Code if missing (use sku or external_id)
+            if (empty($product->code)) {
+                $product->code = $data['code'] ?? ($product->sku ?? $product->external_pos_id);
+            }
+            
+            // Handle Category (Default: 未分類)
+            if (empty($product->category_id)) {
+                $categoryName = $data['category'] ?? '未分類';
+                $category = Category::firstOrCreate(
+                    ['name' => $categoryName],
+                    ['code' => 'CAT-' . strtoupper(bin2hex(random_bytes(4)))]
+                );
+                $product->category_id = $category->id;
+            }
+
+            // Handle Base Unit (Default: 個)
+            if (empty($product->base_unit_id)) {
+                $unitName = $data['unit'] ?? '個';
+                $unit = Unit::firstOrCreate(['name' => $unitName]);
+                $product->base_unit_id = $unit->id;
+            }
+            
+            $product->is_active = $data['is_active'] ?? true;
+            
+            $product->save();
+
+            return $product;
+        });
+    }
+}