170 lines
3.1 KiB
Markdown
170 lines
3.1 KiB
Markdown
|
# 公开接口文档（免鉴权）
|
|||
|
|
|
|||
|
|
基础路径：`/mgt/`，以下接口**不需要** JWT 认证。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1. 登录
|
|||
|
|
|
|||
|
|
**路径**：`POST /mgt/login`
|
|||
|
|
|
|||
|
|
**说明**：支持账号密码登录或 AppId/AppKey 登录，二选一。
|
|||
|
|
|
|||
|
|
**请求体**（LoginRequest）：
|
|||
|
|
|
|||
|
|
| 参数 | 类型 | 必填 | 说明 |
|
|||
|
|
|------|------|------|------|
|
|||
|
|
| account | string | 否 | 账号（与 password 一起使用） |
|
|||
|
|
| password | string | 否 | 密码 |
|
|||
|
|
| phone | string | 否 | 手机号，若使用需符合 phone 格式 |
|
|||
|
|
| phone_code | string | 否 | 手机验证码 |
|
|||
|
|
| workspace | string | 否 | 应用 workspace |
|
|||
|
|
| app_id | string | 否 | 应用 ID（与 app_key 一起使用） |
|
|||
|
|
| app_key | string | 否 | 应用密钥 |
|
|||
|
|
|
|||
|
|
**约束**：`account + password` 或 `app_id + app_key` 必须提供一组。
|
|||
|
|
|
|||
|
|
**请求示例（账号密码）**：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"account": "zhangsan",
|
|||
|
|
"password": "abc12345",
|
|||
|
|
"workspace": "my_app"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**请求示例（应用密钥）**：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"app_id": "my_app",
|
|||
|
|
"app_key": "secret_key_xxx"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**返回**（LoginResp）：
|
|||
|
|
|
|||
|
|
| 参数 | 类型 | 说明 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| token | string | JWT，后续请求放在 Header Authorization |
|
|||
|
|
| user_id | number | 用户 ID |
|
|||
|
|
| identity | string | 用户唯一标识 |
|
|||
|
|
| account | string | 账号 |
|
|||
|
|
| name | string | 姓名 |
|
|||
|
|
| phone | string | 手机号 |
|
|||
|
|
| email | string | 邮箱 |
|
|||
|
|
| avatar | string | 头像 |
|
|||
|
|
|
|||
|
|
**返回示例**：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 0,
|
|||
|
|
"data": {
|
|||
|
|
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
|||
|
|
"user_id": 1,
|
|||
|
|
"identity": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
|
|||
|
|
"account": "zhangsan",
|
|||
|
|
"name": "张三",
|
|||
|
|
"phone": "13800138000",
|
|||
|
|
"email": "zhangsan@example.com",
|
|||
|
|
"avatar": "https://example.com/avatar.png"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2. 刷新 Token
|
|||
|
|
|
|||
|
|
**路径**：`POST /mgt/refresh`
|
|||
|
|
|
|||
|
|
**说明**：基于当前请求中的 JWT 签发新 token。通常需在 Header 中带有效 Authorization。
|
|||
|
|
|
|||
|
|
**请求体**：无，或空 JSON `{}`。
|
|||
|
|
|
|||
|
|
**返回**：
|
|||
|
|
|
|||
|
|
| 参数 | 类型 | 说明 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| token | string | 新的 JWT |
|
|||
|
|
|
|||
|
|
**返回示例**：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 0,
|
|||
|
|
"data": {
|
|||
|
|
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3. 重置密码（短信验证码）
|
|||
|
|
|
|||
|
|
**路径**：`POST /mgt/reset`
|
|||
|
|
|
|||
|
|
**请求体**（ForgetPwdRequest）：
|
|||
|
|
|
|||
|
|
| 参数 | 类型 | 必填 | 说明 |
|
|||
|
|
|------|------|------|------|
|
|||
|
|
| account | string | 是 | 账号 |
|
|||
|
|
| code | string | 是 | 短信验证码 |
|
|||
|
|
| password | string | 是 | 新密码，最少 6 位 |
|
|||
|
|
| phone | string | 是 | 手机号，需符合 phone 格式 |
|
|||
|
|
|
|||
|
|
**请求示例**：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"account": "zhangsan",
|
|||
|
|
"code": "123456",
|
|||
|
|
"password": "newpass123",
|
|||
|
|
"phone": "13800138000"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**返回示例**：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 0,
|
|||
|
|
"data": "密码重置成功"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 4. 健康检查 Ping
|
|||
|
|
|
|||
|
|
**路径**：`GET /mgt/ping`
|
|||
|
|
|
|||
|
|
**说明**：无需请求体，用于健康检查。
|
|||
|
|
|
|||
|
|
**返回示例**：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"message": "Pong"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 5. Session 演示
|
|||
|
|
|
|||
|
|
**路径**：`GET /mgt/session`
|
|||
|
|
|
|||
|
|
**说明**：Session 示例接口，会写入并读取 session。
|
|||
|
|
|
|||
|
|
**返回示例**：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"message": "Pong"
|
|||
|
|
}
|
|||
|
|
```
|