chore: 完善注释，添加 JSDoc

2026-07-19 23:08:58 +08:00
parent 089bfaacf7
commit b23cf4d854
15 changed files with 846 additions and 59 deletions
@@ -0,0 +1,114 @@
+/**
+ * 公共 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;
+  /** 当前是否已订阅 */
+  subscribed: boolean;
+}
+
+/** 主题配置（用于导入/导出或表单） */
+export interface TopicConfig {
+  /** 主题唯一标识，未提供时由后端生成 */
+  id?: string;
+  /** 主题名称（支持通配符） */
+  topic: string;
+  /** 订阅 QoS 等级，默认 1 */
+  qos?: MqttQoS;
+}
+
+/** 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';
+}