# JRSoft Subway 协议设计理念

本文档记录了 JRSoft Subway WebSocket 协议的核心设计决策和理念。

## 目录

- [总体设计理念](#总体设计理念)
- [长时间运行操作](#长时间运行操作)
- [消息类型设计](#消息类型设计)
- [进度上报机制](#进度上报机制)
- [错误处理策略](#错误处理策略)

## 总体设计理念

### 1. 分层架构设计

系统采用严格的分层架构：
- **Backend** → **Gateway** → **Edge** → **Device**
- Gateway 作为中央路由器，管理所有 Edge 连接
- Edge 作为设备接入点，管理本地设备连接
- 设备不直接连接 Gateway，确保架构清晰

### 2. 渐进式复杂度

协议采用渐进式设计，从简单到复杂：
- **Simple命令**：一次请求，一次响应
- **Batch命令**：一次请求，批量执行，汇总响应
- **Complex命令**：一次请求，多次进度更新，最终响应

### 3. 明确的生命周期

每个操作都有清晰的开始和结束：
- 开始：特定的请求消息（command、program）
- 过程：可选的进度更新（progress_update）
- 结束：明确的响应消息（command_response、program_response）

## 长时间运行操作

### Complex命令设计

**为什么需要Complex类型？**
- 某些操作需要执行多个步骤，每个步骤都有独立的结果
- 客户端需要实时了解执行进度
- 传统的请求-响应模式无法满足需求

**设计决策：**
1. 复用现有的 `command` 消息结构，通过 `commandType: 'complex'` 区分
2. 使用 `progress_update` 报告中间结果，保持消息格式统一
3. 最终通过 `command_response` 结束，确保有明确的终止信号

**典型应用场景：**
- 健康检查：需要检查多个组件状态
- 系统诊断：逐步执行多项测试
- 状态监控：持续报告状态变化

### 批量命令新设计（借鉴Complex模式）

**为什么要重新设计批量命令？**
- 当前设计要求设备理解批量概念，增加了复杂度
- 设备需要处理范围解析、批量执行等逻辑
- 难以实时跟踪每个设备的执行状态

**新的设计理念：**
1. 批量命令由 Gateway/Edge 处理向下游传递到 Device
2. Device 将批量命令分解为多个 Simple 命令
3. 每个设备的响应通过 `progress_update` 实时上报
4. 最终通过 `command_response` 返回汇总结果

**优势：**
- **设备端简化**：只需实现 Simple 命令
- **更好的可观察性**：实时看到每个设备状态
- **灵活的执行策略**：Gateway 可控制并发、失败处理等
- **协议统一**：批量和 Complex 都使用相同的进度机制

### 程序上传设计

**为什么程序上传独立于命令系统？**
- 程序上传是特殊的业务流程，不是简单的命令执行
- 需要携带大量元数据（任务ID、程序ID、发布时间等）
- 上传过程涉及多个明确的阶段

**设计决策：**
1. 使用专门的 `program` 和 `program_response` 消息类型
2. 引入 `context` 确保每个进度更新都能关联到具体程序
3. `program_response` 简化设计，仅作为流程结束标志

**阶段划分理由：**
- **downloading**：网络传输阶段
- **decompressing**：文件处理阶段
- **preprocessing**：内容验证阶段
- **createFrames**：数据转换阶段
- **uploading**：设备写入阶段
- **statistics**：结果统计阶段

## 消息类型设计

### 为什么不合并program和command？

虽然两者都支持进度更新，但本质不同：
- **命令**：执行设备操作，关注操作结果
- **程序上传**：传输和安装内容，关注传输进度

保持分离的好处：
1. 语义清晰，易于理解
2. 可以独立演进，互不影响
3. 便于实现不同的业务逻辑

### progress_update的通用性

`progress_update` 设计为通用的进度报告机制，可用于：
- Batch命令、Complex命令的中间结果
- 程序上传的阶段进度
- 未来其他长时间操作

关键设计：
- `sourceType` 区分来源类型
- `report` 提供结构化日志
- `command` 记录设备操作
- `context` 关联程序信息

## 进度上报机制

### 状态管理

六种状态覆盖所有场景：
- **pending**：等待开始
- **in_progress**：执行中
- **paused**：已暂停
- **completed**：成功完成
- **failed**：执行失败
- **cancelled**：已取消

### 日志结构化

统一的 `ReportMessage` 结构：
```typescript
{
  level: 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR' | 'CRITICAL';
  message: string;      // 必需的消息内容
  code?: string;        // 可选的标准化代码
  data?: object;        // 可选的附加数据
}
```

优势：
- 便于日志分级处理
- 支持错误代码标准化
- 可携带结构化数据

## 错误处理策略

### 分层错误处理

1. **传输层错误**：WebSocket连接问题，由Gateway处理
2. **协议层错误**：消息格式错误，返回error消息
3. **业务层错误**：命令执行失败，在响应中体现

### 错误信息设计

- 使用 `report` 结构统一错误信息
- `code` 用于错误分类
- `data` 携带错误详情
- `retryable` 标记是否可重试

## 设计权衡

### 1. 简单性 vs 功能性

选择：优先简单性，通过可选字段扩展功能
- 基础功能保持简单
- 高级功能通过可选字段实现
- 避免过度设计

### 2. 统一性 vs 特殊性

选择：在统一框架下支持特殊需求
- 统一的消息基础结构
- 统一的进度上报机制
- 特殊需求通过扩展字段满足

### 3. 同步 vs 异步

选择：支持两种模式
- Simple命令：同步模式
- Complex命令和程序上传：异步模式
- 通过消息类型自然区分

## 未来扩展性

协议设计考虑了未来扩展：
1. 版本字段支持协议演进
2. 可选字段支持功能扩展
3. 新的消息类型可以无缝添加
4. 向后兼容性通过版本协商实现

---

*本文档会随着协议演进持续更新*