兌換碼管理模組

功能說明

介面字首統一為 http(s)://<your-domain>

生產環境應使用 HTTPS 以保證認證令牌。 HTTP 僅建議用於開發環境。

管理員專用的兌換碼系統。支援批次生成、狀態管理、搜尋過濾等功能。包含自動清理無效兌換碼的維護功能。主要用於促銷活動和使用者激勵。

🔐 管理員鑑權

獲取兌換碼列表

介面名稱：獲取兌換碼列表
HTTP 方法：GET
路徑：/api/redemption/
鑑權要求：管理員
功能簡介：分頁獲取系統中所有兌換碼的列表資訊

💡 請求示例：

const response = await fetch('/api/redemption/?p=1&page_size=20', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  }
});
const data = await response.json();

✅ 成功響應示例：

{
  "success": true,
  "message": "",
  "data": {
    "items": [
      {
        "id": 1,
        "name": "新年活動兌換碼",
        "key": "abc123def456",
        "status": 1,
        "quota": 100000,
        "created_time": 1640908800,
        "redeemed_time": 0,
        "expired_time": 1640995200,
        "used_user_id": 0
      }
    ],
    "total": 50,
    "page": 1,
    "page_size": 20
  }
}

❗ 失敗響應示例：

{
  "success": false,
  "message": "獲取兌換碼列表失敗"
}

🧾 欄位說明：

p （數字）: 頁碼，預設為 1
page_size （數字）: 每頁數量，預設為 20
items （陣列）: 兌換碼資訊列表
total （數字）: 兌換碼總數
page （數字）: 當前頁碼
page_size （數字）: 每頁數量

搜尋兌換碼

介面名稱：搜尋兌換碼
HTTP 方法：GET
路徑：/api/redemption/search
鑑權要求：管理員
功能簡介：根據關鍵詞搜尋兌換碼，支援按 ID 和名稱搜尋

💡 請求示例：

const response = await fetch('/api/redemption/search?keyword=新年&p=1&page_size=20', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  }
});
const data = await response.json();

✅ 成功響應示例：

{
  "success": true,
  "message": "",
  "data": {
    "items": [
      {
        "id": 1,
        "name": "新年活動兌換碼",
        "key": "abc123def456",
        "status": 1,
        "quota": 100000
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}

❗ 失敗響應示例：

{
  "success": false,
  "message": "搜尋兌換碼失敗"
}

🧾 欄位說明：

keyword （字串）: 搜尋關鍵詞，可匹配兌換碼名稱或 ID
p （數字）: 頁碼，預設為 1
page_size （數字）: 每頁數量，預設為 20

獲取單個兌換碼

介面名稱：獲取單個兌換碼
HTTP 方法：GET
路徑：/api/redemption/:id
鑑權要求：管理員
功能簡介：獲取指定兌換碼的詳細資訊

💡 請求示例：

const response = await fetch('/api/redemption/123', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  }
});
const data = await response.json();

✅ 成功響應示例：

{
  "success": true,
  "message": "",
  "data": {
    "id": 123,
    "name": "新年活動兌換碼",
    "key": "abc123def456",
    "status": 1,
    "quota": 100000,
    "created_time": 1640908800,
    "redeemed_time": 0,
    "expired_time": 1640995200,
    "used_user_id": 0,
    "user_id": 1
  }
}

❗ 失敗響應示例：

{
  "success": false,
  "message": "兌換碼不存在"
}

🧾 欄位說明：

id （數字）: 兌換碼 ID，透過 URL 路徑傳遞

建立兌換碼

介面名稱：建立兌換碼
HTTP 方法：POST
路徑：/api/redemption/
鑑權要求：管理員
功能簡介：批次建立兌換碼，支援一次建立多個

💡 請求示例：

const response = await fetch('/api/redemption/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  },
  body: JSON.stringify({
    name: "春節活動兌換碼",
    count: 10,
    quota: 100000,
    expired_time: 1640995200
  })
});
const data = await response.json();

✅ 成功響應示例：

{
  "success": true,
  "message": "",
  "data": [
    "abc123def456",
    "def456ghi789",
    "ghi789jkl012"
  ]
}

❗ 失敗響應示例：

{
  "success": false,
  "message": "兌換碼名稱長度必須在1-20之間"
}

🧾 欄位說明：

name （字串）: 兌換碼名稱，長度必須在 1-20 個字元之間
count （數字）: 要建立的兌換碼數量，必須大於 0 且不超過 100
quota （數字）: 每個兌換碼的配額數量
expired_time （數字）: 過期時間戳，0 表示永不過期
data （陣列）: 成功建立的兌換碼列表

更新兌換碼

介面名稱：更新兌換碼
HTTP 方法：PUT
路徑：/api/redemption/
鑑權要求：管理員
功能簡介：更新兌換碼資訊，支援僅更新狀態或完整更新

💡 請求示例（完整更新）：

const response = await fetch('/api/redemption/', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  },
  body: JSON.stringify({
    id: 123,
    name: "更新的兌換碼名稱",
    quota: 200000,
    expired_time: 1672531200
  })
});
const data = await response.json();

💡 請求示例（僅更新狀態）：

const response = await fetch('/api/redemption/?status_only=true', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  },
  body: JSON.stringify({
    id: 123,
    status: 2
  })
});
const data = await response.json();

✅ 成功響應示例：

{
  "success": true,
  "message": "",
  "data": {
    "id": 123,
    "name": "更新的兌換碼名稱",
    "status": 1,
    "quota": 200000,
    "expired_time": 1672531200
  }
}

❗ 失敗響應示例：

{
  "success": false,
  "message": "過期時間不能早於當前時間"
}

🧾 欄位說明：

id （數字）: 兌換碼 ID，必填
status_only （查詢引數）: 是否僅更新狀態
name （字串）: 兌換碼名稱，可選
quota （數字）: 配額數量，可選
expired_time （數字）: 過期時間戳，可選
status （數字）: 兌換碼狀態，可選

刪除無效兌換碼

介面名稱：刪除無效兌換碼
HTTP 方法：DELETE
路徑：/api/redemption/invalid
鑑權要求：管理員
功能簡介：批次刪除已使用、已禁用或已過期的兌換碼

💡 請求示例：

const response = await fetch('/api/redemption/invalid', {
  method: 'DELETE',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  }
});
const data = await response.json();

✅ 成功響應示例：

{
  "success": true,
  "message": "",
  "data": 15
}

❗ 失敗響應示例：

{
  "success": false,
  "message": "刪除失敗"
}

🧾 欄位說明：

無請求引數
data （數字）: 刪除的兌換碼數量

刪除兌換碼

介面名稱：刪除兌換碼
HTTP 方法：DELETE
路徑：/api/redemption/:id
鑑權要求：管理員
功能簡介：刪除指定的兌換碼

💡 請求示例：

const response = await fetch('/api/redemption/123', {
  method: 'DELETE',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  }
});
const data = await response.json();

✅ 成功響應示例：

{
  "success": true,
  "message": ""
}

❗ 失敗響應示例：

{
  "success": false,
  "message": "兌換碼不存在"
}

🧾 欄位說明：

id （數字）: 兌換碼 ID，透過 URL 路徑傳遞

目錄