create-yss-spec 3.3.0 → 3.3.3

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

@@ -1,66 +0,0 @@
----
-name: yss-excel-mvc
-description: Use when 用于 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-skill-source-index-refresh/references/source-location.md` 定位。
-- 当前技能索引：`references/source-index.md`
-- 重点源码入口通常包括 `RequestExcel`、`ResponseExcel`、`ExcelDynamicData`、参数解析器、返回值处理器、starter 配置。
-
-当组件源码变化后，用 `yss-skill-source-index-refresh` 刷新索引；刷新或读取前先按源码定位策略确认真实位置。
-
-## 常见实现路径
-
-- 导入：`@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/.qoder/skills/yss-excel-mvc/agents/openai.yaml

@@ -1,5 +0,0 @@
-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/.qoder/skills/yss-excel-mvc/assets/ExcelDynamicData.java

@@ -1,66 +0,0 @@
-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/.qoder/skills/yss-excel-mvc/assets/RequestExcel.java

@@ -1,33 +0,0 @@
-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/.qoder/skills/yss-excel-mvc/assets/RequestFastExcelArgumentResolver.java

@@ -1,272 +0,0 @@
-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/.qoder/skills/yss-excel-mvc/assets/ResponseExcel.java

@@ -1,46 +0,0 @@
-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/.qoder/skills/yss-excel-mvc/assets/ResponseFastExcelReturnValueHandler.java

@@ -1,154 +0,0 @@
-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/.qoder/skills/yss-excel-mvc/references/README.md

@@ -1,5 +0,0 @@
-# 相关引用
-
-- 注解：[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)