diff --git a/blade-common/src/main/java/org/springblade/common/excel/ImportFailureExcelUtil.java b/blade-common/src/main/java/org/springblade/common/excel/ImportFailureExcelUtil.java
index 6b0ad40d..d4330eed 100644
--- a/blade-common/src/main/java/org/springblade/common/excel/ImportFailureExcelUtil.java
+++ b/blade-common/src/main/java/org/springblade/common/excel/ImportFailureExcelUtil.java
@@ -80,6 +80,348 @@ public class ImportFailureExcelUtil {
addValidationError(validationErrors, value != null && value.length() > maxLength, message);
}
+ /**
+ * 把「读取 Excel 阶段」的转换异常转成可读的失败原因。
+ *
+ * 背景：单元格里填了无法转换的内容（如金额列填「一万二千元」）时，EasyExcel 会在
+ * {@code ExcelUtil.read(...)} 阶段就抛 {@link cn.idev.excel.exception.ExcelDataConvertException}，
+ * 根本走不到行级校验；若不兜底，用户看到的是
+ * 「Convert data ... to class java.math.BigDecimal error」这类技术文案。
+ *
+ * 本方法据异常里的行列位置与目标类型，生成「第N行「列名」格式不正确：<原值>」这样
+ * 用户能看懂、能定位的文案；列名靠表头反射拿 {@code @ExcelProperty}，拿不到则退回列序号。
+ *
+ * @param exception 读取阶段抛出的异常
+ * @param excelClass 导入模型类（用于按列序号反查表头名）
+ * @return 可读的失败原因；非转换类异常返回 null（交由上层按原样处理）
+ */
+ public static String describeReadFailure(Throwable exception, Class excelClass) {
+ cn.idev.excel.exception.ExcelDataConvertException convertException = findCause(exception,
+ cn.idev.excel.exception.ExcelDataConvertException.class);
+ if (convertException == null) {
+ return null;
+ }
+ Integer rowIndex = convertException.getRowIndex();
+ Integer columnIndex = convertException.getColumnIndex();
+ String columnName = columnName(excelClass, columnIndex);
+ // Excel 行号：EasyExcel 的 rowIndex 为 1 基数据行号（表头占第 1 行），故 Excel 行号 = rowIndex + 1
+ String rowText = rowIndex == null ? "第?行" : "第" + (rowIndex + 1) + "行";
+ String columnText = columnName == null ? ("第" + (columnIndex == null ? "?" : columnIndex + 1) + "列") : "「" + columnName + "」";
+ String value = cellValue(convertException);
+ StringBuilder message = new StringBuilder(rowText).append(columnText).append("格式不正确");
+ if (value != null && !value.isBlank()) {
+ message.append("：").append(value);
+ }
+ return message.toString();
+ }
+
+ /**
+ * 在异常链里查找指定类型的 cause
+ */
+ private static T findCause(Throwable throwable, Class type) {
+ for (Throwable current = throwable; current != null; current = current.getCause()) {
+ if (type.isInstance(current)) {
+ return type.cast(current);
+ }
+ if (current.getCause() == current) {
+ break;
+ }
+ }
+ return null;
+ }
+
+ /**
+ * 按列序号反查表头名（@ExcelProperty 的 value，取不到则用字段名）
+ */
+ private static String columnName(Class excelClass, Integer columnIndex) {
+ if (excelClass == null || columnIndex == null) {
+ return null;
+ }
+ List fields = excelFields(excelClass);
+ if (columnIndex < 0 || columnIndex >= fields.size()) {
+ return null;
+ }
+ Field field = fields.get(columnIndex);
+ ExcelProperty excelProperty = field.getAnnotation(ExcelProperty.class);
+ if (excelProperty == null) {
+ return field.getName();
+ }
+ String[] value = excelProperty.value();
+ String columnName = value.length == 0 ? field.getName() : value[0];
+ return columnName.replace("*", "");
+ }
+
+ /**
+ * 取触发转换失败的单元格原值
+ */
+ private static String cellValue(cn.idev.excel.exception.ExcelDataConvertException exception) {
+ try {
+ cn.idev.excel.metadata.data.CellData cellData = exception.getCellData();
+ if (cellData == null) {
+ return null;
+ }
+ Object data = cellData.getData();
+ if (data == null) {
+ data = cellData.getStringValue();
+ }
+ return data == null ? null : String.valueOf(data).trim();
+ } catch (Exception ignored) {
+ return null;
+ }
+ }
+
+ /**
+ * 以「原始单元格文本」方式重读导入文件，得到的行用于构造读取阶段的失败明细。
+ *
+ * 用途：当 {@code ExcelUtil.read(file, XxxExcel.class)} 因单元格无法转换而失败时，
+ * 已解析的实体列表是不完整的（异常中断了整批读取）。此时用本方法重读一次：
+ * 不做类型转换（直接读成 Map），因此绝不会再抛转换异常，可拿到**原表全部行**，
+ * 供导出「原表全量 + 仅出错行带原因」的失败明细。
+ *
+ * @param file 上传的 Excel 文件
+ * @param excelClass 导入模型类（按列序号反查表头名，用于把列序号映射成列名）
+ * @return 按行组织的明细数据：每行是「表头名 → 单元格文本」的有序 Map；
+ * 读不出内容时返回空列表（调用方按空明细处理）
+ */
+ public static List> readRawRows(java.io.InputStream file, Class excelClass) {
+ List> rawRows = new ArrayList<>();
+ try {
+ cn.idev.excel.read.builder.ExcelReaderBuilder builder = cn.idev.excel.FastExcel
+ .read(file, new cn.idev.excel.event.AnalysisEventListener>() {
+ @Override
+ public void invoke(Map data, cn.idev.excel.context.AnalysisContext context) {
+ rawRows.add(new java.util.LinkedHashMap<>(data));
+ }
+
+ @Override
+ public void doAfterAllAnalysed(cn.idev.excel.context.AnalysisContext context) {
+ // 无需处理
+ }
+ });
+ builder.headRowNumber(1).sheet().doRead();
+ } catch (Exception ignored) {
+ // 重读本身失败时退回空明细，由调用方按「无法读取」提示
+ return new ArrayList<>();
+ }
+ List fields = excelClass == null ? List.of() : excelFields(excelClass);
+ List> rows = new ArrayList<>();
+ for (Map rawRow : rawRows) {
+ Map row = new java.util.LinkedHashMap<>();
+ for (Map.Entry entry : rawRow.entrySet()) {
+ Integer columnIndex = entry.getKey();
+ String columnName = columnIndex != null && columnIndex < fields.size()
+ ? columnName(excelClass, columnIndex)
+ : null;
+ if (columnName == null) {
+ columnName = "第" + (columnIndex == null ? "?" : columnIndex + 1) + "列";
+ }
+ row.put(columnName, entry.getValue());
+ }
+ rows.add(row);
+ }
+ return rows;
+ }
+
+ /**
+ * 导出「读取阶段失败」明细：原表全量行 + 末尾「导入失败原因」列。
+ *
+ * 与 {@link #export} 的区别：本方法直接按重读得到的「表头名 → 单元格文本」写出，
+ * 不依赖导入模型的字段反射，因此适用于「单元格无法转换为实体字段」的场景
+ * （此时实体列表不完整，无法走常规导出）。
+ *
+ * @param response 响应
+ * @param fileName 文件名
+ * @param sheetName 工作表名
+ * @param rawRows {@link #readRawRows} 得到的原表全部行
+ * @param failureMessageByRow 行号（0 基，对应 rawRows 下标）→ 该行失败原因；为 null 表示该行无错
+ */
+ public static void exportRawFailure(HttpServletResponse response, String fileName, String sheetName,
+ List> rawRows, Map failureMessageByRow) {
+ response.setContentType("application/vnd.ms-excel");
+ response.setCharacterEncoding(StandardCharsets.UTF_8.name());
+ String encodeFileName = URLEncoder.encode(fileName, StandardCharsets.UTF_8);
+ response.setHeader("Content-disposition", "attachment;filename=" + encodeFileName + ".xlsx");
+ List headers = new ArrayList<>();
+ for (Map row : rawRows) {
+ for (String key : row.keySet()) {
+ if (!headers.contains(key)) {
+ headers.add(key);
+ }
+ }
+ }
+ headers.add(FAILURE_REASON);
+ List> head = new ArrayList<>();
+ for (String header : headers) {
+ head.add(List.of(header));
+ }
+ List> rows = new ArrayList<>();
+ Map> redColumnsByRow = new HashMap<>();
+ for (int rowIndex = 0; rowIndex < rawRows.size(); rowIndex++) {
+ Map rawRow = rawRows.get(rowIndex);
+ List