mama/star-erp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(integration): 完善外部 API 對接邏輯與安全性

Browse Source 
1. 新增 API Rate Limiting (每分鐘 60 次)
2. 實作 ProductServiceInterface 與 findOrCreateWarehouseByName 解決跨模組耦合問題
3. 強化 OrderSync API 驗證 (price 欄位限制最小 0、payment_method 加上允許白名單)
4. 實作 OrderSync API 冪等性處理，重複訂單直接回傳現有資訊
5. 修正 ProductSync API 同步邏輯，每次同步皆會更新產品分類與單位
6. 完善 integration API 對接手冊內容與 UI 排版
This commit is contained in:
sky121113
2026-02-23 10:10:03 +08:00
parent 29cdf37b71
commit a05acd96dc
13 changed files with 303 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
app/Modules/Integration/Controllers/OrderSyncController.php
View File

@@ -6,66 +6,79 @@ 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 App\Modules\Inventory\Contracts\InventoryServiceInterface;
use App\Modules\Inventory\Contracts\ProductServiceInterface;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Log;
class OrderSyncController extends Controller
{
protected $inventoryService;
protected $productService;
public function __construct(InventoryService $inventoryService)
{
public function __construct(
InventoryServiceInterface $inventoryService,
ProductServiceInterface $productService
) {
$this->inventoryService = $inventoryService;
$this->productService = $productService;
}
public function store(Request $request)
{
// 冪等性處理：若訂單已存在，回傳已建立的訂單資訊
$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|exists:warehouses,id',
'items' => 'required|array',
'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',
'items.*.price' => 'required|numeric|min:0',
]);
try {
return DB::transaction(function () use ($request) {
// 1. Create Order
// 1. 建立訂單
$order = SalesOrder::create([
'external_order_id' => $request->external_order_id,
'status' => 'completed',
'payment_method' => $request->payment_method ?? 'cash',
'total_amount' => 0, // Will calculate
'total_amount' => 0,
'sold_at' => $request->sold_at ?? now(),
'raw_payload' => $request->all(),
]);
// Find Warehouse (Default to "銷售倉庫")
// 2. 查找或建立倉庫
$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,
]);
$warehouse = $this->inventoryService->findOrCreateWarehouseByName($warehouseName);
$warehouseId = $warehouse->id;
}
$totalAmount = 0;
// 3. 處理訂單明細
foreach ($request->items as $itemData) {
// Find product by external ID (Strict Check)
$product = Product::where('external_pos_id', $itemData['pos_product_id'])->first();
// 透過介面查找產品
$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.");
throw new \Exception(
"Product not found for POS ID: " . $itemData['pos_product_id'] . ". Please sync product first."
);
}
$qty = $itemData['qty'];
@@ -73,23 +86,23 @@ class OrderSyncController extends Controller
$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
'product_name' => $product->name,
'quantity' => $qty,
'price' => $price,
'total' => $lineTotal,
]);
// 3. Deduct Stock (Force negative allowed for POS orders)
// 4. 扣除庫存（強制模式，允許負庫存）
$this->inventoryService->decreaseStock(
$product->id,
$warehouseId,
$qty,
"POS Order: " . $order->external_order_id,
true // Force = true
true
);
}

10
app/Modules/Integration/Controllers/ProductSyncController.php
View File

@@ -4,14 +4,14 @@ namespace App\Modules\Integration\Controllers;
use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
use App\Modules\Inventory\Services\ProductService;
use App\Modules\Inventory\Contracts\ProductServiceInterface;
use Illuminate\Support\Facades\Log;
class ProductSyncController extends Controller
{
protected $productService;
public function __construct(ProductService $productService)
public function __construct(ProductServiceInterface $productService)
{
$this->productService = $productService;
}
@@ -21,7 +21,7 @@ class ProductSyncController extends Controller
$request->validate([
'external_pos_id' => 'required|string',
'name' => 'required|string',
'price' => 'nullable|numeric',
'price' => 'nullable|numeric|min:0',
'barcode' => 'nullable|string',
'category' => 'nullable|string',
'unit' => 'nullable|string',
@@ -40,7 +40,9 @@ class ProductSyncController extends Controller
]);
} catch (\Exception $e) {
Log::error('Product Sync Failed', ['error' => $e->getMessage(), 'payload' => $request->all()]);
return response()->json(['message' => 'Sync failed'], 500);
return response()->json([
'message' => 'Sync failed: ' . $e->getMessage(),
], 500);
}
}
}