@thejrsoft/subway-protocol 1.3.0

package/docs/06-reference/faq.md

@@ -0,0 +1,302 @@
+# 常见问题解答（FAQ）
+
+## 协议相关
+
+### Q: 为什么选择 WebSocket 而不是 HTTP？
+
+A: WebSocket 提供了实时双向通信能力，非常适合我们的场景：
+- **实时性**：设备状态变化需要立即通知
+- **双向通信**：设备既要接收命令，也要主动上报状态
+- **低延迟**：避免 HTTP 轮询的开销
+- **持久连接**：减少连接建立的开销
+
+### Q: 协议版本如何管理？
+
+A: 当前协议版本为 1.0，升级策略：
+- 所有消息包含 `version` 字段
+- 向后兼容：新版本支持旧版本消息
+- 版本协商：注册时确定使用的协议版本
+- 平滑升级：支持新旧版本并存
+
+### Q: 消息大小有限制吗？
+
+A: 建议限制：
+- 单个消息不超过 1MB
+- 大文件通过 URL 下载，而非消息体
+- 批量数据分页传输
+- 支持消息压缩（gzip）
+
+### Q: 如何保证消息的可靠性？
+
+A: 多层保障机制：
+- WebSocket 基于 TCP，保证顺序和完整性
+- 心跳机制检测连接状态
+- 请求-响应模式确认执行结果
+- 支持重试和超时处理
+- 关键操作支持回调确认
+
+## 集成问题
+
+### Q: 如何处理网络断开重连？
+
+A: 推荐的重连策略：
+```javascript
+class ReconnectingWebSocket {
+  constructor(url) {
+    this.url = url;
+    this.reconnectInterval = 1000;
+    this.maxReconnectInterval = 30000;
+    this.reconnectDecay = 1.5;
+    this.reconnectAttempts = 0;
+  }
+
+  connect() {
+    this.ws = new WebSocket(this.url);
+    
+    this.ws.onclose = () => {
+      this.reconnect();
+    };
+    
+    this.ws.onopen = () => {
+      this.reconnectAttempts = 0;
+      this.register(); // 重新注册
+    };
+  }
+
+  reconnect() {
+    const timeout = Math.min(
+      this.reconnectInterval * Math.pow(this.reconnectDecay, this.reconnectAttempts),
+      this.maxReconnectInterval
+    );
+    
+    setTimeout(() => {
+      this.reconnectAttempts++;
+      this.connect();
+    }, timeout);
+  }
+}
+```
+
+### Q: Edge 设备注册的正确流程是什么？
+
+A: Edge 和设备的注册流程：
+
+1. **Edge 先注册自己**
+```json
+{
+  "type": "REGISTER",
+  "clientId": "edge-001",
+  "clientType": "EDGE"
+}
+```
+
+2. **Edge 为每个设备注册**
+```json
+{
+  "type": "REGISTER",
+  "clientId": "td-01",
+  "clientType": "DEVICE",
+  "edgeInfo": {
+    "edgeId": "edge-001"
+  }
+}
+```
+
+### Q: 如何实现批量命令的进度跟踪？
+
+A: 使用 progress_update 消息：
+```javascript
+// 批量执行示例
+async function executeBatchCommand(devices, command) {
+  const total = devices.length;
+  let completed = 0;
+  
+  for (const device of devices) {
+    try {
+      const result = await executeOnDevice(device, command);
+      completed++;
+      
+      // 发送进度更新
+      await sendProgressUpdate({
+        requestRef: command.requestRef,
+        status: 'IN_PROGRESS',
+        progress: Math.round((completed / total) * 100),
+        phase: 'executing',
+        command: {
+          deviceId: device.id,
+          result: result
+        }
+      });
+    } catch (error) {
+      // 处理错误但继续执行
+    }
+  }
+  
+  // 发送最终响应
+  return {
+    type: 'COMMAND_RESPONSE',
+    status: 'COMPLETED',
+    summary: { total, completed }
+  };
+}
+```
+
+### Q: 心跳机制的最佳实践？
+
+A: 推荐配置：
+- 发送间隔：30秒
+- 超时时间：90秒（3个心跳周期）
+- 包含序列号用于匹配
+- 利用心跳确认携带服务器状态
+
+```javascript
+class HeartbeatManager {
+  constructor(websocket, clientId) {
+    this.ws = websocket;
+    this.clientId = clientId;
+    this.sequence = 0;
+    this.interval = 30000; // 30秒
+  }
+  
+  start() {
+    this.timer = setInterval(() => {
+      this.send();
+    }, this.interval);
+  }
+  
+  send() {
+    this.ws.send(JSON.stringify({
+      type: 'HEARTBEAT',
+      clientId: this.clientId,
+      sequence: ++this.sequence,
+      clientTime: new Date().toISOString(),
+      timestamp: new Date().toISOString(),
+      version: '1.0'
+    }));
+  }
+  
+  stop() {
+    clearInterval(this.timer);
+  }
+}
+```
+
+## 性能优化
+
+### Q: 如何优化大量设备的消息推送？
+
+A: 性能优化策略：
+1. **消息聚合**：相同的命令合并发送
+2. **批量处理**：使用 BATCH 命令类型
+3. **优先级队列**：重要消息优先处理
+4. **限流控制**：避免消息风暴
+5. **Edge 缓存**：利用 Edge 节点缓存
+
+### Q: Gateway 的负载均衡如何实现？
+
+A: 多种负载均衡策略：
+- **连接数均衡**：新连接分配到连接数最少的 Gateway
+- **消息量均衡**：根据消息吞吐量分配
+- **地理位置**：就近接入原则
+- **设备类型**：特定设备类型分配到特定 Gateway
+
+### Q: 如何处理消息积压？
+
+A: 消息积压处理：
+1. **监控队列长度**：设置阈值告警
+2. **优先级处理**：优先处理高优先级消息
+3. **过期丢弃**：超时消息直接丢弃
+4. **反压控制**：通知发送方降速
+5. **水平扩展**：增加处理节点
+
+## 故障排查
+
+### Q: 设备无法连接到 Gateway？
+
+A: 排查步骤：
+1. **网络连通性**：ping Gateway 地址
+2. **端口开放**：telnet Gateway 18081端口
+3. **防火墙规则**：检查防火墙设置
+4. **证书问题**：如果使用 WSS，检查证书
+5. **日志分析**：查看 Gateway 和设备日志
+
+### Q: 命令执行超时如何处理？
+
+A: 超时处理机制：
+```javascript
+async function executeCommandWithTimeout(command, timeout = 30000) {
+  return Promise.race([
+    executeCommand(command),
+    new Promise((_, reject) => 
+      setTimeout(() => reject(new Error('Command timeout')), timeout)
+    )
+  ]);
+}
+```
+
+### Q: 如何调试协议消息？
+
+A: 调试工具和方法：
+1. **浏览器开发工具**：查看 WebSocket 消息
+2. **Wireshark**：网络层抓包分析
+3. **日志记录**：记录所有收发消息
+4. **Mock Server**：模拟 Gateway 进行测试
+
+```javascript
+// 消息日志中间件
+function messageLogger(direction) {
+  return (message) => {
+    console.log(`[${new Date().toISOString()}] ${direction}:`, 
+      JSON.stringify(message, null, 2));
+    return message;
+  };
+}
+```
+
+## 安全相关
+
+### Q: 如何保证通信安全？
+
+A: 安全措施：
+1. **使用 WSS**：WebSocket over TLS
+2. **Token 认证**：注册时验证身份
+3. **消息签名**：关键命令签名验证
+4. **访问控制**：基于客户端类型的权限控制
+5. **审计日志**：记录所有操作
+
+### Q: 如何防止恶意连接？
+
+A: 防护措施：
+- **连接限流**：限制单 IP 连接数
+- **认证超时**：未认证连接自动断开
+- **黑名单**：恶意 IP 自动封禁
+- **异常检测**：异常行为模式识别
+
+## 扩展性
+
+### Q: 如何添加新的命令类型？
+
+A: 扩展步骤：
+1. 在 C# 模型项目中定义命令
+2. 生成 TypeScript 类型定义
+3. 实现命令处理逻辑
+4. 更新文档
+5. 版本兼容性测试
+
+### Q: 如何支持新的设备类型？
+
+A: 新设备接入：
+1. 定义设备类型和能力
+2. 实现设备通信适配器
+3. 注册设备命令映射
+4. 测试各种命令场景
+5. 更新设备管理文档
+
+### Q: 协议如何支持未来扩展？
+
+A: 扩展性设计：
+- **版本字段**：支持协议演进
+- **通用字段**：metadata、context 等扩展字段
+- **自定义命令**：GenericCommand 支持任意命令
+- **插件机制**：Gateway 和 Edge 支持插件
+- **向后兼容**：新版本兼容旧版本消息

package/docs/06-reference/glossary.md

@@ -0,0 +1,232 @@
+# 术语表
+
+本文档解释 JRSoft Subway 项目中使用的专业术语和概念。
+
+## 系统组件
+
+### Gateway（网关）
+中心路由节点，负责：
+- 管理所有客户端连接（Backend、Edge）
+- 消息路由和转发
+- 连接状态管理
+- 负载均衡
+- 协议转换
+
+### Edge（边缘节点）
+设备代理节点，作为本地网关：
+- 管理本地设备连接
+- 设备状态缓存
+- 命令转发和聚合
+- 离线缓存能力
+- 批量操作优化
+
+### Device（设备）
+物理终端设备：
+- 地铁隧道中的显示屏
+- LED 光柱控制器
+- 同步器设备
+- 传感器设备
+- 媒体播放器
+
+### Backend（后端）
+业务服务系统：
+- Web API 服务
+- 管理控制台
+- 调度系统
+- 监控服务
+- 数据分析服务
+
+## 协议概念
+
+### WebSocket
+全双工通信协议：
+- 基于 TCP 的持久连接
+- 支持实时双向通信
+- 低延迟、高效率
+- 心跳保活机制
+
+### Message（消息）
+协议通信的基本单位：
+- JSON 格式
+- 包含类型、时间戳、版本
+- 支持请求-响应模式
+- 支持单向通知
+
+### Command（命令）
+控制指令：
+- Simple - 简单命令，一次请求一次响应
+- Batch - 批量命令，针对多个设备
+- Complex - 复杂命令，支持多次响应
+
+### Progress Update（进度更新）
+长时间操作的状态报告：
+- 实时进度百分比
+- 阶段性结果
+- 结构化日志
+- 错误和警告信息
+
+## 业务概念
+
+### Program（节目/程序）
+在设备上运行的内容：
+- 广告视频
+- 图片轮播
+- 文字滚动
+- 动态效果
+
+### Client ID（客户端标识）
+唯一标识符格式：
+- Device: `td-01`（隧道设备编号）
+- Edge: `edge-001`（边缘节点编号）
+- Backend: `backend-api`（后端服务名）
+- targetClientId: 直接使用设备ID，如 `td-01`（Gateway 自动路由）
+
+### Request Reference（请求引用）
+命令追踪标识：
+- 唯一标识一次命令请求
+- 用于关联请求和响应
+- 支持异步回调
+- 便于日志追踪
+
+### Session（会话）
+客户端连接生命周期：
+- 注册时创建
+- 心跳维持
+- 注销时销毁
+- 包含认证信息
+
+## 技术概念
+
+### Heartbeat（心跳）
+连接保活机制：
+- 默认 30 秒发送一次
+- 90 秒超时断开
+- 包含序列号
+- 可携带状态信息
+
+### Callback（回调）
+异步通知机制：
+- HTTP POST 请求
+- 命令完成后触发
+- 包含完整响应数据
+- 支持重试机制
+
+### Priority（优先级）
+消息处理优先级：
+- CRITICAL - 关键，立即处理
+- HIGH - 高优先级
+- NORMAL - 普通优先级
+- LOW - 低优先级，空闲时处理
+
+### Timeout（超时）
+操作时限控制：
+- 命令执行超时
+- 连接超时
+- 心跳超时
+- 可配置和扩展
+
+## 状态定义
+
+### Connection State（连接状态）
+- CONNECTING - 连接中
+- CONNECTED - 已连接
+- REGISTERED - 已注册
+- DISCONNECTING - 断开中
+- DISCONNECTED - 已断开
+
+### Command Status（命令状态）
+- PENDING - 待执行
+- IN_PROGRESS - 执行中
+- COMPLETED - 已完成
+- FAILED - 失败
+- TIMEOUT - 超时
+- CANCELLED - 已取消
+
+### Device Status（设备状态）
+- ONLINE - 在线
+- OFFLINE - 离线
+- BUSY - 忙碌
+- ERROR - 错误
+- MAINTENANCE - 维护中
+
+## 数据格式
+
+### ISO 8601
+国际标准时间格式：
+- 示例: `2024-01-20T10:00:00Z`
+- 包含时区信息
+- 精确到秒或毫秒
+- UTC 时间推荐
+
+### Snowflake ID
+分布式唯一ID：
+- 64 位整数
+- 时间戳 + 机器ID + 序列号
+- 保证全局唯一
+- 有序可排序
+
+### Range Expression（范围表达式）
+批量设备选择语法：
+- `1-10` - 1到10号设备
+- `1,3,5` - 1、3、5号设备
+- `1-10,20-30` - 组合范围
+- `0` - 所有设备
+
+## 性能指标
+
+### Latency（延迟）
+消息传输时间：
+- 网络延迟
+- 处理延迟
+- 往返时间（RTT）
+- 通常 <100ms
+
+### Throughput（吞吐量）
+处理能力：
+- 消息/秒（MPS）
+- 并发连接数
+- 带宽利用率
+- 峰值处理能力
+
+### Scalability（可扩展性）
+系统扩展能力：
+- 水平扩展（增加节点）
+- 垂直扩展（增强单机）
+- 负载均衡
+- 分布式架构
+
+## 安全概念
+
+### Authentication（认证）
+身份验证：
+- Token 认证
+- 证书认证
+- API Key
+- 会话管理
+
+### Authorization（授权）
+权限控制：
+- 基于角色（RBAC）
+- 基于资源
+- 操作权限
+- 访问控制列表（ACL）
+
+### Encryption（加密）
+数据保护：
+- TLS/SSL 传输加密
+- 消息签名
+- 敏感数据加密
+- 密钥管理
+
+## 常见缩写
+
+- **WS** - WebSocket
+- **API** - Application Programming Interface
+- **JSON** - JavaScript Object Notation
+- **UTC** - Coordinated Universal Time
+- **RTT** - Round Trip Time
+- **ACK** - Acknowledgment
+- **ID** - Identifier
+- **URL** - Uniform Resource Locator
+- **HTTP** - Hypertext Transfer Protocol
+- **TCP** - Transmission Control Protocol