create-yss-spec 2.1.10 → 2.1.13

package/template/.cursor/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/.cursor/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/.cursor/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/.cursor/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)

package/template/.cursor/skills/yss-excel-mvc/references/source-index.md

@@ -0,0 +1,74 @@
+# yss-excel-mvc Source Index
+
+Generated: 2026-08-17T12:03:37.436Z
+Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
+Source worktree: `dirty`
+Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
+
+This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
+
+Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using `YSS_SOURCE_ROOT`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.
+
+## Component Path Hints
+
+- `yss-microservice-components/yss-component-excel-mvc` (existed when indexed)
+- `yss-microservice-components/yss-component-excel-starter` (existed when indexed)
+
+## Documentation Files
+
+- `yss-microservice-components/yss-component-excel-mvc/README.md`
+
+## Maven Modules
+
+- `yss-microservice-components/yss-component-excel-mvc`
+- `yss-microservice-components/yss-component-excel-starter`
+
+## Key Java Entry Points
+
+- `yss-microservice-components/yss-component-excel-mvc/src/main/java/com/yss/excel/mvc/annotation/EnableExcelMvc.java`
+- `yss-microservice-components/yss-component-excel-mvc/src/main/java/com/yss/excel/mvc/annotation/RequestExcel.java`
+- `yss-microservice-components/yss-component-excel-mvc/src/main/java/com/yss/excel/mvc/annotation/ResponseExcel.java`
+- `yss-microservice-components/yss-component-excel-mvc/src/main/java/com/yss/excel/mvc/config/FastExcelAutoConfiguration.java`
+- `yss-microservice-components/yss-component-excel-mvc/src/main/java/com/yss/excel/mvc/exception/ExcelDataValidationData.java`
+- `yss-microservice-components/yss-component-excel-mvc/src/main/java/com/yss/excel/mvc/exception/ExcelDataValidationException.java`
+- `yss-microservice-components/yss-component-excel-mvc/src/main/java/com/yss/excel/mvc/exception/ExcelMvcExceptionHandler.java`
+- `yss-microservice-components/yss-component-excel-mvc/src/main/java/com/yss/excel/mvc/handler/RequestFastExcelArgumentResolver.java`
+- `yss-microservice-components/yss-component-excel-mvc/src/main/java/com/yss/excel/mvc/handler/ResponseFastExcelReturnValueHandler.java`
+- `yss-microservice-components/yss-component-excel-mvc/src/main/java/com/yss/excel/mvc/model/ExcelDynamicData.java`
+- `yss-microservice-components/yss-component-excel-mvc/src/main/java/com/yss/excel/mvc/util/ExcelUtils.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/ExcelAutoConfiguration.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/ExcelControlProperties.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/ExcelDataRequest.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/ExcelResolverConfiguration.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/annotation/EnableExcelControl.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/annotation/ExcelDynamicSelect.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/annotation/ExcelMeta.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/annotation/ExcelNotation.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/annotation/ExcelSelected.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/annotation/RequestExcel.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/annotation/ResponseExcel.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/aop/DynamicExcelAspect.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/handler/DynamicEasyHandler.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/handler/ExcelCellWidthStyleStrategy.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/handler/RequestExcelArgumentResolver.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/handler/ResponseExcelReturnHandler.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/handler/SelectedSheetWriteHandler.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/handler/TitleHandler.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/handler/WorkbookExcelWriteBuilder.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/model/ExcelComment.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/model/ExcelGeneralData.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/model/ExcelMetaData.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/model/ExcelSelectedResolve.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/model/RowValidationInfo.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/model/excel/CellType.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/model/excel/ExcelCellStyle.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/model/excel/ExcelColHeader.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/model/excel/ExcelDisabled.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/processor/DynamicEasyExcelProcessor.java`
+- `yss-microservice-components/yss-component-excel-starter/src/main/java/com/yss/cloud/excel/processor/ExcelStyleParseProcessor.java`
+
+## Recommended Next Reads
+
+- Start with the documentation files above when learning component usage.
+- Search the key Java entry points for annotations, auto configuration, properties, aspects, interceptors, handlers, and result objects before changing application code.
+- Prefer existing component extension points over rewriting framework logic in business modules.

package/template/.cursor/skills/yss-exception/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: yss-exception
+description: Use when 用于 YSS exception 组件、统一异常模型、异常处理、错误码和异常 starter 接入排障。
+---
+
+# yss-exception
+
+Use this skill for YSS 异常组件. Keep implementation grounded in the local project and resolvable YSS backend component source.
+
+中文说明：本技能用于 YSS 异常组件。执行时优先读取源码索引，避免凭记忆猜类名、配置项或接入方式。
+
+## Source Index First
+
+- Backend source location is environment-specific; resolve it with `yss-source-index/references/source-location.md`.
+- Generated index: `references/source-index.md`
+- Component path hints: `yss-microservice-components/yss-component-exception`
+
+Read `references/source-index.md` as a path-hint index whenever the task depends on exact modules, annotations, auto configuration, properties, controllers, clients, repositories, DTOs, handlers, or troubleshooting.
+
+## Workflow
+
+1. Read `references/source-index.md`, then read `readme.md` before changing exception behavior.
+2. Classify the failure as business exception, known system exception, or unknown exception.
+3. Use `ExceptionFactory` and `ResultErrorCode` conventions instead of ad-hoc runtime exceptions when creating YSS component errors.
+4. Check `YssGlobalExceptionProperties` when global exception output/logging behavior is configurable.
+5. Keep logging semantics aligned: business exceptions usually do not require error-stack logging; system/unknown exceptions usually do.
+
+## Current Source Behavior
+
+- `GlobalExceptionAdvice` currently maps BizException, unknown Exception, and RuntimeException to HTTP 400; the OpenAPI error contract must reflect or deliberately override that behavior.
+- The current RuntimeException handler returns `exception.getLocalizedMessage()` for many runtime failures; treat that as a response-information-leak risk and do not copy it into new APIs without an approved, sanitized error mapping.
+- `yss.exception.level` only controls a direct `printStackTrace()` branch when its value is exactly `debug`; it is not a general response-format switch.
+- Validation binding failures currently become `SysException(PARAM_VALIDATION_ERROR)`. Coordinate changes with `yss-validation` and contract tests.
+
+## Source-Backed Exception Semantics
+
+- `BizException`: clear business meaning, generally no Error log and no retry.
+- `SysException`: known system problem, Error log, retry may be possible.
+- unknown `Exception`: full stack log, retry may be possible.
+
+## Checklist
+
+- Required dependency or starter module is present.
+- Error code/message are meaningful to API consumers.
+- Response messages are sanitized and do not expose raw RuntimeException or localized exception details.
+- Business validation failures are not reported as unknown system errors.
+- Stack traces are preserved for unknown/system failures.
+- Retry guidance matches exception type.
+- Known system failures use `ExceptionFactory.sysException(..., cause)`; Application code does not replace them with ad-hoc `RuntimeException`.
+
+## Do Not
+
+- Do not invent class names or configuration keys without checking the source index.
+- Do not replace component extension points with business-local framework code.
+- Do not broaden the task into unrelated YSS components unless the user asks.

package/template/.cursor/skills/yss-exception/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "yss-exception"
+  short_description: "YSS component skill for yss-exception"
+  default_prompt: "Use yss-exception for this YSS backend component task."

package/template/{.agents/skills/yss-log → .cursor/skills/yss-exception}/references/source-index.md

@@ -1,4 +1,4 @@
-# yss-log Source Index
+# yss-exception Source Index
 
 Generated: 2026-08-17T12:03:37.436Z
 Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
@@ -11,21 +11,22 @@ Paths below are source path hints captured at refresh time. If they do not exist
 
 ## Component Path Hints
 
-- `yss-microservice-components/yss-component-log-starter` (existed when indexed)
+- `yss-microservice-components/yss-component-exception` (existed when indexed)
 
 ## Documentation Files
 
-- `yss-microservice-components/yss-component-log-starter/README.md`
+- `yss-microservice-components/yss-component-exception/readme.md`
 
 ## Maven Modules
 
-- `yss-microservice-components/yss-component-log-starter`
+- `yss-microservice-components/yss-component-exception`
 
 ## Key Java Entry Points
 
-- `yss-microservice-components/yss-component-log-starter/src/main/java/com/yss/cloud/log/CatchAndLog.java`
-- `yss-microservice-components/yss-component-log-starter/src/main/java/com/yss/cloud/log/CatchLogAspect.java`
-- `yss-microservice-components/yss-component-log-starter/src/main/java/com/yss/cloud/log/CatchLogAutoConfiguration.java`
+- `yss-microservice-components/yss-component-exception/src/main/java/com/yss/cloud/exception/ExceptionFactory.java`
+- `yss-microservice-components/yss-component-exception/src/main/java/com/yss/cloud/exception/ResultErrorCode.java`
+- `yss-microservice-components/yss-component-exception/src/main/java/com/yss/cloud/exception/YssGlobalExceptionProperties.java`
+- `yss-microservice-components/yss-component-exception/src/main/java/com/yss/cloud/exception/advice/GlobalExceptionAdvice.java`
 
 ## Recommended Next Reads