[DOCS] 新增並更新 Phase 1 核心機台通訊 API 技術規範文件 (B010~B710)

docs/b601_technical_spec.md

@@ -0,0 +1,49 @@
+# B601 API (發票資訊回傳) 技術規範與執行指南
+
+本文件定義 B601 API 的技術實作規範，用於紀錄每筆訂單對應的電子發票資訊。
+
+---
+
+## 1. 業務流程與角色定義
+
+### 1.1 系統角色
+*   **機台端**：負責與電子發票系統對接、開立發票，並於取得發票號碼後將資訊回傳至雲端。
+*   **雲端 (Star Cloud)**：僅負責**紀錄 (Logging)** 發票資訊，不涉及上傳傳財政部平台或寄送中獎通知。
+
+### 1.2 串聯機制
+*   **關聯 ID**：必須攜帶 B600 取得的 `flow_id`，以便將發票資訊正確掛載至對應的 `orders`。
+
+---
+
+## 2. 資料庫結構：`invoices`
+
+為符合台灣發票規範，除了原始 PDF 欄位外，本系統將擴充相關稅務欄位：
+
+| 欄位 | 說明 | 備註 |
+|------|------|------|
+| `order_id` | 訂單關聯 ID | 透過 `flow_id` 對應 |
+| `invoice_no` | 發票號碼 | 例：AB-12345678 |
+| `invoice_date` | 發票日期 | |
+| `random_number` | 隨機碼 | 4 位數 |
+| `love_code` | 愛心碼 | 捐贈碼 |
+| `business_tax_id` | **公司統編** | 8 位數 |
+| `carrier_id` | **載具編號** | 手機條碼或自然人憑證 |
+| `carrier_type` | **載具類型** | |
+| `status` | **發票狀態** | 1:有效, 0:作廢 |
+
+---
+
+## 3. 發票作廢機制 (Invoice Voiding)
+
+*   **需求確認**：當交易發生退款或特定失敗情境時，機台端需具備回報「發票作廢」的能力。
+*   **API 實作**：
+    *   **方法一**：呼叫 B601 POST 時帶入 `status = 0`。
+    *   **方法二**：新增 `/api/app/B601/void` 專屬端點（待後續細化）。
+
+---
+
+## 4. 待確認事項 (To-be-confirmed)
+
+### 4.1 邏輯關聯與超時
+1.  **發票缺失標記**：若收到 B600 (金流) 但在預設時間內（如 5 分鐘）未收到 B601，後台是否應將該訂單標記為「發票缺失」以供巡檢。
+2.  **重試機制**：機台端在 B601 呼叫失敗時的緩存與重傳策略。