JRSoft Subway WebSocket 协议

统一的 WebSocket 协议定义，供 Gateway、Backend 和 Edge 组件使用。

📌 Versioning Policy（v1.7.3 起明示）

本包采用 schema 版本与 package 版本解耦演进 的策略：

| 概念 | 字段 | 演进规则 | |---|---|---| | Wire schema 版本 | PROTOCOL_VERSION 常量（src/index.ts）| 仅在协议 wire 行为变化时升（删字段 / 加 enum / 改类型等）| | npm 包发布版本 | package.json.version | 可独立 patch（fix publish-time bug、CI hook、文档等无 wire 影响）|

约束：package.json.version 必须 >= PROTOCOL_VERSION（schema 不允许领先包版本）。

例子：v1.7.3 patch 仅修复 v1.7.2 PROTOCOL_VERSION 漏改 + 加 prepublishOnly hook + 加本节文档——没有任何 wire 变化，因此：

package.json.version  = '1.7.3'   ← 新发布
PROTOCOL_VERSION      = '1.7.2'   ← schema 保持

scripts/check-protocol-version.js 在 prepublishOnly hook 中校验这条约束：若 schema 版本与包版本不一致，则 CHANGELOG 当前 entry 必须显式声明（防漏改静默通过）。

历史经验：v1.7.0 → v1.7.2 共 3 次 publish-time 漏改（RATER_DETECT / alias 撒谎 / PROTOCOL_VERSION），全靠 consumer audit catch。v1.7.3 起把这类机械问题写进 hook，consumer audit 焦点战略转移到真正的协议设计问题。

📋 概述

JRSoft Subway Protocol 是一个以 Gateway 为中心的实时通信协议，设计原则：

• 简单性优先 - 基础功能使用最简消息格式
• 渐进增强 - 通过可选字段支持高级功能
• 统一标准 - 所有组件使用 v1.0 协议
• 类型安全 - 完整的 TypeScript 支持

🏗️ 系统架构

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

📚 文档结构

01. 协议规范

• 协议规范 - 完整的协议定义
• 消息类型 - 所有消息类型详解
• 设计理念 - 协议设计决策

02. 命令系统

• Simple 命令 - 点对点命令
• Batch 命令 - 批量控制命令
• Complex 命令 - 复杂交互命令
• 强类型命令 - TypeScript 类型安全

03. 架构设计

• Edge 代理 - Edge 节点设计
• 设备协议 - 设备连接规范
• 消息路由 - 路由机制详解

04. 集成指南

• Gateway 集成 - Gateway 实施指南
• Backend 集成 - Backend 实施指南
• Edge 集成 - Edge 实施指南
• 迁移指南 - 版本迁移说明

05. 示例代码

• 命令示例 - 各类命令的使用示例
• 流程示例 - 完整的业务流程
• 代码片段 - 常用代码模板

06. 参考文档

• API 参考 - 完整的 API 文档
• 术语表 - 专业术语解释
• 常见问题 - FAQ

🚀 快速开始

安装

npm install jrsoft-subway-protocol

基本使用

import { 
  createSimpleCommand,
  validateMessage,
  GatewayClient 
} from 'jrsoft-subway-protocol';

// 创建命令
const command = createSimpleCommand({
  targetClientId: 'td-01',  // 直接指定设备ID
  commandCode: 'SET_BRIGHTNESS',
  deviceType: 'screen',
  deviceId: 1,
  operationType: 'write',
  parameters: { brightness: 80 }
});

// 验证消息
const valid = validateMessage(command);

// 发送命令
const client = new GatewayClient('ws://localhost:18081');
const response = await client.sendCommand(command);

强类型命令

import { createLedSwitchCommand } from 'jrsoft-subway-protocol';

// TypeScript 提供完整的类型检查和智能提示
const ledCommand = createLedSwitchCommand(
  'req-123',           // requestRef
  'td-01',             // targetClientId (设备ID)
  15,                  // deviceId (子硬件ID)
  'ON',                // switch: 'ON' | 'OFF'
  'write'              // operationType
);

🔑 核心特性

消息类型

• register - 客户端注册
• command - 命令请求
• command_response - 命令响应
• progress_update - 进度更新
• program - 节目上传
• heartbeat - 心跳保活
• error - 错误消息

命令类型

• Simple - 单次请求响应的简单命令
• Batch - 批量控制多个子硬件
• Complex - 支持多次响应的复杂命令

客户端类型

• BACKEND - 业务后端服务
• GATEWAY - 中心路由网关
• EDGE - 设备代理节点
• DEVICE - 终端设备

🛠️ 开发工具

类型定义

// 所有类型定义都已导出
import type { 
  CommandMessage,
  CommandResponseMessage,
  ProgressUpdateMessage 
} from 'jrsoft-subway-protocol';

验证工具

// 消息验证
validateMessage(message);

// 类型守卫
if (isCommandMessage(message)) {
  // TypeScript knows this is CommandMessage
}

工厂函数

// 创建各种消息
createRegisterMessage(clientId, clientType);
createHeartbeatMessage(clientId);
createErrorMessage(code, message);

📦 项目结构

jrsoft-subway-protocol/
├── src/                    # 源代码
│   ├── index.ts           # 主入口，协议定义
│   ├── command-types.ts   # 强类型命令定义
│   ├── command-factory.ts # 命令工厂函数
│   └── __tests__/         # 单元测试
├── docs/                   # 文档
│   ├── 01-protocol/       # 协议规范
│   ├── 02-commands/       # 命令系统
│   ├── 03-architecture/   # 架构设计
│   ├── 04-integration/    # 集成指南
│   ├── 05-examples/       # 示例代码
│   └── 06-reference/      # 参考文档
├── examples/               # 示例项目
└── package.json           # 项目配置

📊 版本信息

• 当前版本: 1.0.6
• 协议版本: 1.0
• 最低 Node.js: 14.0.0
• TypeScript: 4.5+

🌟 核心功能

连接管理

• 客户端注册与注销（含 ACK 确认）
• 心跳保活机制（含服务器状态）
• Edge 代理设备注册
• 会话管理和认证

命令系统

• Simple 命令 - 快速点对点控制
• Batch 命令 - 高效批量操作
• Complex 命令 - 复杂交互流程
• 强类型命令 - 基于 C# 模型的类型安全

进度报告

• 统一的 progress_update 机制
• 支持自定义阶段
• 结构化日志（ReportMessage）
• 设备操作追踪

程序管理

• 大文件上传支持
• 多阶段进度反馈
• 断点续传能力
• 完整性校验

🤝 贡献指南

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

📝 更新日志

查看 CHANGELOG.md 了解版本更新历史。

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🔗 相关项目

• jrsoft-subway-gateway - Gateway 实现
• jrsoft-subway-backend - Backend 实现
• jrsoft-subway-edge - Edge 实现

💬 联系方式

• 问题反馈: GitHub Issues
• 邮件: [email protected]