# 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. 协议规范](./docs/01-protocol/)
- [协议规范](./docs/01-protocol/specification.md) - 完整的协议定义
- [消息类型](./docs/01-protocol/message-types.md) - 所有消息类型详解
- [设计理念](./docs/01-protocol/design-rationale.md) - 协议设计决策

### [02. 命令系统](./docs/02-commands/)
- [Simple 命令](./docs/02-commands/simple-command.md) - 点对点命令
- [Batch 命令](./docs/02-commands/batch-command.md) - 批量控制命令
- [Complex 命令](./docs/02-commands/complex-command.md) - 复杂交互命令
- [强类型命令](./docs/02-commands/typed-commands.md) - TypeScript 类型安全

### [03. 架构设计](./docs/03-architecture/)
- [Edge 代理](./docs/03-architecture/edge-proxy.md) - Edge 节点设计
- [设备协议](./docs/03-architecture/device-protocol.md) - 设备连接规范
- [消息路由](./docs/03-architecture/routing-flow.md) - 路由机制详解

### [04. 集成指南](./docs/04-integration/)
- [Gateway 集成](./docs/04-integration/gateway-guide.md) - Gateway 实施指南
- [Backend 集成](./docs/04-integration/backend-guide.md) - Backend 实施指南
- [Edge 集成](./docs/04-integration/edge-guide.md) - Edge 实施指南
- [迁移指南](./docs/04-integration/migration-guide.md) - 版本迁移说明

### [05. 示例代码](./docs/05-examples/)
- 命令示例 - 各类命令的使用示例
- 流程示例 - 完整的业务流程
- 代码片段 - 常用代码模板

### [06. 参考文档](./docs/06-reference/)
- API 参考 - 完整的 API 文档
- 术语表 - 专业术语解释
- 常见问题 - FAQ

## 🚀 快速开始

### 安装

```bash
npm install jrsoft-subway-protocol
```

### 基本使用

```typescript
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);
```

### 强类型命令

```typescript
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** - 终端设备

## 🛠️ 开发工具

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

### 验证工具
```typescript
// 消息验证
validateMessage(message);

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

### 工厂函数
```typescript
// 创建各种消息
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](./CHANGELOG.md) 了解版本更新历史。

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](./LICENSE) 文件了解详情。

## 🔗 相关项目

- [jrsoft-subway-gateway](https://github.com/jrsoft/subway-gateway) - Gateway 实现
- [jrsoft-subway-backend](https://github.com/jrsoft/subway-backend) - Backend 实现
- [jrsoft-subway-edge](https://github.com/jrsoft/subway-edge) - Edge 实现

## 💬 联系方式

- 问题反馈: [GitHub Issues](https://github.com/jrsoft/subway-protocol/issues)
- 邮件: tech@jrsoft.com