# 集成指南

本目录包含将 JRSoft Subway 协议集成到各个组件的详细指南。

## 📚 文档列表

### [Gateway 集成指南](./gateway-guide.md)
Gateway 组件的集成说明：
- WebSocket 服务器配置
- 客户端连接管理
- 消息路由实现
- 性能优化建议

### [Backend 集成指南](./backend-guide.md)
Backend 服务的集成说明：
- FastAPI WebSocket 客户端
- 命令发送和响应处理
- 异步任务管理
- 错误处理策略

### [Edge 集成指南](./edge-guide.md)
Edge 节点的集成说明：
- 双向代理实现
- 设备连接管理
- 消息转发逻辑
- 故障恢复机制

### [迁移指南](./migration-guide.md)
从旧系统迁移到新协议：
- 版本兼容性说明
- 迁移步骤详解
- 常见问题解决
- 回滚方案

## 🚀 快速开始

根据您的角色选择相应的指南：

- **Gateway 开发者** → 阅读 [Gateway 集成指南](./gateway-guide.md)
- **Backend 开发者** → 阅读 [Backend 集成指南](./backend-guide.md)
- **Edge 开发者** → 阅读 [Edge 集成指南](./edge-guide.md)
- **系统升级** → 阅读 [迁移指南](./migration-guide.md)

## 🏗️ 集成架构

```
┌─────────────┐
│   Backend   │ ← HTTP/WebSocket 混合模式
└──────┬──────┘
       │
┌──────▼──────┐
│   Gateway   │ ← 中心路由节点
└──────┬──────┘
       │
┌──────▼──────┐
│    Edge     │ ← 设备代理节点
└──────┬──────┘
       │
┌──────▼──────┐
│   Device    │ ← 终端设备
└─────────────┘
```

## 🔑 核心集成要点

### 1. 协议版本
- 当前版本：1.0
- 所有组件必须使用相同版本
- 版本信息在每个消息中携带

### 2. 连接管理
- 自动重连机制
- 心跳保活（30秒间隔）
- 优雅断开处理

### 3. 消息验证
- 使用提供的验证函数
- 严格的类型检查
- 详细的错误信息

### 4. 性能考虑
- 消息批处理
- 连接池复用
- 异步处理模式

## 📋 集成检查清单

### Gateway
- [ ] WebSocket 服务器启动（端口 18081）
- [ ] 客户端注册处理
- [ ] 消息路由实现
- [ ] 心跳机制
- [ ] 错误处理

### Backend
- [ ] WebSocket 客户端连接
- [ ] 命令发送接口
- [ ] 响应处理逻辑
- [ ] 超时处理
- [ ] 日志记录

### Edge
- [ ] Gateway 连接管理
- [ ] 设备连接接受
- [ ] 双向消息转发
- [ ] 设备状态跟踪
- [ ] 故障恢复

## 🛠️ 调试工具

### 消息调试
```bash
# 监听 WebSocket 消息
wscat -c ws://localhost:18081

# 发送测试消息
echo '{"type":"heartbeat","clientId":"test","timestamp":"2024-01-20T10:00:00Z","version":"1.0"}' | wscat -c ws://localhost:18081
```

### 日志查看
```bash
# Gateway 日志
tail -f /var/log/jrsoft-gateway/gateway.log

# Backend 日志
tail -f /var/log/jrsoft-backend/backend.log
```

## 📊 监控指标

建议监控的关键指标：

1. **连接数** - 活跃的 WebSocket 连接数
2. **消息吞吐** - 每秒处理的消息数
3. **响应时间** - 命令响应的平均时间
4. **错误率** - 失败消息的比例
5. **重连次数** - 连接断开和重连的频率

## 🔗 相关资源

- [协议规范](../01-protocol/) - 了解协议细节
- [命令系统](../02-commands/) - 了解命令类型
- [架构文档](../03-architecture/) - 了解系统架构
- [示例代码](../05-examples/) - 查看实现示例