邀请码 API

邀请码管理接口，包括公开验证/绑定接口和需认证的用户接口。此为可插拔功能模块。

路由前缀：/invite-codes

源码：apps/backend/src/routes/invite-codes.ts

---

认证

接口分为两类：

• 公开接口（/validate、/bind、/settings）：无需认证
• 用户接口（/my/*）：需要 JWT 认证

Authorization: Bearer <JWT>

---

公开接口

1. 验证邀请码

POST /invite-codes/validate

验证邀请码是否可用（注册流程中调用，无需登录）。若邀请码功能关闭，直接返回通过。

请求体：

字段	类型	必填	说明
code	string	是	邀请码
email	string	是	注册邮箱

响应 200 OK（可用）：

{
  "valid": true
}

响应 200 OK（功能关闭）：

{
  "valid": true,
  "message": "Invite code not required"
}

响应 200 OK（同邮箱重复验证）：

{
  "valid": true,
  "alreadyBound": true
}

响应 200 OK（不可用）：

{
  "valid": false,
  "error": "INVALID_CODE"
}

error 错误码：

error	说明
MISSING_PARAMS	缺少 code 或 email
INVALID_CODE	邀请码不存在
CODE_ALREADY_USED	邀请码已被使用
CODE_EXPIRED	邀请码已过期
EMAIL_ALREADY_REGISTERED	邮箱已注册
INTERNAL_ERROR	服务端错误

HTTP 错误码：

HTTP	说明
400	缺少参数
500	服务端错误

---

2. 绑定邀请码

POST /invite-codes/bind

将邀请码绑定到邮箱（注册流程中调用，无需登录）。原子性操作，仅未使用且未过期的邀请码才能绑定。

请求体：

字段	类型	必填	说明
code	string	是	邀请码
email	string	是	注册邮箱

响应 200 OK（成功）：

{
  "success": true
}

响应 200 OK（功能关闭）：

{
  "success": true,
  "message": "Invite code not required"
}

错误码：

HTTP	error	说明
400	MISSING_PARAMS	缺少 code 或 email
400	BIND_FAILED	绑定失败（码已使用或过期）
500	INTERNAL_ERROR	服务端错误

---

3. 获取邀请码配置

GET /invite-codes/settings

获取邀请码功能的公开配置信息。

响应 200 OK：

{
  "enabled": true,
  "creditsPerCode": 1000
}

字段	说明
enabled	邀请码功能是否启用
creditsPerCode	每个邀请码奖励积分数（用户可见单位）

错误码：

HTTP	说明
500	获取配置失败，返回 { "enabled": false }

---

用户接口（需 JWT 认证）

4. 获取我的邀请码列表

GET /invite-codes/my/codes

获取当前用户的所有邀请码（包括已使用的），按创建时间倒序。

响应 200 OK：

{
  "data": [
    {
      "id": "uuid",
      "code": "ABCD1234",
      "credits_milli": 1000000,
      "used_by_email": null,
      "used_at": null,
      "expires_at": "2026-04-06T00:00:00.000Z",
      "created_at": "2026-03-07T00:00:00.000Z"
    }
  ]
}

credits_milli 为毫积分单位（1 积分 = 1000 毫积分）。

错误码：

HTTP	错误	说明
401	Unauthorized	未认证
500	Failed to fetch codes	查询失败
500	Internal server error	服务端错误

---

5. 处理邀请码积分发放

POST /invite-codes/my/redeem

注册完成后处理邀请码积分发放。前端在用户首次登录后调用此接口：

1. 查找绑定到该邮箱的邀请码
2. 发放积分给邀请人和被邀请人
3. 为新用户生成邀请码

响应 200 OK：

{
  "success": true
}

错误码：

HTTP	错误	说明
401	Unauthorized	未认证或无邮箱信息
500	Internal server error	服务端错误

---

6. 生成邀请码

POST /invite-codes/my/generate

为当前用户生成邀请码，自动补齐到配置数量（默认每用户 5 个）。如果已有足够的邀请码，不会重复生成。

邀请码格式：8 位全大写字母 + 数字（排除易混淆字符 0OIL1），有效期默认 30 天。

响应 200 OK（生成了新码）：

{
  "generated": 3
}

响应 200 OK（已有足够）：

{
  "generated": 0,
  "message": "Already have enough codes"
}

错误码：

HTTP	错误	说明
401	Unauthorized	未认证
500	Failed to generate codes	生成失败
500	Internal server error	服务端错误