@thejrsoft/subway-protocol 1.4.14 → 1.6.0

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;  // 总执行时间（毫秒）
@@ -401,13 +403,16 @@ export interface ProgramResponseMessage extends BaseMessage {
  * 不通过协议消息流转，**不**列在此 enum 中（属于 Backend 内部 audit 字符串）。
  */
 export enum ProgressPhase {
-  // ---- 节目处理 pipeline（设备端，实施中）----
+  // ---- 节目处理 pipeline（设备端）----
+  // v1.5.0: PROGRAM 命令统一生命周期 — 加 INIT 起始 / COMPLETE 终态边界
+  PROGRAM_INIT = 'PROGRAM_INIT',                  // v1.5.0 新增 — 任务初始化（参数校验、资源准备、并发检查）
   PROGRAM_FETCH = 'PROGRAM_FETCH',                // 拉取节目源文件（OSS / Edge / 其他）
   PROGRAM_EXTRACT = 'PROGRAM_EXTRACT',            // 解压归档（zip/tar/rar）
   PROGRAM_PREPROCESS = 'PROGRAM_PREPROCESS',      // 图片预处理（缩放/滤镜等）
   PROGRAM_COMPILE = 'PROGRAM_COMPILE',            // 编译为显示帧
   PROGRAM_UPLOAD = 'PROGRAM_UPLOAD',              // 上传到底层显示设备
   PROGRAM_STATS = 'PROGRAM_STATS',                // 上报统计信息
+  PROGRAM_COMPLETE = 'PROGRAM_COMPLETE',          // v1.5.0 新增 — 终态边界（决定 ALL_SUCCESS / PARTIAL / FAILED 等）
 
   // ---- Edge 缓存可见性（v1.4.11 新增）----
   EDGE_CACHE_FETCH = 'EDGE_CACHE_FETCH',          // Edge 从 OSS 拉文件中
@@ -443,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 {
@@ -471,23 +470,101 @@ export enum ReportLevel {
   CRITICAL = 'CRITICAL'
 }
 
-// v1.4.14: 故障分类枚举（4 档，从 v1.4.12 的 3 档扩展）
-// - TRANSPORT: 网络层故障（TCP 连不上、HTTP 5xx、DNS 失败、CAN 总线告警）
-// - TIMEOUT: 等待对端响应超时（设备无应答、节目重试超限、心跳丢失）
-// - RESOURCE: 设备端本地资源耗尽（磁盘满 / 内存不足 / 文件句柄耗尽 / cache 写入失败）
-// - BUSINESS: 业务逻辑结果（用户参数错、节目数据格式错、forbidden 节点）— 缺省值
-export type ReportCategory = 'TRANSPORT' | 'TIMEOUT' | 'RESOURCE' | 'BUSINESS';
-
-// v1.4.14: 解除 v1.4.13 的"仅 SIMPLE/BATCH 使用 category"文档限制；现允许 COMPLEX
-// 命令（PROGRAM / QUICKLY_DETECTION / SYNC_MONITORING_TABLE 等）所有 PROGRESS_UPDATE
-// 与终态响应使用 category。BATCH 聚合 COMMAND_RESPONSE 仍是唯一例外
-// 报告信息
+// v1.5.0: ErrorCategory — 7 类 closed enum（v1.4.14 的 4 档扩展到 7 档）
+// - TRANSPORT: 通讯层失败 — 网络断、CAN 总线告警、HTTP 4xx/5xx、设备离线
+// - TIMEOUT: 等待响应超时 — HTTP 504、设备无应答、命令响应等待超时
+// - RESOURCE: 资源不足/耗尽 — 磁盘满、内存不足、设备槽位耗尽、文件句柄耗尽
+// - BUSINESS: 业务逻辑/状态/异常（兜底）— 业务规则违反、状态机错误、未预期异常
+// - CONFIGURATION: 配置缺失/错误（v1.5.0 新增）— Line.config 字段缺、ParamSet 不完整
+// - PROTOCOL: 协议层错误（v1.5.0 新增）— JSON 解析失败、字段缺失、消息格式错
+// - AUTHORIZATION: 凭证/权限失败（v1.5.0 新增）— DAK 失效、设备未审批、命令权限不足
+export type ErrorCategory =
+  | 'TRANSPORT'
+  | 'TIMEOUT'
+  | 'RESOURCE'
+  | 'BUSINESS'
+  | 'CONFIGURATION'
+  | 'PROTOCOL'
+  | 'AUTHORIZATION';
+
+// v1.5.0: ErrorPhase — 错误可发生的所有 phase（命令的 ProgressPhase 子集）
+// 与 ProgressPhase enum 完全对齐，只是命名 alias 以表达"用作错误归类"语义
+export type ErrorPhase =
+  | 'PROGRAM_INIT'
+  | 'PROGRAM_FETCH'
+  | 'PROGRAM_EXTRACT'
+  | 'PROGRAM_PREPROCESS'
+  | 'PROGRAM_COMPILE'
+  | 'PROGRAM_UPLOAD'
+  | 'PROGRAM_STATS'
+  | 'PROGRAM_COMPLETE'
+  | 'DETECT_INIT'
+  | 'SWITCH_DETECT'
+  | 'SWITCH_CONFIG_READ'
+  | 'SYNC_DETECT'
+  | 'BARGRAPH_DETECT'
+  | 'RATER_DETECT'
+  | 'SYNC_RECOVER'
+  | 'DETECT_COMPLETE'
+  | 'SYNC_EXPORT'
+  | 'BATCH_EXECUTE';
+
+// v1.5.0: ErrorStep — 21 个值，按 phase 归属（详见 message-validator.ts 的 step-phase 映射）
+export type ErrorStep =
+  // PROGRAM_INIT
+  | 'ValidateParameters'
+  | 'PrepareResources'
+  | 'LoadConfig'
+  | 'CheckConcurrency'
+  // PROGRAM_FETCH
+  | 'Download'
+  | 'VerifyChecksum'
+  // PROGRAM_EXTRACT
+  | 'ExtractZip'
+  // PROGRAM_PREPROCESS
+  | 'ResizeImage'
+  | 'AdjustColor'
+  | 'GammaCorrect'
+  | 'Histogram'
+  | 'RGBCorrection'
+  // PROGRAM_COMPILE
+  | 'CompileFrame'
+  | 'MoveFrame'
+  | 'VerifyFrameCount'
+  // PROGRAM_UPLOAD
+  | 'DeviceCheck'
+  | 'DataTransfer'
+  | 'ForbiddenTable'
+  | 'StatusRecovery'
+  | 'RetryLimitExceeded'
+  // PROGRAM_STATS
+  | 'CloudReport';
+
+// v1.5.0: 统一失败信号 schema — 嵌套在 report.data.error 下，仅 ERROR / 终态失败消息携带
+// 4 字段全部必填，3 个 enum 字段在服务端做 strict 校验（拒收未定义值）
+export interface ErrorInfo {
+  phase: ErrorPhase;       // 错误发生在哪个 phase
+  step: ErrorStep;         // 错误发生在 phase 内的哪个具体步骤（必须属于 phase）
+  category: ErrorCategory; // 协议级横切分类（7 类）
+  detail: string;          // 自由文本（英文，grep 友好）
+}
+
+// v1.5.0: ReportData — 嵌套结构，error 仅在失败时存在；其余字段按命令业务字段平铺
+export interface ReportData {
+  error?: ErrorInfo;       // v1.5.0 新增 — 失败信号 schema（level=ERROR / status=FAILED 时必填）
+  [key: string]: any;      // 业务字段平铺（programNo / fileSize / 等）
+}
+
+// v1.5.0: ReportMessage — 移除顶层 category 字段（下沉到 data.error.category）
+//   - data.error 仅在错误时出现（level=ERROR / status=FAILED）
+//   - 成功/进度消息：data 仍为平铺业务字段，无 error
+//   - messageEn 字段为可选，便于 i18n 兼容（默认 = message 英文文本）
 export interface ReportMessage {
   level: ReportLevel;
-  message: string;         // 报告消息
+  message: string;         // 报告消息（推荐英文，作为 i18n 兜底 / 设备日志）
   code?: string;           // 标准化的消息代码
-  data?: Record<string, any>;  // 额外的数据对象
-  category?: ReportCategory;  // v1.4.12 引入 / v1.4.14 扩 4 档（缺省=BUSINESS）
+  messageEn?: string;      // v1.5.0 新增 — 英文文本（与 message 同义，兼容现有结构）
+  data?: ReportData;       // v1.5.0 — 改为 ReportData 嵌套结构（含 error）
 }
 
 // 进度更新消息
@@ -495,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）
@@ -599,21 +676,43 @@ export function isDeviceApprovalResponseMessage(msg: any): msg is DeviceApproval
   return msg && msg.type === MessageType.DEVICE_APPROVAL_RESPONSE;
 }
 
-// v1.4.14: ReportCategory 类型守卫（消费方收到未知值时降级到 BUSINESS）
-export const VALID_REPORT_CATEGORIES: readonly ReportCategory[] = [
+// v1.5.0: ErrorCategory 类型守卫（消费方收到未知值时降级到 BUSINESS）
+export const VALID_ERROR_CATEGORIES: readonly ErrorCategory[] = [
   'TRANSPORT',
   'TIMEOUT',
   'RESOURCE',
   'BUSINESS',
+  'CONFIGURATION',
+  'PROTOCOL',
+  'AUTHORIZATION',
 ] as const;
 
-export function isValidReportCategory(value: any): value is ReportCategory {
-  return typeof value === 'string' && (VALID_REPORT_CATEGORIES as readonly string[]).includes(value);
+export function isValidErrorCategory(value: any): value is ErrorCategory {
+  return typeof value === 'string' && (VALID_ERROR_CATEGORIES as readonly string[]).includes(value);
 }
 
-// v1.4.14: normalizeReportCategory — 未知值降级到 'BUSINESS'（forward-compatibility 标准做法）
-export function normalizeReportCategory(value: any): ReportCategory {
-  return isValidReportCategory(value) ? value : 'BUSINESS';
+// v1.5.0: normalizeErrorCategory — 未知值降级到 'BUSINESS'（forward-compatibility 标准做法）
+export function normalizeErrorCategory(value: any): ErrorCategory {
+  return isValidErrorCategory(value) ? value : 'BUSINESS';
+}
+
+// v1.5.0: ErrorStep ↔ ErrorPhase 归属映射（强校验：step 必须属于 phase）
+export const ERROR_STEP_BY_PHASE: Record<string, readonly ErrorStep[]> = {
+  PROGRAM_INIT: ['ValidateParameters', 'PrepareResources', 'LoadConfig', 'CheckConcurrency'] as const,
+  PROGRAM_FETCH: ['Download', 'VerifyChecksum'] as const,
+  PROGRAM_EXTRACT: ['ExtractZip'] as const,
+  PROGRAM_PREPROCESS: ['ResizeImage', 'AdjustColor', 'GammaCorrect', 'Histogram', 'RGBCorrection'] as const,
+  PROGRAM_COMPILE: ['CompileFrame', 'MoveFrame', 'VerifyFrameCount'] as const,
+  PROGRAM_UPLOAD: ['DeviceCheck', 'DataTransfer', 'ForbiddenTable', 'StatusRecovery', 'RetryLimitExceeded'] as const,
+  PROGRAM_STATS: ['CloudReport'] as const,
+  PROGRAM_COMPLETE: [] as const,
+  // QUICKLY_DETECTION / SYNC_MONITORING_TABLE 在 v1.5.x 后续补充 step 归属
+} as const;
+
+export function isValidErrorStepForPhase(step: any, phase: any): boolean {
+  if (typeof step !== 'string' || typeof phase !== 'string') return false;
+  const allowed = ERROR_STEP_BY_PHASE[phase];
+  return Array.isArray(allowed) && (allowed as readonly string[]).includes(step);
 }
 
 
@@ -785,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;
@@ -821,7 +920,7 @@ export class MessageFactory {
   static createCommandResponseMessage(
     clientId: string,  // 添加：响应设备标识
     requestRef: string,
-    status: CommandStatus,
+    status: MessageStatus,
     result: any,
     message?: string,
     options?: {
@@ -857,7 +956,7 @@ export class MessageFactory {
   static createProgramResponseMessage(
     clientId: string,  // 添加：响应设备标识
     requestRef: string,
-    status: CommandStatus,
+    status: MessageStatus,
     result: any,
     message?: string,
     options?: {
@@ -1067,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;
+  }
 }
 
 
@@ -1093,7 +1308,7 @@ export type AnyMessage =
   | ErrorMessage;
 
 // 导出常量
-export const PROTOCOL_VERSION = '1.4.14';
+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 {