# 心跳实时配置更新功能

## 📋 功能概述

通过心跳机制实现客户端配置的实时更新，无需重启应用即可应用新的配置。

## 🔧 实现原理

### 后端实现

心跳API (`/api/user/heartbeat`) 在每次响应中包含最新的客户端配置信息：

```json
{
  "code": 200,
  "msg": "成功",
  "data": {
    "expire_time": "2026-12-31T23:59:59",
    "server_time": "2026-01-06T17:23:25.000000",
    "session_status": "active",
    "next_heartbeat": 30,
    "session_expires_at": "2026-01-07T17:23:25.000000",
    "session_extend_enabled": true,
    "session_extend_threshold_hours": 4,
    "client_configs": {
      "api_timeout_seconds": 30,
      "client_heartbeat_interval_seconds": 30,
      "max_heartbeat_failures": 10,
      "max_network_failures": 15
    }
  }
}
```

### 客户端实现

客户端在每次心跳成功时检查并更新配置：

```typescript
// 检查是否有配置更新
if (updatedUserInfo.client_configs) {
  console.log('检测到配置更新:', updatedUserInfo.client_configs)

  // 更新全局配置
  Object.assign(props.globalConfig, newConfig)

  // 如果心跳间隔发生变化，需要重新启动心跳
  if (oldInterval !== newInterval) {
    console.log(`心跳间隔从 ${oldInterval} 秒变为 ${newInterval} 秒，重新启动心跳`)
    stopHeartbeat()
    startHeartbeat()
  }
}
```

## 📊 配置项说明

| 配置项 | 说明 | 默认值 | 影响 |
|-------|------|-------|------|
| `api_timeout_seconds` | API请求超时秒数 | 30 | API调用的超时时间 |
| `client_heartbeat_interval_seconds` | 客户端心跳间隔秒数 | 30 | 心跳检测频率 |
| `max_heartbeat_failures` | 最大心跳失败次数 | 10 | 超过后暂停心跳检测 |
| `max_network_failures` | 网络异常最大失败次数 | 15 | 超过后自动登出 |

## 🔄 配置更新流程

1. **管理员修改配置**：
   ```sql
   UPDATE system_config SET config_value='60' WHERE config_key='client_heartbeat_interval_seconds';
   ```

2. **客户端自动更新**：
   - 心跳请求 → 服务器返回最新配置
   - 客户端检测到配置变化 → 更新本地配置
   - 如有必要，重新启动相关服务

3. **实时生效**：
   - 无需重启应用
   - 立即生效

## 🛡️ 安全特性

- **验证机制**：只有有效的用户会话才能获取配置
- **类型安全**：配置值会自动转换为正确的数据类型
- **容错处理**：配置更新失败不影响心跳功能
- **日志记录**：配置更新会被记录到客户端日志

## 📈 优势

### 🚀 实时性
- 配置变更秒级生效
- 支持动态调整系统行为

### 🔧 维护性
- 热更新，无需重启
- 集中化配置管理
- 支持A/B测试和灰度发布

### 📊 可观测性
- 配置变更可追踪
- 客户端日志记录
- 管理员可监控配置生效情况

## 🧪 测试验证

### 后端测试
```bash
cd /Users/wuzilong/work/00code/Buff/backend
python test_heartbeat_config.py
```

### 客户端测试
1. 启动应用并登录
2. 修改数据库配置
3. 观察客户端日志中的配置更新信息
4. 验证新配置是否生效

## 📝 使用示例

### 修改心跳间隔
```sql
-- 将心跳间隔改为60秒
UPDATE system_config SET config_value='60' WHERE config_key='client_heartbeat_interval_seconds';
```

客户端会在下次心跳时自动调整间隔，并输出日志：
```
检测到配置更新: {client_heartbeat_interval_seconds: 60}
心跳间隔从 30 秒变为 60 秒，重新启动心跳
```

### 修改失败重试次数
```sql
-- 增加网络异常容忍度
UPDATE system_config SET config_value='20' WHERE config_key='max_network_failures';
```

客户端会自动应用新配置，提高网络异常的容忍度。

## 🔍 监控和调试

### 日志监控
客户端会在检测到配置更新时输出详细日志：
```
[心跳] 检测到配置更新: {...}
[心跳] 心跳间隔从 X 秒变为 Y 秒，重新启动心跳
```

### 配置验证
可以通过以下方式验证配置是否正确应用：

1. **客户端日志**：查看心跳日志中的配置更新信息
2. **数据库查询**：检查system_config表的配置值
3. **API测试**：调用心跳API查看返回的client_configs

## 🚨 注意事项

- 配置更新只在心跳成功时进行
- 网络异常时不会更新配置（避免配置丢失）
- 敏感配置需要重启应用才能生效
- 建议在低峰期进行重要配置变更

---

*此功能让系统具备了真正的动态配置能力，大大提升了系统的灵活性和可维护性。*