830 lines
24 KiB
Markdown
830 lines
24 KiB
Markdown
# 用户认证登录API文档
|
||
|
||
## 目录
|
||
1. [用户登录](#用户登录)
|
||
2. [获取用户信息](#获取用户信息)
|
||
3. [获取具有指定权限的用户列表](#获取具有指定权限的用户列表)
|
||
|
||
## 📋 文档说明
|
||
|
||
本文档记录用户认证、登录、用户信息管理等相关 API 接口。
|
||
|
||
**依赖文档**: 请先阅读 [API 文档基础规范.md](./API文档基础规范.md) 了解通用规范。
|
||
|
||
**统一身份认证**: 前端「统一认证登录」按钮的完整业务流程、CAS OAuth2.0 接入说明及排查指南，请参阅 [统一身份认证接入说明.md](../统一身份认证接入说明.md)。
|
||
|
||
---
|
||
|
||
## 🔐 用户认证
|
||
|
||
### 用户登录
|
||
|
||
**接口地址**: `POST /auth/login`
|
||
|
||
**接口描述**: 用户登录认证接口，支持密码登录。请求数据使用 AES+RSA 混合加密传输，确保安全性。
|
||
|
||
**权限要求**: 无需认证（公开接口）
|
||
|
||
**安全机制**:
|
||
|
||
- **数据加密**: 请求参数使用 AES 对称加密
|
||
- **密钥保护**: AES 密钥使用 RSA 非对称加密
|
||
- **自动解密**: 后端自动解密请求数据和响应数据
|
||
|
||
**请求头配置**:
|
||
|
||
```json
|
||
{
|
||
"Content-Type": "application/json;charset=utf-8",
|
||
"clientid": "e5cd7e4891bf95d1d19206ce24a7b32e",
|
||
"encrypt-key": "[RSA加密的AES密钥]",
|
||
"referer": "http://localhost/login?redirect=%252Findex",
|
||
"Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8",
|
||
"isToken": "false",
|
||
"isEncrypt": "true",
|
||
"repeatSubmit": "false"
|
||
}
|
||
```
|
||
|
||
**关键请求头说明**:
|
||
|
||
| 请求头名 | 必填 | 说明 | 示例值 |
|
||
| ----------- | ---- | --------------------------------- | -------------------------------------------- |
|
||
| clientid | 是 | 客户端 ID，用于身份验证 | "e5cd7e4891bf95d1d19206ce24a7b32e" |
|
||
| encrypt-key | 是 | RSA 加密的 AES 密钥，用于数据解密 | "Q8Td0si9R3EYj3pFe50rzn/8wxo69Y9uR6LE..." |
|
||
| referer | 是 | 来源页面地址，用于请求来源验证 | "http://localhost/login?redirect=%252Findex" |
|
||
|
||
**加密流程说明**:
|
||
|
||
1. 前端生成随机 AES 密钥（32 位字符串）
|
||
2. 使用 AES-ECB-PKCS7 模式加密请求数据
|
||
3. 使用 RSA 公钥加密 AES 密钥
|
||
4. 将加密后的 AES 密钥放入请求头`encrypt-key`
|
||
5. 后端使用 RSA 私钥解密 AES 密钥，再解密请求数据
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|
||
| --------- | ------ | ---- | ------------------------------------ | ---------------------------------- |
|
||
| tenantId | string | 是 | 租户 ID，多租户系统标识 | "000000" |
|
||
| username | string | 是 | 用户名，长度 2-30 字符 | "admin" |
|
||
| password | string | 是 | 用户密码，长度 5-30 字符 | "admin123" |
|
||
| clientId | string | 是 | 客户端 ID，用于权限控制 | "e5cd7e4891bf95d1d19206ce24a7b32e" |
|
||
| grantType | string | 是 | 授权类型，目前支持 password | "password" |
|
||
| code | string | 否 | 验证码（当系统开启验证码时必填） | "1234" |
|
||
| uuid | string | 否 | 验证码唯一标识（当需要验证码时必填） | "uuid-string" |
|
||
|
||
**请求示例**:
|
||
|
||
```json
|
||
{
|
||
"tenantId": "000000",
|
||
"username": "admin",
|
||
"password": "admin123",
|
||
"clientId": "e5cd7e4891bf95d1d19206ce24a7b32e",
|
||
"grantType": "password"
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJsb2dpblR5cGUiOiJsb2dpbiIsImxvZ2luSWQiOiJzeXNfdXNlcjoxIiwicm5TdHIiOiJ5MlhvbHRnd1Y2YjUzRnRMVzF4SFR1anRSUERjeGdmYyIsImNsaWVudGlkIjoiZTVjZDdlNDg5MWJmOTVkMWQxOTIwNmNlMjRhN2IzMmUiLCJ0ZW5hbnRJZCI6IjAwMDAwMCIsInVzZXJJZCI6MSwidXNlck5hbWUiOiJhZG1pbiIsImRlcHRJZCI6MTAzLCJkZXB0TmFtZSI6IuaZuuiDveaOp-WItuWtpumZoiIsImRlcHRDYXRlZ29yeSI6IiIsIm5pY2tOYW1lIjoi55av54uC55qE54uu5a2QTGkifQ.WI6iY3AgwPz7ceI8WDsVy-GaTXZnU-JKUYUTjhQdoKM",
|
||
"refresh_token": null,
|
||
"expire_in": 604800,
|
||
"refresh_expire_in": null,
|
||
"client_id": "e5cd7e4891bf95d1d19206ce24a7b32e",
|
||
"scope": null,
|
||
"openid": null
|
||
}
|
||
}
|
||
```
|
||
|
||
**实际 Token 解析信息**:
|
||
|
||
| 字段名 | 值 | 说明 |
|
||
| --------- | ----------------- | --------- |
|
||
| userId | 1 | 用户 ID |
|
||
| userName | admin | 用户名 |
|
||
| nickName | 疯狂狮子 Li | 用户昵称 |
|
||
| deptId | 103 | 部门 ID |
|
||
| deptName | 智胜技术开发团队 | 部门名称 |
|
||
| tenantId | 000000 | 租户 ID |
|
||
| clientId | e5cd7e4891bf95... | 客户端 ID |
|
||
| loginType | login | 登录类型 |
|
||
|
||
**Token 有效期**: 7 天 (604800 秒)
|
||
|
||
**响应参数说明**:
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
| ----------------- | ------ | ------------------------------ |
|
||
| access_token | string | 访问令牌，用于 API 调用认证 |
|
||
| refresh_token | string | 刷新令牌，用于获取新的访问令牌 |
|
||
| expire_in | long | 访问令牌过期时间（秒） |
|
||
| refresh_expire_in | long | 刷新令牌过期时间（秒） |
|
||
| client_id | string | 客户端 ID |
|
||
| scope | string | 权限范围 |
|
||
| openid | string | 第三方登录标识（可为空） |
|
||
|
||
**多种登录方式支持**:
|
||
|
||
系统采用策略模式，支持多种登录方式：
|
||
|
||
1. **密码登录** (`grantType: "password"`)
|
||
|
||
- 使用用户名和密码登录
|
||
- 支持验证码验证（可配置开关）
|
||
- BCrypt 密码加密存储
|
||
|
||
2. **邮箱登录** (`grantType: "email"`)
|
||
|
||
- 使用邮箱和邮箱验证码登录
|
||
- 需要先发送邮箱验证码
|
||
|
||
3. **短信登录** (`grantType: "sms"`)
|
||
|
||
- 使用手机号和短信验证码登录
|
||
- 需要先发送短信验证码
|
||
|
||
4. **小程序登录** (`grantType: "xcx"`)
|
||
- 微信小程序授权登录
|
||
- 需要小程序码和应用 ID
|
||
|
||
**错误码说明**:
|
||
|
||
| 错误码 | 错误信息 | 说明 | 解决方案 |
|
||
| ------ | ---------------------------- | ----------------------- | ---------------------- |
|
||
| 400 | 参数校验失败 | 请求参数格式错误 | 检查参数格式和必填字段 |
|
||
| 400 | 客户端 id 异常 | clientId 不存在或被禁用 | 检查 clientId 配置 |
|
||
| 400 | 授权类型不正确 | grantType 不支持 | 使用支持的授权类型 |
|
||
| 400 | 当前系统没有开启注册功能 | 租户未开启注册 | 联系管理员开启注册功能 |
|
||
| 401 | 用户不存在 | 用户名不存在 | 检查用户名是否正确 |
|
||
| 401 | 用户已被停用 | 用户账号被禁用 | 联系管理员激活账号 |
|
||
| 401 | 密码错误 | 用户密码不正确 | 检查密码是否正确 |
|
||
| 401 | 验证码已过期 | 验证码超时 | 重新获取验证码 |
|
||
| 401 | 验证码错误 | 验证码输入错误 | 检查验证码是否正确 |
|
||
| 403 | 登录失败次数过多，账户已锁定 | 密码错误次数超限 | 等待解锁或联系管理员 |
|
||
| 500 | 租户不存在 | tenantId 无效 | 检查租户配置 |
|
||
|
||
**安全特性**:
|
||
|
||
1. **密码安全**:
|
||
|
||
- BCrypt 哈希加密存储
|
||
- 登录失败次数限制
|
||
- 账户自动锁定机制
|
||
|
||
2. **传输安全**:
|
||
|
||
- AES+RSA 混合加密
|
||
- 防重放攻击保护
|
||
- HTTPS 协议传输
|
||
|
||
3. **会话安全**:
|
||
|
||
- JWT Token 认证
|
||
- Token 自动过期机制
|
||
- 刷新 Token 机制
|
||
|
||
4. **多租户安全**:
|
||
- 租户隔离验证
|
||
- 客户端权限控制
|
||
- 不同设备类型支持
|
||
|
||
**实际使用示例**:
|
||
|
||
```javascript
|
||
// 完整的登录实现示例（AES+RSA加密）
|
||
const axios = require('axios');
|
||
const CryptoJS = require('crypto-js');
|
||
const NodeRSA = require('node-rsa');
|
||
|
||
async function loginWithEncryption(username = 'admin', password = 'admin123') {
|
||
// 配置信息
|
||
const CONFIG = {
|
||
url: 'http://localhost/dev-api/auth/login',
|
||
clientId: 'e5cd7e4891bf95d1d19206ce24a7b32e',
|
||
tenantId: '000000',
|
||
referer: 'http://localhost/login?redirect=%252Findex',
|
||
rsaKey: 'MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAKoR8mX0rGKLqzcWmOzbfj64K8ZIgOdHnzkXSOVOZbFu/TJhZ7rFAN+eaGkl3C4buccQd/EjEsj9ir7ijT7h96MCAwEAAQ==',
|
||
};
|
||
|
||
// 生成32位随机AES密钥
|
||
function generateAESKey() {
|
||
const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
|
||
let result = '';
|
||
for (let i = 0; i < 32; i++) {
|
||
result += chars.charAt(Math.floor(Math.random() * chars.length));
|
||
}
|
||
return result;
|
||
}
|
||
|
||
// AES加密
|
||
function aesEncrypt(data, key) {
|
||
const keyUtf8 = CryptoJS.enc.Utf8.parse(key);
|
||
return CryptoJS.AES.encrypt(data, keyUtf8, {
|
||
mode: CryptoJS.mode.ECB,
|
||
padding: CryptoJS.pad.Pkcs7,
|
||
}).toString();
|
||
}
|
||
|
||
// RSA加密AES密钥
|
||
function rsaEncrypt(aesKey) {
|
||
const pemKey = `-----BEGIN PUBLIC KEY-----\n${CONFIG.rsaKey}\n-----END PUBLIC KEY-----`;
|
||
const rsaKey = new NodeRSA(pemKey);
|
||
rsaKey.setOptions({ encryptionScheme: 'pkcs1' });
|
||
const aesKeyBase64 = CryptoJS.enc.Base64.stringify(CryptoJS.enc.Utf8.parse(aesKey));
|
||
return rsaKey.encrypt(aesKeyBase64, 'base64');
|
||
}
|
||
|
||
// 生成AES密钥并加密登录数据
|
||
const aesKey = generateAESKey();
|
||
const loginData = {
|
||
tenantId: CONFIG.tenantId,
|
||
username: username,
|
||
password: password,
|
||
clientId: CONFIG.clientId,
|
||
grantType: 'password',
|
||
};
|
||
|
||
const encryptedData = aesEncrypt(JSON.stringify(loginData), aesKey);
|
||
const encryptedKey = rsaEncrypt(aesKey);
|
||
|
||
// 设置请求头
|
||
const headers = {
|
||
'Content-Type': 'application/json;charset=utf-8',
|
||
clientid: CONFIG.clientId,
|
||
'encrypt-key': encryptedKey,
|
||
referer: CONFIG.referer,
|
||
'Accept-Language': 'zh-CN,zh;q=0.9,en;q=0.8',
|
||
isToken: 'false',
|
||
isEncrypt: 'true',
|
||
repeatSubmit: 'false',
|
||
};
|
||
|
||
// 发送登录请求
|
||
const response = await axios.post(CONFIG.url, encryptedData, {
|
||
headers: headers,
|
||
timeout: 10000,
|
||
});
|
||
|
||
if (response.data.code === 200 && response.data.data?.access_token) {
|
||
return response.data.data.access_token;
|
||
} else {
|
||
throw new Error(response.data.msg || 'Login failed');
|
||
}
|
||
}
|
||
|
||
// 使用示例
|
||
loginWithEncryption()
|
||
.then((token) => {
|
||
console.log('Login successful, token:', token);
|
||
})
|
||
.catch((error) => {
|
||
console.error('Login failed:', error.message);
|
||
});
|
||
```
|
||
|
||
**快速测试脚本**:
|
||
|
||
项目中提供了完整的测试脚本，位于`test/`目录：
|
||
|
||
- `test/custom-login-script.js` - 完整功能版
|
||
- `test/quick-token-getter.js` - 快速获取版
|
||
- `test/登录脚本使用说明.md` - 详细使用文档
|
||
|
||
### 退出登录
|
||
|
||
**接口地址**: `POST /auth/logout`
|
||
|
||
**接口描述**: 用户退出登录，清除服务端会话信息
|
||
|
||
**权限要求**: 需要登录
|
||
|
||
**请求参数**: 无需请求体
|
||
|
||
**请求头**:
|
||
|
||
```json
|
||
{
|
||
"Authorization": "Bearer {access_token}"
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "退出成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**功能说明**:
|
||
|
||
- 清除服务端 Token 会话
|
||
- 关闭 SSE 连接（如果开启）
|
||
- 清理用户登录状态
|
||
|
||
### 获取验证码
|
||
|
||
**接口地址**: `GET /auth/code`
|
||
|
||
**接口描述**: 获取图形验证码，用于登录时的安全验证
|
||
|
||
**权限要求**: 无需认证
|
||
|
||
**请求参数**: 无
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"uuid": "d7c2c4c4-4e9d-4a5f-9c1a-2b3c4d5e6f7g",
|
||
"img": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGQAAABH..."
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应参数说明**:
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
| ------ | ------ | ----------------------- |
|
||
| uuid | string | 验证码唯一标识 |
|
||
| img | string | Base64 编码的验证码图片 |
|
||
|
||
**使用流程**:
|
||
|
||
1. 前端调用此接口获取验证码图片和 UUID
|
||
2. 用户输入验证码
|
||
3. 登录时将验证码和 UUID 一起提交
|
||
4. 服务端验证验证码的正确性和有效性
|
||
|
||
---
|
||
|
||
## 👤 用户信息
|
||
|
||
### 获取当前用户信息
|
||
|
||
**接口地址**: `GET /system/user/getInfo`
|
||
|
||
**接口描述**: 获取当前登录用户的详细信息，包括角色权限等
|
||
|
||
**权限要求**: 需要登录
|
||
|
||
**请求参数**: 无
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"user": {
|
||
"userId": 1,
|
||
"userName": "admin",
|
||
"nickName": "疯狂狮子Li",
|
||
"email": "admin@example.com",
|
||
"phonenumber": "13800138000",
|
||
"sex": "1",
|
||
"avatar": "1938120323613728770",
|
||
"avatarUrl": "http://example.com/ruoyi/2025/08/31/xxxx.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&...",
|
||
"status": "0",
|
||
"loginIp": "127.0.0.1",
|
||
"loginDate": "2025-01-26 10:30:00",
|
||
"tenantId": "000000",
|
||
"deptId": 103,
|
||
"deptName": "智胜技术开发团队"
|
||
},
|
||
"roles": ["admin", "common"],
|
||
"permissions": ["*:*:*"]
|
||
}
|
||
}
|
||
```
|
||
|
||
**字段说明补充**:
|
||
|
||
- `avatar`：始终返回 `sys_user.avatar` 中存储的 OSS ID（字符串），用于鉴权下载接口 `/resource/oss/download/{ossId}`。
|
||
- `avatarUrl`：系统通过 `TransConstant.OSS_ID_TO_URL` 规则实时翻译得到的可直接访问地址（MinIO 预签名 URL），供无需链路改造的场景快速显示；有效期受 OSS 策略控制。
|
||
|
||
前端如需在带 Token 的受保护组件（如 `ImagePreview`）中展示，请优先使用 `avatar` 并通过统一的认证下载逻辑获取图片，避免直接暴露临时 URL。
|
||
|
||
**超级管理员权限说明**:
|
||
|
||
admin 用户具有系统最高权限`*:*:*`，可以访问所有功能模块和执行所有操作。
|
||
|
||
---
|
||
|
||
## 🏢 租户管理
|
||
|
||
### 获取租户列表
|
||
|
||
**接口地址**: `GET /auth/tenant/list`
|
||
|
||
**接口描述**: 获取系统可用的租户列表，用于登录时选择租户
|
||
|
||
**权限要求**: 无需认证
|
||
|
||
**请求参数**: 无
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"tenantEnabled": true,
|
||
"voList": [
|
||
{
|
||
"tenantId": "000000",
|
||
"companyName": "杭州第一技师学院",
|
||
"domain": "hzdyjs.edu.cn",
|
||
"status": "0"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应参数说明**:
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
| ------------- | ------- | ------------------ |
|
||
| tenantEnabled | boolean | 是否启用多租户功能 |
|
||
| voList | array | 租户列表 |
|
||
|
||
**voList 中每项参数**:
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
| ----------- | ------ | ------------------- |
|
||
| tenantId | string | 租户 ID |
|
||
| companyName | string | 租户名称 |
|
||
| domain | string | 租户域名 |
|
||
| status | string | 状态(0 正常 1 停用) |
|
||
|
||
---
|
||
|
||
---
|
||
|
||
## 📱 移动端登录实现
|
||
|
||
### 移动端特殊配置
|
||
|
||
移动端使用uni-app框架，登录实现与web端保持API兼容，但在实现细节上有所差异：
|
||
|
||
**网络请求配置**:
|
||
```javascript
|
||
// mobile/src/utils/request.js
|
||
const baseURL = 'http://localhost:8080'
|
||
|
||
const request = (options) => {
|
||
return new Promise((resolve, reject) => {
|
||
const token = getToken()
|
||
|
||
uni.request({
|
||
url: baseURL + options.url,
|
||
method: options.method || 'GET',
|
||
data: options.data || {},
|
||
header: {
|
||
'Content-Type': 'application/json',
|
||
'Authorization': token,
|
||
'clientid': 'e5cd7e4891bf95d1d19206ce24a7b32e',
|
||
'referer': baseURL,
|
||
...options.header,
|
||
},
|
||
// 响应处理逻辑...
|
||
})
|
||
})
|
||
}
|
||
```
|
||
|
||
**登录API调用**:
|
||
```javascript
|
||
// 移动端登录API
|
||
export const api = {
|
||
login: (data) =>
|
||
request({
|
||
url: '/auth/login',
|
||
method: 'POST',
|
||
data: {
|
||
tenantId: data.tenantId || '000000',
|
||
username: data.username,
|
||
password: data.password,
|
||
clientId: data.clientId || 'e5cd7e4891bf95d1d19206ce24a7b32e',
|
||
grantType: data.grantType || 'password'
|
||
},
|
||
header: {
|
||
isToken: false,
|
||
isEncrypt: true,
|
||
repeatSubmit: false
|
||
}
|
||
}),
|
||
|
||
getUserInfo: () =>
|
||
request({
|
||
url: '/system/user/getInfo',
|
||
method: 'GET'
|
||
}),
|
||
|
||
// 其他API...
|
||
}
|
||
```
|
||
|
||
### 移动端用户信息缓存
|
||
|
||
**用户信息存储工具**:
|
||
```javascript
|
||
// mobile/src/utils/request.js
|
||
export const userStorage = {
|
||
// 保存登录信息
|
||
saveLoginInfo: (loginResult, userInfo) => {
|
||
try {
|
||
uni.setStorageSync('access_token', loginResult.access_token)
|
||
if (userInfo) {
|
||
uni.setStorageSync('userInfo', JSON.stringify(userInfo))
|
||
}
|
||
uni.setStorageSync('isLoggedIn', true)
|
||
} catch (e) {
|
||
console.error('保存登录信息失败:', e)
|
||
}
|
||
},
|
||
|
||
// 获取用户信息
|
||
getUserInfo: () => {
|
||
try {
|
||
const userInfo = uni.getStorageSync('userInfo')
|
||
return userInfo ? JSON.parse(userInfo) : null
|
||
} catch (e) {
|
||
return null
|
||
}
|
||
},
|
||
|
||
// 检查登录状态
|
||
isLoggedIn: () => {
|
||
try {
|
||
const isLoggedIn = uni.getStorageSync('isLoggedIn')
|
||
const token = uni.getStorageSync('access_token')
|
||
return !!(isLoggedIn && token)
|
||
} catch (e) {
|
||
return false
|
||
}
|
||
},
|
||
|
||
// 清除登录信息
|
||
clearLoginInfo: () => {
|
||
try {
|
||
uni.removeStorageSync('access_token')
|
||
uni.removeStorageSync('userInfo')
|
||
uni.removeStorageSync('isLoggedIn')
|
||
} catch (e) {
|
||
console.error('清除登录信息失败:', e)
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 移动端登录流程
|
||
|
||
1. **应用启动** → 检查登录状态 → 未登录自动跳转登录页
|
||
2. **用户登录** → 调用`/auth/login`API → 获取access_token
|
||
3. **获取用户信息** → 调用`/system/user/getInfo`API → 获取用户详情
|
||
4. **缓存信息** → 使用`userStorage.saveLoginInfo()`缓存登录信息
|
||
5. **页面访问** → 所有页面自动检查登录状态
|
||
6. **退出登录** → 清除本地缓存 → 跳转登录页
|
||
|
||
### 移动端页面入口配置
|
||
|
||
**pages.json配置**:
|
||
```json
|
||
{
|
||
"pages": [
|
||
{
|
||
"path": "pages/login/index",
|
||
"style": {
|
||
"navigationBarTitleText": "登录",
|
||
"navigationStyle": "custom",
|
||
"navigationBarBackgroundColor": "transparent",
|
||
"backgroundColor": "transparent"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 移动端登录状态验证
|
||
|
||
**全局登录验证**:
|
||
```javascript
|
||
// 在每个需要登录的页面中
|
||
onLoad() {
|
||
this.checkLoginStatus();
|
||
},
|
||
|
||
methods: {
|
||
checkLoginStatus() {
|
||
if (!userStorage.isLoggedIn()) {
|
||
uni.reLaunch({
|
||
url: '/pages/login/index'
|
||
});
|
||
return false;
|
||
}
|
||
return true;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 移动端与web端差异
|
||
|
||
| 特性 | Web端 | 移动端 |
|
||
|------|-------|--------|
|
||
| 框架 | Vue 3 + TypeScript | Vue 2 + uni-app |
|
||
| 存储 | localStorage | uni.storage |
|
||
| 网络请求 | axios | uni.request |
|
||
| 路由跳转 | router.push | uni.navigateTo/reLaunch |
|
||
| UI组件 | Element Plus | uview-ui |
|
||
| 加密方式 | AES+RSA | 支持，但简化实现 |
|
||
|
||
### 移动端登录页面特性
|
||
|
||
- ✅ **现代化UI**: 渐变背景 + 毛玻璃效果
|
||
- ✅ **租户选择**: 支持多租户选择（与web端一致）
|
||
- ✅ **表单验证**: 完整的输入验证和错误提示
|
||
- ✅ **响应式设计**: 适配不同屏幕尺寸
|
||
- ✅ **无障碍访问**: 支持键盘导航和屏幕阅读器
|
||
- ✅ **安全存储**: 使用uni.storage安全存储用户信息
|
||
|
||
---
|
||
|
||
## 📞 联系方式
|
||
|
||
如有认证相关问题，请联系开发团队或查看项目仓库的 Issues。
|
||
|
||
---
|
||
|
||
**📝 维护**: 用户认证登录 API 文档
|
||
**🔄 更新记录**:
|
||
- 2025-11-28：`/system/user/getInfo` 增加 `avatarUrl` 字段，并明确 `avatar` 返回 OSS ID
|
||
- 2025-01-03：文档初始化
|
||
**📁 文件**: 用户认证登录 API.md
|
||
|
||
## 获取具有指定权限的用户列表
|
||
|
||
### 基本信息
|
||
- **接口URL**: `/system/user/list-by-permission`
|
||
- **请求方式**: GET
|
||
- **接口描述**: 获取具有指定权限的用户列表
|
||
- **权限标识**: `system:user:list`
|
||
|
||
### 请求参数
|
||
#### Query参数
|
||
| 参数名 | 类型 | 是否必须 | 说明 | 示例值 |
|
||
|--------|------|----------|------|--------|
|
||
| permission | string | 是 | 权限标识符 | hq:hallAudit:list |
|
||
|
||
### 响应参数
|
||
```typescript
|
||
{
|
||
code: number; // 状态码
|
||
msg: string; // 提示信息
|
||
rows: {
|
||
userId: string; // 用户ID
|
||
userName: string; // 用户名
|
||
nickName: string; // 昵称
|
||
dept: {
|
||
deptId: string; // 部门ID
|
||
deptName: string; // 部门名称
|
||
};
|
||
avatar: string; // 头像OSS ID
|
||
avatarUrl?: string; // 头像访问URL（可选，预签名）
|
||
}[];
|
||
total: number; // 总记录数
|
||
}
|
||
```
|
||
|
||
### 响应示例
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"rows": [
|
||
{
|
||
"userId": "1",
|
||
"userName": "admin",
|
||
"nickName": "管理员",
|
||
"dept": {
|
||
"deptId": "1",
|
||
"deptName": "后勤部"
|
||
},
|
||
"avatar": "1938120323613728770",
|
||
"avatarUrl": "http://example.com/avatar.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&..."
|
||
}
|
||
],
|
||
"total": 1
|
||
}
|
||
```
|
||
|
||
### 错误码
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 401 | 未登录或登录超时 |
|
||
| 403 | 没有权限 |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
### 注意事项
|
||
1. 该接口需要用户登录后才能访问
|
||
2. 返回的用户信息已过滤敏感字段
|
||
3. 建议前端对结果进行缓存，避免频繁请求
|
||
4. 返回结果按照用户名（`user_name`）升序排序
|
||
|
||
### 使用示例
|
||
```typescript
|
||
// 前端调用示例
|
||
import { listUsersByPermission } from '@/api/system/user';
|
||
|
||
async function getAuditors() {
|
||
try {
|
||
const res = await listUsersByPermission('hq:hallAudit:list');
|
||
if (res.code === 200) {
|
||
return res.rows;
|
||
}
|
||
} catch (error) {
|
||
console.error('获取审核人员列表失败:', error);
|
||
return [];
|
||
}
|
||
}
|
||
```
|
||
|
||
## 根据部门获取用户列表
|
||
|
||
### 基本信息
|
||
- **接口URL**: `/system/user/list/dept/{deptId}`
|
||
- **请求方式**: GET
|
||
- **接口描述**: 根据部门ID获取该部门下所有启用状态的用户，用于部门人员选择器
|
||
- **权限标识**: `system:user:list`
|
||
|
||
### 路径参数
|
||
| 参数名 | 类型 | 是否必须 | 说明 | 示例值 |
|
||
|--------|------|----------|------|--------|
|
||
| deptId | number | 是 | 部门ID | 1001 |
|
||
|
||
### 响应参数
|
||
```typescript
|
||
{
|
||
code: number;
|
||
msg: string;
|
||
data: {
|
||
userId: number;
|
||
userName: string;
|
||
nickName: string;
|
||
phonenumber: string;
|
||
}[];
|
||
}
|
||
```
|
||
|
||
### 注意事项
|
||
1. 只返回未删除且状态为正常的用户
|
||
2. 返回结果按照用户名（`user_name`）升序排序，便于快速定位
|
||
|
||
## 批量获取用户基础信息
|
||
|
||
### 基本信息
|
||
- **接口URL**: `/system/user/optionselect`
|
||
- **请求方式**: GET
|
||
- **接口描述**: 根据用户ID集合（可选）和部门ID（可选）批量获取基础用户信息
|
||
- **权限标识**: `system:user:query`
|
||
|
||
### Query参数
|
||
| 参数名 | 类型 | 是否必须 | 说明 | 示例值 |
|
||
|--------|------|----------|------|--------|
|
||
| userIds | string | 否 | 逗号分隔的用户ID集合 | 1,2,3 |
|
||
| deptId | number | 否 | 指定部门ID时仅返回该部门用户 | 1001 |
|
||
|
||
### 响应参数
|
||
```typescript
|
||
{
|
||
code: number;
|
||
msg: string;
|
||
data: {
|
||
userId: number;
|
||
userName: string;
|
||
nickName: string;
|
||
phonenumber: string;
|
||
}[];
|
||
}
|
||
```
|
||
|
||
### 注意事项
|
||
1. 用户ID集合为空时返回有权限范围内的全部用户
|
||
2. 返回结果默认按照用户名（`user_name`）升序排序，保持前端下拉展示一致性
|