[REFACTOR] 統一訂單同步 API 錯誤回應與修正 Linter 警告

docs/integration/products_api.md

@@ -0,0 +1,64 @@
+# 商品查詢 API (External Product Fetch)
+
+本 API 供外部系統（如 POS）從 Star ERP 獲取商品資料。支援分頁、關鍵字搜尋與增量同步。
+
+## 1. 介面詳情
+- **Endpoint**: `GET /api/v1/integration/products`
+- **Authentication**: `Bearer Token` (Sanctum)
+- **Tenant Isolation**: 需透過 `X-Tenant-Domain` Header 或網域識別租戶。
+
+## 2. 請求參數 (Query Parameters)
+
+| 參數名 | 類型 | 必填 | 說明 |
+| :--- | :--- | :--- | :--- |
+| `keyword` | `string` | 否 | 關鍵字搜尋（符合名稱、代碼、條碼或外部編號）。 |
+| `category` | `string` | 否 | 分類名稱精準過濾（例如：`飲品`）。 |
+| `updated_after` | `datetime` | 否 | 增量同步機制。僅回傳該時間點之後有異動的商品（格式：`Y-m-d H:i:s`）。 |
+| `per_page` | `integer` | 否 | 每頁筆數（預設 50，最大 100）。 |
+| `page` | `integer` | 否 | 分頁頁碼（預設 1）。 |
+
+## 3. 回應結構 (JSON)
+
+### 成功回應 (200 OK)
+```json
+{
+    "status": "success",
+    "data": [
+        {
+            "id": 12,
+            "code": "COKE-001",
+            "barcode": "4710001",
+            "name": "可口可樂 600ml",
+            "external_pos_id": "POS-P-001",
+            "category_name": "飲品",
+            "brand": "可口可樂",
+            "specification": "600ml",
+            "unit_name": "瓶",
+            "price": 25.0,
+            "is_active": true,
+            "updated_at": "2026-03-19 09:30:00"
+        }
+    ],
+    "meta": {
+        "current_page": 1,
+        "last_page": 5,
+        "per_page": 50,
+        "total": 240
+    }
+}
+```
+
+## 4. 同步策略建議
+
+### 初次同步 (Initial Sync)
+1. 第一次串接時，不帶 `updated_after`。
+2. 根據 `meta.last_page` 遍歷所有分頁，將全量商品存入 POS。
+
+### 增量同步 (Incremental Sync)
+1. 記錄上一次同步成功的時間戳記。
+2. 定期調用 API 並帶入 `updated_after={timestamp}`。
+3. 僅處理回傳的商品資料進行更新或新增。
+
+## 5. 常見錯誤
+- `401 Unauthorized`: Token 無效或已過期。
+- `422 Unprocessable Entity`: 參數驗證失敗（例如 `updated_after` 格式錯誤）。