create-yss-spec 1.0.0

package/template/.codex/skills/yss-excel-mvc/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: yss-excel-mvc
+description: 用于 Spring MVC 下的 Excel 导入导出实现。当用户提到 RequestExcel、ResponseExcel、Excel 导入解析、Excel 下载、动态列导出或导入导出接口异常时调用。
+---
+
+# yss-excel-mvc
+
+用于处理基于注解的 Excel 导入导出能力。
+
+## 何时使用
+
+- 用户要新增 Excel 导入接口。
+- 用户要新增 Excel 导出接口。
+- 用户提到 `@RequestExcel`、`@ResponseExcel`、`ExcelDynamicData`。
+- 用户反馈下载文件名异常、导入失败、动态列导出错位。
+
+## 工作方式
+
+1. 先识别是导入、固定模型导出还是动态列导出。
+2. 涉及真实注解、解析器、返回处理器、文件名或排障时，先读 `references/source-index.md`，再定位源码或文档。
+3. 先看现有 Controller 和返回结构，再决定是否只加注解还是要改模型。
+4. 优先复用项目现有的导入导出 VO，不要重新造重复模型。
+
+## 源码索引
+
+- 源码位置不要假设固定目录；先按 `yss-source-index/references/source-location.md` 定位。
+- 当前技能索引：`references/source-index.md`
+- 重点源码入口通常包括 `RequestExcel`、`ResponseExcel`、`ExcelDynamicData`、参数解析器、返回值处理器、starter 配置。
+
+当组件源码变化后，用 `yss-source-index` 刷新索引；刷新或读取前先按源码定位策略确认真实位置。
+
+## 常见实现路径
+
+- 导入：`@RequestExcel List<T>`
+- 固定模型导出：`@ResponseExcel` + `List<VO>`
+- 动态列导出：返回 `ExcelDynamicData`
+
+## 检查清单
+
+- 启动类是否启用了 Excel MVC 能力。
+- 上传字段名是否与前端一致。
+- 导出接口是否正确设置文件名和 sheet 名。
+- POST 下载场景是否能从响应头取到文件名。
+- 动态列场景下 `columns`、`columnCn`、`rows` 是否一一对应。
+- 导出 VO 字段注解和列顺序是否与前端模板一致。
+- 大数据量导出是否需要流式、分页或异步任务，避免 Controller 一次性堆内存。
+
+## 排障顺序
+
+1. 确认 starter 和 MVC 配置是否生效。
+2. 导入先查 multipart 字段名、文件格式、模型字段注解。
+3. 固定列导出先查 `@ResponseExcel`、返回类型、VO 注解。
+4. 动态列导出先查 `ExcelDynamicData` 的列、列中文名、行数据对齐。
+5. 下载文件名问题先查响应头、编码和前端取 header 逻辑。
+
+## 修改约束
+
+- 不要把 Excel 导出和普通 JSON 返回写在同一方法里混用。
+- 不要在不知道文件命名规则时硬编码中文名模板。
+- 动态列导出优先用 `ExcelDynamicData`，不要在 Controller 里手写列映射。
+
+## 按需读取
+
+- 源码索引：`references/source-index.md`
+- 注解与返回结构：`assets/RequestExcel.java`、`assets/ResponseExcel.java`、`assets/ExcelDynamicData.java`
+- MVC 解析器：`assets/RequestFastExcelArgumentResolver.java`、`assets/ResponseFastExcelReturnValueHandler.java`

package/template/.codex/skills/yss-excel-mvc/agents/openai.yaml

@@ -0,0 +1,5 @@
+version: 1
+interface:
+  display_name: "YSS Excel MVC"
+  short_description: "Excel 导入导出与 Spring MVC 接入规范"
+  default_prompt: "Use $yss-excel-mvc to implement or debug Excel import and export endpoints in Spring MVC."

package/template/.codex/skills/yss-excel-mvc/assets/ExcelDynamicData.java

@@ -0,0 +1,66 @@
+package com.yss.excel.mvc.model;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 动态Excel导出数据模型
+ *
+ * @author daomingzhu
+ * @date 2024-01-23
+ */
+public class ExcelDynamicData {
+
+    /**
+     * 列名列表（Map中的Key）
+     */
+    private List<String> columns = new ArrayList<>();
+
+    /**
+     * 列名中文列表（Excel表头）
+     */
+    private List<String> columnCn = new ArrayList<>();
+
+    /**
+     * 行数据列表
+     */
+    private List<Map<String, Object>> rows = new ArrayList<>();
+
+    /**
+     * 导出文件名（可选，优先级高于注解）
+     */
+    private String fileName;
+
+    public List<String> getColumns() {
+        return columns;
+    }
+
+    public void setColumns(List<String> columns) {
+        this.columns = columns;
+    }
+
+    public List<String> getColumnCn() {
+        return columnCn;
+    }
+
+    public void setColumnCn(List<String> columnCn) {
+        this.columnCn = columnCn;
+    }
+
+    public List<Map<String, Object>> getRows() {
+        return rows;
+    }
+
+    public void setRows(List<Map<String, Object>> rows) {
+        this.rows = rows;
+    }
+
+    public String getFileName() {
+        return fileName;
+    }
+
+    public void setFileName(String fileName) {
+        this.fileName = fileName;
+    }
+}

package/template/.codex/skills/yss-excel-mvc/assets/RequestExcel.java

@@ -0,0 +1,33 @@
+package com.yss.excel.mvc.annotation;
+
+import java.lang.annotation.*;
+
+/**
+ * 导入Excel注解
+ * 用于Controller方法参数，将上传的Excel文件解析为List对象
+ *
+ * @author daomingzhu
+ * @date 2024-01-13
+ */
+@Target(ElementType.PARAMETER)
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+public @interface RequestExcel {
+
+    /**
+     * 前端上传的文件名称，默认为 file
+     */
+    String fileName() default "file";
+
+    /**
+     * 是否忽略空行
+     */
+    boolean ignoreEmptyRow() default true;
+    boolean throwErrorData() default false;
+
+    /**
+     * 校验上传文件的原始文件名（正则表达式）
+     * 如果不匹配则抛出异常
+     */
+    String matchFilePattern() default "";
+}

package/template/.codex/skills/yss-excel-mvc/assets/RequestFastExcelArgumentResolver.java

@@ -0,0 +1,272 @@
+package com.yss.excel.mvc.handler;
+
+import com.yss.excel.mvc.annotation.RequestExcel;
+import com.yss.excel.mvc.util.ExcelUtils;
+import lombok.Setter;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.cglib.beans.BeanMap;
+import org.springframework.core.MethodParameter;
+import org.apache.fesod.sheet.annotation.ExcelProperty;
+import com.yss.excel.mvc.exception.ExcelDataValidationException;
+import org.springframework.util.MultiValueMap;
+import org.springframework.validation.BindException;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.util.StringUtils;
+import org.springframework.web.bind.support.WebDataBinderFactory;
+import org.springframework.web.context.request.NativeWebRequest;
+import org.springframework.web.method.support.HandlerMethodArgumentResolver;
+import org.springframework.web.method.support.ModelAndViewContainer;
+import org.springframework.web.multipart.MultipartFile;
+import org.springframework.web.multipart.MultipartHttpServletRequest;
+
+import javax.servlet.http.HttpServletRequest;
+import javax.validation.ConstraintViolation;
+import javax.validation.Valid;
+import javax.validation.Validator;
+import java.io.IOException;
+import java.io.InputStream;
+import java.lang.reflect.ParameterizedType;
+import java.lang.reflect.Type;
+import java.util.*;
+
+/**
+ * Excel导入参数解析器
+ *
+ * @author daomingzhu
+ * @date 2024-01-13
+ */
+@Slf4j
+public class RequestFastExcelArgumentResolver implements HandlerMethodArgumentResolver {
+
+    @Setter
+    private Validator validator;
+
+    @Override
+    public boolean supportsParameter(MethodParameter parameter) {
+        return parameter.hasParameterAnnotation(RequestExcel.class);
+    }
+
+    @Override
+    public Object resolveArgument(MethodParameter parameter, ModelAndViewContainer mavContainer,
+            NativeWebRequest webRequest, WebDataBinderFactory binderFactory) throws Exception {
+        RequestExcel requestExcel = parameter.getParameterAnnotation(RequestExcel.class);
+        HttpServletRequest request = webRequest.getNativeRequest(HttpServletRequest.class);
+        if (request == null) {
+            throw new IllegalArgumentException("HTTP request cannot be null");
+        }
+        List<InputStream> inputStreams = new ArrayList<>();
+        try {
+            if (!(request instanceof MultipartHttpServletRequest)) {
+                inputStreams.add(request.getInputStream());
+            } else {
+                MultipartHttpServletRequest multipartRequest = (MultipartHttpServletRequest) request;
+                MultiValueMap<String, MultipartFile> multipartRequestFileMap = multipartRequest.getMultiFileMap();
+                if (multipartRequestFileMap.isEmpty()) {
+                    log.warn("Uploaded file is empty for parameter: {}", parameter.getParameterName());
+                    return Collections.emptyList();
+                }
+
+                // 获取所有文件
+                multipartRequestFileMap.forEach((key, multipartFile) -> {
+                    for (MultipartFile file : multipartFile) {
+                        if (!file.isEmpty()) {
+                            // 验证文件类型
+                            validateFileType(file);
+
+                            // 校验文件名正则匹配
+                            if (StringUtils.hasText(requestExcel.matchFilePattern())) {
+                                String originalFilename = file.getOriginalFilename();
+                                if (originalFilename != null && !originalFilename.matches(requestExcel.matchFilePattern())) {
+                                    throw new IllegalArgumentException(String.format("文件名 [%s] 不匹配校验规则 [%s]", originalFilename,
+                                            requestExcel.matchFilePattern()));
+                                }
+                            }
+                            try {
+                                inputStreams.add(file.getInputStream());
+                            } catch (IOException e) {
+                                throw new RuntimeException(e);
+                            }
+                        }
+                    }
+                });
+
+                if (inputStreams.isEmpty()) {
+                    log.warn("No valid files found for parameter: {}", parameter.getParameterName());
+                    return Collections.emptyList();
+                }
+            }
+
+            Class<?> targetClass = getTargetClass(parameter);
+            if (targetClass == null) {
+                log.warn("Could not determine target class for parameter: {}", parameter.getParameterName());
+                return Collections.emptyList();
+            }
+
+            List<Object> allList = new ArrayList<>();
+            try {
+                for (InputStream is : inputStreams) {
+                    List<?> list = ExcelUtils.read(is, targetClass);
+                    if (list != null) {
+                        allList.addAll((List) list);
+                    }
+                }
+            } catch (Exception e) {
+                log.error("Failed to parse excel file for parameter: {}", parameter.getParameterName(), e);
+                throw new RuntimeException("Excel parsing failed: " + e.getMessage());
+            }
+
+            // 数据校验
+            validateIfApplicable(parameter, requestExcel.throwErrorData(), allList);
+
+            return allList;
+        } finally {
+            for (InputStream is : inputStreams) {
+                if (is != null) {
+                    try {
+                        is.close();
+                    } catch (IOException e) {
+                        log.warn("Failed to close input stream", e);
+                    }
+                }
+            }
+        }
+    }
+
+    private void validateIfApplicable(MethodParameter parameter, Boolean throwErrorData, List<?> list)
+            throws BindException {
+        if (validator == null || list == null || list.isEmpty()) {
+            return;
+        }
+
+        if (parameter.hasParameterAnnotation(Validated.class) || parameter.hasParameterAnnotation(Valid.class)) {
+            java.util.LinkedList<java.util.Map<String, Object>> errorDataList = new java.util.LinkedList<>();
+            boolean hasError = false;
+            java.util.Map<String, String> errorHeader = new java.util.LinkedHashMap<>();
+            Class<?> targetClass = getTargetClass(parameter);
+
+            // 提取表头信息
+            if (targetClass != null) {
+                java.lang.reflect.Field[] fields = targetClass.getDeclaredFields();
+                for (java.lang.reflect.Field field : fields) {
+                    ExcelProperty excelProperty = field.getAnnotation(ExcelProperty.class);
+                    if (excelProperty != null && excelProperty.value().length > 0) {
+                        errorHeader.put(field.getName(), excelProperty.value()[0]);
+                    } else {
+                        errorHeader.put(field.getName(), field.getName());
+                    }
+                }
+                errorHeader.put("errorMessage", "错误信息");
+            }
+
+            List<String> errorMessages = new ArrayList<>();
+            for (Object object : list) {
+                Set<ConstraintViolation<Object>> violations = validator.validate(object);
+                if (!violations.isEmpty()) {
+                    hasError = true;
+                    java.util.Map<String, Object> map = BeanMap.create(object);
+                    StringBuilder errorMessage = new StringBuilder();
+                    for (ConstraintViolation<Object> violation : violations) {
+                        if (errorMessage.length() > 0) {
+                            errorMessage.append("; ");
+                        }
+                        String fieldErrorName = violation.getPropertyPath().toString();
+                        if (errorHeader.containsKey(fieldErrorName)) {
+                            fieldErrorName = errorHeader.get(fieldErrorName);
+                        }
+                        errorMessage.append(fieldErrorName).append(violation.getMessage());
+                    }
+                    errorMessages.add(errorMessage.toString());
+                    map.put("errorMessage", errorMessage.toString());
+                    errorDataList.add(map);
+                }
+            }
+
+            if (!Boolean.TRUE.equals(throwErrorData)) {
+                if (hasError) {
+                    throw new IllegalArgumentException("Data validation errors: " + errorMessages);
+                }
+            } else {
+                if (hasError) {
+                    throw new ExcelDataValidationException(errorHeader, errorDataList);
+                }
+            }
+        }
+    }
+
+    /**
+     * 获取目标类型（List<T> 中的 T）
+     */
+    private Class<?> getTargetClass(MethodParameter parameter) {
+        Type type = parameter.getGenericParameterType();
+        if (type instanceof ParameterizedType) {
+            ParameterizedType parameterizedType = (ParameterizedType) type;
+            Type[] actualTypeArguments = parameterizedType.getActualTypeArguments();
+            if (actualTypeArguments != null && actualTypeArguments.length > 0) {
+                return (Class<?>) actualTypeArguments[0];
+            }
+        }
+        return null;
+    }
+
+    /**
+     * 验证上传的文件类型是否为Excel文件
+     *
+     * @param file 上传的文件
+     * @throws IllegalArgumentException 如果文件不是Excel格式
+     */
+    private void validateFileType(MultipartFile file) {
+        String fileName = file.getOriginalFilename();
+        if (fileName == null) {
+            throw new IllegalArgumentException("File name cannot be null");
+        }
+        String contentType = file.getContentType();
+        String fileExtension = getFileExtension(fileName);
+        // 检查文件扩展名和内容类型
+        boolean isValidExcel = isValidExcelExtension(fileExtension) || isValidExcelContentType(contentType);
+        if (!isValidExcel) {
+            log.warn("Invalid file type detected. File name: {}, Content type: {}", fileName, contentType);
+            throw new IllegalArgumentException(
+                    String.format("Invalid file type: %s. Only Excel files (.xls, .xlsx) are allowed.", fileName));
+        }
+    }
+
+    /**
+     * 获取文件扩展名
+     *
+     * @param fileName 文件名
+     * @return 扩展名（不包含点号）
+     */
+    private String getFileExtension(String fileName) {
+        int lastDotIndex = fileName.lastIndexOf('.');
+        if (lastDotIndex > 0 && lastDotIndex < fileName.length() - 1) {
+            return fileName.substring(lastDotIndex + 1).toLowerCase();
+        }
+        return "";
+    }
+
+    /**
+     * 检查文件扩展名是否为有效的Excel格式
+     *
+     * @param extension 文件扩展名
+     * @return 是否为有效Excel扩展名
+     */
+    private boolean isValidExcelExtension(String extension) {
+        return "xls".equals(extension) || "xlsx".equals(extension);
+    }
+
+    /**
+     * 检查内容类型是否为有效的Excel格式
+     *
+     * @param contentType 内容类型
+     * @return 是否为有效Excel内容类型
+     */
+    private boolean isValidExcelContentType(String contentType) {
+        if (contentType == null) {
+            return false;
+        }
+        return contentType.equals("application/vnd.ms-excel") ||
+                contentType.equals("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet") ||
+                contentType.startsWith("application/vnd.ms-excel") ||
+                contentType.startsWith("application/vnd.openxmlformats-officedocument.spreadsheetml");
+    }
+}

package/template/.codex/skills/yss-excel-mvc/assets/ResponseExcel.java

@@ -0,0 +1,46 @@
+package com.yss.excel.mvc.annotation;
+
+import java.lang.annotation.*;
+
+/**
+ * 导出Excel注解
+ * 用于Controller方法，将返回值导出为Excel文件
+ *
+ * @author daomingzhu
+ * @date 2024-01-13
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+public @interface ResponseExcel {
+
+    /**
+     * 导出的文件名称
+     */
+    String name() default "";
+
+    /**
+     * Sheet名称
+     */
+    String sheet() default "Sheet1";
+
+    /**
+     * 文件后缀，支持 xlsx, xls, csv
+     */
+    String suffix() default "xlsx";
+
+    /**
+     * 密码（可选）
+     */
+    String password() default "";
+    
+    /**
+     * 包含的字段（可选）
+     */
+    String[] include() default {};
+
+    /**
+     * 排除的字段（可选）
+     */
+    String[] exclude() default {};
+}

package/template/.codex/skills/yss-excel-mvc/assets/ResponseFastExcelReturnValueHandler.java

@@ -0,0 +1,154 @@
+package com.yss.excel.mvc.handler;
+
+import com.yss.excel.mvc.annotation.ResponseExcel;
+import com.yss.excel.mvc.model.ExcelDynamicData;
+import com.yss.excel.mvc.util.ExcelUtils;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.core.MethodParameter;
+import org.springframework.util.StringUtils;
+import org.springframework.web.context.request.NativeWebRequest;
+import org.springframework.web.method.support.HandlerMethodReturnValueHandler;
+import org.springframework.web.method.support.ModelAndViewContainer;
+
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+import java.lang.reflect.ParameterizedType;
+import java.lang.reflect.Type;
+import java.net.URLEncoder;
+import java.time.LocalDateTime;
+import java.time.format.DateTimeFormatter;
+import java.util.List;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/**
+ * Excel导出返回值处理器
+ *
+ * @author daomingzhu
+ * @date 2024-01-13
+ */
+@Slf4j
+public class ResponseFastExcelReturnValueHandler implements HandlerMethodReturnValueHandler {
+
+    private static final Pattern PARAM_PATTERN = Pattern.compile("\\{([^}]+)\\}");
+
+    @Override
+    public boolean supportsReturnType(MethodParameter returnType) {
+        return returnType.hasMethodAnnotation(ResponseExcel.class);
+    }
+
+    @Override
+    public void handleReturnValue(Object returnValue, MethodParameter returnType,
+            ModelAndViewContainer mavContainer, NativeWebRequest webRequest) throws Exception {
+        mavContainer.setRequestHandled(true);
+        HttpServletResponse response = webRequest.getNativeResponse(HttpServletResponse.class);
+        HttpServletRequest request = webRequest.getNativeRequest(HttpServletRequest.class);
+        ResponseExcel responseExcel = returnType.getMethodAnnotation(ResponseExcel.class);
+
+        if (response == null) {
+            return;
+        }
+
+        String fileName = responseExcel.name();
+        if (!StringUtils.hasText(fileName)) {
+            fileName = "export_" + System.currentTimeMillis();
+        } else {
+            // 解析文件名中的占位符
+            fileName = resolveFileName(fileName, request);
+        }
+
+        // 如果返回值是ExcelDynamicData且指定了文件名，则覆盖（支持POST请求动态文件名）
+        if (returnValue instanceof ExcelDynamicData) {
+            ExcelDynamicData dynamicData = (ExcelDynamicData) returnValue;
+            if (StringUtils.hasText(dynamicData.getFileName())) {
+                fileName = dynamicData.getFileName();
+            }
+        }
+
+        String suffix = responseExcel.suffix();
+        String fullFileName = fileName + "." + suffix;
+
+        response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");
+        response.setCharacterEncoding("utf-8");
+        response.setHeader("Access-Control-Expose-Headers", "Content-Disposition");
+        String encodedFileName = URLEncoder.encode(fullFileName, "UTF-8").replaceAll("\\+", "%20");
+        response.setHeader("Content-Disposition",
+                "attachment;filename=" + encodedFileName + ";filename*=utf-8''" + encodedFileName);
+
+        if (returnValue == null) {
+            return;
+        }
+
+        if (returnValue instanceof ExcelDynamicData) {
+            ExcelDynamicData dynamicData = (ExcelDynamicData) returnValue;
+            ExcelUtils.writeMap(response.getOutputStream(), dynamicData.getColumns(), dynamicData.getColumnCn(),
+                    dynamicData.getRows(), responseExcel.sheet());
+            return;
+        }
+
+        if (returnValue instanceof List) {
+            List<?> list = (List<?>) returnValue;
+            if (list.isEmpty()) {
+                // 如果为空列表，尝试获取泛型类型，写入空表头
+                Class<?> targetClass = getTargetClass(returnType);
+                if (targetClass != null) {
+                    ExcelUtils.write(response.getOutputStream(), (Class) targetClass, (List) list,
+                            responseExcel.sheet());
+                }
+                return;
+            }
+
+            Class<?> clazz = list.get(0).getClass();
+            ExcelUtils.write(response.getOutputStream(), (Class) clazz, (List) list, responseExcel.sheet());
+        }
+    }
+
+    /**
+     * 解析文件名中的占位符
+     * 支持格式：
+     * {paramName} - 请求参数
+     * {yyyyMMdd} - 当前日期格式化
+     */
+    private String resolveFileName(String fileName, HttpServletRequest request) {
+        if (!StringUtils.hasText(fileName)) {
+            return fileName;
+        }
+
+        Matcher matcher = PARAM_PATTERN.matcher(fileName);
+        StringBuffer sb = new StringBuffer();
+        while (matcher.find()) {
+            String key = matcher.group(1);
+            String replacement = "";
+            // 尝试作为日期格式解析
+            try {
+                replacement = LocalDateTime.now().format(DateTimeFormatter.ofPattern(key));
+            } catch (Exception e) {
+                // 不是日期格式，尝试从请求参数获取
+                if (request != null) {
+                    String paramValue = request.getParameter(key);
+                    if (paramValue != null) {
+                        replacement = paramValue;
+                    }
+                }
+            }
+            matcher.appendReplacement(sb, Matcher.quoteReplacement(replacement));
+        }
+        matcher.appendTail(sb);
+        return sb.toString();
+    }
+
+    /**
+     * 获取目标类型（List<T> 中的 T）
+     */
+    private Class<?> getTargetClass(MethodParameter parameter) {
+        Type type = parameter.getGenericParameterType();
+        if (type instanceof ParameterizedType) {
+            ParameterizedType parameterizedType = (ParameterizedType) type;
+            Type[] actualTypeArguments = parameterizedType.getActualTypeArguments();
+            if (actualTypeArguments != null && actualTypeArguments.length > 0) {
+                return (Class<?>) actualTypeArguments[0];
+            }
+        }
+        return null;
+    }
+}

package/template/.codex/skills/yss-excel-mvc/references/README.md

@@ -0,0 +1,5 @@
+# 相关引用
+
+- 注解：[RequestExcel.java](../assets/RequestExcel.java) / [ResponseExcel.java](../assets/ResponseExcel.java)
+- 处理器：[RequestFastExcelArgumentResolver.java](../assets/RequestFastExcelArgumentResolver.java) / [ResponseFastExcelReturnValueHandler.java](../assets/ResponseFastExcelReturnValueHandler.java)
+- 动态模型：[ExcelDynamicData.java](../assets/ExcelDynamicData.java)