@thejrsoft/subway-protocol 1.4.14 → 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;
+}