[DOCS] 補齊 B690 來店禮驗證的錯誤回應文件

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

@@ -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` (來店禮) 完成扣減。
 
 ---

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)。'
                 ],
             ],

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">