fix: oauth2文档

OAuth2-Token接口使用文档.md

@@ -0,0 +1,179 @@
+# OAuth2 Token 接口使用文档
+
+## 接口地址
+
+```
+POST http://{域名}/system/oauth2/token
+Content-Type: application/x-www-form-urlencoded
+```
+
+## 通用规则
+
+- 所有请求**必须**携带 HTTP Basic Auth 请求头：`Authorization: Basic base64(client_id:secret)`
+- 响应格式：`{"code":0,"msg":"...","data":{...}}`
+- `code=0` 表示成功
+- 默认客户端：`client_id=default`、`secret=admin123`
+
+---
+
+## 支持的授权模式
+
+### 1. 客户端模式 `client_credentials`（外部系统调用推荐）
+
+**适用场景**：机器对机器调用，无需用户登录。
+
+```bash
+curl -X POST "http://localhost:48080/system/oauth2/token" \
+  -u "default:admin123" \
+  -d "grant_type=client_credentials"
+```
+
+参数：
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `grant_type` | 是 | 固定值 `client_credentials` |
+| `scope` | 否 | 授权范围，多个用空格分隔，如 `read write` |
+
+成功响应：
+
+```json
+{
+  "code": 0,
+  "data": {
+    "access_token": "a1b2c3d4-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "refresh_token": "r1r2r3r4-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "expires_in": 7200,
+    "token_type": "bearer",
+    "scope": "read write",
+    "user_id": 0
+  }
+}
+```
+
+---
+
+### 2. 密码模式 `password`
+
+**适用场景**：用户直接用账号密码换取 token（如移动端 App 登录）。
+
+```bash
+curl -X POST "http://localhost:48080/system/oauth2/token" \
+  -u "default:admin123" \
+  -d "grant_type=password" \
+  -d "username=admin" \
+  -d "password=admin123"
+```
+
+参数：
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `grant_type` | 是 | 固定值 `password` |
+| `username` | 是 | 用户账号 |
+| `password` | 是 | 用户密码 |
+| `scope` | 否 | 授权范围，多个用空格分隔 |
+
+---
+
+### 3. 授权码模式 `authorization_code`
+
+**适用场景**：第三方应用需要用户授权后才能访问用户数据（如 SSO 单点登录）。
+
+分两步走：
+
+**第一步**：用户浏览器访问授权页，拿到 `code`
+
+```bash
+浏览器访问：
+http://localhost:48080/system/oauth2/authorize?clientId=default
+```
+
+用户确认授权后，回调地址会带上 `code` 参数。
+
+**第二步**：用 `code` 换 token
+
+```bash
+curl -X POST "http://localhost:48080/system/oauth2/token" \
+  -u "default:admin123" \
+  -d "grant_type=authorization_code" \
+  -d "code=xxxx" \
+  -d "redirect_uri=https://回调地址" \
+  -d "state=1"
+```
+
+参数：
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `grant_type` | 是 | 固定值 `authorization_code` |
+| `code` | 是 | 第一步获取的授权码 |
+| `redirect_uri` | 是 | 必须与第一步的回调地址一致 |
+| `state` | 否 | 透传的状态值，用于防 CSRF |
+
+---
+
+### 4. 刷新令牌 `refresh_token`
+
+**适用场景**：token 快过期时，用 `refresh_token` 换新 token，无需重新登录。
+
+```bash
+curl -X POST "http://localhost:48080/system/oauth2/token" \
+  -u "default:admin123" \
+  -d "grant_type=refresh_token" \
+  -d "refresh_token=r1r2r3r4-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+```
+
+参数：
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `grant_type` | 是 | 固定值 `refresh_token` |
+| `refresh_token` | 是 | 之前获取的 refresh_token |
+
+---
+
+## 其他接口
+
+### 校验 Token
+
+```bash
+curl -X POST "http://localhost:48080/system/oauth2/check-token" \
+  -u "default:admin123" \
+  -d "token=要校验的access_token"
+```
+
+### 撤销 Token（登出）
+
+```bash
+curl -X DELETE "http://localhost:48080/system/oauth2/token?token=要撤销的access_token" \
+  -u "default:admin123"
+```
+
+---
+
+## 四种模式对比
+
+| 模式 | grant_type 值 | 是否需用户参与 | 适用场景 |
+|------|-------------|-------------|---------|
+| 客户端模式 | `client_credentials` | 否 | 外部系统调用、定时任务、机器间通信 |
+| 密码模式 | `password` | 是（提供账号密码） | 移动端 App 登录、信任的客户端 |
+| 授权码模式 | `authorization_code` | 是（浏览器确认授权） | 第三方应用 SSO、开放平台 |
+| 刷新令牌 | `refresh_token` | 否 | Token 续期，配合以上任意模式使用 |
+
+---
+
+## 外部系统完整调用流程
+
+```
+① 你在后台创建 OAuth2 客户端，拿到 client_id + secret
+         │
+② 外部系统用 client_credentials 模式换 token
+   curl -u "client_id:secret" -d "grant_type=client_credentials"
+         │
+③ 拿到 access_token，之后每个请求带上
+   curl -H "Authorization: Bearer <access_token>" /admin-api/xxx
+         │
+④ token 过期前，用 refresh_token 续期
+   curl -u "client_id:secret" -d "grant_type=refresh_token" -d "refresh_token=xxx"
+```