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"
|
||
}
|
||
```
|