mama/star-cloud
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[DOCS] 補齊 B024, B027, B055 API 技術規格與文檔定義
All checks were successful
star-cloud-deploy-demo / deploy-demo (push) Successful in 1m1s
Details

Browse Source 
1. 更新技術手冊 (SKILL.md) 與 API 規格文件 (api-docs.php)，補齊 B024, B027, B055 之定義。
2. 修正文件序號跳號問題，確保 B017 序號正確銜接。
3. 詳細說明 B055 之指令 ID 遠端出貨運作機制。
This commit is contained in:
sky121113
2026-04-14 17:36:56 +08:00
parent 2702e5a655
commit f49938d1a7
2 changed files with 151 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
config/api-docs.php
View File

@@ -506,6 +506,92 @@ return [
]
],
'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']
]
],
]
]
]