diff --git a/.agents/skills/api-technical-specs/SKILL.md b/.agents/skills/api-technical-specs/SKILL.md index 2961a4d..430daf4 100644 --- a/.agents/skills/api-technical-specs/SKILL.md +++ b/.agents/skills/api-technical-specs/SKILL.md @@ -265,12 +265,9 @@ description: 本技能規範定義了 Star Cloud 系統中所有機台 (IoT) 與 用於機台端獲取目前所有貨道的最新庫存、效期與狀態。通常由 B010 回應 `status: 49` 觸發。 - **URL**: GET /api/v1/app/machine/reload_msg/B017 -- **Authentication**: Bearer Token (Header) 或 API Key (Body/Query) +- **Authentication**: Bearer Token (Header) - **Request Body:** 無 (由 Token 自動識別機台) -| 參數 | 類型 | 必填 | 說明 | 範例 | -| :--- | :--- | :--- | :--- | :--- | - - **Response Body:** | 參數 | 類型 | 說明 | 範例 | @@ -293,3 +290,67 @@ description: 本技能規範定義了 Star Cloud 系統中所有機台 (IoT) 與 > [!IMPORTANT] > **同步機制**：B017 為全量同步。App 收到回應後應更新本地資料庫對應貨道的數值。成功請求後，雲端會自動將相關的 `reload_stock` 指令標記為 `success`。 + +--- + +### 3.9 B024: 取貨碼/通行碼驗證與消耗回報 (Access Code Verify & Report) +用於處理機台端的代碼取貨流程。包含驗證代碼有效性（驗證階段）與確認出貨完成後的狀態消耗（回報階段）。 + +- **URL**: POST|PUT /api/v1/app/sell/access-code/B024 +- **Authentication**: Bearer Token (Header) +- **Request Body (POST - 驗證階段):** + +| 參數 | 類型 | 必填 | 說明 | 範例 | +| :--- | :--- | :--- | :--- | :--- | +| passCode | String | 是 | 使用者輸入的取貨碼/通行碼 | "12345678" | + +- **Response Body (POST - 驗證成功 200):** +雲端將回傳該碼對應的權限或待出貨商品資訊。 + +| 參數 | 類型 | 說明 | 範例 | +| :--- | :--- | :--- | :--- | +| res1 | String | 該代碼在雲端的關聯 ID | "99" | +| res2 | String | 操作模式 (1: 出貨, 2: 僅驗證) | "1" | +| res3 | String | 預計出貨商品 ID | "5" | +| res4 | String | 折扣金額或活動標籤 | "0.0" | + +- **Request Body (PUT - 回報階段):** +當機台端確認實體出貨成功後，必須發送此請求以耗刷該代碼。 + +| 參數 | 類型 | 必填 | 說明 | 範例 | +| :--- | :--- | :--- | :--- | :--- | +| accessCodeId | String | 是 | 驗證階段取得的 res1 (ID) | "99" | +| status | String | 是 | 出貨結果 (1: 成功, 0: 失敗) | "1" | + +--- + +### 3.10 B027: 贈品碼/優惠券驗證與消耗回報 (Free Gift Verify & Report) +用於處理行銷贈品券、0 元購活動或特定的優惠券核銷流程。 + +- **URL**: POST|PUT /api/v1/app/sell/free-gift/B027 +- **Authentication**: Bearer Token (Header) +- **運作模式**: + - **POST**: 提交 `passCode` 驗證該贈品券是否有效。成功後雲端會回傳對應活動 ID 與商品配置。 + - **PUT**: 當該贈品（0 元商品）出貨完成後，向雲端回報消耗，確保優惠券不會重複核銷。 + +> [!NOTE] +> B027 與 B024 的邏輯具備高度對稱性，區別在於 B027 通常綁定的是特定的行銷活動 (Campaign) 與 0 元出貨邏輯。 + +--- + +### 3.11 B055: 遠端指令出貨控制 (Remote Dispense / Force Open) +用於遠端手動驅動機台出貨。通常用於補償使用者、測試機台或客服協助開門的情景。 + +- **URL**: POST|PUT /api/v1/app/machine/dispense/B055 +- **Authentication**: Bearer Token (Header) +- **運作模式**: + - **POST (查詢)**: 當 B010 收到 `status: 85` 時呼叫。雲端會回傳待執行的貨道編號與指令 ID。 + - **PUT (回報)**: 實體出貨完成後回報結果，以便雲端將該指令標記為「已執行」。 + +- **Request Body (PUT - 回報階段):** + +| 參數 | 類型 | 必填 | 說明 | 範例 | +| :--- | :--- | :--- | :--- | :--- | +| id | String | 是 | 雲端下發的指令 ID | "20260414001" | +| type | String | 是 | 出貨類型代碼 (通常為 0) | "0" | +| stock | String | 是 | 出貨後的貨道剩餘數量 | "9" | diff --git a/config/api-docs.php b/config/api-docs.php index a86ecf5..0112cb5 100644 --- a/config/api-docs.php +++ b/config/api-docs.php @@ -506,6 +506,92 @@ return [ ] ], 'notes' => 'B017 為全量同步。實作上後端會依據 slot_no 進行排序，並將相關指令狀態更新為已完成。' + ], + [ + 'name' => 'B024: 取貨碼/通行碼驗證與消耗回報', + 'slug' => 'b024-access-code', + 'method' => 'POST/PUT', + 'path' => '/api/v1/app/sell/access-code/B024', + 'description' => '處理代碼取貨流程。POST 用於驗證碼有效性，PUT 用於回報出貨成功並消耗代碼。', + 'headers' => [ + 'Authorization' => 'Bearer ', + 'Content-Type' => 'application/json', + ], + 'parameters' => [ + 'passCode' => [ + 'type' => 'string', + 'description' => '取貨碼 (POST)', + ], + 'accessCodeId' => [ + 'type' => 'string', + 'description' => '代碼 ID (PUT)', + ], + 'status' => [ + 'type' => 'string', + 'description' => '出貨狀態 (PUT: 1:成功, 0:失敗)', + ], + ], + 'response_parameters' => [ + 'res1' => ['type' => 'string', 'description' => '雲端關聯 ID'], + 'res3' => ['type' => 'string', 'description' => '預計出貨商品 ID'], + ], + 'request' => [ + 'passCode' => '12345678' + ], + 'response' => [ + 'success' => true, + 'res1' => '99', + 'res3' => '5' + ], + ], + [ + 'name' => 'B027: 贈品碼/優惠券驗證與消耗回報', + 'slug' => 'b027-freebie-code', + 'method' => 'POST/PUT', + 'path' => '/api/v1/app/sell/free-gift/B027', + 'description' => '處理贈品券與 0 元購活動。邏輯與 B024 相似但對象為行銷贈品。', + 'headers' => [ + 'Authorization' => 'Bearer ', + 'Content-Type' => 'application/json', + ], + 'parameters' => [ + 'passCode' => [ + 'type' => 'string', + 'description' => '贈品碼 (POST)', + ], + ], + 'response_parameters' => [ + 'success' => ['type' => 'boolean', 'description' => '驗證結果'], + ], + 'request' => [ + 'passCode' => 'FREE888' + ], + 'response' => [ + 'success' => true, + 'message' => 'Free gift verified' + ], + ], + [ + 'name' => 'B055: 遠端指令出貨控制 (Remote Dispense)', + 'slug' => 'b055-remote-dispense', + 'method' => 'POST/PUT', + 'path' => '/api/v1/app/machine/dispense/B055', + 'description' => '遠端手動驅動機台出貨。POST 用於獲取待處理指令，PUT 用於回報出貨完成。', + 'headers' => [ + 'Authorization' => 'Bearer ', + 'Content-Type' => 'application/json', + ], + 'parameters' => [ + 'id' => ['type' => 'string', 'description' => '指令 ID (PUT)'], + 'stock' => ['type' => 'string', 'description' => '剩餘庫存 (PUT)'], + ], + 'request' => [], + 'response' => [ + 'success' => true, + 'data' => [ + ['slot_no' => '1', 'order_id' => 'RE-123'] + ] + ], ] ] ]