# 架构文档

本目录包含 JRSoft Subway 系统的架构设计文档。

## 📚 文档列表

### [Edge 代理架构](./edge-proxy.md)
Edge 节点的设计和实现：
- Edge 作为设备代理的角色
- 设备连接管理
- 消息路由和转发
- 故障处理和重连机制

### [设备协议](./device-protocol.md)
设备到 Edge 的 WebSocket 协议：
- 设备注册流程
- 心跳机制（30秒间隔）
- 命令转发和响应
- 连接状态管理

### [消息路由流程](./routing-flow.md)
系统中的消息路由机制：
- Backend → Gateway → Edge → Device 流程
- targetClientId 格式和解析
- 路由决策逻辑
- 错误处理和超时

## 🏗️ 系统架构

```
┌─────────────┐     ┌─────────────┐     ┌──────────┐     ┌──────────┐
│   Backend   │────▶│   Gateway   │────▶│   Edge   │────▶│  Device  │
│  (FastAPI)  │◀────│(WebSocket)  │◀────│  (Proxy) │◀────│(Client)  │
└─────────────┘     └─────────────┘     └──────────┘     └──────────┘
     18082              18081             Dynamic          Dynamic
```

## 🔑 核心概念

### 连接管理
- **Backend-Gateway**: HTTP/WebSocket 混合模式
- **Gateway-Edge**: 持久 WebSocket 连接
- **Edge-Device**: 设备主动连接，Edge 管理

### 标识符格式
- **Edge ID**: `edge-{location}` (如 `edge-001`)
- **Device ID**: `{type}-{number}` (如 `td-01`, `screen-05`)
- **Target Client ID**: 直接使用设备ID (如 `td-01`)，Gateway自动路由

### 消息流向
- **下行命令**: Backend → Gateway → Edge → Device
- **上行响应**: Device → Edge → Gateway → Backend
- **进度更新**: 支持多次中间状态报告

## 🚀 快速理解

1. **Gateway 是中心枢纽** - 所有消息都经过 Gateway 路由
2. **Edge 是设备代理** - 设备不直接连接 Gateway
3. **设备主动连接** - 设备连接到 Edge，而非相反
4. **自动路由** - Backend只需指定设备ID，Gateway自动查找对应Edge

## 🔗 相关文档

- [协议规范](../01-protocol/) - 了解消息格式
- [命令系统](../02-commands/) - 了解命令类型
- [集成指南](../04-integration/) - 如何集成各组件