SOMS/src/Documentation/EnhancedRealTimeCommunicationService_README.md

# 增强的实时通信服务 (Enhanced RealTimeCommunicationService)

## 概述

RealTimeCommunicationService 已经完全集成了 CommunicationConfiguration 中的所有配置项，提供了配置驱动的实时通信功能。该服务现在支持动态配置、智能故障转移、超时控制、消息压缩、持久化等高级功能。

## 主要增强功能

### 1. 配置驱动的通信方式选择
- **WebSocket优先级**: 根据配置自动选择 WebSocket 或 SignalR 作为主要通信方式
- **智能故障转移**: 当主要通信方式失败时，自动切换到备用方式
- **可配置重试**: 支持配置重试次数和重试策略

### 2. 超时控制
- **WebSocket超时**: 独立配置 WebSocket 连接超时时间
- **SignalR超时**: 独立配置 SignalR 连接超时时间
- **动态超时应用**: 每次通信都会应用最新的超时配置

### 3. 消息优化
- **消息压缩**: 根据配置启用/禁用消息压缩
- **消息持久化**: 支持重要消息的持久化存储
- **队列管理**: 配置消息队列最大长度

### 4. 连接管理
- **并发连接限制**: 配置最大并发连接数
- **心跳检测**: 可配置的心跳检测间隔
- **健康状况监控**: 实时监控通信服务健康状况

## 配置项说明

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| IsWebSocketPriority | bool | false | 是否优先使用WebSocket |
| WebSocketTimeoutSeconds | int | 30 | WebSocket连接超时时间(秒) |
| SignalRTimeoutSeconds | int | 30 | SignalR连接超时时间(秒) |
| EnableAutoFailover | bool | true | 是否启用自动故障转移 |
| FailoverRetryCount | int | 3 | 故障转移重试次数 |
| HeartbeatIntervalSeconds | int | 30 | 心跳检测间隔(秒) |
| EnableMessageCompression | bool | false | 是否启用消息压缩 |
| MaxConcurrentConnections | int | 1000 | 最大并发连接数 |
| MaxMessageQueueLength | int | 10000 | 消息队列最大长度 |
| EnableMessagePersistence | bool | false | 是否启用消息持久化 |

## 使用示例

### 基本用法

```csharp
// 注入服务
private readonly IRealTimeCommunicationService _communicationService;

// 发送通知（自动应用配置）
await _communicationService.SendNotificationToUserAsync(
    "user-001",
    "系统通知",
    "info",
    "重要提醒",
    transformerSubstationId // 可选：指定变电站ID获取特定配置
);
```

### 获取配置信息

```csharp
// 获取当前配置
var config = await _communicationService.GetCommunicationConfigurationAsync();

// 获取健康状况
var health = await _communicationService.GetCommunicationHealthStatusAsync();
```

### 高级功能

```csharp
// 发送告警（包含故障转移和超时控制）
await _communicationService.SendAlarmAsync(
    alarmData,
    "high",
    targetUsers,
    transformerSubstationId
);

// 发送实时数据（应用压缩和持久化配置）
await _communicationService.SendDataUpdateAsync(
    "sensor_data",
    sensorData,
    null, // 广播
    transformerSubstationId
);
```

## 配置继承机制

服务支持三级配置继承：

1. **变电站特定配置** - 优先级最高
2. **全局配置** - 当变电站配置不存在时使用
3. **系统默认值** - 当数据库配置不存在时使用

```csharp
// 获取配置的优先级顺序
var config = await _configurationCacheService.GetWebSocketPriorityAsync(stationId);
// 1. 查找 stationId 对应的配置
// 2. 如果不存在，查找全局配置 (TransformerSubstationId = null)
// 3. 如果仍不存在，使用默认值
```

## 故障转移机制

### 自动故障转移流程

1. **主要方式尝试**: 根据配置优先级选择 WebSocket 或 SignalR
2. **重试机制**: 失败时按配置的重试次数进行重试
3. **备用方式**: 如果启用自动故障转移，切换到备用通信方式
4. **异常处理**: 所有方式都失败时抛出聚合异常

```csharp
// 故障转移配置示例
{
    "IsWebSocketPriority": true,     // 优先WebSocket
    "EnableAutoFailover": true,      // 启用故障转移
    "FailoverRetryCount": 3,         // 重试3次
    "WebSocketTimeoutSeconds": 15,   // WebSocket超时15秒
    "SignalRTimeoutSeconds": 30      // SignalR超时30秒
}
```

## 性能优化

### 缓存机制
- **配置缓存**: 使用 MemoryCache 缓存配置，避免频繁数据库查询
- **缓存过期**: 30分钟绝对过期，15分钟滑动过期
- **缓存预热**: 系统启动时预加载常用配置

### 消息优化
- **压缩支持**: 大消息自动压缩，减少网络传输
- **批量发送**: 支持批量用户消息发送
- **队列管理**: 防止消息队列溢出

## 监控和调试

### 健康检查
```csharp
var health = await _communicationService.GetCommunicationHealthStatusAsync();
// 返回：
// - 配置信息
// - 连接状态
// - 在线用户统计
// - 服务可用性
```

### 日志记录
服务会记录详细的操作日志：
- 配置加载和应用
- 通信方式选择
- 故障转移过程
- 性能指标
- 错误信息

## 最佳实践

### 1. 配置管理
- 为不同环境设置不同的配置
- 定期检查和优化配置参数
- 使用配置缓存预热提升性能

### 2. 故障处理
- 启用自动故障转移提高可靠性
- 合理设置重试次数避免过度重试
- 监控故障转移频率

### 3. 性能优化
- 根据网络环境调整超时时间
- 在高并发场景下启用消息压缩
- 合理设置连接数和队列长度限制

### 4. 监控运维
- 定期检查通信服务健康状况
- 监控在线用户数量变化
- 分析日志识别潜在问题

## 扩展性

服务设计支持未来扩展：
- 新增通信协议支持
- 自定义故障转移策略
- 更多消息优化选项
- 高级监控指标

## 注意事项

1. **配置更新**: 配置更新后需要清除相关缓存
2. **网络环境**: 根据实际网络环境调整超时和重试参数
3. **资源消耗**: 启用压缩和持久化会增加CPU和存储消耗
4. **兼容性**: 确保客户端支持所选的通信协议

## 相关文档

- [CommunicationConfiguration 配置管理](./CommunicationConfiguration_README.md)
- [通信配置系统实现总结](../通信配置系统实现总结.md)
- [API 文档](./API_Documentation.md)