@thejrsoft/subway-protocol 1.5.0 → 1.6.0

package/src/code-meta.ts

@@ -0,0 +1,322 @@
+/**
+ * CodeMeta — v1.6.0 协议核心
+ *
+ * report.code 是业务命运的单一信息源；status / level / semantic 全部由此派生。
+ *
+ * 设备端调用 dispatchMessage(code, data) 时，协议层自动按 code 推导 status / level，
+ * 集成方接收消息后调用 resolveCodeMeta(code) 查表得到 semantic / requiresErrorBlock 等。
+ *
+ * 设计依据：claude-docs/protocol-upgrade-proposal-v1.6.0.md
+ */
+
+// v1.6.0: 使用 type-only import 避免与 index.ts 的循环依赖
+//   index.ts 在 MessageFactory.dispatchMessage 中 import code-meta，
+//   code-meta 本文件如果运行时 import ./index 会触发 TDZ。
+//   使用 type import 仅在编译期解析，运行时不产生 cyclic require。
+import type { ReportLevel } from './index';
+
+/** v1.6.0：单一 status enum，合并 v1.5.0 的 CommandStatus + ProgressStatus */
+export enum MessageStatus {
+  IN_PROGRESS = 'IN_PROGRESS',
+  COMPLETED = 'COMPLETED',
+  FAILED = 'FAILED',
+  CANCELLED = 'CANCELLED',
+}
+
+/** 业务语义分类——终态语义 + 进度语义 */
+export type CodeSemantic =
+  // 终态语义（仅在 isTerminal=true 时出现）
+  | 'success'
+  | 'partial'
+  | 'failure'
+  | 'no-op'
+  | 'cancel'
+  | 'busy'
+  // 进度语义（isTerminal=false）
+  | 'phase_start'
+  | 'phase_end'
+  | 'phase_failed'
+  | 'step_success'
+  | 'step_skipped'
+  | 'step_progress'
+  | 'retry'
+  | 'retry_pending'
+  | 'warning';
+
+/**
+ * 单一 code 的元数据描述符
+ *
+ * 派生字段（status / level）会序列化进消息；
+ * 客户端字段（semantic / requiresErrorBlock / isTerminal）仅供查表，不进消息。
+ */
+export interface CodeMeta {
+  isTerminal: boolean;
+  status: MessageStatus;
+  level: ReportLevel;
+  semantic: CodeSemantic;
+  requiresErrorBlock: boolean;
+}
+
+/**
+ * 终态 code 显式 META 表
+ *
+ * 这些 code 是业务命运决断点，每个语义都是独特的，**不能用后缀规则推导**。
+ * 设备端发送终态消息时，dispatchMessage 在此表查询，自动填充消息字段。
+ */
+export const EXPLICIT_META: Record<string, CodeMeta> = {
+  // ═══════════ PROGRAM 节目部署 ═══════════
+  PROGRAM_COMPLETED: {
+    isTerminal: true,
+    status: MessageStatus.COMPLETED,
+    level: 'INFO' as ReportLevel,
+    semantic: 'success',
+    requiresErrorBlock: false,
+  },
+  PROGRAM_PARTIALLY_SUCCEEDED: {
+    isTerminal: true,
+    status: MessageStatus.COMPLETED,
+    level: 'WARNING' as ReportLevel,
+    semantic: 'partial',
+    requiresErrorBlock: false,
+  },
+  PROGRAM_ALL_FAILED: {
+    isTerminal: true,
+    status: MessageStatus.FAILED,
+    level: 'ERROR' as ReportLevel,
+    semantic: 'failure',
+    requiresErrorBlock: true,
+  },
+  PROGRAM_NO_PROGRAMS: {
+    isTerminal: true,
+    status: MessageStatus.COMPLETED,
+    level: 'INFO' as ReportLevel,
+    semantic: 'no-op',
+    requiresErrorBlock: false,
+  },
+  PROGRAM_UPLOAD_FAILED: {
+    isTerminal: true,
+    status: MessageStatus.FAILED,
+    level: 'ERROR' as ReportLevel,
+    semantic: 'failure',
+    requiresErrorBlock: true,
+  },
+  PROGRAM_UPLOAD_BUSY: {
+    isTerminal: true,
+    status: MessageStatus.FAILED,
+    level: 'WARNING' as ReportLevel,
+    semantic: 'busy',
+    requiresErrorBlock: true,
+  },
+  PROGRAM_UPLOAD_CANCELLED: {
+    isTerminal: true,
+    status: MessageStatus.CANCELLED,
+    level: 'WARNING' as ReportLevel,
+    semantic: 'cancel',
+    requiresErrorBlock: true,
+  },
+
+  // ═══════════ QUICKLY_DETECTION 一键检测 ═══════════
+  QUICK_DETECTION_ALL_ONLINE: {
+    isTerminal: true,
+    status: MessageStatus.COMPLETED,
+    level: 'INFO' as ReportLevel,
+    semantic: 'success',
+    requiresErrorBlock: false,
+  },
+  QUICK_DETECTION_PARTIAL_ONLINE: {
+    isTerminal: true,
+    status: MessageStatus.COMPLETED,
+    level: 'WARNING' as ReportLevel,
+    semantic: 'partial',
+    requiresErrorBlock: false,
+  },
+  QUICK_DETECTION_ALL_OFFLINE: {
+    isTerminal: true,
+    status: MessageStatus.COMPLETED,
+    level: 'ERROR' as ReportLevel,
+    semantic: 'failure',
+    requiresErrorBlock: true,
+  },
+  QUICK_DETECTION_FAILED: {
+    isTerminal: true,
+    status: MessageStatus.FAILED,
+    level: 'ERROR' as ReportLevel,
+    semantic: 'failure',
+    requiresErrorBlock: true,
+  },
+  QUICK_DETECTION_BUSY: {
+    isTerminal: true,
+    status: MessageStatus.FAILED,
+    level: 'WARNING' as ReportLevel,
+    semantic: 'busy',
+    requiresErrorBlock: true,
+  },
+
+  // ═══════════ SYNC_MONITORING_TABLE 监播导出 ═══════════
+  SYNC_MONITORING_TABLE_READ_SUCCESS: {
+    isTerminal: true,
+    status: MessageStatus.COMPLETED,
+    level: 'INFO' as ReportLevel,
+    semantic: 'success',
+    requiresErrorBlock: false,
+  },
+  SYNC_MONITORING_TABLE_READ_FAILED: {
+    isTerminal: true,
+    status: MessageStatus.FAILED,
+    level: 'ERROR' as ReportLevel,
+    semantic: 'failure',
+    requiresErrorBlock: true,
+  },
+};
+
+/**
+ * 进度 code 后缀规则
+ *
+ * 进度消息有数百个 code（按 PROGRAM_FETCH_DOWNLOAD_PROGRESS 这种命名规范），
+ * 不可能逐一罗列 META，但 level / status / semantic 完全可从后缀派生。
+ *
+ * 优先级从高到低，首次命中即返回。
+ */
+interface SuffixRule {
+  /** 后缀匹配（endsWith）*/
+  suffix?: string;
+  /** 中缀匹配（用于 _WARN_ 这种夹中间的情况）*/
+  infix?: string;
+  meta: Omit<CodeMeta, 'isTerminal'>;
+}
+
+const SUFFIX_RULES: SuffixRule[] = [
+  {
+    suffix: '_FAILED',
+    meta: {
+      status: MessageStatus.IN_PROGRESS,
+      level: 'ERROR' as ReportLevel,
+      semantic: 'phase_failed',
+      requiresErrorBlock: true,
+    },
+  },
+  {
+    suffix: '_RETRY_PENDING',
+    meta: {
+      status: MessageStatus.IN_PROGRESS,
+      level: 'WARNING' as ReportLevel,
+      semantic: 'retry_pending',
+      requiresErrorBlock: false,
+    },
+  },
+  {
+    suffix: '_RETRY',
+    meta: {
+      status: MessageStatus.IN_PROGRESS,
+      level: 'WARNING' as ReportLevel,
+      semantic: 'retry',
+      requiresErrorBlock: false,
+    },
+  },
+  {
+    // 后缀或中缀都命中：例 PROGRAM_UPLOAD_WARN_CAN_BUS_ALARM
+    infix: '_WARN',
+    meta: {
+      status: MessageStatus.IN_PROGRESS,
+      level: 'WARNING' as ReportLevel,
+      semantic: 'warning',
+      requiresErrorBlock: false,
+    },
+  },
+  {
+    suffix: '_SKIPPED',
+    meta: {
+      status: MessageStatus.IN_PROGRESS,
+      level: 'INFO' as ReportLevel,
+      semantic: 'step_skipped',
+      requiresErrorBlock: false,
+    },
+  },
+  {
+    suffix: '_COMPLETED',
+    meta: {
+      status: MessageStatus.IN_PROGRESS,
+      level: 'INFO' as ReportLevel,
+      semantic: 'phase_end',
+      requiresErrorBlock: false,
+    },
+  },
+  {
+    suffix: '_START',
+    meta: {
+      status: MessageStatus.IN_PROGRESS,
+      level: 'INFO' as ReportLevel,
+      semantic: 'phase_start',
+      requiresErrorBlock: false,
+    },
+  },
+  {
+    suffix: '_PROGRESS',
+    meta: {
+      status: MessageStatus.IN_PROGRESS,
+      level: 'INFO' as ReportLevel,
+      semantic: 'step_progress',
+      requiresErrorBlock: false,
+    },
+  },
+  {
+    suffix: '_SUCCESS',
+    meta: {
+      status: MessageStatus.IN_PROGRESS,
+      level: 'INFO' as ReportLevel,
+      semantic: 'step_success',
+      requiresErrorBlock: false,
+    },
+  },
+];
+
+/**
+ * 兜底 META（未知 code 时返回）
+ *
+ * 接收方收到未知 code 时降级到 step_progress，避免阻塞协议处理。
+ */
+const FALLBACK_META: CodeMeta = {
+  isTerminal: false,
+  status: MessageStatus.IN_PROGRESS,
+  level: 'INFO' as ReportLevel,
+  semantic: 'step_progress',
+  requiresErrorBlock: false,
+};
+
+/**
+ * 单一 code 解析入口
+ *
+ * 解析顺序：
+ *   1. 终态显式表（EXPLICIT_META） — 30 个 closed enum
+ *   2. 后缀规则（SUFFIX_RULES） — 9 条规则覆盖数百个进度 code
+ *   3. 兜底（FALLBACK_META） — 未知 code 降级
+ *
+ * @param code report.code 字符串
+ * @returns CodeMeta — status / level / semantic / requiresErrorBlock / isTerminal
+ */
+export function resolveCodeMeta(code: string): CodeMeta {
+  if (EXPLICIT_META[code]) {
+    return EXPLICIT_META[code];
+  }
+  for (const rule of SUFFIX_RULES) {
+    if (rule.suffix && code.endsWith(rule.suffix)) {
+      return { isTerminal: false, ...rule.meta };
+    }
+    if (rule.infix && code.includes(rule.infix)) {
+      return { isTerminal: false, ...rule.meta };
+    }
+  }
+  return FALLBACK_META;
+}
+
+/**
+ * 判断 code 是否已知（命中显式表或后缀规则，不走兜底）
+ */
+export function isKnownCode(code: string): boolean {
+  if (EXPLICIT_META[code]) return true;
+  for (const rule of SUFFIX_RULES) {
+    if (rule.suffix && code.endsWith(rule.suffix)) return true;
+    if (rule.infix && code.includes(rule.infix)) return true;
+  }
+  return false;
+}

package/src/index.ts

@@ -1,13 +1,18 @@
 /**
  * JRSoft Subway 统一WebSocket协议定义
  * 版本: 1.0
- * 
+ *
  * 功能特性:
  * 1. 统一消息格式定义
  * 2. 支持设备注册、命令执行、心跳等核心功能
  * 3. 支持 Edge 代理模式
+ *
+ * v1.6.0：单一 MessageStatus + CodeMeta + dispatchMessage（详见 code-meta.ts）
  */
 
+// v1.6.0：从 code-meta 模块导入工具（用于 MessageFactory.dispatchMessage）
+import { resolveCodeMeta, MessageStatus } from './code-meta';
+
 // 消息类型枚举
 export enum MessageType {
   // 连接管理
@@ -74,14 +79,11 @@ export enum Priority {
   EMERGENCY = 'EMERGENCY'
 }
 
-// 命令状态
-export enum CommandStatus {
-  COMPLETED = 'COMPLETED',
-  FAILED = 'FAILED',
-  TIMEOUT = 'TIMEOUT',
-  CANCELLED = 'CANCELLED',
-  IN_PROGRESS = 'IN_PROGRESS'  // Gateway特有
-}
+// v1.6.0: 单一 MessageStatus enum 取代 CommandStatus / ProgressStatus
+// 字符串值与 v1.5.0 重叠的 4 值保持一致：'IN_PROGRESS' / 'COMPLETED' / 'FAILED' / 'CANCELLED'
+// 死代码值删除：CommandStatus.TIMEOUT / ProgressStatus.PENDING / PAUSED
+// TIMEOUT 语义迁移：status=FAILED + report.data.error.category='TIMEOUT'
+export { MessageStatus, type CodeMeta, type CodeSemantic, resolveCodeMeta, isKnownCode, EXPLICIT_META } from './code-meta';
 
 // 基础消息接口
 export interface BaseMessage {
@@ -288,7 +290,7 @@ export interface CommandResponseMessage extends BaseMessage {
   type: MessageType.COMMAND_RESPONSE;
   clientId: string;                  // 响应设备标识
   requestRef: string;
-  status: CommandStatus;
+  status: MessageStatus;
   result?: CommandResult;            // 命令执行结果
   report?: ReportMessage;
   executionTime?: number;
@@ -381,7 +383,7 @@ export interface ProgramResponseMessage extends BaseMessage {
   type: MessageType.PROGRAM_RESPONSE;
   clientId: string;                   // 响应设备标识
   requestRef: string;
-  status: CommandStatus;  // 使用相同的状态枚举
+  status: MessageStatus;  // v1.6.0 统一 status enum
   context?: ProgramContext;       // 上下文信息（可选）
   report?: ReportMessage;  // 日志信息（可选）
   executionTime?: number;  // 总执行时间（毫秒）
@@ -446,15 +448,9 @@ export interface DeviceOperationRecord {
   result?: Record<string, any>; // 命令执行结果对象
 }
 
-// 进度状态
-export enum ProgressStatus {
-  PENDING = 'PENDING',
-  IN_PROGRESS = 'IN_PROGRESS',
-  PAUSED = 'PAUSED',
-  COMPLETED = 'COMPLETED',
-  FAILED = 'FAILED',
-  CANCELLED = 'CANCELLED'
-}
+// v1.6.0：原 ProgressStatus enum 删除——所有消息的 status 字段统一类型为 MessageStatus
+// 删除的死代码值：PENDING / PAUSED（两个值在 v1.5.0 内 0 引用，全协议历史从未真实发出）
+// 集成方：import { MessageStatus } from '@thejrsoft/subway-protocol'
 
 // 程序上下文信息
 export interface ProgramContext {
@@ -576,7 +572,7 @@ export interface ProgressUpdateMessage extends BaseMessage {
   type: MessageType.PROGRESS_UPDATE;
   clientId: string;            // 上报设备标识
   requestRef: string;
-  status: ProgressStatus;      // 状态
+  status: MessageStatus;       // v1.6.0 统一 status enum（进度消息一律 IN_PROGRESS）
   phase: ProgressPhase | string;  // 当前阶段（支持自定义阶段）
   progress: number;            // 0-100 进度百分比
   sourceType: ProgressSourceType;    // 来源类型：COMMAND/SYSTEM/EDGE（v1.4.11 加 EDGE）
@@ -888,7 +884,7 @@ export class MessageFactory {
     phase: ProgressPhase | string,
     progress: number,
     message?: string,
-    status: ProgressStatus = ProgressStatus.IN_PROGRESS,
+    status: MessageStatus = MessageStatus.IN_PROGRESS,
     options?: {
       level?: ReportLevel;
       code?: string;
@@ -924,7 +920,7 @@ export class MessageFactory {
   static createCommandResponseMessage(
     clientId: string,  // 添加：响应设备标识
     requestRef: string,
-    status: CommandStatus,
+    status: MessageStatus,
     result: any,
     message?: string,
     options?: {
@@ -960,7 +956,7 @@ export class MessageFactory {
   static createProgramResponseMessage(
     clientId: string,  // 添加：响应设备标识
     requestRef: string,
-    status: CommandStatus,
+    status: MessageStatus,
     result: any,
     message?: string,
     options?: {
@@ -1170,6 +1166,122 @@ export class MessageFactory {
       version: '1.0'
     };
   }
+
+  /**
+   * v1.6.0: 统一消息派发接口
+   *
+   * 设备端发送终态消息（COMMAND_RESPONSE / PROGRAM_RESPONSE）或进度消息（PROGRESS_UPDATE）时，
+   * 只需要提供 code 和业务字段，协议层通过 CodeMeta 自动推导 status / level / 消息类型。
+   *
+   * 替代旧的 createCommandResponseMessage / createProgramResponseMessage / createProgressUpdateMessage。
+   *
+   * @param params dispatch 参数
+   * @returns 完整的协议消息（具体类型由 code 派生的 isTerminal 决定）
+   * @throws Error 当 code 要求 data.error 但 params.error 缺失时
+   */
+  static dispatchMessage(params: {
+    clientId: string;
+    requestRef: string;
+    code: string;
+    message: string;
+    /** 终态消息：result 块；进度消息：业务平铺字段 */
+    data?: Record<string, any>;
+    /** v1.5.0 失败 schema — 当 code 要求时必填 */
+    error?: {
+      phase: string;
+      step: string;
+      category: string;
+      detail: string;
+    };
+    /** 仅进度消息：phase 与 progress */
+    phase?: ProgressPhase | string;
+    progress?: number;
+    /** 进度消息 sourceType（默认 COMMAND）*/
+    sourceType?: ProgressSourceType;
+    /** 终态消息 result 块（COMMAND_RESPONSE）*/
+    result?: any;
+    /** 终态消息 context（PROGRAM_RESPONSE）*/
+    context?: ProgramContext;
+    /** 终态消息 executionTime */
+    executionTime?: number;
+  }): CommandResponseMessage | ProgramResponseMessage | ProgressUpdateMessage {
+    const meta = resolveCodeMeta(params.code);
+
+    // 强校验：requiresErrorBlock 时 data.error 必填
+    if (meta.requiresErrorBlock && !params.error) {
+      throw new Error(
+        `dispatchMessage: code "${params.code}" requires data.error (4 fields: phase/step/category/detail)`,
+      );
+    }
+
+    const reportData: Record<string, any> = { ...(params.data || {}) };
+    if (params.error) {
+      reportData.error = params.error;
+    }
+
+    const report: ReportMessage = {
+      level: meta.level,
+      message: params.message,
+      code: params.code,
+      data: reportData,
+    };
+
+    const timestamp = new Date().toISOString();
+    const version = '1.0';
+
+    if (meta.isTerminal) {
+      // 通过 code 前缀决定终态消息类型：PROGRAM_* → PROGRAM_RESPONSE，其余 → COMMAND_RESPONSE
+      const isProgramTerminal =
+        params.code.startsWith('PROGRAM_') && !params.code.startsWith('PROGRAM_FETCH') &&
+        !params.code.startsWith('PROGRAM_EXTRACT') && !params.code.startsWith('PROGRAM_PREPROCESS') &&
+        !params.code.startsWith('PROGRAM_COMPILE') && !params.code.startsWith('PROGRAM_STATS') &&
+        !params.code.startsWith('PROGRAM_INIT');
+
+      if (isProgramTerminal) {
+        const msg: ProgramResponseMessage = {
+          type: MessageType.PROGRAM_RESPONSE,
+          clientId: params.clientId,
+          requestRef: params.requestRef,
+          status: meta.status as MessageStatus,
+          context: params.context,
+          report,
+          executionTime: params.executionTime,
+          timestamp,
+          version,
+        };
+        return msg;
+      } else {
+        const msg: CommandResponseMessage = {
+          type: MessageType.COMMAND_RESPONSE,
+          clientId: params.clientId,
+          requestRef: params.requestRef,
+          status: meta.status as MessageStatus,
+          result: params.result,
+          report,
+          executionTime: params.executionTime,
+          timestamp,
+          version,
+        };
+        return msg;
+      }
+    }
+
+    // 进度消息
+    const progressMsg: ProgressUpdateMessage = {
+      type: MessageType.PROGRESS_UPDATE,
+      clientId: params.clientId,
+      requestRef: params.requestRef,
+      status: meta.status as MessageStatus,
+      phase: params.phase ?? '',
+      progress: params.progress ?? 0,
+      sourceType: params.sourceType ?? 'COMMAND',
+      context: params.context,
+      report,
+      timestamp,
+      version,
+    };
+    return progressMsg;
+  }
 }
 
 
@@ -1196,7 +1308,7 @@ export type AnyMessage =
   | ErrorMessage;
 
 // 导出常量
-export const PROTOCOL_VERSION = '1.5.0';
+export const PROTOCOL_VERSION = '1.6.0';
 export const DEFAULT_TIMEOUT = 10000;
 export const DEFAULT_PRIORITY = Priority.NORMAL;
 

package/src/message-validator.ts

@@ -6,10 +6,9 @@ import {
   MessageType,
   ClientType,
   Priority,
-  CommandStatus,
+  MessageStatus,
   OperationType,
   CommandType,
-  ProgressStatus,
   ProgressPhase,
   ReportLevel,
   ProgramType,
@@ -336,7 +335,7 @@ export class MessageValidator {
     }
     if (!message.status) {
       errors.push('status is required');
-    } else if (!this.isValidProgressStatus(message.status)) {
+    } else if (!this.isValidMessageStatus(message.status)) {
       errors.push(`Invalid status: ${message.status}`);
     }
     if (!message.phase) {
@@ -536,8 +535,8 @@ export class MessageValidator {
   /**
    * 验证命令状态
    */
-  static isValidCommandStatus(status: string): boolean {
-    return Object.values(CommandStatus).includes(status as CommandStatus);
+  static isValidMessageStatus(status: string): boolean {
+    return Object.values(MessageStatus).includes(status as MessageStatus);
   }
 
   /**
@@ -554,13 +553,6 @@ export class MessageValidator {
     return Object.values(CommandType).includes(commandType as CommandType);
   }
 
-  /**
-   * 验证进度状态
-   */
-  static isValidProgressStatus(status: string): boolean {
-    return Object.values(ProgressStatus).includes(status as ProgressStatus);
-  }
-
   /**
    * 验证进度阶段
    */

package/src/protocol-utils.ts

@@ -3,7 +3,7 @@
  */
 
 import {
-  CommandStatus,
+  MessageStatus,
   Priority,
   ClientType,
   MessageType,
@@ -26,26 +26,26 @@ import {
  */
 export class ProtocolUtils {
   /**
-   * 将 CommandStatus 枚举转换为字符串
+   * 将 MessageStatus 枚举转换为字符串
    */
-  static statusToString(status: CommandStatus): string {
+  static statusToString(status: MessageStatus): string {
     return status.toString();
   }
 
   /**
-   * 将字符串转换为 CommandStatus 枚举
+   * 将字符串转换为 MessageStatus 枚举
    * @throws {Error} 如果字符串不是有效的状态值
    */
-  static stringToStatus(status: string): CommandStatus {
+  static stringToStatus(status: string): MessageStatus {
     // 处理大小写和空格
     const normalizedStatus = status.trim().toUpperCase();
     
     // 检查是否是有效的枚举值
-    if (!Object.values(CommandStatus).includes(normalizedStatus as CommandStatus)) {
-      throw new Error(`Invalid command status: ${status}. Valid values are: ${Object.values(CommandStatus).join(', ')}`);
+    if (!Object.values(MessageStatus).includes(normalizedStatus as MessageStatus)) {
+      throw new Error(`Invalid command status: ${status}. Valid values are: ${Object.values(MessageStatus).join(', ')}`);
     }
     
-    return normalizedStatus as CommandStatus;
+    return normalizedStatus as MessageStatus;
   }
 
   /**
@@ -225,7 +225,7 @@ export class ProtocolUtils {
    * 安全的枚举转换（不抛出异常）
    * @returns 枚举值或 null
    */
-  static tryParseStatus(status: string): CommandStatus | null {
+  static tryParseStatus(status: string): MessageStatus | null {
     try {
       return this.stringToStatus(status);
     } catch {