┌─────────────────────────────────────────────────────────────────┐
│                    FastAPI Core 架构文档                        │
│                     WebSocket 重构版本                          │
└─────────────────────────────────────────────────────────────────┘

📅 更新时间: 2024-08-13
🔄 版本: WebSocket架构重构 v2.0

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🎯 架构重构目标
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ 遵循单一职责原则 (Single Responsibility Principle)
✅ 提高代码可读性和可维护性
✅ 简化架构，减少职责重叠
✅ 便于单元测试和扩展

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🏗️ 重构后的架构设计
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📁 app/core/websocket/
├── 📄 manager.py              # 🎯 轻量级协调器
├── 📄 client_manager.py       # 🔌 客户端生命周期管理
├── 📄 channel_manager.py      # 📡 Channel创建和管理
├── 📄 send_controller.py      # 📤 统一消息发送控制
├── 📄 heartbeat_manager.py    # 💓 心跳消息管理
├── 📄 client.py              # 🌐 WebSocket客户端
├── 📄 channel.py             # 📢 消息队列Channel
└── 📄 serializer.py          # 🔄 消息序列化

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔧 各组件职责分工
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1️⃣ WebSocketManager (协调器)
   └── 🎯 单一职责：协调各个专门的管理器
       ├── 协调客户端管理器
       ├── 协调Channel管理器
       ├── 协调发送控制器
       ├── 协调心跳管理器
       └── 提供统一的API接口

2️⃣ WebSocketClientManager (客户端管理)
   └── 🎯 单一职责：WebSocket客户端生命周期管理
       ├── 创建客户端
       ├── 连接客户端
       ├── 断开客户端
       ├── 移除客户端
       └── 获取客户端信息

3️⃣ WebSocketChannelManager (Channel管理)
   └── 🎯 单一职责：WebSocket Channel的创建和管理
       ├── 创建Channel
       ├── 销毁Channel
       ├── 获取Channel信息
       └── 管理Channel生命周期

4️⃣ WebSocketSendController (发送控制)
   └── 🎯 单一职责：统一的消息发送逻辑
       ├── 统一发送循环
       ├── 消息发送到WebSocket
       ├── 优先级控制
       └── 发送任务管理

5️⃣ WebSocketHeartbeatManager (心跳管理)
   └── 🎯 单一职责：心跳消息的发送和管理
       ├── 心跳任务管理
       ├── 心跳消息发送
       ├── 心跳间隔控制
       └── 心跳状态监控

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔄 数据流向图
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📤 发送流程:
API请求 → WebSocketManager → ChannelManager → SendController → WebSocketClient

📥 接收流程:
WebSocketClient → WebSocketManager → ChannelManager → ReceiveChannel

💓 心跳流程:
HeartbeatManager → ChannelManager → SendController → WebSocketClient

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⚡ 优先级机制
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🎯 智能优先级控制:
1. 优先发送 send_channel 的业务数据
2. 只有在 send_channel 没有数据时才发送 heartbeat_channel 的心跳
3. 避免心跳占用业务数据带宽
4. 实现真正的优先级控制，避免并发竞争

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔍 API端点状态
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ endpoints.create_and_connect_client - 正常运行
✅ 支持创建WebSocket客户端
✅ 支持自动创建3个Channel (heartbeat, send, receive)
✅ 支持智能心跳机制
✅ 支持优先级消息发送

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 架构优势
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ 单一职责原则：每个类都有明确的职责
✅ 高内聚低耦合：组件间依赖关系清晰
✅ 易于测试：每个组件可以独立测试
✅ 易于扩展：新增功能不影响现有组件
✅ 代码可读性：职责明确，逻辑清晰
✅ 维护性强：问题定位和修复更容易

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🚀 性能优化
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ 统一发送控制：避免多个发送循环竞争
✅ 智能心跳：避免不必要的带宽占用
✅ 异步处理：充分利用asyncio性能优势
✅ 资源管理：及时清理不需要的资源

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📝 使用示例
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

```python
# 创建并连接客户端
client = await websocket_manager.create_client("test_client", "ws://localhost:8080/ws", 30)
success = await websocket_manager.connect_client("test_client")

# 发送消息
await websocket_manager.send_message("test_client", "data", {"key": "value"})

# 发送心跳
await websocket_manager.send_heartbeat("test_client")

# 获取统计信息
stats = websocket_manager.get_stats()
```

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔧 测试状态
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ 集成测试通过
✅ API端点测试通过
✅ 优先级机制测试通过
✅ 心跳机制测试通过
✅ 资源清理测试通过

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 待办事项
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔄 持续优化:
- 监控性能指标
- 优化内存使用
- 增强错误处理
- 完善日志记录

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📞 技术支持
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

如有问题，请查看:
- modify.md - 详细修改记录
- 各组件源码注释
- 测试文件示例

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━