refactor: 增强代码注释以提升可读性和维护性

2026-05-18 10:10:16 +08:00
parent 84afd6e6c0
commit a2300b3a29
22 changed files with 192 additions and 1 deletions
@@ -232,6 +232,13 @@ public class ExportExcelServiceImpl implements IExportExcelService {
         */
        private DemoCityData pData;

+        /**
+         * 构造城市演示数据。
+         *
+         * @param id 数据库 id
+         * @param pid 父级 id
+         * @param name 名称
+         */
        public DemoCityData(Integer id, Integer pid, String name) {
            this.id = id;
            this.pid = pid;
@@ -19,10 +19,22 @@ public record OnlineUserCleanEvent(Long roleId, Collection<Long> userIds) {
        }
    }

+    /**
+     * 创建按角色清理在线用户事件。
+     *
+     * @param roleId 角色 ID
+     * @return 在线用户清理事件
+     */
    public static OnlineUserCleanEvent byRole(Long roleId) {
        return new OnlineUserCleanEvent(roleId, null);
    }

+    /**
+     * 创建按用户清理在线用户事件。
+     *
+     * @param userIds 用户 ID 集合
+     * @return 在线用户清理事件
+     */
    public static OnlineUserCleanEvent byUsers(Collection<Long> userIds) {
        return new OnlineUserCleanEvent(null, userIds);
    }
@@ -15,14 +15,34 @@ public record OssConfigChangeEvent(
    boolean defaultConfig
 ) {

+    /**
+     * 创建保存 OSS 配置后的变更事件。
+     *
+     * @param configKey 当前配置 key
+     * @param oldConfigKey 变更前配置 key
+     * @param configJson 当前配置 JSON
+     * @return OSS 配置变更事件
+     */
    public static OssConfigChangeEvent save(String configKey, String oldConfigKey, String configJson) {
        return new OssConfigChangeEvent(configKey, oldConfigKey, configJson, false);
    }

+    /**
+     * 创建删除 OSS 配置后的变更事件。
+     *
+     * @param configKey 配置 key
+     * @return OSS 配置变更事件
+     */
    public static OssConfigChangeEvent remove(String configKey) {
        return new OssConfigChangeEvent(configKey, null, null, false);
    }

+    /**
+     * 创建切换默认 OSS 配置后的变更事件。
+     *
+     * @param configKey 默认配置 key
+     * @return OSS 配置变更事件
+     */
    public static OssConfigChangeEvent useDefault(String configKey) {
        return new OssConfigChangeEvent(configKey, null, null, true);
    }