Agent · 控制端点 API

索引：backend/real-agent-web/src/main/java/com/ai/agent/real/web/controller/auth/AuthController.java + UserProfileController + UserAgentPreferenceController

包含 Auth（登录/注册）、UserProfile（用户资料）、UserAgentPreference（Agent 偏好）等控制类端点。

---

Auth · 认证

Method	Path	用途
POST	/api/auth/register	邮箱+密码+验证码注册
POST	/api/auth/login	邮箱+密码登录
POST	/api/auth/login/email	邮箱验证码登录
POST	/api/auth/login/phone	手机号验证码登录
POST	/api/auth/email/send	发送邮箱验证码
POST	/api/auth/sms/send	发送短信验证码
GET	/api/auth/oauth2/google/state	获取 Google OAuth state
POST	/api/auth/oauth2/google	Google OAuth 登录
POST	/api/auth/refresh	刷新 Token
POST	/api/auth/logout	登出
POST	/api/auth/password/change	修改密码（已登录态）

---

1 · 邮箱+密码登录

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "yourPassword123"
}

响应 · LoginResponse

{
  "code": 200,
  "message": "success.login",
  "data": {
    "accessToken": "eyJhbGciOi...",
    "refreshToken": "eyJhbGciOi...",
    "expiresIn": 7200,
    "user": {
      "userId": "uuid-...",
      "username": "user@example.com",
      "nickname": "Tony Stark",
      "avatarUrl": "https://...",
      "email": "user@example.com",
      "phone": null,
      "credits": 100.00000000,
      "totalCreditsUsed": 23.50000000,
      "status": 1,
      "onboardingCompleted": true,
      "subscription": {
        "planId": "pro",
        "expiresAt": "2027-05-14T00:00:00+08:00"
      }
    }
  }
}

Token 携带方式

所有后续请求：Authorization: Bearer {accessToken}

---

2 · 注册

POST /api/auth/register
Content-Type: application/json

{
  "email": "newuser@example.com",
  "password": "Strong@Pass1",
  "code": "123456",
  "nickname": "可选",
  "avatarUrl": "可选"
}

字段	校验
email	合法邮箱
password	必填（强度由前端校验）
code	六位数字（先调用 /api/auth/email/send 获取）

---

3 · 邮箱验证码登录（免密）

POST /api/auth/email/send
{ "email": "user@example.com" }

POST /api/auth/login/email
{ "email": "user@example.com", "code": "123456" }

无需密码，验证码六位数字。

---

4 · 手机号验证码登录

POST /api/auth/sms/send
{ "phone": "13800138000" }

POST /api/auth/login/phone
{ "phone": "13800138000", "code": "123456" }

手机号正则：^1[3-9]\d{9}$（仅中国大陆）。

---

5 · Google OAuth

# Step 1: 获取 state
GET /api/auth/oauth2/google/state

# Step 2: 前端跳转 Google 授权，回调拿到 code 后
POST /api/auth/oauth2/google
{
  "code": "google-auth-code",
  "state": "step-1-的-state"
}

---

6 · 刷新 Token

POST /api/auth/refresh
{ "refreshToken": "eyJhbGciOi..." }

设备绑定

Refresh 时后端会比对 IP + User-Agent，设备不匹配返回 401 auth.error.deviceVerifyFailed，需重新登录。

---

7 · 修改密码

POST /api/auth/password/change
Authorization: Bearer $TOKEN

{ "newPassword": "NewStrong@1" }

强度要求：^(?=.*[A-Za-z])(?=.*\d)[A-Za-z\d@$!%*#?&]{8,}$（至少 8 位，含字母 + 数字）。

---

8 · 登出

POST /api/auth/logout
Authorization: Bearer $TOKEN

Token 进入黑名单立即失效。

---

UserProfile · 用户资料

[TODO: 端点详情待索引 UserProfileController.java，预期含 GET/PUT /api/users/me、头像上传、昵称修改等]

---

UserAgentPreference · Agent 偏好

[TODO: 端点详情待索引 UserAgentPreferenceController.java，预期含模型偏好、默认 ExecutionMode、Skill 自动启用等]

---

UserModelPreference · 模型偏好

[TODO: 端点详情待索引 UserModelPreferenceController.java，预期含默认 LLM 模型、温度、最大 token 等]

---

速率限制

端点类别	限制
/api/auth/login*	5 次 / 分钟 / IP
/api/auth/*/send	1 次 / 分钟 / 邮箱或手机号
其他认证端点	60 次 / 分钟 / 用户

超过返回 429 Too Many Requests。

---

相关

• Chat API — 主对话端点
• Help · API Key 在哪