用户邀请功能接口文档

概述

用户邀请功能允许用户通过邀请码邀请新用户注册，并在满足条件时获得奖励。该功能包括生成邀请码、验证邀请码、处理注册奖励等。

功能模块

用户注册时使用邀请码
邀请码管理（列表、详情）
邀请关系管理（列表）

接口列表

1. 用户注册接口（包含邀请码功能）

接口地址: /api/signup

请求方法: POST

功能说明: 用户注册接口，支持通过邀请码注册。如果提供了有效的邀请码，系统将创建邀请关系并触发奖励。

请求参数:

参数名	类型	必填	说明
email	string	是	用户邮箱
password	string	是	用户密码
token	string	是	邮箱验证码
language_id	integer	否	语言ID
user_invite_code	string	否	邀请码
remember	boolean	否	是否记住登录

响应参数:

参数名	类型	说明
status	string	状态 (success/fail)
message	string	返回消息
code	integer	状态码
data	object	返回数据
data.token	string	访问令牌
data.user	object	用户信息

示例请求:

{
  "email": "user@example.com",
  "password": "password123",
  "token": "123456",
  "user_invite_code": "ABCDEF"
}

示例响应:

{
  "status": "success",
  "message": "Sign Up Success",
  "code": 200,
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
    "user": {
      "id": 1,
      "name": "User Name",
      "email": "user@example.com"
    }
  }
}

错误码:

ErrorCode::SystemUserInvateCodeNotFound (30010): 邀请码不存在或无效

2. 获取用户邀请码列表

接口地址: /api/invite_codes/list

请求方法: POST

功能说明: 获取当前用户创建的邀请码列表。

请求参数:

参数名	类型	必填	说明
code	string	否	邀请码筛选
status	string	否	状态筛选 (active,inactive,expired)
page	integer	否	页码
per_page	integer	否	每页数量

响应参数:

参数名	类型	说明
code	integer	状态码
message	string	返回消息
data	array	邀请码列表

邀请码对象:

参数名	类型	说明
id	integer	邀请码ID
inviter_user_id	integer	邀请者用户ID
code	string	邀请码
invite_code_type_id	integer	邀请码类型ID
status	string	状态 (active,inactive,expired)
reward_max_usage	integer	最大奖励次数
expires_at	string	过期时间
created_at	string	创建时间
updated_at	string	更新时间

示例请求:

{
  "page": 1,
  "per_page": 10
}

示例响应:

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "inviter_user_id": 1,
      "code": "ABCDEF",
      "invite_code_type_id": 1,
      "status": "active",
      "reward_max_usage": 10,
      "expires_at": "2025-12-31 23:59:59",
      "created_at": "2025-08-11 10:00:00",
      "updated_at": "2025-08-11 10:00:00"
    }
  ]
}

3. 获取邀请码详情

接口地址: /api/invite_codes/info

请求方法: POST

功能说明: 获取指定邀请码的详细信息，包括邀请统计。

请求参数:

参数名	类型	必填	说明
id	integer	是	邀请码ID

响应参数:

参数名	类型	说明
code	integer	状态码
message	string	返回消息
data	object	邀请码详情

邀请码详情对象:

参数名	类型	说明
id	integer	邀请码ID
inviter_user_id	integer	邀请者用户ID
code	string	邀请码
invite_code_type_id	integer	邀请码类型ID
status	string	状态 (active,inactive,expired)
reward_max_usage	integer	最大奖励次数
expires_at	string	过期时间
created_at	string	创建时间
updated_at	string	更新时间
invited_count	integer	已邀请人数
reward_received_count	integer	已获得奖励次数

示例请求:

{
  "id": 1
}

示例响应:

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "inviter_user_id": 1,
    "code": "ABCDEF",
    "invite_code_type_id": 1,
    "status": "active",
    "reward_max_usage": 10,
    "expires_at": "2025-12-31 23:59:59",
    "created_at": "2025-08-11 10:00:00",
    "updated_at": "2025-08-11 10:00:00",
    "invited_count": 2,
    "reward_received_count": 2
  }
}

4. 获取邀请关系列表

接口地址: /api/user_invite_relations/list

请求方法: POST

功能说明: 获取指定邀请码的邀请关系列表。

请求参数:

参数名	类型	必填	说明
invite_code_id	integer	是	邀请码ID
is_rewarded	boolean	否	是否已获得奖励筛选
page	integer	否	页码
size	integer	否	每页数量

响应参数:

参数名	类型	说明
data	array	邀请关系列表
total	integer	总记录数

邀请关系对象:

参数名	类型	说明
id	integer	邀请关系ID
invite_code_id	integer	邀请码ID
inviter_user_id	integer	邀请者用户ID
invitee_user_id	integer	被邀请者用户ID
is_rewarded	boolean	是否已获得奖励
created_at	string	创建时间
updated_at	string	更新时间
invitee	object	被邀请者信息
invitee.id	integer	被邀请者ID
invitee.name	string	被邀请者名称
invitee.avatar_id	integer	头像ID
invitee.avatar	object	头像信息

示例请求:

{
  "invite_code_id": 1,
  "is_rewarded": true
}

示例响应:

{
  "data": [
    {
      "id": 1,
      "invite_code_id": 1,
      "inviter_user_id": 1,
      "invitee_user_id": 2,
      "is_rewarded": true,
      "created_at": "2025-08-11 10:30:00",
      "updated_at": "2025-08-11 10:30:00",
      "invitee": {
        "id": 2,
        "name": "Invited User",
        "avatar_id": 1,
        "avatar": {
          "id": 1,
          "path": "/avatars/1.jpg"
        }
      }
    }
  ],
  "total": 1
}

数据模型

邀请码状态枚举

值	说明
active	活跃可用
inactive	非活跃
expired	已过期

奖励日志状态枚举

值	说明
pending	待发放
processing	发放中
completed	已发放
failed	发放失败
cancelled	已取消

奖励接收者类型枚举

值	说明
inviter	邀请者
invitee	被邀请者

奖励触发条件枚举

值	说明
register_success	注册成功
complete_first_order	完成首单
complete_first_payment	完成首次支付

奖励类型枚举

值	说明
invitee_credit	给被邀请者积分
inviter_credit	给邀请者积分

业务流程

用户注册时可选择使用邀请码
系统验证邀请码有效性
如果邀请码有效，创建邀请关系
根据配置触发相应的奖励
用户可查看自己的邀请码及邀请统计
用户可查看邀请关系列表

实现细节

邀请码的使用次数是实时计算的，通过统计关联的邀请关系数量得出
邀请码的最大使用次数由 reward_max_usage 字段控制，-1 表示无限制

错误处理

邀请码不存在或无效时，返回统一的错误码
数据库操作失败时，记录日志并返回相应错误
系统会在处理邀请码和奖励发放时自动记录错误日志，便于问题排查

#用户邀请功能接口文档

#概述

#功能模块

#接口列表

#1. 用户注册接口（包含邀请码功能）

#2. 获取用户邀请码列表

#3. 获取邀请码详情

#4. 获取邀请关系列表

#数据模型

#邀请码状态枚举

#奖励日志状态枚举

#奖励接收者类型枚举

#奖励触发条件枚举

#奖励类型枚举

#业务流程

#实现细节

#错误处理

用户邀请功能接口文档

概述

功能模块

接口列表

1. 用户注册接口（包含邀请码功能）

2. 获取用户邀请码列表

3. 获取邀请码详情

4. 获取邀请关系列表

数据模型

邀请码状态枚举

奖励日志状态枚举

奖励接收者类型枚举

奖励触发条件枚举

奖励类型枚举

业务流程

实现细节

错误处理