feat(core):优化表格构建逻辑以支持字段过滤与描述映射

- 在 `FsTableUtil` 中移除冗余的 `getHeadTemplateBuilder` 重载方法，统一构建入口
- 新增 `getIncludeFieldHeaders` 方法，增强字段包含逻辑，支持驼峰与下划线格式匹配
-修复表头排序问题，确保启用描述时正确应用字段顺序
- 在 `PropertyUtil` 中新增 `getHeaders`重载方法，支持传入字段过滤列表
-`优化 `SheetBuilder 构建流程，使其能正确传递 `includeFields` 并应用字段描述映射
- 移除不必要的包导入与空行，提升代码可读性- 增加 `@NotNull` 注解以强化静态检查能力

src/main/java/cn/isliu/core/builder/SheetBuilder.java

@@ -158,7 +158,7 @@ public class SheetBuilder<T> {
         Map<String, FieldProperty> fieldsMap = filterFieldsMap(allFieldsMap);
 
         // 生成表头
-        List<String> headers = PropertyUtil.getHeaders(fieldsMap);
+        List<String> headers = PropertyUtil.getHeaders(fieldsMap, includeFields);
 
         // 获取表格配置
         TableConf tableConf = PropertyUtil.getTableConf(clazz);
@@ -170,7 +170,7 @@ public class SheetBuilder<T> {
         String sheetId = FsApiUtil.createSheet(sheetName, client, spreadsheetToken);
 
         // 2、添加表头数据
-        FsApiUtil.putValues(spreadsheetToken, FsTableUtil.getHeadTemplateBuilder(sheetId, headers, fieldsMap, includeFields, tableConf, fieldDescriptions), client);
+        FsApiUtil.putValues(spreadsheetToken, FsTableUtil.getHeadTemplateBuilder(sheetId, headers, fieldsMap, tableConf, fieldDescriptions), client);
 
         // 3、设置表格样式
         FsApiUtil.setTableStyle(FsTableUtil.getDefaultTableStyle(sheetId, fieldsMap, tableConf), client, spreadsheetToken);

src/main/java/cn/isliu/core/utils/FsTableUtil.java

@@ -14,6 +14,7 @@ import cn.isliu.core.service.CustomValueService;
 import com.google.gson.JsonElement;
 import com.google.gson.JsonParser;
 import com.google.gson.JsonSyntaxException;
+import org.jetbrains.annotations.NotNull;
 
 import java.lang.reflect.InvocationTargetException;
 import java.util.*;
@@ -356,18 +357,18 @@ public class FsTableUtil {
         setTableOptions(spreadsheetToken, headers, fieldsMap, sheetId, enableDesc, null);
     }
 
+//    public static CustomValueService.ValueRequest getHeadTemplateBuilder(String sheetId, List<String> headers,
+//                   Map<String, FieldProperty> fieldsMap, TableConf tableConf) {
+//        return getHeadTemplateBuilder(sheetId, headers, fieldsMap, null, tableConf);
+//    }
+
     public static CustomValueService.ValueRequest getHeadTemplateBuilder(String sheetId, List<String> headers,
                                                                          Map<String, FieldProperty> fieldsMap, TableConf tableConf) {
-        return getHeadTemplateBuilder(sheetId, headers, fieldsMap, null, tableConf);
+        return getHeadTemplateBuilder(sheetId, headers, fieldsMap, tableConf, null);
     }
 
     public static CustomValueService.ValueRequest getHeadTemplateBuilder(String sheetId, List<String> headers,
-                                                                         Map<String, FieldProperty> fieldsMap, List<String> includeFields, TableConf tableConf) {
+                                                                         Map<String, FieldProperty> fieldsMap, TableConf tableConf, Map<String, String> fieldDescriptions) {
-        return getHeadTemplateBuilder(sheetId, headers, fieldsMap, includeFields, tableConf, null);
-    }
-
-    public static CustomValueService.ValueRequest getHeadTemplateBuilder(String sheetId, List<String> headers,
-                                                                         Map<String, FieldProperty> fieldsMap, List<String> includeFields, TableConf tableConf, Map<String, String> fieldDescriptions) {
 
         String position = FsTableUtil.getColumnNameByNuNumber(headers.size());
 
@@ -378,22 +379,15 @@ public class FsTableUtil {
         int maxLevel = getMaxLevel(fieldsMap);
 
         if (maxLevel == 1) {
-            // 单层级表头：按order排序的headers
-            List<String> sortedHeaders;
-            if (includeFields != null && !includeFields.isEmpty()) {
-                sortedHeaders = includeFields.stream().sorted(Comparator.comparingInt(headers::indexOf)).collect(Collectors.toList());
-            } else {
-                sortedHeaders = getSortedHeaders(fieldsMap);
-            }
             int titleRow = tableConf.titleRow();
             if (tableConf.enableDesc()) {
                 int descRow = titleRow + 1;
                 batchPutValuesBuilder.addRange(sheetId + "!A" + titleRow + ":" + position + descRow);
-                batchPutValuesBuilder.addRow(sortedHeaders.toArray());
+                batchPutValuesBuilder.addRow(headers.toArray());
-                batchPutValuesBuilder.addRow(getDescArray(sortedHeaders, fieldsMap, fieldDescriptions));
+                batchPutValuesBuilder.addRow(getDescArray(headers, fieldsMap, fieldDescriptions));
             } else {
                 batchPutValuesBuilder.addRange(sheetId + "!A" + titleRow + ":" + position + titleRow);
-                batchPutValuesBuilder.addRow(sortedHeaders.toArray());
+                batchPutValuesBuilder.addRow(headers.toArray());
             }
         } else {
 
@@ -421,21 +415,47 @@ public class FsTableUtil {
 
             // 如果启用了描述，在最后一行添加描述
             if (tableConf.enableDesc()) {
-                List<String> finalHeaders;
-                if (includeFields != null && !includeFields.isEmpty()) {
-                    finalHeaders = includeFields.stream().sorted(Comparator.comparingInt(headers::indexOf)).collect(Collectors.toList());
-                } else {
-                    finalHeaders = getSortedHeaders(fieldsMap);
-                }
                 int descRow = maxLevel + 1;
                 batchPutValuesBuilder.addRange(sheetId + "!A" + descRow + ":" + position + descRow);
-                batchPutValuesBuilder.addRow(getDescArray(finalHeaders, fieldsMap, fieldDescriptions));
+                batchPutValuesBuilder.addRow(getDescArray(headers, fieldsMap, fieldDescriptions));
             }
         }
 
         return batchPutValuesBuilder.build();
     }
 
+    @NotNull
+    private static List<String> getIncludeFieldHeaders(List<String> headers, Map<String, FieldProperty> fieldsMap, List<String> includeFields) {
+        return includeFields.stream()
+                .map(includeField -> {
+                    // 查找匹配的fieldsMap key
+                    for (Map.Entry<String, FieldProperty> entry : fieldsMap.entrySet()) {
+                        FieldProperty fieldProperty = entry.getValue();
+                        if (fieldProperty != null && fieldProperty.getTableProperty() != null) {
+                            String field = fieldProperty.getField();
+                            if (field != null) {
+                                // 获取最后一个属性并转换为下划线格式
+                                String[] split = field.split("\\.");
+                                String lastValue = split[split.length - 1];
+                                String underscoreFormat = StringUtil.toUnderscoreCase(lastValue);
+                                // 如果匹配，返回fieldsMap的key
+                                if (underscoreFormat.equals(includeField)) {
+                                    return entry.getKey();
+                                }
+
+                                if (lastValue.equals(includeField)) {
+                                    return entry.getKey();
+                                }
+                            }
+                        }
+                    }
+                    // 如果没有匹配到，返回原始值
+                    return includeField;
+                })
+                .sorted(Comparator.comparingInt(includeFields::indexOf))
+                .collect(Collectors.toList());
+    }
+
     /**
      * 获取按order排序的表头列表
      *
@@ -480,6 +500,9 @@ public class FsTableUtil {
                     String fieldPath = fieldProperty.getField();
                     String fieldName = fieldPath.substring(fieldPath.lastIndexOf(".") + 1);
                     desc = fieldDescriptions.get(fieldName);
+                    if (desc == null) {
+                        desc = fieldDescriptions.get(StringUtil.toUnderscoreCase(fieldName));
+                    }
                 }
 
                 // 如果映射中没有找到，则从注解中获取

src/main/java/cn/isliu/core/utils/PropertyUtil.java

@@ -349,7 +349,7 @@ public class PropertyUtil {
                 clazz.equals(Character.class) ||
                 clazz.equals(Byte.class) ||
                 clazz.equals(Short.class) ||
-                clazz.equals(java.util.Date.class) ||
+                clazz.equals(Date.class) ||
                 clazz.equals(java.time.LocalDate.class) ||
                 clazz.equals(java.time.LocalDateTime.class));
     }
@@ -365,7 +365,70 @@ public class PropertyUtil {
      */
     @NotNull
     public static List<String> getHeaders(Map<String, FieldProperty> fieldsMap) {
+        return getSortedHeaders(fieldsMap);
+    }
+
+    /**
+     * 从字段属性映射中提取表头列表
+     *
+     * 此方法根据字段的@TableProperty注解中的order属性对字段进行排序，
+     * 返回按顺序排列的表头列表，用于数据展示时的列顺序。
+     *
+     * @param fieldsMap 字段属性映射
+     * @return 按顺序排列的表头列表
+     */
+    @NotNull
+    public static List<String> getHeaders(Map<String, FieldProperty> fieldsMap, List<String> includeFields) {
+        List<String> sortedHeaders;
+        if (includeFields != null && !includeFields.isEmpty()) {
+            sortedHeaders = getIncludeFieldHeaders(fieldsMap, includeFields);
+        } else {
+            sortedHeaders = getSortedHeaders(fieldsMap);
+        }
+        return sortedHeaders;
+    }
+
+    @NotNull
+    private static List<String> getIncludeFieldHeaders(Map<String, FieldProperty> fieldsMap, List<String> includeFields) {
+        return includeFields.stream()
+                .map(includeField -> {
+                    // 查找匹配的fieldsMap key
+                    for (Map.Entry<String, FieldProperty> entry : fieldsMap.entrySet()) {
+                        FieldProperty fieldProperty = entry.getValue();
+                        if (fieldProperty != null && fieldProperty.getTableProperty() != null) {
+                            String field = fieldProperty.getField();
+                            if (field != null) {
+                                // 获取最后一个属性并转换为下划线格式
+                                String[] split = field.split("\\.");
+                                String lastValue = split[split.length - 1];
+                                String underscoreFormat = StringUtil.toUnderscoreCase(lastValue);
+                                // 如果匹配，返回fieldsMap的key
+                                if (underscoreFormat.equals(includeField)) {
+                                    return entry.getKey();
+                                }
+
+                                if (lastValue.equals(includeField)) {
+                                    return entry.getKey();
+                                }
+                            }
+                        }
+                    }
+                    // 如果没有匹配到，返回原始值
+                    return includeField;
+                })
+                .sorted(Comparator.comparingInt(includeFields::indexOf))
+                .collect(Collectors.toList());
+    }
+
+    /**
+     * 获取按order排序的表头列表
+     *
+     * @param fieldsMap 字段属性映射
+     * @return 按order排序的表头列表
+     */
+    private static List<String> getSortedHeaders(Map<String, FieldProperty> fieldsMap) {
         return fieldsMap.entrySet().stream()
+                .filter(entry -> entry.getValue() != null && entry.getValue().getTableProperty() != null)
                 .sorted(Comparator.comparingInt(entry -> entry.getValue().getTableProperty().order()))
                 .map(Map.Entry::getKey)
                 .collect(Collectors.toList());