# 术语表

本文档解释 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