<?php

return [
    'title' => 'Star Cloud IoT API 說明文件',
    'version' => 'v1.0.0',
    'description' => '此文件提供 Star Cloud 智能販賣機 IoT 端點通訊協議說明，供硬體端與前端開發者調研與串接使用。',
    'categories' => [
        [
            'name' => '機台核心通訊 (IoT Core)',
            'apis' => [
                [
                    '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 (貨道同步), 50: reload B005 (基礎參數), 51: reboot (重啟)
60: reboot card machine (刷卡機重啟), 61: checkout (結帳)
70: unlock (解鎖), 71: lock (鎖定), 72: sellCode reload B023 (即期品)
75: exp reload B026 (效期), 79: read B050 (參數讀取)
81: sync timer status (B710), 85: reload B0552 (出貨腳本)',
                            '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)。若為空則代表無指令。'
                ]
            ]
        ]
    ]
];