|
|
@@ -0,0 +1,681 @@
|
|
|
+# 统一认证平台（LQAI-middle-platform）接入流程及 API 接口文档
|
|
|
+
|
|
|
+> **参考样本**: 样本中心（LQAdminPlatform）已实现的统一认证接入方案
|
|
|
+> **统一认证平台地址**: `http://192.168.92.61:8200`
|
|
|
+> **统一认证平台前端**: `http://192.168.92.61:9200`
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 一、系统架构概览
|
|
|
+
|
|
|
+```
|
|
|
+┌─────────────────────────────────────────────────────────────┐
|
|
|
+│ 统一认证平台 (LQAI-middle-platform) │
|
|
|
+│ 端口: 8200 (后端) / 9200 (前端) │
|
|
|
+│ │
|
|
|
+│ 功能: │
|
|
|
+│ • 用户注册 / 登录 / 密码管理 │
|
|
|
+│ • 应用管理 (子应用注册、client_id/secret 生成) │
|
|
|
+│ • OAuth2 授权码流程 │
|
|
|
+│ • RBAC 角色权限管理 │
|
|
|
+│ • JWT Token 签发与验证 │
|
|
|
+│ • 子应用工作台（点击子应用图标触发 SSO 跳转） │
|
|
|
+│ │
|
|
|
+│ 数据存储: MySQL (lq_ai_middle_platform) + Redis │
|
|
|
+└──────────────────────┬──────────────────────────────────────┘
|
|
|
+ │ OAuth2 / HTTP
|
|
|
+ │
|
|
|
+ ┌──────────────┼──────────────┐
|
|
|
+ │ │ │
|
|
|
+ ┌────▼────┐ ┌─────▼─────┐ ┌────▼────┐
|
|
|
+ │样本中心 │ │Agent平台 │ │ 标注平台 │ ... 其他子系统
|
|
|
+ │(8000) │ │ (8002) │ │ (9003) │
|
|
|
+ └─────────┘ └───────────┘ └─────────┘
|
|
|
+```
|
|
|
+
|
|
|
+### 角色定位
|
|
|
+
|
|
|
+| 角色 | 说明 |
|
|
|
+|------|------|
|
|
|
+| **统一认证平台** (LQAI-middle-platform) | OAuth2 授权服务器（Authorization Server），同时也是一个 SSO 中心 |
|
|
|
+| **子系统** (如样本中心 LQAdminPlatform) | OAuth2 客户端（Client），同时自身也是一个小型 OAuth2 服务器，可以为下游系统提供授权 |
|
|
|
+| **子系统前端** | 负责 SSO 回调处理和 Token 交换 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 二、SSO 单点登录接入流程
|
|
|
+
|
|
|
+### 2.1 整体流程图
|
|
|
+
|
|
|
+```
|
|
|
+用户在统一认证平台工作台点击子系统图标
|
|
|
+ │
|
|
|
+ ▼
|
|
|
+① 统一认证平台后端生成 OAuth2 授权码 code
|
|
|
+ POST /auth/sso-redirect → 返回重定向URL: {frontend_url}/auth/callback?code=xxx
|
|
|
+ │
|
|
|
+ ▼
|
|
|
+② 302 重定向到子系统前端 /auth/callback?code=xxx
|
|
|
+ │
|
|
|
+ ▼
|
|
|
+③ 子系统前端 POST /api/oauth/exchange-code { "code": "xxx" }
|
|
|
+ │
|
|
|
+ ▼
|
|
|
+④ 子系统后端与统一认证平台进行后端到后端通信:
|
|
|
+ 4a. POST {SSO_BASE_URL}/oauth/token → 换取 SSO access_token
|
|
|
+ 4b. GET {SSO_BASE_URL}/oauth/userinfo → 获取用户信息+角色
|
|
|
+ │
|
|
|
+ ▼
|
|
|
+⑤ 子系统后端同步用户到本地数据库（查找或创建用户、同步角色）
|
|
|
+ │
|
|
|
+ ▼
|
|
|
+⑥ 子系统后端签发本地 JWT，返回 { token, refresh_token, user }
|
|
|
+ │
|
|
|
+ ▼
|
|
|
+⑦ 子系统前端保存 Token，跳转首页
|
|
|
+```
|
|
|
+
|
|
|
+### 2.2 详细步骤说明
|
|
|
+
|
|
|
+#### Step 1: 统一认证平台生成授权码
|
|
|
+
|
|
|
+当用户在统一认证平台前端工作台的"应用列表"中点击某个子系统图标时：
|
|
|
+
|
|
|
+- 统一认证平台后端调用 `POST /auth/sso-redirect` 接口
|
|
|
+- 后端为当前登录用户生成一个 OAuth2 授权码（authorization code），存入 Redis，有效期 10 分钟
|
|
|
+- 返回子系统的回调 URL，格式为 `{REDIRECT_URI}?code={auth_code}`
|
|
|
+
|
|
|
+#### Step 2: 重定向到子系统前端
|
|
|
+
|
|
|
+- 统一认证平台前端通过 302 重定向将用户引导至子系统前端的回调页面
|
|
|
+- URL 格式: `http://localhost:3000/auth/callback?code=xxxxxx`
|
|
|
+
|
|
|
+#### Step 3: 子系统前端调用换码接口
|
|
|
+
|
|
|
+子系统前端从 URL 参数中提取 `code`，调用子系统后端的换码接口：
|
|
|
+
|
|
|
+```typescript
|
|
|
+// 示例代码
|
|
|
+const code = new URLSearchParams(window.location.search).get('code');
|
|
|
+const response = await fetch('/api/oauth/exchange-code', {
|
|
|
+ method: 'POST',
|
|
|
+ headers: { 'Content-Type': 'application/json' },
|
|
|
+ body: JSON.stringify({ code })
|
|
|
+});
|
|
|
+const result = await response.json();
|
|
|
+// result.data.token → 本地 JWT access_token
|
|
|
+// result.data.refresh_token → 刷新令牌
|
|
|
+// result.data.user → 用户信息（含角色）
|
|
|
+```
|
|
|
+
|
|
|
+#### Step 4-5: 子系统后端与统一认证平台交互 + 同步用户
|
|
|
+
|
|
|
+子系统后端收到 `code` 后执行 `_sso_exchange_code` 核心流程：
|
|
|
+
|
|
|
+1. **用 code 换 SSO access_token** — 调用统一认证平台的 `/oauth/token` 端点
|
|
|
+2. **获取用户信息** — 调用统一认证平台的 `/oauth/userinfo` 端点
|
|
|
+3. **同步用户** — 在本地数据库查找或创建用户，同步角色信息
|
|
|
+
|
|
|
+#### Step 6-7: 签发本地 JWT 并返回
|
|
|
+
|
|
|
+- 子系统后端用自己的 `SECRET_KEY` 签发本地 JWT
|
|
|
+- 返回给前端 `{ token, refresh_token, user }`
|
|
|
+- 前端保存 Token 到 localStorage/sessionStorage，跳转首页
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 三、子系统接入前准备
|
|
|
+
|
|
|
+### 3.1 在统一认证平台注册子应用
|
|
|
+
|
|
|
+通过统一认证平台的系统管理模块（或数据库直接插入）在 `t_sys_app` 表中注册子系统：
|
|
|
+
|
|
|
+| 字段 | 说明 | 示例值 |
|
|
|
+|------|------|--------|
|
|
|
+| `name` | 子系统名称 | "样本中心" |
|
|
|
+| `app_key` | 客户端 ID（client_id），32 位随机字符串 | `WviiGL8KQE20tQhmhQPQhhJ5QpFK51F6` |
|
|
|
+| `app_secret` | 客户端密钥（client_secret），64 位随机字符串 | `9WXP88hEHJiHRSiUdmx7ip5oQPzY0bnJNsEswQoO4sk6juCplyJTcnAiZsv7e3lJ` |
|
|
|
+| `redirect_uris` | 允许的重定向 URI（JSON 数组） | `["http://localhost:3000/auth/callback"]` |
|
|
|
+| `scope` | 授权范围（JSON 数组） | `["profile", "email"]` |
|
|
|
+| `is_active` | 是否启用 | `1` |
|
|
|
+| `is_trusted` | 是否信任（跳过授权确认页） | `1` |
|
|
|
+| `home_url` | 子系统首页 URL | `http://localhost:3000` |
|
|
|
+| `icon_url` | 子系统图标 URL | 可选 |
|
|
|
+
|
|
|
+### 3.2 子系统侧配置
|
|
|
+
|
|
|
+在子系统的配置文件中添加 SSO 配置段：
|
|
|
+
|
|
|
+```ini
|
|
|
+[sso]
|
|
|
+SSO_BASE_URL=http://192.168.92.61:8200
|
|
|
+CLIENT_ID=WviiGL8KQE20tQhmhQPQhhJ5QpFK51F6
|
|
|
+CLIENT_SECRET=9WXP88hEHJiHRSiUdmx7ip5oQPzY0bnJNsEswQoO4sk6juCplyJTcnAiZsv7e3lJ
|
|
|
+REDIRECT_URI=http://localhost:3000/auth/callback
|
|
|
+FRONTEND_URL=http://localhost:3000
|
|
|
+SCOPE=email
|
|
|
+SSO_LOGOUT_REDIRECT_URL=http://192.168.92.61:9200/login
|
|
|
+```
|
|
|
+
|
|
|
+> **注意**: `CLIENT_ID` 和 `CLIENT_SECRET` 必须与统一认证平台 `t_sys_app` 表中注册的 `app_key` 和 `app_secret` 一致。
|
|
|
+
|
|
|
+### 3.3 角色映射
|
|
|
+
|
|
|
+子系统需要确保本地 `t_sys_role` 表中存在与统一认证平台对应的角色。样本中心的角色包括：
|
|
|
+
|
|
|
+| 统一认证平台角色 code | 说明 |
|
|
|
+|----------------------|------|
|
|
|
+| `super_admin` | 超级管理员 |
|
|
|
+| `sam_sys_admin` | 样本中心系统管理员 |
|
|
|
+| `sam_data_operator` | 样本中心数据操作员 |
|
|
|
+
|
|
|
+统一认证平台 `/oauth/userinfo` 返回的 `roles` 字段格式为对象数组：
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "roles": [
|
|
|
+ { "name": "超级管理员", "code": "super_admin" },
|
|
|
+ { "name": "样本中心系统管理员", "code": "sam_sys_admin" }
|
|
|
+ ]
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+子系统从每个对象中提取 `code` 字段进行角色匹配和本地同步。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 四、统一认证平台核心 API 接口
|
|
|
+
|
|
|
+以下接口由 **统一认证平台（LQAI-middle-platform，端口 8200）** 提供，子系统需要调用。
|
|
|
+
|
|
|
+### 4.1 获取 SSO 授权 URL
|
|
|
+
|
|
|
+> 供子系统前端构建"跳转到统一认证平台登录"的链接
|
|
|
+
|
|
|
+- **接口**: `GET /oauth/authorize`
|
|
|
+- **认证**: 不需要
|
|
|
+
|
|
|
+| 参数 | 类型 | 必填 | 说明 |
|
|
|
+|------|------|------|------|
|
|
|
+| `response_type` | string | 是 | 固定值 `code` |
|
|
|
+| `client_id` | string | 是 | 子应用的 app_key |
|
|
|
+| `redirect_uri` | string | 是 | 回调地址（必须在 t_sys_app 中注册过） |
|
|
|
+| `scope` | string | 否 | 授权范围，空格分隔，默认 `profile` |
|
|
|
+| `state` | string | 否 | 防 CSRF 状态参数 |
|
|
|
+
|
|
|
+**响应**: 302 重定向（如果用户已登录则重定向到 `redirect_uri?code=xxx`，未登录则重定向到登录页面）
|
|
|
+
|
|
|
+### 4.2 获取授权码 URL（SSO 免登）
|
|
|
+
|
|
|
+> 统一认证平台内部使用，当用户点击子系统图标时调用
|
|
|
+
|
|
|
+- **接口**: `POST /auth/sso-redirect`
|
|
|
+- **认证**: 需要用户已登录统一认证平台
|
|
|
+- **请求体**:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "client_id": "WviiGL8KQE20tQhmhQPQhhJ5QpFK51F6",
|
|
|
+ "redirect_uri": "http://localhost:3000/auth/callback"
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+- **响应**:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": "000000",
|
|
|
+ "message": "success",
|
|
|
+ "data": {
|
|
|
+ "redirect_url": "http://localhost:3000/auth/callback?code=xxxxxx"
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 4.3 令牌交换端点
|
|
|
+
|
|
|
+> **子系统后端调用此接口，用授权码换取 SSO access_token**
|
|
|
+
|
|
|
+- **接口**: `POST /oauth/token`
|
|
|
+- **Content-Type**: `application/x-www-form-urlencoded`
|
|
|
+- **认证**: 不需要
|
|
|
+
|
|
|
+| 参数 | 类型 | 必填 | 说明 |
|
|
|
+|------|------|------|------|
|
|
|
+| `grant_type` | string | 是 | 固定值 `authorization_code` |
|
|
|
+| `code` | string | 是 | 授权码 |
|
|
|
+| `redirect_uri` | string | 是 | 与 Step 1 中使用的 redirect_uri 一致 |
|
|
|
+| `client_id` | string | 是 | 子应用的 app_key |
|
|
|
+| `client_secret` | string | 是 | 子应用的 app_secret |
|
|
|
+
|
|
|
+**成功响应** (200):
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "access_token": "eyJhbGciOiJIUzI1NiIs...",
|
|
|
+ "token_type": "Bearer",
|
|
|
+ "expires_in": 7200,
|
|
|
+ "refresh_token": "xxxxxxxxxxxxxxxxxxxx",
|
|
|
+ "scope": "profile email"
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**失败响应**:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "error": "invalid_grant",
|
|
|
+ "error_description": "授权码无效"
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+| error 值 | 说明 |
|
|
|
+|----------|------|
|
|
|
+| `invalid_request` | 缺少必填参数 |
|
|
|
+| `unsupported_grant_type` | grant_type 不支持 |
|
|
|
+| `invalid_client` | client_id 或 client_secret 错误 |
|
|
|
+| `invalid_grant` | 授权码无效/已使用/过期，或 redirect_uri 不匹配 |
|
|
|
+
|
|
|
+### 4.4 获取用户信息
|
|
|
+
|
|
|
+> **子系统后端调用此接口，获取当前登录用户的详细信息**
|
|
|
+
|
|
|
+- **接口**: `GET /oauth/userinfo`
|
|
|
+- **认证**: Bearer Token（使用 4.3 返回的 access_token）
|
|
|
+
|
|
|
+**请求头**:
|
|
|
+
|
|
|
+```
|
|
|
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
|
|
|
+```
|
|
|
+
|
|
|
+**成功响应** (200):
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "sub": "user_xxx",
|
|
|
+ "username": "admin",
|
|
|
+ "email": "admin@example.com",
|
|
|
+ "avatar_url": "https://...",
|
|
|
+ "real_name": "管理员",
|
|
|
+ "company": "四川路桥",
|
|
|
+ "department": "技术部",
|
|
|
+ "position": "工程师",
|
|
|
+ "roles": [
|
|
|
+ { "name": "超级管理员", "code": "super_admin" },
|
|
|
+ { "name": "样本中心系统管理员", "code": "sam_sys_admin" }
|
|
|
+ ]
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+> 返回的字段根据 token 的 scope 过滤：`profile` scope 返回基本信息，`email` scope 返回邮箱，`phone` scope 返回手机号。
|
|
|
+
|
|
|
+**失败响应**:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "error": "invalid_token",
|
|
|
+ "error_description": "User not found or inactive"
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 五、子系统侧需要实现的 API 接口
|
|
|
+
|
|
|
+以下是子系统（如样本中心）自身需要实现的接口，用于完成 SSO 接入。
|
|
|
+
|
|
|
+### 5.1 授权码交换接口（核心免登接口）
|
|
|
+
|
|
|
+- **接口**: `POST /api/oauth/exchange-code`
|
|
|
+- **Content-Type**: `application/json`
|
|
|
+- **认证**: 不需要
|
|
|
+- **用途**: 前端收到 SSO 回调的 code 后，调用此接口换取本地 JWT
|
|
|
+
|
|
|
+**请求体**:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": "xxxxxx"
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**成功响应**:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": "000000",
|
|
|
+ "message": "登录成功",
|
|
|
+ "data": {
|
|
|
+ "token": "eyJhbGciOiJIUzI1NiIs...",
|
|
|
+ "refresh_token": "xxxxxxxxxxxxxxxxxxxx",
|
|
|
+ "user": {
|
|
|
+ "id": "user_xxx",
|
|
|
+ "username": "admin",
|
|
|
+ "email": "admin@example.com",
|
|
|
+ "phone": "138xxxx",
|
|
|
+ "is_superuser": true,
|
|
|
+ "is_active": true,
|
|
|
+ "roles": ["super_admin", "sam_sys_admin"]
|
|
|
+ }
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**失败响应**:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": "100001",
|
|
|
+ "message": "缺少授权码",
|
|
|
+ "data": null
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": "500001",
|
|
|
+ "message": "登录失败: 获取令牌失败",
|
|
|
+ "data": null
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 5.2 获取 SSO 授权 URL
|
|
|
+
|
|
|
+- **接口**: `GET /auth/sso/authorize`
|
|
|
+- **认证**: 不需要
|
|
|
+
|
|
|
+| 参数 | 类型 | 必填 | 说明 |
|
|
|
+|------|------|------|------|
|
|
|
+| `redirect` | bool | 否 | 为 true 时直接 302 重定向到 SSO 授权页 |
|
|
|
+
|
|
|
+**响应** (redirect=false):
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": "000000",
|
|
|
+ "message": "获取授权URL成功",
|
|
|
+ "data": {
|
|
|
+ "authorize_url": "http://192.168.92.61:8200/oauth/authorize?client_id=xxx&redirect_uri=xxx&response_type=code&scope=email"
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 5.3 SSO 回调端点（旧流程，后端 302 重定向方式）
|
|
|
+
|
|
|
+- **接口**: `GET /auth/callback`
|
|
|
+- **认证**: 不需要
|
|
|
+
|
|
|
+| 参数 | 类型 | 必填 | 说明 |
|
|
|
+|------|------|------|------|
|
|
|
+| `code` | string | 是 | SSO 授权码 |
|
|
|
+| `error` | string | 否 | SSO 返回的错误码 |
|
|
|
+| `error_description` | string | 否 | 错误描述 |
|
|
|
+| `state` | string | 否 | 状态参数 |
|
|
|
+
|
|
|
+**响应**: 302 重定向到 `前端URL/oauth/callback?token=xxx&refresh_token=xxx`
|
|
|
+
|
|
|
+> **注意**: 这是旧流程，建议使用 `POST /api/oauth/exchange-code` 的新流程（前端直接调用 API 换码，不依赖后端 302 重定向）。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 六、子系统侧的其他认证相关 API
|
|
|
+
|
|
|
+除了 SSO 接入外，子系统还需要提供标准认证接口供前端使用。
|
|
|
+
|
|
|
+### 6.1 本地密码登录
|
|
|
+
|
|
|
+- **接口**: `POST /api/v1/auth/login`
|
|
|
+- **Content-Type**: `application/json`
|
|
|
+
|
|
|
+**请求体**:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "username": "admin",
|
|
|
+ "password": "Admin123456",
|
|
|
+ "remember_me": false
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**响应**:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": "000000",
|
|
|
+ "message": "登录成功",
|
|
|
+ "data": {
|
|
|
+ "access_token": "eyJ...",
|
|
|
+ "refresh_token": "xxx...",
|
|
|
+ "token_type": "Bearer",
|
|
|
+ "expires_in": 1200
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 6.2 刷新 Token
|
|
|
+
|
|
|
+- **接口**: `POST /api/v1/auth/refresh`
|
|
|
+- **请求体**: `{ "refresh_token": "xxx" }`
|
|
|
+
|
|
|
+### 6.3 登出
|
|
|
+
|
|
|
+- **接口**: `POST /api/v1/auth/logout`
|
|
|
+- **请求体**: `{ "token": "xxx", "refresh_token": "xxx" }`
|
|
|
+- **响应** (含 SSO 登出重定向 URL):
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": "000000",
|
|
|
+ "message": "登出成功",
|
|
|
+ "data": {
|
|
|
+ "sso_logout_url": "http://192.168.92.61:9200/login"
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 6.4 获取当前用户信息
|
|
|
+
|
|
|
+- **接口**: `GET /api/v1/auth/userinfo` 或 `GET /api/v1/auth/me`
|
|
|
+- **认证**: Bearer Token
|
|
|
+- **响应**:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": "000000",
|
|
|
+ "data": {
|
|
|
+ "id": "user_xxx",
|
|
|
+ "username": "admin",
|
|
|
+ "email": "admin@example.com",
|
|
|
+ "phone": "138xxxx",
|
|
|
+ "roles": ["super_admin"],
|
|
|
+ "permissions": []
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 6.5 获取验证码
|
|
|
+
|
|
|
+- **接口**: `GET /api/v1/auth/captcha`
|
|
|
+- **认证**: 不需要
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 七、统一认证平台的 OAuth2 服务端 API
|
|
|
+
|
|
|
+统一认证平台自身也是一个 OAuth2 授权服务器，可以为下游子系统提供 OAuth2 服务。
|
|
|
+
|
|
|
+### 7.1 应用管理（系统管理员操作）
|
|
|
+
|
|
|
+通过统一认证平台的系统管理模块管理子应用，相关接口前缀 `/api/v1`：
|
|
|
+
|
|
|
+| 方法 | 路径 | 说明 |
|
|
|
+|------|------|------|
|
|
|
+| `GET` | `/api/v1/system/app/list` | 获取应用列表 |
|
|
|
+| `POST` | `/api/v1/system/app/create` | 创建应用（自动生成 app_key/app_secret） |
|
|
|
+| `PUT` | `/api/v1/system/app/update/{id}` | 更新应用信息 |
|
|
|
+| `DELETE` | `/api/v1/system/app/delete/{id}` | 删除应用 |
|
|
|
+| `POST` | `/api/v1/system/app/reset_secret/{id}` | 重置应用密钥 |
|
|
|
+| `GET` | `/api/v1/system/app/accessible` | 获取当前用户可访问的应用列表 |
|
|
|
+
|
|
|
+### 7.2 角色管理
|
|
|
+
|
|
|
+| 方法 | 路径 | 说明 |
|
|
|
+|------|------|------|
|
|
|
+| `GET` | `/api/v1/system/role/list` | 获取角色列表 |
|
|
|
+| `POST` | `/api/v1/system/role/create` | 创建角色 |
|
|
|
+| `PUT` | `/api/v1/system/role/update/{id}` | 更新角色 |
|
|
|
+| `DELETE` | `/api/v1/system/role/delete/{id}` | 删除角色 |
|
|
|
+| `GET` | `/api/external/v1/system/role/user_list/{role_code}` | 按角色 code 查询用户列表 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 八、Token 机制说明
|
|
|
+
|
|
|
+### 8.1 统一认证平台侧 Token
|
|
|
+
|
|
|
+| Token 类型 | 有效期 | 存储方式 | 说明 |
|
|
|
+|-----------|--------|---------|------|
|
|
|
+| Access Token | 30 分钟（默认）| Redis (`auth:access:{user_id}:{token}`) | 访问令牌，含用户身份和角色 |
|
|
|
+| Refresh Token | 30 天 | Redis (`auth:refresh:{user_id}:{token}`) | 刷新令牌，用于换取新 Access Token |
|
|
|
+| OAuth Access Token | 120 分钟 | Redis (`auth:oauth_access:{client_id}:{token}`) | OAuth2 流程中颁发给子应用的令牌 |
|
|
|
+| OAuth Authorization Code | 10 分钟 | Redis (`auth:oauth_code:{code}`) | 一次性授权码，使用后即失效 |
|
|
|
+
|
|
|
+### 8.2 子系统侧 Token
|
|
|
+
|
|
|
+| Token 类型 | 有效期 | 存储方式 | 说明 |
|
|
|
+|-----------|--------|---------|------|
|
|
|
+| Access Token | 20 分钟 | MySQL + Redis | 子系统本地登录令牌 |
|
|
|
+| Refresh Token | 24 小时 | MySQL + Redis | 刷新令牌 |
|
|
|
+
|
|
|
+### 8.3 滑动过期机制
|
|
|
+
|
|
|
+子系统实现了 JWT Token 的滑动过期机制：
|
|
|
+
|
|
|
+- 当 Token 使用时间超过其总生命周期的 **50%** 时，中间件会自动生成新 Token
|
|
|
+- 新 Token 通过响应头 `X-New-Token` 返回给前端
|
|
|
+- 前端检测到 `X-New-Token` 后替换本地旧 Token
|
|
|
+- 无需前端主动刷新即可保持登录状态
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 九、前端接入参考代码
|
|
|
+
|
|
|
+### 9.1 SSO 免登流程（推荐方式）
|
|
|
+
|
|
|
+```typescript
|
|
|
+// 1. 统一认证平台重定向到子系统前端，URL 携带 code 参数
|
|
|
+// 例如: http://localhost:3000/auth/callback?code=xxxxxx
|
|
|
+
|
|
|
+// 2. 在回调页面中提取 code 并调用换码接口
|
|
|
+const code = new URLSearchParams(window.location.search).get('code');
|
|
|
+
|
|
|
+if (code) {
|
|
|
+ const response = await fetch('/api/oauth/exchange-code', {
|
|
|
+ method: 'POST',
|
|
|
+ headers: { 'Content-Type': 'application/json' },
|
|
|
+ body: JSON.stringify({ code })
|
|
|
+ });
|
|
|
+ const result = await response.json();
|
|
|
+
|
|
|
+ if (result.code === '000000') {
|
|
|
+ // 3. 保存 Token
|
|
|
+ localStorage.setItem('token', result.data.token);
|
|
|
+ localStorage.setItem('refresh_token', result.data.refresh_token);
|
|
|
+ localStorage.setItem('user', JSON.stringify(result.data.user));
|
|
|
+
|
|
|
+ // 4. 跳转到首页
|
|
|
+ router.push('/home');
|
|
|
+ } else {
|
|
|
+ // 登录失败，跳回登录页
|
|
|
+ router.push(`/login?error=${result.message}`);
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 9.2 前端请求拦截器（携带 Token）
|
|
|
+
|
|
|
+```typescript
|
|
|
+// Axios 请求拦截器示例
|
|
|
+axios.interceptors.request.use(config => {
|
|
|
+ const token = localStorage.getItem('token');
|
|
|
+ if (token) {
|
|
|
+ config.headers.Authorization = `Bearer ${token}`;
|
|
|
+ }
|
|
|
+ return config;
|
|
|
+});
|
|
|
+
|
|
|
+// 响应拦截器处理 Token 刷新
|
|
|
+axios.interceptors.response.use(
|
|
|
+ response => {
|
|
|
+ const newToken = response.headers['x-new-token'];
|
|
|
+ if (newToken) {
|
|
|
+ localStorage.setItem('token', newToken);
|
|
|
+ }
|
|
|
+ return response;
|
|
|
+ },
|
|
|
+ error => {
|
|
|
+ if (error.response?.status === 401) {
|
|
|
+ // Token 过期，清除并跳转登录
|
|
|
+ localStorage.removeItem('token');
|
|
|
+ localStorage.removeItem('refresh_token');
|
|
|
+ router.push('/login');
|
|
|
+ }
|
|
|
+ return Promise.reject(error);
|
|
|
+ }
|
|
|
+);
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 十、接入 Checklist
|
|
|
+
|
|
|
+- [ ] 在统一认证平台注册子应用，获取 `client_id` 和 `client_secret`
|
|
|
+- [ ] 在子应用配置文件中添加 `[sso]` 配置段
|
|
|
+- [ ] 子应用后端实现 `POST /api/oauth/exchange-code` 换码接口
|
|
|
+- [ ] 子应用前端实现回调页面 `/auth/callback`，从 URL 提取 code 并调换码接口
|
|
|
+- [ ] 子应用本地数据库初始化角色表（`t_sys_role`），确保角色 code 与统一认证平台一致
|
|
|
+- [ ] 子应用配置 CORS 允许前端域名访问
|
|
|
+- [ ] 配置 Token 滑动过期中间件
|
|
|
+- [ ] 配置登出时返回 SSO 登出重定向 URL
|
|
|
+- [ ] 测试完整 SSO 流程：统一认证平台登录 → 点击子系统 → 自动免登进入子系统
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 十一、错误码说明
|
|
|
+
|
|
|
+### 统一响应格式
|
|
|
+
|
|
|
+所有接口使用统一的响应格式：
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": "000000",
|
|
|
+ "message": "success",
|
|
|
+ "data": { ... },
|
|
|
+ "timestamp": "2026-05-10T12:00:00Z"
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 业务错误码
|
|
|
+
|
|
|
+| 错误码 | 说明 |
|
|
|
+|--------|------|
|
|
|
+| `000000` | 成功 |
|
|
|
+| `100001` | 缺少授权码 |
|
|
|
+| `400001` | SSO 授权码无效 |
|
|
|
+| `400002` | SSO 用户信息格式异常 |
|
|
|
+| `500001` | 服务器内部错误 |
|
|
|
+
|
|
|
+### OAuth2 标准错误
|
|
|
+
|
|
|
+| error | 说明 |
|
|
|
+|-------|------|
|
|
|
+| `invalid_request` | 请求参数不完整或格式错误 |
|
|
|
+| `invalid_client` | client_id 或 client_secret 错误 |
|
|
|
+| `invalid_grant` | 授权码无效、已使用、过期或 redirect_uri 不匹配 |
|
|
|
+| `invalid_scope` | 请求的 scope 超出应用注册范围 |
|
|
|
+| `unsupported_response_type` | response_type 不支持（仅支持 code） |
|
|
|
+| `unsupported_grant_type` | grant_type 不支持（仅支持 authorization_code） |
|
|
|
+| `access_denied` | 用户拒绝授权 |
|
|
|
+| `server_error` | 服务器内部错误 |
|
