# OIDC 集成说明

## 概述

本项目已经使用 `oidc-client-ts` 库集成 OpenID Connect 认证，替换了原有的自定义登录实现。

## 新增文件

### 1. OIDC 配置
- `src/config/oidc.ts` - OIDC 客户端配置

### 2. OIDC 服务
- `src/services/oidc-auth.service.ts` - OIDC 认证服务封装

### 3. 回调页面
- `src/views/_core/authentication/callback.vue` - OIDC 登录回调处理页面

### 4. API 更新
- `src/api/core/auth.ts` - 更新为使用 OIDC token

### 5. Store 更新
- `src/store/auth.ts` - 更新为使用 OIDC 认证流程

## 修改文件

### 1. 路由配置
- `src/router/routes/core.ts` - 添加了 `/auth/callback` 路由
- `src/router/guard.ts` - 更新为使用 OIDC 认证检查

### 2. 请求拦截器
- `src/api/request.ts` - 更新为使用 OIDC 的 token 刷新

### 3. 环境配置
- `.env.development` - 添加 `VITE_AUTH_SERVER_URL` 配置

## 环境变量

在 `.env` 文件中配置以下变量：

```env
# OIDC认证服务器地址
VITE_AUTH_SERVER_URL=http://localhost:5132
```

## 认证流程

### 密码模式登录 (Resource Owner Password Credentials)

1. 用户在登录页面输入用户名和密码
2. 调用 `authStore.authLogin({ username, password })`
3. 使用 OIDC 的 `signinResourceOwnerCredentials` 方法直接获取 token
4. Token 存储到 store，并在请求头中携带
5. 获取用户信息并设置到用户 store

### 授权码模式登录 (Authorization Code Flow)

1. 前端调用 `oidcAuthService.signinRedirect()` 重定向到认证服务器
2. 用户在认证服务器完成认证
3. 认证服务器重定向回 `/auth/callback?code=...`
4. 回调页面调用 `authStore.handleCallback()` 处理授权码
5. 换取访问令牌并存储

## Token 管理

### 自动续期

- 当 token 即将过期（60秒前），OIDC 服务会自动静默续期
- 如果静默续期失败，会重定向到登录页

### 手动刷新

```typescript
await authStore.refreshToken();
```

### 退出登录

```typescript
await authStore.logout();
```

## API 使用

### 使用 Access Token

API 请求会自动携带 Bearer token：

```typescript
// 请求头会自动添加
Authorization: Bearer {access_token}
```

### 获取用户信息

```typescript
// 从 token claims 获取
const userInfo = getUserInfoFromToken(user);

// 或从服务器获取
const userInfo = await getUserInfoApi();
```

## 错误处理

### 常见错误

1. **invalid_grant** - 用户名或密码错误
2. **invalid_client** - 客户端 ID 无效
3. **expired_token** - Token 已过期
4. **invalid_token** - Token 无效

所有错误都会显示友好的提示信息，并重定向到登录页。

## 注意事项

1. **Token 存储**：Token 存储在 localStorage 中，由 oidc-client-ts 管理
2. **CORS 配置**：认证服务器需要配置 CORS 允许前端域名
3. **HTTPS**：生产环境必须使用 HTTPS
4. **PKCE**：如果使用授权码模式，建议启用 PKCE 增强安全性

## 后端要求

认证服务器必须支持以下功能：

- OpenID Connect 1.0 兼容
- Resource Owner Password Credentials 授权类型
- Authorization Code 授权类型
- Refresh Token 支持
- Userinfo 端点

## 开发建议

1. 开发时使用 `http://localhost:5132` 作为认证服务器
2. 生产环境配置实际的认证服务器地址
3. 使用浏览器开发者工具的 Application 标签查看存储的 token
4. 监控网络请求，查看 OAuth 流程

## 迁移指南

如果你之前使用自定义的登录实现：

1. 删除旧的登录 API 调用
2. 替换为使用 `authStore.authLogin()` 方法
3. 确保 request 拦截器使用 OIDC token
4. 添加 `/auth/callback` 路由
5. 配置环境变量 `VITE_AUTH_SERVER_URL`

## 故障排除

### Token 过期问题

如果遇到 token 频繁过期：

1. 检查认证服务器的 token 有效期设置
2. 确保自动续期功能正常工作
3. 查看浏览器控制台的错误信息

### CORS 问题

如果遇到 CORS 错误：

1. 确保认证服务器配置了 CORS
2. 检查前端域名是否在允许列表中
3. 确认 `VITE_AUTH_SERVER_URL` 配置正确

### 回调失败

如果登录回调失败：

1. 检查 `redirect_uri` 是否匹配
2. 确认认证服务器返回的授权码
3. 查看浏览器控制台的详细错误信息