礼品卡 API

礼品卡验证与核销接口（用户端）。此为可插拔功能模块。

路由前缀：/gift-cards

源码：apps/backend/src/routes/gift-cards.ts

认证

所有接口需要 JWT 认证：

Authorization: Bearer <JWT>

端点

1. 验证礼品卡码

GET /gift-cards/validate/:code

验证礼品卡码是否有效，返回礼品卡信息（不消耗）。

路径参数：

参数	说明
`code`	礼品卡码

响应 200 OK（有效）：

json

{
  "valid": true,
  "credits": 100,
  "expiresAt": "2026-06-01T00:00:00.000Z"
}

响应 200 OK（无效）：

json

{
  "valid": false,
  "error": "礼品卡已被使用"
}

错误码：

HTTP	错误	说明
400	`请输入礼品卡码`	未提供 code
500	`验证失败`	服务端错误

2. 核销礼品卡

POST /gift-cards/redeem

核销礼品卡，将积分充值到用户所在团队。

原子性与幂等（2026-06-10，issue #692）：核销在数据库单事务 RPC redeem_gift_card_atomic 内完成「锁卡行 → 状态翻转 → 幂等流水（幂等键 gift-card-<卡id>）→ 余额增量」。并发兑换同一张卡只会成功一次，输家收到 礼品卡已被使用；重复请求不会重复发放积分；过期卡实时拒绝并自动置为 expired。

请求体：

字段	类型	必填	说明
`code`	string	是	礼品卡码
`teamId`	string	否	指定充值到的团队 ID（需为该团队成员或 owner）

响应 200 OK：

json

{
  "success": true,
  "creditsGranted": 100,
  "message": "成功兑换 100 积分"
}

错误码：

HTTP	错误	说明
400	`请输入礼品卡码`	未提供 code
400	核销失败信息	礼品卡已使用、已过期等
401	`Unauthorized`	未认证
403	`无权为该团队兑换礼品卡`	指定了 teamId 但无权限
500	`核销失败`	服务端错误

礼品卡 API ​

认证 ​

端点 ​

1. 验证礼品卡码 ​

2. 核销礼品卡 ​

礼品卡 API

认证

端点

1. 验证礼品卡码

2. 核销礼品卡