From 3ee1112c4ce9b1acfa7ac5959a4e1ffd19ee0fce Mon Sep 17 00:00:00 2001
From: Charles7c <charles7c@126.com>
Date: Sat, 9 Aug 2025 17:40:10 +0800
Subject: [PATCH] =?UTF-8?q?refactor(extension/crud):=20=E4=BC=98=E5=8C=96?=
 =?UTF-8?q?=E6=A0=91=E5=9E=8B=E7=BB=93=E6=9E=84=E5=AD=97=E5=85=B8=E9=85=8D?=
 =?UTF-8?q?=E7=BD=AE=E7=9B=B8=E5=85=B3=E5=91=BD=E5=90=8D=E5=8F=8A=E6=B3=A8?=
 =?UTF-8?q?=E9=87=8A=20DICT=5FTREE=20->=20TREE=5FDICT?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../extension/crud/annotation/DictModel.java    |  6 ++++++
 .../extension/crud/annotation/TreeField.java    |  7 ++-----
 .../crud/autoconfigure/CrudProperties.java      | 17 ++++++++++-------
 ...es.java => CrudTreeDictModelProperties.java} |  9 +++++----
 .../crud/controller/AbstractCrudController.java | 10 +++++-----
 .../starter/extension/crud/enums/Api.java       |  4 ++--
 .../extension/crud/service/CrudService.java     |  5 ++++-
 .../extension/crud/service/CrudServiceImpl.java | 12 ++++++------
 .../extension/crud/service/CrudServiceImpl.java | 12 ++++++------
 9 files changed, 46 insertions(+), 36 deletions(-)
 rename continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/autoconfigure/{CrudTreeProperties.java => CrudTreeDictModelProperties.java} (91%)

diff --git a/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/annotation/DictModel.java b/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/annotation/DictModel.java
index 0690c249..f103f37c 100644
--- a/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/annotation/DictModel.java
+++ b/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/annotation/DictModel.java
@@ -16,11 +16,17 @@
 
 package top.continew.starter.extension.crud.annotation;
 
+import top.continew.starter.extension.crud.model.query.SortQuery;
+
 import java.lang.annotation.*;
 
 /**
  * 字典结构映射
  *
+ * <p>用于查询字典列表 API（下拉选项等场景）</p>
+ *
+ * @see top.continew.starter.extension.crud.controller.AbstractCrudController#dict(Object, SortQuery)
+ *
  * @author Charles7c
  * @since 2.1.0
  */
diff --git a/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/annotation/TreeField.java b/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/annotation/TreeField.java
index cb22a4ad..607d481a 100644
--- a/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/annotation/TreeField.java
+++ b/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/annotation/TreeField.java
@@ -16,19 +16,16 @@
 
 package top.continew.starter.extension.crud.annotation;
 
-import top.continew.starter.extension.crud.autoconfigure.CrudTreeProperties;
-
 import java.lang.annotation.*;
 
 /**
- * 树结构字段
+ * 树结构字段映射
  *
  * <p>
- * 用于复杂树场景，例如：表格
+ * 用于复杂树场景，例如：表格列表
  * </p>
  *
  * @see cn.hutool.core.lang.tree.TreeNodeConfig
- * @see CrudTreeProperties
  *
  * @author Charles7c
  * @since 1.0.0
diff --git a/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/autoconfigure/CrudProperties.java b/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/autoconfigure/CrudProperties.java
index 852545f9..16bedb32 100644
--- a/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/autoconfigure/CrudProperties.java
+++ b/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/autoconfigure/CrudProperties.java
@@ -19,6 +19,7 @@ package top.continew.starter.extension.crud.autoconfigure;
 import org.springframework.boot.context.properties.ConfigurationProperties;
 import org.springframework.boot.context.properties.NestedConfigurationProperty;
 import top.continew.starter.core.constant.PropertiesConstants;
+import top.continew.starter.extension.crud.model.query.SortQuery;
 
 /**
  * CRUD 配置属性
@@ -30,17 +31,19 @@ import top.continew.starter.core.constant.PropertiesConstants;
 public class CrudProperties {
 
     /**
-     * 树配置
-     * <p>用于简单树场景，例如：树选择（下拉）</p>
+     * 树型字典结构映射配置
+     *
+     * @see top.continew.starter.extension.crud.controller.AbstractCrudController#dictTree(Object, SortQuery)
+     * @see top.continew.starter.extension.crud.service.CrudService#tree(Object, SortQuery, boolean)
      */
     @NestedConfigurationProperty
-    private CrudTreeProperties tree = new CrudTreeProperties();
+    private CrudTreeDictModelProperties treeDictModel = new CrudTreeDictModelProperties();
 
-    public CrudTreeProperties getTree() {
-        return tree;
+    public CrudTreeDictModelProperties getTreeDictModel() {
+        return treeDictModel;
     }
 
-    public void setTree(CrudTreeProperties tree) {
-        this.tree = tree;
+    public void setTreeDictModel(CrudTreeDictModelProperties treeDictModel) {
+        this.treeDictModel = treeDictModel;
     }
 }
diff --git a/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/autoconfigure/CrudTreeProperties.java b/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/autoconfigure/CrudTreeDictModelProperties.java
similarity index 91%
rename from continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/autoconfigure/CrudTreeProperties.java
rename to continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/autoconfigure/CrudTreeDictModelProperties.java
index a7c90e48..1916be80 100644
--- a/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/autoconfigure/CrudTreeProperties.java
+++ b/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/autoconfigure/CrudTreeDictModelProperties.java
@@ -19,20 +19,21 @@ package top.continew.starter.extension.crud.autoconfigure;
 import cn.hutool.core.lang.tree.TreeNodeConfig;
 import top.continew.starter.core.util.validation.CheckUtils;
 import top.continew.starter.extension.crud.annotation.TreeField;
+import top.continew.starter.extension.crud.model.query.SortQuery;
 
 /**
- * CRUD 树列表配置属性
+ * 树型字典结构映射配置属性
  *
  * <p>
- * 用于简单树场景，例如：树选择（下拉）
+ * 用于查询树型结构字典列表 API（树型结构下拉选项等场景）
  * </p>
  *
- * @see TreeField
+ * @see top.continew.starter.extension.crud.controller.AbstractCrudController#dictTree(Object, SortQuery)
  *
  * @author Charles7c
  * @since 2.7.2
  */
-public class CrudTreeProperties {
+public class CrudTreeDictModelProperties {
 
     /**
      * ID 字段名
diff --git a/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/controller/AbstractCrudController.java b/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/controller/AbstractCrudController.java
index 9744b819..604d16b3 100644
--- a/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/controller/AbstractCrudController.java
+++ b/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/controller/AbstractCrudController.java
@@ -204,16 +204,16 @@ public abstract class AbstractCrudController<S extends CrudService<L, D, Q, C>,
     }
 
     /**
-     * 查询字典树列表
+     * 查询树型字典列表
      *
      * @param query     查询条件
      * @param sortQuery 排序查询条件
-     * @return 字典树列表信息
+     * @return 树型字典列表信息
      */
-    @CrudApi(Api.DICT_TREE)
-    @Operation(summary = "查询字典树列表", description = "查询树型结构字典列表（树型结构下拉选项等场景）")
+    @CrudApi(Api.TREE_DICT)
+    @Operation(summary = "查询树型字典列表", description = "查询树型结构字典列表（树型结构下拉选项等场景）")
     @GetMapping("/dict/tree")
-    public List<Tree<Long>> dictTree(@Valid Q query, @Valid SortQuery sortQuery) {
+    public List<Tree<Long>> treeDict(@Valid Q query, @Valid SortQuery sortQuery) {
         return baseService.tree(query, sortQuery, true);
     }
 }
diff --git a/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/enums/Api.java b/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/enums/Api.java
index a4248512..cfe278b0 100644
--- a/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/enums/Api.java
+++ b/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/enums/Api.java
@@ -75,7 +75,7 @@ public enum Api {
     DICT,
 
     /**
-     * 字典树列表（树型结构下拉选项等场景）
+     * 树型字典列表（树型结构下拉选项等场景）
      */
-    DICT_TREE
+    TREE_DICT
 }
\ No newline at end of file
diff --git a/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/service/CrudService.java b/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/service/CrudService.java
index 75bbf1e2..d0da0436 100644
--- a/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/service/CrudService.java
+++ b/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-core/src/main/java/top/continew/starter/extension/crud/service/CrudService.java
@@ -65,9 +65,11 @@ public interface CrudService<L, D, Q, C> {
      *
      * @param query     查询条件
      * @param sortQuery 排序查询条件
-     * @param isSimple  是否为简单树结构（不包含基本树结构之外的扩展字段，简单树（下拉列表）使用全局配置结构，复杂树（表格）使用 @TreeField 局部配置）
+     * @param isSimple  是否为简单树结构（不包含基本树结构之外的扩展字段，简单树（例如：下拉列表）使用 CrudTreeDictModelProperties
+     *                  全局树型字典映射配置，复杂树（例如：表格）使用 @TreeField 局部结构配置）
      * @return 树列表信息
      * @see TreeField
+     * @see top.continew.starter.extension.crud.autoconfigure.CrudTreeDictModelProperties
      */
     List<Tree<Long>> tree(@Valid Q query, @Valid SortQuery sortQuery, boolean isSimple);
 
@@ -82,6 +84,7 @@ public interface CrudService<L, D, Q, C> {
      * @author lishuyan
      * @since 2.13.3
      * @see TreeField
+     * @see top.continew.starter.extension.crud.autoconfigure.CrudTreeDictModelProperties
      */
     List<Tree<Long>> tree(@Valid Q query, @Valid SortQuery sortQuery, boolean isSimple, boolean isSingleRoot);
 
diff --git a/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-mf/src/main/java/top/continew/starter/extension/crud/service/CrudServiceImpl.java b/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-mf/src/main/java/top/continew/starter/extension/crud/service/CrudServiceImpl.java
index c4dfedd9..bf701022 100644
--- a/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-mf/src/main/java/top/continew/starter/extension/crud/service/CrudServiceImpl.java
+++ b/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-mf/src/main/java/top/continew/starter/extension/crud/service/CrudServiceImpl.java
@@ -44,7 +44,7 @@ import top.continew.starter.excel.util.ExcelUtils;
 import top.continew.starter.extension.crud.annotation.DictModel;
 import top.continew.starter.extension.crud.annotation.TreeField;
 import top.continew.starter.extension.crud.autoconfigure.CrudProperties;
-import top.continew.starter.extension.crud.autoconfigure.CrudTreeProperties;
+import top.continew.starter.extension.crud.autoconfigure.CrudTreeDictModelProperties;
 import top.continew.starter.extension.crud.model.entity.BaseIdDO;
 import top.continew.starter.extension.crud.model.query.PageQuery;
 import top.continew.starter.extension.crud.model.query.SortQuery;
@@ -103,16 +103,16 @@ public class CrudServiceImpl<M extends BaseMapper<T>, T extends BaseIdDO, L, D,
             return CollUtil.newArrayList();
         }
         CrudProperties crudProperties = SpringUtil.getBean(CrudProperties.class);
-        CrudTreeProperties treeProperties = crudProperties.getTree();
+        CrudTreeDictModelProperties treeDictModel = crudProperties.getTreeDictModel();
         TreeField treeField = listClass.getDeclaredAnnotation(TreeField.class);
         TreeNodeConfig treeNodeConfig;
         Long rootId;
-        // 简单树（下拉列表）使用全局配置结构，复杂树（表格）使用局部配置
+        // 简单树（例如：下拉列表）使用 CrudTreeDictModelProperties 全局树型字典映射配置，复杂树（例如：表格）使用 @TreeField 局部结构配置
         if (isSimple) {
-            treeNodeConfig = treeProperties.genTreeNodeConfig();
-            rootId = treeProperties.getRootId();
+            treeNodeConfig = treeDictModel.genTreeNodeConfig();
+            rootId = treeDictModel.getRootId();
         } else {
-            treeNodeConfig = treeProperties.genTreeNodeConfig(treeField);
+            treeNodeConfig = treeDictModel.genTreeNodeConfig(treeField);
             rootId = treeField.rootId();
         }
         if (isSingleRoot) {
diff --git a/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-mp/src/main/java/top/continew/starter/extension/crud/service/CrudServiceImpl.java b/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-mp/src/main/java/top/continew/starter/extension/crud/service/CrudServiceImpl.java
index 8e37c90d..a2955399 100644
--- a/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-mp/src/main/java/top/continew/starter/extension/crud/service/CrudServiceImpl.java
+++ b/continew-starter-extension/continew-starter-extension-crud/continew-starter-extension-crud-mp/src/main/java/top/continew/starter/extension/crud/service/CrudServiceImpl.java
@@ -46,7 +46,7 @@ import top.continew.starter.excel.util.ExcelUtils;
 import top.continew.starter.extension.crud.annotation.DictModel;
 import top.continew.starter.extension.crud.annotation.TreeField;
 import top.continew.starter.extension.crud.autoconfigure.CrudProperties;
-import top.continew.starter.extension.crud.autoconfigure.CrudTreeProperties;
+import top.continew.starter.extension.crud.autoconfigure.CrudTreeDictModelProperties;
 import top.continew.starter.extension.crud.model.entity.BaseIdDO;
 import top.continew.starter.extension.crud.model.query.PageQuery;
 import top.continew.starter.extension.crud.model.query.SortQuery;
@@ -105,16 +105,16 @@ public class CrudServiceImpl<M extends BaseMapper<T>, T extends BaseIdDO, L, D,
             return CollUtil.newArrayList();
         }
         CrudProperties crudProperties = SpringUtil.getBean(CrudProperties.class);
-        CrudTreeProperties treeProperties = crudProperties.getTree();
+        CrudTreeDictModelProperties treeDictModel = crudProperties.getTreeDictModel();
         TreeField treeField = listClass.getDeclaredAnnotation(TreeField.class);
         TreeNodeConfig treeNodeConfig;
         Long rootId;
-        // 简单树（下拉列表）使用全局配置结构，复杂树（表格）使用局部配置
+        // 简单树（例如：下拉列表）使用 CrudTreeDictModelProperties 全局树型字典映射配置，复杂树（例如：表格）使用 @TreeField 局部结构配置
         if (isSimple) {
-            treeNodeConfig = treeProperties.genTreeNodeConfig();
-            rootId = treeProperties.getRootId();
+            treeNodeConfig = treeDictModel.genTreeNodeConfig();
+            rootId = treeDictModel.getRootId();
         } else {
-            treeNodeConfig = treeProperties.genTreeNodeConfig(treeField);
+            treeNodeConfig = treeDictModel.genTreeNodeConfig(treeField);
             rootId = treeField.rootId();
         }
         if (isSingleRoot) {