From a5e5390cd1cb0cfff5bd0c26ac4aa27e077bbcde Mon Sep 17 00:00:00 2001
From: sky121113 <sky121113@gmail.com>
Date: Thu, 11 Jun 2026 15:00:50 +0800
Subject: [PATCH] =?UTF-8?q?[DOCS]=20=E8=A3=9C=E9=BD=8A=20B690=20=E4=BE=86?=
 =?UTF-8?q?=E5=BA=97=E7=A6=AE=E9=A9=97=E8=AD=89=E7=9A=84=E9=8C=AF=E8=AA=A4?=
 =?UTF-8?q?=E5=9B=9E=E6=87=89=E6=96=87=E4=BB=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

1. SKILL.md B690 章節新增 400 (格式錯誤) 與 429 (已鎖定) 兩種錯誤回應表格，與 verifyWelcomeGift 實際回傳一致。
2. config/api-docs.php B690 條目新增 error_responses 陣列，列出 400 / 404 / 429 錯誤碼與訊息。
3. api-docs.blade.php 新增通用「錯誤回應 (Error Responses)」渲染區塊，其他端點可沿用 error_responses 欄位。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .agents/skills/api-technical-specs/SKILL.md | 18 ++++++++++++++
 config/api-docs.php                         | 17 ++++++++++++++
 resources/views/docs/api-docs.blade.php     | 26 +++++++++++++++++++++
 3 files changed, 61 insertions(+)

diff --git a/.agents/skills/api-technical-specs/SKILL.md b/.agents/skills/api-technical-specs/SKILL.md
index 41bc9c7..7dea6c2 100644
--- a/.agents/skills/api-technical-specs/SKILL.md
+++ b/.agents/skills/api-technical-specs/SKILL.md
@@ -336,6 +336,24 @@ description: 本技能規範定義了 Star Cloud 系統中所有機台 (IoT) 與
 | code | Integer | 業務狀態碼 | 404 |
 | remaining_attempts | Integer | 剩餘嘗試次數 | 3 |
 
+**Response (Failed 400 — 格式錯誤):**
+
+| 參數 | 類型 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- |
+| success | Boolean | 請求是否成功 | false |
+| message | String | 失敗原因 (code 非 8 位數) | Invalid format |
+| code | Integer | 業務狀態碼 | 400 |
+
+**Response (Failed 429 — 已鎖定):**
+
+連續錯誤達 5 次後，該機台於鎖定期間 (60 秒) 內的所有驗證請求皆回傳此回應。
+
+| 參數 | 類型 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- |
+| success | Boolean | 請求是否成功 | false |
+| message | String | 失敗原因 | Too many attempts. Locked. |
+| code | Integer | 業務狀態碼 | 429 |
+
 - **消耗機制**: 出貨完成後，由機台發送 MQTT `finalize` 訊息，並在 `payment_type` 帶入 `7` (來店禮) 完成扣減。
 
 ---
diff --git a/config/api-docs.php b/config/api-docs.php
index 685d4bd..5d30920 100644
--- a/config/api-docs.php
+++ b/config/api-docs.php
@@ -695,6 +695,23 @@ return [
                             'status' => 'active'
                         ]
                     ],
+                    'error_responses' => [
+                        [
+                            'code' => 400,
+                            'message' => 'Invalid format',
+                            'description' => 'code 非 8 位數或缺少必填欄位。'
+                        ],
+                        [
+                            'code' => 404,
+                            'message' => 'Invalid or expired code',
+                            'description' => '代碼不存在、已失效或已過期。回應另含 remaining_attempts (剩餘嘗試次數)。'
+                        ],
+                        [
+                            'code' => 429,
+                            'message' => 'Too many attempts. Locked.',
+                            'description' => '連續錯誤達 5 次，該機台驗證功能於鎖定期間 (60 秒) 內皆回傳此回應。'
+                        ],
+                    ],
                     'notes' => '安全性：連續錯誤 5 次將鎖定該機台驗證功能 1 分鐘。消耗流程已遷移至 MQTT (payment_type=7)。'
                 ],
             ],
diff --git a/resources/views/docs/api-docs.blade.php b/resources/views/docs/api-docs.blade.php
index d8dc5f2..0162a44 100644
--- a/resources/views/docs/api-docs.blade.php
+++ b/resources/views/docs/api-docs.blade.php
@@ -328,6 +328,32 @@
                             </div>
                             @endif
 
+                            @if(isset($api['error_responses']) && count($api['error_responses']) > 0)
+                            <div>
+                                <h4 class="text-xs font-black text-slate-400 uppercase tracking-widest mb-4">錯誤回應 (Error Responses)</h4>
+                                <div class="overflow-hidden rounded-2xl border border-slate-200 shadow-sm bg-white mb-6">
+                                    <table class="w-full param-table">
+                                        <thead>
+                                            <tr>
+                                                <th class="w-[15%]">HTTP / code</th>
+                                                <th class="w-[30%]">message</th>
+                                                <th>說明</th>
+                                            </tr>
+                                        </thead>
+                                        <tbody>
+                                            @foreach($api['error_responses'] as $err)
+                                            <tr class="hover:bg-slate-50/50 transition-colors">
+                                                <td><span class="px-2 py-1 rounded bg-rose-100 text-[10px] font-black text-rose-600 uppercase tracking-wider">{{ $err['code'] }}</span></td>
+                                                <td class="font-black text-slate-900 text-sm">{{ $err['message'] }}</td>
+                                                <td class="text-slate-600 font-semibold text-sm whitespace-pre-line">{{ $err['description'] }}</td>
+                                            </tr>
+                                            @endforeach
+                                        </tbody>
+                                    </table>
+                                </div>
+                            </div>
+                            @endif
+
                             @if(isset($api['notes']))
                             <div class="p-6 bg-cyan-50/50 border border-cyan-100 rounded-3xl mt-6">
                                 <h5 class="text-cyan-700 font-black mb-2 flex items-center gap-2 text-lg">