feat(integration): 擴充產品同步 API 欄位與驗證強化

1. ProductSync API 新增防護機制，為既有欄位加上字串長度與金額上限限制
2. 開放並接收 ERP Product Model 實用欄位（品牌、規格、成本價、會員價、批發價）
3. 更新 ProductService 寫入邏輯以支援新增的可選欄位
4. 同步更新 api-integration.md 手冊，加入新欄位說明與 JSON 範例

app/Modules/Integration/Controllers/ProductSyncController.php

@@ -19,12 +19,17 @@ class ProductSyncController extends Controller
     public function upsert(Request $request)
     {
         $request->validate([
-            'external_pos_id' => 'required|string',
+            'external_pos_id' => 'required|string|max:255',
-            'name' => 'required|string',
+            'name' => 'required|string|max:255',
-            'price' => 'nullable|numeric|min:0',
+            'price' => 'nullable|numeric|min:0|max:99999999.99',
-            'barcode' => 'nullable|string',
+            'barcode' => 'nullable|string|max:100',
-            'category' => 'nullable|string',
+            'category' => 'nullable|string|max:100',
-            'unit' => 'nullable|string',
+            'unit' => 'nullable|string|max:100',
+            'brand' => 'nullable|string|max:100',
+            'specification' => 'nullable|string|max:255',
+            'cost_price' => 'nullable|numeric|min:0|max:99999999.99',
+            'member_price' => 'nullable|numeric|min:0|max:99999999.99',
+            'wholesale_price' => 'nullable|numeric|min:0|max:99999999.99',
             'updated_at' => 'nullable|date',
         ]);
 

app/Modules/Inventory/Services/ProductService.php

@@ -41,6 +41,13 @@ class ProductService implements ProductServiceInterface
             $product->barcode = $data['barcode'] ?? $product->barcode;
             $product->price = $data['price'] ?? 0;
             
+            // Map newly added extended fields
+            if (isset($data['brand'])) $product->brand = $data['brand'];
+            if (isset($data['specification'])) $product->specification = $data['specification'];
+            if (isset($data['cost_price'])) $product->cost_price = $data['cost_price'];
+            if (isset($data['member_price'])) $product->member_price = $data['member_price'];
+            if (isset($data['wholesale_price'])) $product->wholesale_price = $data['wholesale_price'];
+            
             // Generate Code if missing (use code or external_id)
             if (empty($product->code)) {
                 $product->code = $data['code'] ?? $product->external_pos_id;

resources/markdown/manual/api-integration.md

@@ -23,25 +23,38 @@ Star ERP 系統提供外部整合 API (Integration API) 供電商前台、POS
 
 ### Request Body (JSON)
 
-| 欄位名稱 | 型態 | 必填 | 說明 |
+| 欄位名稱 | 類型 | 必填 | 說明 |
 | :--- | :--- | :---: | :--- |
-| `external_pos_id` | String | **是** | 第三方系統中的唯一產品 ID，ERP 會依此 ID 判斷是否為同一商品 |
+| `external_pos_id` | String | **是** | 在 POS 系統中的唯一商品 ID (Primary Key) |
-| `name` | String | **是** | 產品名稱 |
+| `name` | String | **是** | 商品名稱 (最大 255 字元) |
-| `price` | Number | 否 | 產品售價 |
+| `price` | Decimal | 否 | 商品售價 (預設 0) |
-| `barcode` | String | 否 | 產品條碼 |
+| `barcode` | String | 否 | 商品條碼 (最大 100 字元) |
-| `category` | String | 否 | 產品分類名稱 |
+| `category` | String | 否 | 商品分類名稱。若系統中不存在，會自動建立 (最大 100 字元) |
-| `unit` | String | 否 | 單位 (例如: 個, 瓶, 箱) |
+| `unit` | String | 否 | 商品單位 (例如：個、杯、件)。若不存在會自動建立 (最大 100 字元) |
-| `updated_at` | String(Date) | 否 | 第三方系統的最後更新時間 (格式: YYYY-MM-DD HH:mm:ss) |
+| `brand` | String | 否 | 商品品牌名稱 (最大 100 字元) |
+| `specification` | String | 否 | 商品規格描述 (最大 255 字元) |
+| `cost_price` | Decimal | 否 | 成本價 (預設 0) |
+| `member_price` | Decimal | 否 | 會員價 (預設 0) |
+| `wholesale_price` | Decimal | 否 | 批發價 (預設 0) |
+| `is_active` | Boolean| 否 | 是否上架/啟用 (預設 true) |
+| `updated_at` | String | 否 | POS 端的最後更新時間 (格式: YYYY-MM-DD HH:mm:ss) |
 
 **請求範例：**
 ```json
 {
-    "external_pos_id": "POS-ITEM-001",
+  "external_pos_id": "POS-PROD-9001",
-    "name": "特級冷壓初榨橄欖油",
+  "name": "特級冷壓初榨橄欖油 500ml",
-    "price": 450,
+  "price": 380.00,
-    "barcode": "4711234567890",
+  "barcode": "4711234567890",
-    "category": "調味料",
+  "category": "調味料",
-    "unit": "瓶"
+  "unit": "瓶",
+  "brand": "健康王",
+  "specification": "500ml / 玻璃瓶裝",
+  "cost_price": 250.00,
+  "member_price": 350.00,
+  "wholesale_price": 300.00,
+  "is_active": true,
+  "updated_at": "2024-03-15 14:30:00"
 }
 ```