From 5f6a8ab089b1292bb99d30c86f858e88f09834c6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=B5=B5=E5=BF=A0=E6=9E=97?= <170083662@qq.com>
Date: Fri, 27 Feb 2026 15:23:59 +0800
Subject: [PATCH] =?UTF-8?q?feat(excel):=20=E6=B7=BB=E5=8A=A0Excel=E5=AF=BC?=
 =?UTF-8?q?=E5=85=A5=E8=A1=A8=E5=A4=B4=E5=88=AB=E5=90=8D=E6=94=AF=E6=8C=81?=
 =?UTF-8?q?=E5=8A=9F=E8=83=BD?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增ExcelHeaderAlias注解用于定义表头别名
- 在CreditExternalImportParam中为认缴出资额字段添加别名映射
- 扩展ExcelImportSupport类支持运行时表头别名解析
- 实现别名到标准表头名称的规范化映射逻辑
- 保持导出模板表头不变的情况下支持多种导入表头格式
---
 .../credit/controller/ExcelImportSupport.java | 15 ++++++++++++
 .../credit/excel/ExcelHeaderAlias.java        | 23 +++++++++++++++++++
 .../param/CreditExternalImportParam.java      |  2 ++
 3 files changed, 40 insertions(+)
 create mode 100644 src/main/java/com/gxwebsoft/credit/excel/ExcelHeaderAlias.java

diff --git a/src/main/java/com/gxwebsoft/credit/controller/ExcelImportSupport.java b/src/main/java/com/gxwebsoft/credit/controller/ExcelImportSupport.java
index 7d8c647..9e5711e 100644
--- a/src/main/java/com/gxwebsoft/credit/controller/ExcelImportSupport.java
+++ b/src/main/java/com/gxwebsoft/credit/controller/ExcelImportSupport.java
@@ -5,6 +5,7 @@ import cn.afterturn.easypoi.excel.ExcelImportUtil;
 import cn.afterturn.easypoi.excel.annotation.Excel;
 import cn.afterturn.easypoi.excel.entity.ExportParams;
 import cn.afterturn.easypoi.excel.entity.ImportParams;
+import com.gxwebsoft.credit.excel.ExcelHeaderAlias;
 import org.apache.poi.ss.usermodel.Cell;
 import org.apache.poi.ss.usermodel.CellType;
 import org.apache.poi.ss.usermodel.DataFormatter;
@@ -353,6 +354,20 @@ public class ExcelImportSupport {
                     // key -> canonical annotation name
                     map.putIfAbsent(key, name);
                 }
+
+                // Allow import-time header aliases without changing the exported template header.
+                ExcelHeaderAlias alias = field.getAnnotation(ExcelHeaderAlias.class);
+                if (alias != null && alias.value() != null) {
+                    for (String aliasName : alias.value()) {
+                        if (aliasName == null || aliasName.trim().isEmpty()) {
+                            continue;
+                        }
+                        String aliasKey = normalizeHeaderKey(aliasName);
+                        if (!aliasKey.isEmpty()) {
+                            map.putIfAbsent(aliasKey, name);
+                        }
+                    }
+                }
             }
             current = current.getSuperclass();
         }
diff --git a/src/main/java/com/gxwebsoft/credit/excel/ExcelHeaderAlias.java b/src/main/java/com/gxwebsoft/credit/excel/ExcelHeaderAlias.java
new file mode 100644
index 0000000..f8a6d55
--- /dev/null
+++ b/src/main/java/com/gxwebsoft/credit/excel/ExcelHeaderAlias.java
@@ -0,0 +1,23 @@
+package com.gxwebsoft.credit.excel;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Excel 导入表头别名。
+ *
+ * <p>EasyPOI 的 {@code @Excel(name=...)} 仅支持一个表头名；当上游模板存在多种表头写法时，
+ * 可用此注解声明别名，让 {@link com.gxwebsoft.credit.controller.ExcelImportSupport} 在导入前把别名规范化为 canonical 表头。</p>
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.FIELD)
+public @interface ExcelHeaderAlias {
+
+    /**
+     * 允许匹配的表头别名列表（任意一个匹配即视为该列）。
+     */
+    String[] value();
+}
+
diff --git a/src/main/java/com/gxwebsoft/credit/param/CreditExternalImportParam.java b/src/main/java/com/gxwebsoft/credit/param/CreditExternalImportParam.java
index 68cd0d4..7c51764 100644
--- a/src/main/java/com/gxwebsoft/credit/param/CreditExternalImportParam.java
+++ b/src/main/java/com/gxwebsoft/credit/param/CreditExternalImportParam.java
@@ -1,6 +1,7 @@
 package com.gxwebsoft.credit.param;
 
 import cn.afterturn.easypoi.excel.annotation.Excel;
+import com.gxwebsoft.credit.excel.ExcelHeaderAlias;
 import lombok.Data;
 
 import java.io.Serializable;
@@ -31,6 +32,7 @@ public class CreditExternalImportParam implements Serializable {
     private String shareholdingRatio;
 
     @Excel(name = "认缴出资额")
+    @ExcelHeaderAlias({"认缴出资额/持股数"})
     private String subscribedInvestmentAmount;
 
     @Excel(name = "认缴出资日期")