frost-mqtt-client/app/types/jsdoc.d.ts

/**
 * 公共 MQTT 类型定义
 * 供 renderer 与 main 进程共享，避免在多个模块中重复定义 JSDoc @typedef
 */

/** MQTT QoS 等级 */
export type MqttQoS = 0 | 1 | 2;

/** MQTT 服务器连接状态 */
export type MqttServerStatus = 'disconnected' | 'connecting' | 'connected' | 'error';

/** MQTT 主题 */
export interface MqttTopic {
  /** 主题唯一标识 */
  id: string;
  /** 主题名称（支持通配符） */
  topic: string;
  /** 订阅 QoS 等级 */
  qos: MqttQoS;
  /** 主题备注，空字符串表示未备注 */
  comment: string;
  /** 当前是否已订阅 */
  subscribed: boolean;
}

/** 主题配置（用于导入/导出或表单） */
export interface TopicConfig {
  /** 主题唯一标识，未提供时由后端生成 */
  id?: string;
  /** 主题名称（支持通配符） */
  topic: string;
  /** 订阅 QoS 等级，默认 1 */
  qos?: MqttQoS;
  /** 主题备注，默认空字符串 */
  comment?: string;
}

/** MQTT 服务器配置（不含运行时状态） */
export interface ServerConfig {
  /** 显示名称 */
  name: string;
  /** 主机地址 */
  host: string;
  /** 端口号，默认 1883 */
  port?: number;
  /** 连接协议，默认 'mqtt' */
  protocol?: 'mqtt' | 'mqtts' | 'ws' | 'wss';
  /** 客户端 ID，默认随机生成 */
  clientId?: string;
  /** 用户名，默认空字符串 */
  username?: string;
  /** 密码，默认空字符串 */
  password?: string;
  /** 心跳间隔（秒），默认 60 */
  keepAlive?: number;
  /** 是否清理会话，默认 true */
  cleanSession?: boolean;
  /** 连接超时（毫秒），默认 10000 */
  connectTimeout?: number;
  /** 是否自动重连，默认 true */
  reconnect?: boolean;
  /** 重连间隔（毫秒），默认 5000 */
  reconnectInterval?: number;
  /** 初始主题列表 */
  topics?: TopicConfig[];
}

/** MQTT 服务器运行时对象 */
export interface MqttServer extends ServerConfig {
  /** 服务器唯一标识 */
  id: string;
  /** 当前连接状态 */
  status: MqttServerStatus;
  /** 该服务器下的主题列表 */
  topics: MqttTopic[];
}

/** 发布/订阅选项 */
export interface PublishOptions {
  /** QoS 等级，默认 1 */
  qos?: MqttQoS;
  /** 是否保留消息，默认 false */
  retain?: boolean;
}

/** MQTT 消息（订阅接收或本地发布） */
export interface MqttMessage {
  /** 消息唯一标识 */
  id: string;
  /** 接收/发送时间（格式为 HH:mm:ss.SSS） */
  time: string;
  /** 消息主题 */
  topic: string;
  /** 消息负载内容 */
  payload: string;
  /** 消息 QoS 等级 */
  qos: MqttQoS;
  /** 是否为保留消息 */
  retain: boolean;
  /** 消息方向：pub 表示发布，sub 表示订阅 */
  direction: 'pub' | 'sub';
}

/** 发布历史记录 */
export interface PublishRecord {
  /** 发布时间（格式为 HH:mm:ss.SSS） */
  time: string;
  /** 目标主题 */
  topic: string;
  /** 发布内容 */
  payload: string;
  /** 发布 QoS 等级 */
  qos: MqttQoS;
  /** 是否保留消息 */
  retain: boolean;
  /** 固定为 pub */
  direction: 'pub';
}