管理员礼品卡 API

管理员礼品卡管理路由，提供礼品卡的创建（含批量）、查询、统计和作废功能。

基础路径

/admin/gift-cards

认证方式

使用 combinedAuth + adminAudit 中间件。仅支持 JWT Bearer Token 认证，且需要 site:admin 权限。

Authorization: Bearer <jwt_token>

---

端点列表

GET /admin/gift-cards

获取礼品卡列表（含创建者和兑换者信息）。

请求参数（Query）

参数	类型	必填	默认值	说明
page	number	否	1	页码
pageSize	number	否	20	每页数量
status	string	否	无	状态筛选（如 active、redeemed、voided、expired）
batchId	string	否	无	按批次 ID 筛选
sortBy	string	否	created_at	排序字段：created_at / credits_milli / redeemed_at
sortOrder	string	否	desc	排序方向：asc / desc

响应格式

{
  "success": true,
  "items": [
    {
      "id": "uuid",
      "code": "GIFT-XXXX-XXXX",
      "credits_milli": 10000000,
      "credits": 10000,
      "status": "active",
      "batch_id": "uuid",
      "owner_user_id": "uuid",
      "redeemer_user_id": null,
      "redeemed_at": null,
      "expires_at": "2026-12-31T23:59:59Z",
      "note": "测试礼品卡",
      "created_at": "2026-03-07T00:00:00Z",
      "owner": {
        "user_id": "uuid",
        "email": "admin@example.com",
        "display_name": "管理员"
      },
      "redeemer": null
    }
  ],
  "total": 100,
  "page": 1,
  "pageSize": 20
}

响应字段说明

字段	类型	说明
items[].credits_milli	number	积分数（毫积分，数据库存储格式）
items[].credits	number	积分数（用户可见单位，= credits_milli / 1000）
items[].status	string	状态：active / redeemed / voided / expired
items[].owner	object	创建者信息
items[].redeemer	object | null	兑换者信息

错误码

HTTP 状态码	说明
403	仅支持 JWT 认证 / 缺少 site:admin 权限
500	获取礼品卡列表失败

---

GET /admin/gift-cards/stats

获取礼品卡统计数据。

请求参数

无。

响应格式

{
  "success": true,
  "stats": {
    "total": 500,
    "active": 300,
    "redeemed": 150,
    "voided": 30,
    "expired": 20,
    "total_credits_milli": 5000000000,
    "redeemed_credits_milli": 1500000000
  }
}

错误码

HTTP 状态码	说明
403	仅支持 JWT 认证 / 缺少 site:admin 权限
500	获取统计失败

---

GET /admin/gift-cards/:id

获取礼品卡详情（含创建者和兑换者信息）。

请求参数

参数	位置	类型	必填	说明
id	Path	string	是	礼品卡 ID

响应格式

{
  "success": true,
  "giftCard": {
    "id": "uuid",
    "code": "GIFT-XXXX-XXXX",
    "credits_milli": 10000000,
    "credits": 10000,
    "status": "active",
    "batch_id": "uuid",
    "owner_user_id": "uuid",
    "redeemer_user_id": null,
    "redeemed_at": null,
    "expires_at": "2026-12-31T23:59:59Z",
    "note": "备注",
    "created_at": "2026-03-07T00:00:00Z",
    "owner": {
      "user_id": "uuid",
      "email": "admin@example.com",
      "display_name": "管理员"
    },
    "redeemer": null
  }
}

错误码

HTTP 状态码	说明
403	仅支持 JWT 认证 / 缺少 site:admin 权限
404	礼品卡不存在
500	获取礼品卡详情失败

---

POST /admin/gift-cards

创建礼品卡（支持批量创建）。

请求参数（Body）

字段	类型	必填	默认值	说明
credits	number	是	-	积分数量（用户可见单位，必须大于 0）
quantity	number	否	1	创建数量（1-100）
expiresAt	string	否	无	过期时间（ISO 格式）
note	string	否	无	备注

响应格式

HTTP 201：

{
  "success": true,
  "giftCards": [
    {
      "id": "uuid",
      "code": "GIFT-XXXX-XXXX",
      "credits_milli": 10000000,
      "credits": 10000,
      "status": "active",
      "batch_id": "uuid",
      "owner_user_id": "uuid",
      "expires_at": "2026-12-31T23:59:59Z",
      "note": "备注",
      "created_at": "2026-03-07T00:00:00Z"
    }
  ],
  "count": 1
}

错误码

HTTP 状态码	说明
400	积分数量必须大于 0 / 数量必须在 1-100 之间
401	未认证
403	仅支持 JWT 认证 / 缺少 site:admin 权限
500	创建礼品卡失败

---

POST /admin/gift-cards/:id/void

作废礼品卡。仅可作废状态为 active 的礼品卡。

请求参数

参数	位置	类型	必填	说明
id	Path	string	是	礼品卡 ID

响应格式

{
  "success": true
}

错误码

HTTP 状态码	说明
400	只能作废可用状态的礼品卡
403	仅支持 JWT 认证 / 缺少 site:admin 权限
404	礼品卡不存在
500	作废失败

---

源码

• 路由文件：apps/backend/src/routes/admin/gift-cards.ts
• 礼品卡服务：apps/backend/src/services/gift-card.service.ts