# 员工门户登录超时配置说明

## 问题需求

修改员工门户(hzhub-portal-employee)的登录超时时间为1小时，超时后自动退出。

## 配置原理

### Token超时机制

HZHub使用Sa-Token进行认证管理，token超时时间由 `sys_client` 表的 `active_timeout` 字段控制：

| 字段 | 说明 | 单位 | 默认值 |
|------|------|------|--------|
| `active_timeout` | token活跃超时时间 | 秒 | 1800 (30分钟) |
| `timeout` | token固定超时时间 | 秒 | 604800 (7天) |

**区别说明：**
- **active_timeout**: 用户活跃超时，用户在指定时间内无操作则token失效
- **timeout**: token绝对超时，从登录开始计时，无论是否活跃都将在该时间后失效

### 客户端配置

员工门户使用的客户端ID: `e5cd7e4891bf95d1d19206ce24a7b32e`（来自 .env.development）

## 修改方案

### 方法1：执行SQL更新（推荐）

执行以下SQL脚本将员工门户的超时时间修改为1小时：

```bash
# 连接数据库
mysql -u root -phzhub123

# 执行更新SQL
source /tmp/update_employee_timeout.sql
```

或手动执行SQL：

```sql
-- 查询当前配置
SELECT id, client_id, client_key, active_timeout, timeout, status 
FROM sys_client 
WHERE client_id = 'e5cd7e4891bf95d1d19206ce24a7b32e';

-- 更新为1小时超时
UPDATE sys_client 
SET active_timeout = 3600 
WHERE client_id = 'e5cd7e4891bf95d1d19206ce24a7b32e';

-- 验证结果
SELECT id, client_id, client_key, active_timeout, timeout, status 
FROM sys_client 
WHERE client_id = 'e5cd7e4891bf95d1d19206ce24a7b32e';
```

### 方法2：通过管理后台修改

1. 登录管理后台: http://localhost:5666
2. 进入 "系统管理" -> "客户端管理"
3. 找到 `client_id = e5cd7e4891bf95d1d19206ce24a7b32e` 的记录
4. 编辑该记录，将 `活跃超时时间` 修改为 `3600`
5. 保存

## 超时时间建议

根据不同场景，建议的超时时间配置：

| 场景 | active_timeout | timeout | 说明 |
|------|----------------|---------|------|
| 内部员工 | 3600 (1小时) | 604800 (7天) | 平衡安全性和便利性 |
| 移动端APP | 7200 (2小时) | 604800 (7天) | 移动端使用频率高 |
| 公共终端 | 1800 (30分钟) | 86400 (1天) | 安全性优先 |
| 超级管理员 | 1800 (30分钟) | 86400 (1天) | 高安全性要求 |

## 验证配置生效

修改后需要**重新登录**才能生效：

1. 清除浏览器缓存或使用隐身模式
2. 访问员工门户登录页面
3. 登录后等待1小时不操作
4. 再次访问应自动跳转到登录页面

## 技术实现

### 后端实现

登录时通过 `SaLoginParameter.setActiveTimeout()` 设置：

```java
// PasswordAuthStrategy.java
SaLoginParameter model = new SaLoginParameter();
model.setActiveTimeout(client.getActiveTimeout()); // 从sys_client表读取
LoginHelper.login(loginUser, model);
```

### 前端响应

前端通过以下方式检测token过期：

1. **API响应401**: 拦截器检测到401状态码，自动跳转登录页
2. **路由守卫**: 访问页面时检查token是否有效
3. **本地存储**: Pinia持久化存储token，过期后自动清除

## 相关配置文件

- **后端配置**: `/data/hzhub/hzhub-ai/hzhub-common/hzhub-common-satoken/src/main/resources/common-satoken.yml`
  - `dynamic-active-timeout: true` - 允许动态设置token有效期

- **前端配置**: `/data/hzhub/hzhub-portal-employee/.env.development`
  - `VITE_CLIENT_ID=e5cd7e4891bf95d1d19206ce24a7b32e` - 客户端ID

- **数据库表**: `sys_client`
  - `active_timeout` - 活跃超时时间（秒）
  - `timeout` - 固定超时时间（秒）

## 常见问题

### Q: 修改后没有生效？

A: 需要**重新登录**。已登录的token不会立即失效，只有新登录的token才会使用新的超时时间。

### Q: 如何测试超时是否正确？

A:
1. 登录系统
2. 等待设定的超时时间（如1小时）
3. 不进行任何操作
4. 刷新页面或访问API，应自动跳转到登录页

### Q: 可以设置为永不过期吗？

A: 不建议。为了安全考虑，应该设置合理的超时时间。如需延长，可以设置为更大的值：

```sql
-- 设置为8小时
UPDATE sys_client SET active_timeout = 28800 WHERE client_id = 'e5cd7e4891bf95d1d19206ce24a7b32e';

-- 设置为12小时
UPDATE sys_client SET active_timeout = 43200 WHERE client_id = 'e5cd7e4891bf95d1d19206ce24a7b32e';
```

## 相关文档

- [Sa-Token官方文档](https://sa-token.cc/)
- [HZHub认证流程](../docs/architecture/README.md)
- [服务管理脚本](./SERVICE_MANAGEMENT.md)