用户模块

用户分为两种类型，注册时通过 user_type 字段区分：

  • 个人用户（personal）：个人开发者，手机号/邮箱注册，个人实名认证
  • 企业用户（enterprise）：企业主账号，企业认证后可管理子成员账号
企业账号（enterprise）
  └── 成员账号（member）── 由企业管理员邀请，共享企业钱包与配额

1.1 通用用户接口

注册

POST /api/v1/users/register

密码安全： password 字段必须使用 RSA 公钥加密后传输，不得明文传输。请先调用 GET /api/v1/auth/public-key 获取公钥，详见授权模块 2.1。

请求体：

{
  "user_type": "personal",
  "email": "user@example.com",
  "key_id": "rsa_key_20240101_001",
  "password": "Base64(RSA_ENCRYPT('Aa123456!', public_key))",
  "phone": "13800138000",
  "captcha_token": "captcha_xxx"
}
字段 类型 必填 说明
user_type string 是 personal / enterprise
email string 是 邮箱，唯一
key_id string 是 公钥标识，从 GET /auth/public-key 获取
password string 是 RSA 加密后的 Base64 字符串（原始密码 8-32 位，含字母+数字）
phone string 否 手机号
enterprise_name string 企业必填 企业名称
captcha_token string 是 图形验证码 Token

响应：

{
  "code": 0,
  "data": {
    "user_id": "u_01HX...",
    "email": "user@example.com",
    "user_type": "personal",
    "created_at": "2024-01-01T12:00:00Z"
  }
}

HTTP 状态码： 201 创建成功，409 邮箱已注册

查询当前用户信息

GET /api/v1/users/me

响应：

{
  "code": 0,
  "data": {
    "user_id": "u_01HX...",
    "email": "user@example.com",
    "phone": "138****8000",
    "user_type": "personal",
    "nickname": "张三",
    "avatar": "https://oss.example.com/avatars/xxx.jpg",
    "realname_verified": true,
    "membership_level": "basic",
    "membership_expires_at": "2024-12-31T23:59:59Z",
    "created_at": "2024-01-01T00:00:00Z"
  }
}

更新个人信息

PUT /api/v1/users/me

{
  "nickname": "李四",
  "avatar": "https://oss.example.com/avatars/new.jpg"
}

修改密码

PUT /api/v1/users/me/password

密码安全： old_password 和 new_password 均必须使用 RSA 公钥加密后传输，不得明文传输。

{
  "key_id": "rsa_key_20240101_001",
  "old_password": "Base64(RSA_ENCRYPT('Aa123456!', public_key))",
  "new_password": "Base64(RSA_ENCRYPT('Bb654321!', public_key))"
}
字段 类型 必填 说明
key_id string 是 公钥标识，从 GET /auth/public-key 获取
old_password string 是 当前密码的 RSA 加密 Base64 字符串
new_password string 是 新密码的 RSA 加密 Base64 字符串

HTTP 状态码： 200 成功，400 旧密码错误或 key_id 无效/已过期

发送邮箱验证码

POST /api/v1/users/me/verify/email

{
  "email": "user@example.com",
  "purpose": "register"
}

purpose 枚举：register / reset_password / change_email

管理员查询用户

GET /admin/v1/users/{user_id}

GET /admin/v1/users — 用户列表

查询参数 类型 说明
user_type string personal / enterprise
status string active / frozen
keyword string 搜索邮箱/手机号/昵称
page int 页码
page_size int 每页条数

1.2 API Key 管理

查询 API Key 列表

GET /api/v1/users/me/apikeys

查询参数 说明
key_type production / test
status active / disabled / expired

响应：

{
  "code": 0,
  "data": {
    "items": [
      {
        "key_id": "key_01HX...",
        "name": "生产环境主 Key",
        "key_prefix": "sk-prod-abc1****",
        "key_type": "production",
        "status": "active",
        "last_used_at": "2024-01-01T12:00:00Z",
        "expires_at": null,
        "created_at": "2024-01-01T00:00:00Z"
      }
    ],
    "total": 3
  }
}

创建 API Key

POST /api/v1/users/me/apikeys

{
  "name": "生产环境主 Key",
  "key_type": "production",
  "expires_at": null,
  "allowed_models": [],
  "allowed_ips": []
}
字段 类型 说明
name string Key 名称，便于识别
key_type string production / test
expires_at string|null 过期时间，null 表示永不过期
allowed_models array 允许调用的模型 ID 列表，空数组表示全部
allowed_ips array IP 白名单，空数组表示不限制

响应（仅在创建时返回完整 Key，之后不再显示）：

{
  "code": 0,
  "data": {
    "key_id": "key_01HX...",
    "api_key": "sk-prod-abcdefghijklmnopqrstuvwxyz123456",
    "name": "生产环境主 Key",
    "key_type": "production"
  }
}

删除 API Key

DELETE /api/v1/users/me/apikeys/{key_id}

HTTP 状态码： 200 成功，404 Key 不存在

1.3 个人实名认证

提交实名认证

POST /api/v1/users/me/verify/realname

{
  "real_name": "张三",
  "id_card": "110101199001011234",
  "id_card_front": "https://oss.example.com/id_cards/front.jpg",
  "id_card_back": "https://oss.example.com/id_cards/back.jpg"
}

查询实名认证状态

GET /api/v1/users/me/verify/realname

{
  "code": 0,
  "data": {
    "status": "verified",
    "real_name": "张**",
    "verified_at": "2024-01-01T12:00:00Z"
  }
}

status 枚举：unverified / pending / verified / rejected

1.4 企业用户认证与信息

提交企业认证

POST /api/v1/users/me/verify/enterprise

{
  "enterprise_name": "XX 科技有限公司",
  "credit_code": "91110000XXXXXXXX",
  "license_image": "https://oss.example.com/licenses/xxx.jpg",
  "contact_name": "李四",
  "contact_phone": "13900139000"
}

查询企业信息

GET /api/v1/enterprise/profile

{
  "code": 0,
  "data": {
    "enterprise_id": "ent_01HX...",
    "enterprise_name": "XX 科技有限公司",
    "credit_code": "9111****",
    "verify_status": "verified",
    "member_count": 12,
    "contact_name": "李四",
    "contact_phone": "139****9000"
  }
}

更新企业信息

PUT /api/v1/enterprise/profile

1.5 企业成员管理

成员列表

GET /api/v1/enterprise/members

{
  "code": 0,
  "data": {
    "items": [
      {
        "member_id": "u_01HX...",
        "email": "dev@company.com",
        "nickname": "开发同学",
        "role": "member",
        "status": "active",
        "quota": {
          "tokens_per_day": 500000,
          "tokens_used_today": 12000
        },
        "joined_at": "2024-01-01T00:00:00Z"
      }
    ],
    "total": 12
  }
}

邀请成员

POST /api/v1/enterprise/members/invite

{
  "email": "newmember@company.com",
  "role": "member"
}

移除成员

DELETE /api/v1/enterprise/members/{member_id}

查询成员配额

GET /api/v1/enterprise/members/{member_id}/quota

设置成员配额

PUT /api/v1/enterprise/members/{member_id}/quota

{
  "tokens_per_day": 1000000,
  "requests_per_day": 500
}

修改成员角色

PUT /api/v1/enterprise/members/{member_id}/role

{ "role": "admin" }

role 枚举：admin / member