AI
AI Skill
泽汐（Evetide）统一登录 AI 接入指南：复制下方 Markdown 给 AI 助手，即可让 AI 帮你完成登录接入、快捷登录配置与配额使用。
evetide-login Skill
# 泽汐统一登录接入 Skill（evetide-login）
> 给 AI / 开发者使用的接入指南。按照本 Skill 即可完成「泽汐统一登录」OAuth 2.0 授权码模式接入。
> 平台：泽汐（Zexi）统一登录 · 产品 code：`evetide_login`（按调用次数计量）
## 1. 这是什么
泽汐统一登录（evetide_login）为你的应用提供**免自建账号体系的登录能力**。用户通过统一的登录页完成登录/注册，你的应用通过标准 OAuth 2.0 授权码模式换取用户信息，无需关心密码存储、验证码、第三方登录对接。
### 适用场景
- Web 网站 / H5：浏览器跳转授权
- 移动 App：WebView / 系统浏览器 + 自定义 scheme 回调
- 后端服务：作为认证中心，为你的 API 提供鉴权
## 2. 前置准备（申请应用）
在开发者中心控制台创建应用，获得：
- `client_id`（应用标识）
- `client_secret`（应用密钥，**仅存后端**，绝不能暴露在前端）
- `redirect_uri`（授权回调地址，需在控制台配置并精确匹配）
## 3. 核心端点
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `BASE_URL/api_authorize.php` | 授权入口（登录/注册/授权页） |
| POST | `BASE_URL/api_token.php` | code 换 access_token（Basic 认证） |
| GET | `BASE_URL/api_userinfo.php` | 获取用户信息（Bearer 认证） |
其中 `BASE_URL` = `https://login.evetide.cn`
## 4. 接入流程（3 步）
### 步骤 1：发起授权
浏览器跳转到授权入口：
```text
GET {BASE_URL}/api_authorize.php?client_id={client_id}
&redirect_uri={redirect_uri}
&response_type=code
&scope=openid+profile+email
&state={random_state}
```
- `state`：随机字符串，**必须在发起时保存到 session/本地**，回调时比对，防止 CSRF
- `scope`：固定 `openid profile email`
- 用户未登录会先看到登录页，登录后进入授权确认页
### 步骤 2：code 换 token（后端）
用户授权后跳回 `redirect_uri?code=xxx&state=yyy`。后端收到 code 后，用 Basic 认证换取 token：
```http
POST {BASE_URL}/api_token.php
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code={code}&redirect_uri={redirect_uri}
```
响应：
```json
{ "code": 0, "data": { "access_token": "...", "token_type": "Bearer", "expires_in": 3600, "scope": "openid profile email" } }
```
### 步骤 3：获取用户信息
用 access_token 以 Bearer 方式调用：
```http
GET {BASE_URL}/api_userinfo.php
Authorization: Bearer {access_token}
```
响应：
```json
{ "code": 0, "data": {
"sub": "login_temp/lll",
"name": "昵称",
"preferred_username": "lll",
"email": "user@example.com",
"email_verified": true,
"picture": "头像URL",
"scope": "openid profile email"
} }
```
用 `sub` 作为本地用户唯一标识，创建你的业务登录态。
## 5. 参数速查
| 参数 | 必填 | 说明 |
|---|---|---|
| client_id | 是 | 应用标识 |
| redirect_uri | 是 | 回调地址，必须与注册值一致 |
| response_type | 是 | 固定 `code` |
| scope | 是 | `openid profile email` |
| state | 是 | 防 CSRF 随机串 |
## 6. 错误处理
| 场景 | HTTP | 说明 |
|---|---|---|
| 参数缺失/非法 | 400 | 检查请求参数 |
| 凭据错误 | 401 | client_id/secret 或 token 无效 |
| 应用未启用 | 403 | 控制台检查应用状态 |
| 配额不足 | 429 | 每日额度或资源包用尽，需购买资源包 |
| 授权被拒绝 | 302 回 redirect_uri 带 `error=access_denied` | 用户点了拒绝，可提示取消 |
> 配额说明：evetide_login 产品按调用次数计量。每日免费额度用尽后自动扣减资源包；无资源包时接口返回 429。请在你的应用中对 429 做友好提示。
## 7. 安全要点
- `client_secret` 仅存后端，禁止打包进前端/App
- 严格校验回调的 `state`，防止登录 CSRF
- `access_token` 有效期 1 小时，过期需重新授权或刷新（如支持 refresh token）
- 不要在前端暴露 token，用 HttpOnly Cookie 存业务登录态
## 8. 平台能力
- 快捷登录：GitHub / Gitee / 微信 / QQ / 钉钉 / 飞书（用户侧自动绑定）
- 账号体系：邮箱+密码、验证码
- 配额：按产品独立计量，资源包按次购买