create-yss-spec 2.1.10 → 2.1.11

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