<?php

return [
    'title' => 'Star Cloud IoT API 說明文件',
    'version' => 'v1.0.0',
    'description' => '此文件提供 Star Cloud 智能販賣機 IoT 端點通訊協議說明，供硬體端與前端開發者調研與串接使用。',
    'categories' => [
        [
            'name' => '機台核心通訊 (IoT Core)',
            'apis' => [
                [
                    'name' => 'B000: 維運人員登入認證 (Technician Login)',
                    'slug' => 'b000-tech-login',
                    'method' => 'POST',
                    'path' => '/api/v1/app/admin/login/B000',
                    'description' => '機台啟動引導的第一步。維運人員輸入個人帳密與機台編號進行認證，成功後核發臨時 Sanctum Token 供後續 B014 下載敏感設定使用。',
                    'headers' => [
                        'Content-Type' => 'application/json',
                    ],
                    'parameters' => [
                        'username' => [
                            'type' => 'string',
                            'required' => true,
                            'description' => '維運人員帳號',
                            'example' => 'admin_test'
                        ],
                        'password' => [
                            'type' => 'string',
                            'required' => true,
                            'description' => '維運人員密碼',
                            'example' => 'password123'
                        ],
                        'machine' => [
                            'type' => 'string',
                            'required' => true,
                            'description' => '機台序號 (Serial No)',
                            'example' => 'SN202604130001'
                        ],
                    ],
                    'response_parameters' => [
                        'message' => [
                            'type' => 'string',
                            'description' => '回應訊息',
                            'example' => 'Success'
                        ],
                        'token' => [
                            'type' => 'string',
                            'description' => '臨時身份認證 Token (Sanctum)',
                            'example' => '1|abcdefg...'
                        ],
                    ],
                    'request' => [
                        'username' => 'admin_test',
                        'password' => 'password123',
                        'machine' => 'SN202604130001'
                    ],
                    'response' => [
                        'message' => 'Success',
                        'token' => '1|abcdefg...'
                    ],
                ],
                [
                    'name' => 'B014: 機台參數與金鑰下載 (Config Download)',
                    'slug' => 'b014-config-download',
                    'method' => 'GET',
                    'path' => '/api/v1/app/machine/setting/B014',
                    'description' => '機台引導階段的第二步。在人員登入後，透過此介面下載金流金鑰、電子發票設定與機台專屬通訊 Token。',
                    'headers' => [
                        'Authorization' => 'Bearer <user_token>',
                        'Content-Type' => 'application/json',
                    ],
                    'parameters' => [
                        'machine' => [
                            'type' => 'string',
                            'required' => true,
                            'description' => '機台序號',
                            'example' => 'SN202604130001'
                        ],
                    ],
                    'response_parameters' => [
                        'success' => [
                            'type' => 'boolean',
                            'description' => '是否成功',
                            'example' => true
                        ],
                        'data' => [
                            'type' => 'array',
                            'description' => '配置物件陣列。包含：t050v01 (序號), api_token (通訊 Token), t050v41~43 (玉山設定), t050v34~38 (發票設定), TP_... (趨勢/手機支付設定)',
                            'example' => [
                                [
                                    't050v01' => 'SN202604130001',
                                    'api_token' => 'mac_token_...',
                                    't050v41' => '80812345',
                                    't050v34' => '2000132',
                                    'TP_APP_ID' => 'GP_001'
                                ]
                            ]
                        ],
                    ],
                    'request' => [],
                    'response' => [
                        'success' => true,
                        'code' => 200,
                        'data' => [
                            [
                                't050v01' => 'SN202604130001',
                                'api_token' => 'mac_token_...',
                                't050v41' => '80812345',
                                't050v42' => '9001',
                                't050v43' => 'hash_key',
                                't050v34' => '2000132',
                                'TP_APP_ID' => 'GP_001'
                            ]
                        ]
                    ],
                    'notes' => '此 API 受 auth:sanctum 保護，必須在 Header 帶上從 B000 取得的 Token。'
                ],
                [
                    'name' => 'B005: 廣告清單同步 (Ad Sync)',
                    'slug' => 'b005-ad-sync',
                    'method' => 'GET',
                    'path' => '/api/v1/app/machine/ad/B005',
                    'description' => '用於機台端獲取目前應播放的廣告檔案 URL 清單。此介面無需 Request Body。',
                    'headers' => [
                        'Authorization' => 'Bearer <api_token>',
                        'Content-Type' => 'application/json',
                    ],
                    'parameters' => [],
                    'response_parameters' => [
                        'success' => [
                            'type' => 'boolean',
                            'description' => '請求是否成功',
                            'example' => true
                        ],
                        'code' => [
                            'type' => 'integer',
                            'description' => '內部業務狀態碼',
                            'example' => 200
                        ],
                        'data' => [
                            'type' => 'array',
                            'description' => '廣告物件陣列。內部欄位包含：t070v01 (名稱), t070v02 (秒數), t070v03 (位置：1:販賣頁, 2:來店禮, 3:待機廣告), t070v04 (URL), t070v05 (順位)',
                            'example' => [
                                [
                                    't070v01' => '測試機台廣告',
                                    't070v02' => 15,
                                    't070v03' => 3,
                                    't070v04' => 'https://example.com/ad1.mp4',
                                    't070v05' => 1
                                ]
                            ]
                        ],
                    ],
                    'request' => [],
                    'response' => [
                        'success' => true,
                        'code' => 200,
                        'message' => 'OK',
                        'data' => [
                            [
                                't070v01' => '測試機台廣告',
                                't070v02' => 15,
                                't070v03' => 3,
                                't070v04' => 'https://example.com/ad1.mp4',
                                't070v05' => 1
                            ]
                        ]
                    ],
                ],
                [
                    'name' => 'B009: 貨道庫存即時回報 (Inventory Report)',
                    'slug' => 'b009-inventory-report',
                    'method' => 'PUT',
                    'path' => '/api/v1/app/products/supplementary/B009',
                    'description' => '當人員在機台端完成操作後，將目前的貨道實體狀態同步回雲端。需進行 RBAC 權限核查。',
                    'headers' => [
                        'Authorization' => 'Bearer <api_token>',
                        'Content-Type' => 'application/json',
                    ],
                    'parameters' => [
                        'account' => [
                            'type' => 'string',
                            'required' => true,
                            'description' => '操作人員帳號',
                            'example' => '0999123456'
                        ],
                        'data' => [
                            'type' => 'array',
                            'required' => true,
                            'description' => '貨道數據陣列。tid: 貨道號, t060v00: 商品 ID, num: 庫存量',
                            'example' => [
                                ['tid' => '1', 't060v00' => '1', 'num' => '10']
                            ]
                        ],
                    ],
                    'response_parameters' => [
                        'success' => [
                            'type' => 'boolean',
                            'description' => '同步是否成功',
                            'example' => true
                        ],
                        'code' => [
                            'type' => 'integer',
                            'description' => '內部業務狀態碼',
                            'example' => 200
                        ],
                        'message' => [
                            'type' => 'string',
                            'description' => '回應訊息',
                            'example' => 'Slot report synchronized success'
                        ],
                        'status' => [
                            'type' => 'string',
                            'description' => '固定回傳 49 代表同步完成',
                            'example' => '49'
                        ],
                    ],
                    'request' => [
                        'account' => '0999123456',
                        'data' => [
                            ['tid' => '1', 't060v00' => '1', 'num' => '10']
                        ]
                    ],
                    'response' => [
                        'success' => true,
                        'code' => 200,
                        'message' => 'Slot report synchronized success',
                        'status' => '49'
                    ],
                ],
                [
                    'name' => 'B010: 心跳上報與狀態同步 (Heartbeat)',
                    'slug' => 'b010-heartbeat',
                    'method' => 'POST',
                    'path' => '/api/v1/app/machine/status/B010',
                    'description' => '機台定期向雲端回報當前頁面、版本、溫度及門禁狀態。身份由 Bearer Token 識別。',
                    'headers' => [
                        'Authorization' => 'Bearer <api_token>',
                        'Content-Type' => 'application/json',
                    ],
                    'parameters' => [
                        'current_page' => [
                            'type' => 'integer',
                            'required' => true,
                            'description' => '當前頁面編號。對照表：
0: 離線, 1: 主頁面, 2: 販賣頁, 3: 管理頁, 4: 補貨頁, 5: 教學頁
6: 購買中, 7: 鎖定頁, 60: 出貨成功, 61: 貨道測試, 62: 付款選擇
63: 等待付款, 64: 出貨, 65: 收據簽單, 66: 通行碼, 67: 取貨碼
68: 訊息顯示, 69: 取消購買, 610: 購買結束, 611: 來店禮, 612: 出貨失敗',
                            'example' => 1
                        ],
                        'firmware_version' => [
                            'type' => 'string',
                            'required' => true,
                            'description' => '軟體或韌體版本號',
                            'example' => '1.0.5'
                        ],
                        'model' => [
                            'type' => 'string',
                            'required' => false,
                            'description' => '機台型號',
                            'example' => 'STAR-V1'
                        ],
                        'temperature' => [
                            'type' => 'float',
                            'required' => false,
                            'description' => '感測環境溫度',
                            'example' => 25.5
                        ],
                        'door_status' => [
                            'type' => 'integer',
                            'required' => false,
                            'description' => '門禁狀態 (0: 關閉, 1: 開啟)',
                            'example' => 0
                        ],
                        'log' => [
                            'type' => 'string',
                            'required' => false,
                            'description' => '事件日誌主訊息',
                            'example' => 'Door opened'
                        ],
                        'log_level' => [
                            'type' => 'string',
                            'required' => false,
                            'description' => '日誌等級 (info, warning, error)',
                            'example' => 'info'
                        ],
                        'log_payload' => [
                            'type' => 'object',
                            'required' => false,
                            'description' => '詳細上下文 (JSON 對象)',
                            'example' => ['error_code' => 500, 'component' => 'door_sensor']
                        ],
                    ],
                    'response_parameters' => [
                        'success' => [
                            'type' => 'boolean',
                            'description' => '請求是否處理成功',
                            'example' => true
                        ],
                        'code' => [
                            'type' => 'integer',
                            'description' => '內部業務狀態碼',
                            'example' => 200
                        ],
                        'message' => [
                            'type' => 'string',
                            'description' => '回應訊息說明',
                            'example' => 'OK'
                        ],
                        'status' => [
                            'type' => 'string',
                            'description' => '雲端指令代碼。對照表：
49: reload B017 (貨道同步), 51: reboot (重啟系統)
60: reboot card machine (刷卡機重啟), 61: checkout (觸發結帳)
70: unlock (解鎖), 71: lock (鎖定), 85: reload B0552 (遠端出貨)
待定義: change (遠端找零 - 目前 Java App 尚無對接)',
                            'example' => '49'
                        ],
                    ],
                    'request' => [
                        'current_page' => 1,
                        'firmware_version' => '1.0.5',
                        'model' => 'STAR-V1',
                        'temperature' => 25.5,
                        'door_status' => 0,
                        'log' => 'Door opened',
                        'log_level' => 'info',
                        'log_payload' => [
                            'error_code' => 500,
                            'component' => 'door_sensor'
                        ],
                    ],
                    'response' => [
                        'success' => true,
                        'code' => 200,
                        'message' => 'OK',
                        'status' => '49'
                    ],
                    'notes' => '機台收到 B010 回應中的特定 `status` 代碼後，應根據對照表執行對應的指令動作或 API 呼叫 (如 B017)。若為空則代表無指令。'
                ],
                [
                    'name' => 'B012: 商品配置與商品主檔同步 (Unified Sync)',
                    'slug' => 'b012-unified-sync',
                    'method' => 'GET/PATCH',
                    'path' => '/api/v1/app/machine/products/B012',
                    'description' => '用於機台端獲取目前所有可販售商品的詳細配置。GET 為全量同步，PATCH 為增量更新。',
                    'headers' => [
                        'Authorization' => 'Bearer <api_token>',
                        'Content-Type' => 'application/json',
                    ],
                    'parameters' => [],
                    'response_parameters' => [
                        'success' => [
                            'type' => 'boolean',
                            'description' => '請求是否處理成功',
                            'example' => true
                        ],
                        'code' => [
                            'type' => 'integer',
                            'description' => '內部業務狀態碼',
                            'example' => 200
                        ],
                        'data' => [
                            'type' => 'array',
                            'description' => '商品明細物件陣列',
                            'example' => [
                                [
                                    't060v00' => '1',
                                    't060v01' => '可口可樂 330ml',
                                    't060v01_en' => 'Coca Cola',
                                    't060v01_jp' => 'コカコーラ',
                                    't060v03' => 'Cold Drink',
                                    't060v06' => 'https://.../coke.png',
                                    't060v09' => 25.0,
                                    't060v11' => 10,
                                    't060v30' => 20.0,
                                    't063v03' => 25.0,
                                    't060v40' => 'Buy 1 Get 1',
                                    't060v41' => 'SKU-001',
                                    'spring_limit' => 10,
                                    'track_limit' => 15
                                ]
                            ]
                        ]
                    ],
                    'request' => [],
                    'response' => [
                        'success' => true,
                        'code' => 200,
                        'message' => 'OK',
                        'data' => [
                            [
                                't060v00' => '1',
                                't060v01' => '可口可樂 330ml',
                                't060v01_en' => 'Coca Cola',
                                't060v01_jp' => 'コカコーラ',
                                't060v03' => 'Cold Drink',
                                't060v06' => 'https://.../coke.png',
                                't060v09' => 25.0,
                                't060v11' => 10,
                                't060v30' => 20.0,
                                't063v03' => 25.0,
                                't060v40' => 'Buy 1 Get 1',
                                't060v41' => 'SKU-001',
                                'spring_limit' => 10,
                                'track_limit' => 15
                            ]
                        ]
                    ],
                    'notes' => '運作邏輯 (Client-side Logic): GET 執行全量同步，App 應於收到成功回應後，先執行 deleteAll() 再進行 insertAll()。PATCH 執行增量更新，App 僅對記憶體中的既存商品進行欄位值覆蓋 (Patching)。'
                ],
                [
                    'name' => 'B013: 機台故障與異常狀態上報 (Error/Status Report)',
                    'slug' => 'b013-error-report',
                    'method' => 'POST',
                    'path' => '/api/v1/app/machine/error/B013',
                    'description' => '用於接收機台發出的即時硬體狀態代碼（如卡貨、門未關）。身份由 Bearer Token 識別，回傳成功代表伺服器已將任務列入異步隊列處理。',
                    'headers' => [
                        'Authorization' => 'Bearer <api_token>',
                        'Content-Type' => 'application/json',
                    ],
                    'parameters' => [
                        'tid' => [
                            'type' => 'integer',
                            'required' => false,
                            'description' => '涉及到之具體貨道編號 (Slot No)',
                            'example' => 12
                        ],
                        'error_code' => [
                            'type' => 'string',
                            'required' => true,
                            'description' => '硬體狀態代碼 (4 位 16 進位字串)',
                            'example' => '0403'
                        ],
                    ],
                    'response_parameters' => [
                        'success' => [
                            'type' => 'boolean',
                            'description' => '請求是否已成功接收',
                            'example' => true
                        ],
                        'code' => [
                            'type' => 'integer',
                            'description' => '內部業務狀態碼',
                            'example' => 200
                        ],
                    ],
                    'request' => [
                        'tid' => 12,
                        'error_code' => '0403',
                    ],
                    'response' => [
                        'success' => true,
                        'code' => 200,
                        'message' => 'Error report accepted'
                    ],
                    'notes' => '硬體代碼對照表見後端 MachineService::ERROR_CODE_MAP 定義。
0402: 出貨成功, 0403: 貨道卡貨, 0202: 貨道缺貨, 0415: 取貨門異常...等。'
                ],
                [
                    'name' => 'B017: 貨道庫存同步 (Slot Synchronization)',
                    'slug' => 'b017-slot-sync',
                    'method' => 'GET',
                    'path' => '/api/v1/app/machine/reload_msg/B017',
                    'description' => '用於機台端獲獲取所有貨道的最新庫存、效期與狀態。通常由 B010 回傳 status: 49 時觸發。',
                    'headers' => [
                        'Authorization' => 'Bearer <api_token>',
                        'Content-Type' => 'application/json',
                    ],
                    'parameters' => [],
                    'response_parameters' => [
                        'success' => [
                            'type' => 'boolean',
                            'description' => '是否成功',
                            'example' => true
                        ],
                        'data' => [
                            'type' => 'array',
                            'description' => '貨道數據陣列。',
                            'example' => [
                                [
                                    'tid' => '1',
                                    'num' => 10,
                                    'expiry_date' => '2026-12-31',
                                    'batch_no' => 'B2026',
                                    'status' => '1'
                                ]
                            ]
                        ],
                    ],
                    'request' => [],
                    'response' => [
                        'success' => true,
                        'code' => 200,
                        'data' => [
                            [
                                'tid' => '1',
                                'num' => 10,
                                'expiry_date' => '2026-12-31',
                                'batch_no' => 'B2026',
                                'product_id' => 1,
                                'capacity' => 15,
                                'status' => '1'
                            ]
                        ]
                    ],
                    '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 <api_token>',
                        '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 <api_token>',
                        '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 <api_token>',
                        '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']
                        ]
                    ],
                ]
            ]
        ]
    ]
];