chore: 完善注释，添加 JSDoc

app/src/main/mqtt-manager.js

@@ -4,6 +4,27 @@ import { join } from 'path';
 
 import mqtt from 'mqtt';
 
+// ==================== 类型定义 ====================
+
+/**
+ * 从公共类型定义文件引入 MQTT 相关类型
+ * @typedef {import('@types/jsdoc').MqttQoS} MqttQoS
+ * @typedef {import('@types/jsdoc').MqttServerStatus} MqttServerStatus
+ * @typedef {import('@types/jsdoc').MqttTopic} MqttTopic
+ * @typedef {import('@types/jsdoc').TopicConfig} TopicConfig
+ * @typedef {import('@types/jsdoc').ServerConfig} ServerConfig
+ * @typedef {import('@types/jsdoc').MqttServer} MqttServer
+ * @typedef {import('@types/jsdoc').PublishOptions} PublishOptions
+ * @typedef {import('@types/jsdoc').MqttMessage} MqttMessage
+ * @typedef {import('@types/jsdoc').PublishRecord} PublishRecord
+ */
+
+// ==================== 类定义 ====================
+
+/**
+ * MQTT 管理器
+ * 负责 MQTT 服务器配置持久化、连接管理、主题订阅/发布、消息存储等核心逻辑
+ */
 class MqttManager {
 
   constructor() {
@@ -17,6 +38,10 @@ class MqttManager {
     this.loadData();
   }
 
+  /**
+   * 生成唯一消息 id
+   * @returns {string} 消息唯一标识
+   */
   nextMsgId() {
     this.msgIdCounter = (this.msgIdCounter + 1) % Number.MAX_SAFE_INTEGER;
     return 'msg_' + Date.now() + '_' + this.msgIdCounter;
@@ -24,6 +49,10 @@ class MqttManager {
 
   // ==================== 数据持久化 ====================
 
+  /**
+   * 获取用户数据目录，若不存在则创建
+   * @returns {string} 用户数据目录路径
+   */
   getDataDir() {
 
     let dir = app.getPath('userData');
@@ -36,6 +65,10 @@ class MqttManager {
 
   }
 
+  /**
+   * 从本地文件加载服务器、消息和发布历史数据
+   * 文件不存在或解析失败时初始化默认服务器
+   */
   loadData() {
     try {
       if (existsSync(this.dataPath)) {
@@ -76,6 +109,9 @@ class MqttManager {
     }
   }
 
+  /**
+   * 将当前服务器、消息和发布历史保存到本地文件
+   */
   saveData() {
     try {
 
@@ -96,6 +132,9 @@ class MqttManager {
     }
   }
 
+  /**
+   * 初始化默认示例服务器
+   */
   initDefaultServers() {
 
     let defaults = [
@@ -133,14 +172,27 @@ class MqttManager {
 
   // ==================== 监听器 ====================
 
+  /**
+   * 添加 MQTT 事件监听器
+   * @param {Function} callback - 回调函数，接收 (event, data) 参数
+   */
   addListener(callback) {
     this.listeners.add(callback);
   }
 
+  /**
+   * 移除 MQTT 事件监听器
+   * @param {Function} callback - 要移除的回调函数
+   */
   removeListener(callback) {
     this.listeners.delete(callback);
   }
 
+  /**
+   * 通知所有监听器
+   * @param {string} event - 事件名称
+   * @param {*} data - 事件数据
+   */
   notify(event, data) {
     this.listeners.forEach((cb) => {
       try {
@@ -153,6 +205,10 @@ class MqttManager {
 
   // ==================== 服务器管理 ====================
 
+  /**
+   * 获取所有服务器列表
+   * @returns {MqttServer[]} 服务器配置数组
+   */
   getServers() {
     return Array.from(this.servers.values()).map((s) => ({
       ...s,
@@ -160,10 +216,19 @@ class MqttManager {
     }));
   }
 
+  /**
+   * 根据 id 获取服务器配置
+   * @param {string} id - 服务器 id
+   * @returns {MqttServer | null} 服务器配置或 null
+   */
   getServer(id) {
     return this.servers.get(id) || null;
   }
 
+  /**
+   * 获取服务器配置字段 schema
+   * @returns {Record<string, Function>} 字段名到处理函数的映射
+   */
   getServerConfigSchema() {
     return {
       name: (c, e) => c.name ?? e?.name,
@@ -181,6 +246,13 @@ class MqttManager {
     };
   }
 
+  /**
+   * 根据配置构建服务器字段
+   * @param {ServerConfig} config - 新配置
+   * @param {MqttServer | null} existing - 已有服务器配置
+   * @param {{ keepExistingPassword?: boolean }} options - 可选项
+   * @returns {ServerConfig} 处理后的字段对象
+   */
   buildServerFields(config, existing = null, options = {}) {
     let schema = this.getServerConfigSchema();
     let fields = {};
@@ -190,6 +262,11 @@ class MqttManager {
     return fields;
   }
 
+  /**
+   * 构建主题对象
+   * @param {TopicConfig} t - 原始主题数据
+   * @returns {MqttTopic} 标准化后的主题对象
+   */
   buildTopic(t) {
     return {
       id: t.id || 'topic_' + Date.now() + '_' + Math.random().toString(36).slice(2, 6),
@@ -199,6 +276,11 @@ class MqttManager {
     };
   }
 
+  /**
+   * 添加服务器
+   * @param {ServerConfig} config - 服务器配置
+   * @returns {MqttServer} 创建后的服务器对象
+   */
   addServer(config) {
 
     let id = 'srv_' + Date.now() + '_' + Math.random().toString(36).slice(2, 6);
@@ -218,6 +300,12 @@ class MqttManager {
 
   }
 
+  /**
+   * 更新服务器配置
+   * @param {string} id - 服务器 id
+   * @param {ServerConfig} config - 新的服务器配置
+   * @returns {MqttServer | null} 更新后的服务器对象或 null
+   */
   updateServer(id, config) {
 
     let server = this.servers.get(id);
@@ -234,6 +322,10 @@ class MqttManager {
 
   }
 
+  /**
+   * 删除服务器，并断开其连接
+   * @param {string} id - 服务器 id
+   */
   deleteServer(id) {
     // 先断开连接
     this.disconnect(id);
@@ -243,6 +335,10 @@ class MqttManager {
     this.saveData();
   }
 
+  /**
+   * 导出所有服务器配置（不含运行时状态）
+   * @returns {ServerConfig[]} 服务器配置数组
+   */
   exportServers() {
     let schemaKeys = Object.keys(this.getServerConfigSchema());
     return Array.from(this.servers.values()).map((s) => {
@@ -255,6 +351,11 @@ class MqttManager {
     });
   }
 
+  /**
+   * 构建导出用的主题对象
+   * @param {MqttTopic} t - 主题对象
+   * @returns {TopicConfig} 导出主题对象
+   */
   buildTopicExport(t) {
     return {
       id: t.id,
@@ -263,6 +364,11 @@ class MqttManager {
     };
   }
 
+  /**
+   * 导入服务器配置列表，会覆盖现有配置
+   * @param {ServerConfig[]} serverList - 服务器配置数组
+   * @returns {MqttServer[]} 导入后的服务器列表
+   */
   importServers(serverList) {
     if (!Array.isArray(serverList)) {
       throw new Error('导入格式错误：必须是服务器配置数组');
@@ -302,6 +408,11 @@ class MqttManager {
 
   // ==================== 连接管理 ====================
 
+  /**
+   * 连接指定服务器
+   * @param {string} id - 服务器 id
+   * @returns {boolean} 是否成功发起连接
+   */
   connect(id) {
 
     let server = this.servers.get(id);
@@ -399,6 +510,10 @@ class MqttManager {
     }
   }
 
+  /**
+   * 断开指定服务器的连接
+   * @param {string} id - 服务器 id
+   */
   disconnect(id) {
 
     let client = this.clients.get(id);
@@ -421,6 +536,14 @@ class MqttManager {
   }
 
   // ==================== 订阅管理 ====================
+
+  /**
+   * 执行订阅操作（内部方法）
+   * @param {string} serverId - 服务器 id
+   * @param {string} topic - 主题名称
+   * @param {PublishOptions} opts - 订阅选项
+   * @returns {boolean} 是否发起订阅
+   */
   _doSubscribe(serverId, topic, opts) {
 
     let client = this.clients.get(serverId);
@@ -447,6 +570,13 @@ class MqttManager {
 
   }
 
+  /**
+   * 为主题列表添加新主题
+   * @param {string} serverId - 服务器 id
+   * @param {string} topic - 主题名称
+   * @param {MqttQoS} qos - QoS 等级
+   * @returns {MqttTopic | null} 添加后的主题对象或 null
+   */
   addTopic(serverId, topic, qos = 1) {
     let server = this.servers.get(serverId);
     if (!server) {
@@ -472,6 +602,12 @@ class MqttManager {
 
   }
 
+  /**
+   * 移除主题并取消订阅
+   * @param {string} serverId - 服务器 id
+   * @param {string} topic - 主题名称
+   * @returns {boolean} 是否移除成功
+   */
   removeTopic(serverId, topic) {
 
     let server = this.servers.get(serverId);
@@ -491,6 +627,12 @@ class MqttManager {
 
   }
 
+  /**
+   * 订阅指定主题
+   * @param {string} serverId - 服务器 id
+   * @param {string} topic - 主题名称
+   * @returns {boolean} 是否发起订阅
+   */
   subscribe(serverId, topic) {
 
     let server = this.servers.get(serverId);
@@ -509,6 +651,12 @@ class MqttManager {
 
   }
 
+  /**
+   * 取消订阅指定主题
+   * @param {string} serverId - 服务器 id
+   * @param {string} topic - 主题名称
+   * @returns {boolean} 是否发起取消订阅
+   */
   unsubscribe(serverId, topic) {
 
     let client = this.clients.get(serverId);
@@ -532,6 +680,14 @@ class MqttManager {
 
   }
 
+  /**
+   * 更新主题信息，必要时取消旧主题并重新订阅新主题
+   * @param {string} serverId - 服务器 id
+   * @param {string} topicId - 主题 id
+   * @param {string} newTopic - 新的主题名称
+   * @param {number} newQos - 新的 QoS 等级
+   * @returns {boolean} 是否更新成功
+   */
   updateTopic(serverId, topicId, newTopic, newQos) {
 
     let server = this.servers.get(serverId);
@@ -583,6 +739,11 @@ class MqttManager {
 
   }
 
+  /**
+   * 批量订阅服务器下所有未订阅的主题
+   * @param {string} serverId - 服务器 id
+   * @returns {boolean} 是否发起批量订阅
+   */
   subscribeAll(serverId) {
 
     let client = this.clients.get(serverId);
@@ -625,6 +786,14 @@ class MqttManager {
 
   // ==================== 消息发布 ====================
 
+  /**
+   * 向指定主题发布消息
+   * @param {string} serverId - 服务器 id
+   * @param {string} topic - 目标主题
+   * @param {string} payload - 消息内容
+   * @param {PublishOptions} opts - 发布选项
+   * @returns {boolean} 是否发起发布
+   */
   publish(serverId, topic, payload, opts = {}) {
 
     let client = this.clients.get(serverId);
@@ -700,19 +869,37 @@ class MqttManager {
 
   // ==================== 消息管理 ====================
 
+  /**
+   * 获取指定服务器的消息列表
+   * @param {string} serverId - 服务器 id
+   * @returns {MqttMessage[]} 消息数组
+   */
   getMessages(serverId) {
     return this.messages.get(serverId) || [];
   }
 
+  /**
+   * 获取指定服务器的发布历史
+   * @param {string} serverId - 服务器 id
+   * @returns {PublishRecord[]} 发布历史数组
+   */
   getPublishHistory(serverId) {
     return this.publishHistory.get(serverId) || [];
   }
 
+  /**
+   * 清空指定服务器的消息列表
+   * @param {string} serverId - 服务器 id
+   */
   clearMessages(serverId) {
     this.messages.set(serverId, []);
     this.saveData();
   }
 
+  /**
+   * 清空指定服务器的发布历史
+   * @param {string} serverId - 服务器 id
+   */
   clearPublishHistory(serverId) {
     this.publishHistory.set(serverId, []);
     this.saveData();