# 会员兑换码 API

所有接口前缀：`/api/v1`  
除登录外都需要：`Authorization: Bearer <session_key>`（见：`docs/common/auth.md`）

## 1) 生成兑换码（后台口令）

`POST /api/v1/membership/redeem_codes`

Header：
- `X-Admin-Token: <ADMIN_API_TOKEN>`

请求体：
```json
{
  "count": 10,
  "plan": "month",
  "duration_days": 30,
  "expires_at": "2026-12-31 23:59:59",
  "max_uses": 1
}
```

说明：
- 需要在环境变量配置 `ADMIN_API_TOKEN`，否则接口会返回 503。
- 兑换码明文只在生成时返回；服务端只保存 `sha256(code)`。

成功响应（示例）：
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "count": 10,
    "codes": [
      { "code": "ABCD...1234", "plan": "month" }
    ]
  }
}
```

## 2) 使用兑换码开通/延长会员

`POST /api/v1/membership/redeem`

请求体：
```json
{
  "code": "ABCD...1234"
}
```

成功响应（示例）：
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "plan": "month",
    "starts_at": "2026-01-03T10:00:00+08:00",
    "ends_at": "2026-02-02T10:00:00+08:00",
    "extended": false,
    "code_suffix": "X7K9Q2"
  }
}
```

常见错误：
- `400`：兑换码无效/过期/已被使用/不可用
- `401`：未登录或 token 失效