@thejrsoft/subway-protocol 1.3.0

package/COMMAND_VALIDATION_RULES.md

@@ -0,0 +1,178 @@
+# 命令验证规则说明
+
+## 命令接口设计
+
+### 1. 类型安全的命令接口
+
+为了提供编译时类型安全，我们定义了三个特定的命令接口：
+
+```typescript
+// 简单命令 - 单设备操作
+interface SimpleCommand {
+  commandType: CommandType.SIMPLE;  // 字面量类型，必须是 'SIMPLE'
+  deviceId: number | string;        // 单个设备
+  deviceType: string;               // 必需
+  operationType: OperationType;     // 必需
+}
+
+// 批量命令 - 多设备操作
+interface BatchCommand {
+  commandType: CommandType.BATCH;   // 字面量类型，必须是 'BATCH'
+  deviceId: number[] | string;      // 设备数组或范围表达式
+  deviceType: string;               // 必需
+  operationType: OperationType;     // 必需
+}
+
+// 复杂命令 - 系统级操作
+interface ComplexCommand {
+  commandType: CommandType.COMPLEX; // 字面量类型，必须是 'COMPLEX'
+  deviceId?: number | number[] | string;  // 可选
+  deviceType?: string;              // 可选
+  operationType?: OperationType;    // 可选
+}
+```
+
+### 2. 通用命令接口（GenericCommand）
+
+用于处理运行时动态构建的命令：
+
+```typescript
+interface GenericCommand {
+  commandType?: CommandType;  // 可选，默认为 SIMPLE
+  deviceId?: number | number[] | string;
+  deviceType?: string;
+  operationType?: OperationType;
+}
+```
+
+**重要**：GenericCommand 的字段都是可选的，但实际验证规则由 `MessageValidator` 在运行时根据 `commandType` 的值动态应用。
+
+## 验证规则
+
+### MessageValidator 的验证逻辑
+
+```typescript
+const commandType = message.command.commandType || CommandType.SIMPLE;
+
+switch (commandType) {
+  case CommandType.SIMPLE:
+    // 必需: deviceType, deviceId, operationType
+    // deviceId 必须是单个值（不能是数组）
+    
+  case CommandType.BATCH:
+    // 必需: deviceType, deviceId, operationType
+    // deviceId 必须是数组或字符串（范围表达式）
+    
+  case CommandType.COMPLEX:
+    // 可选: deviceType, deviceId, operationType
+}
+```
+
+### 验证示例
+
+#### 1. SIMPLE 命令验证
+
+```typescript
+// ✅ 有效的 SIMPLE 命令
+const simpleCmd: GenericCommand = {
+  commandType: CommandType.SIMPLE,
+  commandCode: 'LedSwitch',
+  deviceId: 123,  // 单个设备
+  deviceType: 'pillar',
+  operationType: OperationType.WRITE
+};
+
+// ❌ 无效的 SIMPLE 命令
+const invalidSimple: GenericCommand = {
+  commandType: CommandType.SIMPLE,
+  commandCode: 'LedSwitch',
+  deviceId: [123, 124],  // 错误：SIMPLE 不支持数组
+  deviceType: 'pillar',
+  operationType: OperationType.WRITE
+};
+// 验证器会报错："SIMPLE command deviceId must be a single value"
+```
+
+#### 2. BATCH 命令验证
+
+```typescript
+// ✅ 有效的 BATCH 命令
+const batchCmd: GenericCommand = {
+  commandType: CommandType.BATCH,
+  commandCode: 'LedSwitch',
+  deviceId: [123, 124, 125],  // 设备数组
+  deviceType: 'pillar',
+  operationType: OperationType.WRITE
+};
+
+// ✅ 也是有效的 BATCH 命令
+const batchRangeCmd: GenericCommand = {
+  commandType: CommandType.BATCH,
+  commandCode: 'LedSwitch',
+  deviceId: '123-130',  // 范围表达式
+  deviceType: 'pillar',
+  operationType: OperationType.WRITE
+};
+
+// ❌ 无效的 BATCH 命令
+const invalidBatch: GenericCommand = {
+  commandType: CommandType.BATCH,
+  commandCode: 'LedSwitch',
+  deviceId: 123,  // 错误：BATCH 需要数组或字符串
+  deviceType: 'pillar',
+  operationType: OperationType.WRITE
+};
+// 验证器会报错："BATCH command deviceId must be an array or string"
+```
+
+#### 3. COMPLEX 命令验证
+
+```typescript
+// ✅ 有效的 COMPLEX 命令（最小配置）
+const complexCmd: GenericCommand = {
+  commandType: CommandType.COMPLEX,
+  commandCode: 'SystemDiagnostics'
+  // deviceId, deviceType, operationType 都是可选的
+};
+
+// ✅ 也是有效的 COMPLEX 命令（包含可选字段）
+const complexCmdFull: GenericCommand = {
+  commandType: CommandType.COMPLEX,
+  commandCode: 'SystemReset',
+  deviceId: 'all',  // 可以提供但不是必需的
+  parameters: { force: true }
+};
+```
+
+## 为什么这样设计？
+
+1. **类型安全的接口（SimpleCommand, BatchCommand, ComplexCommand）**
+   - 编译时类型检查
+   - IDE 自动补全
+   - 明确的 API 契约
+
+2. **通用接口（GenericCommand）**
+   - 处理动态构建的命令
+   - 向后兼容
+   - 灵活的运行时验证
+
+3. **验证器分离**
+   - 业务逻辑与类型定义分离
+   - 可以轻松修改验证规则而不影响类型定义
+   - 支持自定义验证逻辑
+
+## 使用建议
+
+1. **编写新代码时**：优先使用类型安全的接口（SimpleCommand, BatchCommand, ComplexCommand）
+
+2. **处理外部输入时**：使用 GenericCommand + MessageValidator
+
+3. **类型断言**：
+   ```typescript
+   // 验证后进行类型断言
+   const result = MessageValidator.validateCommandMessage(message);
+   if (result.valid && message.command.commandType === CommandType.SIMPLE) {
+     const simpleCmd = message.command as SimpleCommand;
+     // 现在 TypeScript 知道 deviceId 是 number | string
+   }
+   ```

package/DOCUMENTATION_REORGANIZATION_SUMMARY.md

@@ -0,0 +1,81 @@
+# 文档重组总结
+
+## 重组完成
+
+已将 jrsoft-subway-protocol 的文档重新组织为清晰的 6 个主题目录结构。
+
+## 新的文档结构
+
+```
+docs/
+├── 01-protocol/          # 协议规范
+│   ├── README.md        # 索引
+│   ├── specification.md # 协议规范（原 PROTOCOL_SPECIFICATION.md）
+│   ├── message-types.md # 消息类型详解（新增）
+│   └── design-rationale.md # 设计理念（原 DESIGN_RATIONALE.md）
+│
+├── 02-commands/         # 命令系统
+│   ├── README.md       # 索引
+│   ├── simple-command.md # Simple 命令（原 SIMPLE_COMMAND_FLOW.md）
+│   ├── batch-command.md  # Batch 命令（合并自两个文档）
+│   ├── complex-command.md # Complex 命令（原 COMPLEX_COMMAND_FLOW.md）
+│   └── typed-commands.md # 强类型命令（合并自两个文档）
+│
+├── 03-architecture/     # 架构设计
+│   ├── README.md       # 索引
+│   ├── edge-proxy.md   # Edge 代理（原 EDGE_PROXY_GUIDE.md）
+│   ├── device-protocol.md # 设备协议（原 device-to-edge-protocol.md）
+│   └── routing-flow.md # 消息路由（新增）
+│
+├── 04-integration/      # 集成指南
+│   ├── README.md       # 索引
+│   ├── gateway-guide.md # Gateway 指南（原 GATEWAY_INTEGRATION.md）
+│   ├── backend-guide.md # Backend 指南（新增）
+│   ├── edge-guide.md   # Edge 指南（新增）
+│   └── migration-guide.md # 迁移指南（原 MIGRATION_GUIDE.md）
+│
+├── 05-examples/         # 示例代码
+│   └── README.md       # 索引（待补充具体示例）
+│
+└── 06-reference/        # 参考文档
+    └── README.md       # 索引（待补充 API 文档等）
+```
+
+## 主要改进
+
+### 1. 文档合并
+- **批量命令文档**：将 `BATCH_COMMAND_DESIGN.md` 和 `batch-command-specification.md` 合并为统一的 `batch-command.md`
+- **强类型命令文档**：将 `TYPED_COMMANDS_SUMMARY.md` 和 `typed-commands-guide.md` 合并为 `typed-commands.md`
+
+### 2. 新增文档
+- **消息类型详解** (`message-types.md`)：从协议规范中提取，专门详解所有消息类型
+- **消息路由流程** (`routing-flow.md`)：详细说明系统的消息路由机制
+- **Backend 集成指南** (`backend-guide.md`)：完整的 Python/FastAPI 集成示例
+- **Edge 集成指南** (`edge-guide.md`)：详细的 Edge 节点实现指南
+
+### 3. 结构优化
+- 每个目录都有 README.md 作为索引
+- 按主题分类，便于查找
+- 从协议→命令→架构→集成的渐进式学习路径
+- 清晰的导航和交叉引用
+
+### 4. 已删除文件
+移除了以下已迁移的旧文档：
+- 根目录的所有 `.md` 文档（除 README.md 和 CHANGELOG.md）
+- `docs/` 目录下的旧文档
+
+## 后续建议
+
+1. **补充示例代码**：在 `05-examples/` 目录下添加具体的命令示例和流程示例
+2. **完善 API 文档**：在 `06-reference/` 目录下添加完整的 API 参考文档
+3. **添加图表**：为架构和流程文档添加更多可视化图表
+4. **版本管理**：为文档添加版本标记，便于追踪更新
+
+## 文档维护指南
+
+1. **新增功能**：在相应的主题目录下添加文档
+2. **更新内容**：保持同一主题的内容在同一文档中
+3. **交叉引用**：使用相对路径链接相关文档
+4. **索引更新**：修改文档时同步更新目录的 README.md
+
+通过这次重组，文档结构更加清晰，便于开发者查找和学习。

package/DOCUMENTATION_STRUCTURE.md

@@ -0,0 +1,106 @@
+# 文档结构优化方案
+
+## 当前问题
+
+1. **文档分散**：根目录和 docs/ 目录都有文档，组织不清晰
+2. **内容重复**：
+   - BATCH_COMMAND_DESIGN.md 和 docs/batch-command-specification.md
+   - TYPED_COMMANDS_SUMMARY.md 和 docs/typed-commands-guide.md
+   - 多个文档包含类似的命令示例
+3. **分类混乱**：设计文档、规范文档、实施指南混在一起
+4. **导航困难**：缺少清晰的文档层次结构
+
+## 新的文档结构
+
+```
+jrsoft-subway-protocol/
+├── README.md                    # 项目概述和快速导航
+├── CHANGELOG.md                 # 版本变更记录
+├── docs/
+│   ├── 01-protocol/            # 核心协议规范
+│   │   ├── README.md           # 协议概述
+│   │   ├── specification.md    # 完整协议规范（合并现有内容）
+│   │   ├── message-types.md    # 消息类型详解
+│   │   └── design-rationale.md # 设计理念和决策
+│   │
+│   ├── 02-commands/            # 命令系统文档
+│   │   ├── README.md           # 命令系统概述
+│   │   ├── simple-command.md   # Simple 命令详解
+│   │   ├── batch-command.md    # Batch 命令详解（合并内容）
+│   │   ├── complex-command.md  # Complex 命令详解
+│   │   └── typed-commands.md   # 强类型命令系统（合并内容）
+│   │
+│   ├── 03-architecture/        # 架构相关文档
+│   │   ├── README.md           # 架构概述
+│   │   ├── edge-proxy.md       # Edge 代理架构
+│   │   ├── device-protocol.md  # 设备到 Edge 协议
+│   │   └── routing-flow.md     # 消息路由流程
+│   │
+│   ├── 04-integration/         # 集成和实施指南
+│   │   ├── README.md           # 集成概述
+│   │   ├── gateway-guide.md    # Gateway 集成指南
+│   │   ├── backend-guide.md    # Backend 集成指南
+│   │   ├── edge-guide.md       # Edge 集成指南
+│   │   └── migration-guide.md  # 迁移指南
+│   │
+│   ├── 05-examples/            # 示例和参考
+│   │   ├── README.md           # 示例概述
+│   │   ├── command-examples.md # 各类命令示例
+│   │   ├── flow-examples.md    # 流程示例
+│   │   └── code-snippets.md    # 代码片段
+│   │
+│   └── 06-reference/           # 参考文档
+│       ├── api.md              # API 参考
+│       ├── glossary.md         # 术语表
+│       └── faq.md              # 常见问题
+│
+├── examples/                    # 代码示例（保持不变）
+└── src/                        # 源代码（保持不变）
+```
+
+## 文档合并计划
+
+### 1. 批量命令文档合并
+- 将 `BATCH_COMMAND_DESIGN.md` 和 `docs/batch-command-specification.md` 合并
+- 新文件：`docs/02-commands/batch-command.md`
+- 保留最新的 progress_update 设计
+- 整合范围语法示例
+
+### 2. 强类型命令文档合并
+- 将 `TYPED_COMMANDS_SUMMARY.md` 和 `docs/typed-commands-guide.md` 合并
+- 新文件：`docs/02-commands/typed-commands.md`
+- 包含 C# 模型集成内容
+
+### 3. 协议规范整理
+- 将 `PROTOCOL_SPECIFICATION.md` 作为主要规范文档
+- 移除其中的重复示例，引用专门的示例文档
+- 新位置：`docs/01-protocol/specification.md`
+
+### 4. 命令流程文档整理
+- 整合 `SIMPLE_COMMAND_FLOW.md`、`COMPLEX_COMMAND_FLOW.md`
+- 新位置：`docs/02-commands/` 目录下的各自文件
+
+### 5. 架构文档整理
+- `EDGE_PROXY_GUIDE.md` → `docs/03-architecture/edge-proxy.md`
+- `docs/device-to-edge-protocol.md` → `docs/03-architecture/device-protocol.md`
+- 添加消息路由流程文档
+
+### 6. 集成指南整理
+- `GATEWAY_INTEGRATION.md` → `docs/04-integration/gateway-guide.md`
+- `MIGRATION_GUIDE.md` → `docs/04-integration/migration-guide.md`
+
+## 实施步骤
+
+1. 创建新的目录结构
+2. 逐个合并和迁移文档
+3. 更新所有内部链接
+4. 删除旧文档
+5. 更新 README.md 导航
+
+## 优势
+
+1. **清晰的层次结构**：按主题分类，易于导航
+2. **避免重复**：相同主题的内容集中在一处
+3. **渐进式学习**：从协议到命令，从架构到实施
+4. **便于维护**：每个主题有独立的 README 索引
+5. **专业性**：符合技术文档的最佳实践

package/GATEWAY_MIGRATION_GUIDE.md

@@ -0,0 +1,130 @@
+# Gateway 迁移到 Protocol 包指南
+
+## 概述
+Gateway 必须完全迁移到使用 `@jrsoft/subway-protocol` 包，Protocol 是唯一的协议标准。
+
+## 迁移原则
+1. **不修改 Protocol**：Protocol 保持现有的严格定义
+2. **Gateway 必须适配**：Gateway 需要适配 Protocol 的所有要求
+3. **不考虑向后兼容**：这是未上线项目，可以进行破坏性更改
+
+## 主要改动点
+
+### 1. 类型定义迁移
+- 删除 `src/types/common.types.ts` 中的消息类型定义
+- 导入并使用 `@jrsoft/subway-protocol` 的类型
+
+### 2. 必需字段适配
+Gateway 需要确保所有消息都包含 Protocol 要求的必需字段：
+- **timestamp**: 所有消息都需要时间戳
+- **version**: 所有消息都需要协议版本
+- **callback**: CommandMessage 必须提供回调 URL
+
+### 3. 枚举类型迁移
+- 使用 Protocol 的枚举类型（ClientType, Priority, CommandStatus 等）
+- 移除字符串字面量，改用枚举
+
+### 4. 需要修改的核心文件
+
+#### 消息处理相关
+- `src/ws/message.handler.ts` - 使用 Protocol 的消息类型
+- `src/ws/websocket.handler.ts` - 使用 Protocol 的类型守卫
+- `src/dispatcher/command.dispatcher.ts` - 使用 Protocol 的 Command 类型
+
+#### API 控制器
+- `src/api/device.controller.ts` - 确保 callback 必填
+- `src/api/gateway.controller.ts` - 确保 callback 必填
+- `src/api/enhanced-device.controller.ts` - 使用 Protocol 类型
+
+#### 工具和回调
+- `src/callback/callback.handler.ts` - 使用 Protocol 的响应类型
+- `src/callback/enhanced-callback.handler.ts` - 使用 Protocol 的消息类型
+- `src/utils/message.factory.ts` - 删除，使用 Protocol 的 MessageFactory
+
+## 具体迁移步骤
+
+### Step 1: 安装 Protocol 包
+```bash
+cd jrsoft-subway-gateway
+npm install @jrsoft/subway-protocol@latest
+```
+
+### Step 2: 更新导入
+将所有本地类型导入改为从 Protocol 包导入：
+```typescript
+// Before
+import { CommandMessage, BaseMessage } from '../types/common.types';
+
+// After
+import { CommandMessage, BaseMessage, MessageType, ClientType } from '@jrsoft/subway-protocol';
+```
+
+### Step 3: 适配必需字段
+确保所有创建的消息都包含必需字段：
+```typescript
+// 创建命令时必须提供 callback
+const commandMessage = MessageFactory.createCommandMessage(
+  requestRef,
+  targetClientId,
+  command,
+  callbackUrl, // 必需，不能为空
+  { priority, timeout }
+);
+```
+
+### Step 4: 使用 Protocol 的工厂方法
+```typescript
+import { MessageFactory } from '@jrsoft/subway-protocol';
+
+// 使用 Protocol 的工厂方法创建消息
+const registerMessage = MessageFactory.createRegisterMessage(
+  clientId,
+  ClientType.DEVICE,
+  clientInfo
+);
+```
+
+### Step 5: 使用 Protocol 的验证器
+```typescript
+import { MessageValidator } from '@jrsoft/subway-protocol';
+
+// 验证接收到的消息
+const validation = MessageValidator.validateMessage(message);
+if (!validation.isValid) {
+  throw new Error(validation.errors.join(', '));
+}
+```
+
+## 注意事项
+
+### 1. Callback URL 处理
+- Gateway API 必须要求调用方提供 callback URL
+- 如果调用方确实不需要回调，可以提供一个占位符 URL（如 'http://noop'）
+- 在回调处理时检查 URL 是否为占位符，避免不必要的网络请求
+
+### 2. 内部接口保留
+以下接口是 Gateway 内部使用，不需要迁移到 Protocol：
+- `PendingCommand`
+- `LongRunningCommand`
+- `DeviceConnection`
+- `IDeviceManager`
+- `ICommandDispatcher`
+
+### 3. 常量迁移
+使用 Protocol 提供的常量：
+```typescript
+import { PROTOCOL_VERSION, DEFAULT_TIMEOUT, Priority } from '@jrsoft/subway-protocol';
+```
+
+## 测试策略
+1. 更新所有单元测试，使用 Protocol 类型
+2. 更新集成测试，确保消息格式符合 Protocol 标准
+3. 使用 MessageValidator 验证所有发送和接收的消息
+
+## 完成标准
+- [ ] 所有消息类型使用 Protocol 定义
+- [ ] 所有消息创建使用 MessageFactory
+- [ ] 所有消息验证使用 MessageValidator  
+- [ ] 删除本地的重复类型定义
+- [ ] 所有测试通过
+- [ ] callback 字段在所有命令中都是必需的