create-yss-spec 2.1.10 → 2.1.13

package/template/.cursor/skills/yss-dto/references/README.md

@@ -0,0 +1,67 @@
+# 参考资料
+
+本文档详细介绍了 `yss-component-dto` 组件的核心数据传输对象（DTO）。这些 DTO 类被广泛应用于各个服务项目，用于规范数据交互格式。公开 HTTP/JSON 的可复用映射以 `openapi-wire-profile.yaml` 为准；本文不把 Java 字段或 getter 自动等同于 wire shape。
+
+## 核心类 (Core Classes)
+
+### 1. Result.java
+
+**位置**: `../assets/Result.java`
+
+通用响应包装类，用于统一 API 接口的返回格式。
+
+**核心字段**:
+
+- `success`: 操作是否成功 (boolean)
+- `code`: Java 内部类型为 `Object`；公开 wire contract 仅允许 `string | integer | null`
+- `message`: 消息描述 (String, 默认 "数据返回正常")
+- `dataType`: 返回数据格式
+- `tips`: 提示消息
+
+**常用静态方法**:
+
+- `buildSuccess()`: 构建成功响应
+- `buildSuccess(String message)`: 构建带消息的成功响应
+- `buildFailure(String message)`: 构建失败响应
+- `buildFailure(String errCode, String message)`: 构建带错误码的失败响应
+
+### 2. PageQuery.java
+
+**位置**: `../assets/PageQuery.java`
+
+分页查询基础类，所有需要分页的查询参数都应继承此类。
+
+**核心字段**:
+
+- `pageIndex`: 当前页码 (默认 1)
+- `pageSize`: 每页条数 (默认 10)
+- `orderBy`: 排序字段
+- `orderDirection`: 排序方向 (ASC/DESC, 默认 DESC)
+- `tempTotalCount`: 临时总数字段（由分页插件回填）
+
+**功能**:
+
+- 提供了链式调用的 Setter 方法 (`setPageIndex`, `setPageSize` 等)。
+- 自动计算偏移量 `getOffset()`。
+
+## HTTP/JSON 映射边界
+
+- 新契约使用 `com.yss.cloud.dto.result`；`com.yss.cloud.dto.response` 只作为 legacy / compatibility 线索。
+- 公共响应 schema 使用 `YssResultMeta`，具体 endpoint schema 使用 `allOf` 组合，并声明 `x-yss-response-wrapper`。
+- `MultiResult.data` 和 `PageResult.data` 为数组；`SingleResult.data` 绑定具体 endpoint schema。不要把 `SingleResult<T>`、`MultiResult<T>` 或 `PageResult<T>` 的 Java 泛型文字直接写成 OpenAPI schema。
+- `PageQuery` 的客户端字段是 `pageIndex/pageSize/orderBy/orderDirection/groupBy`；`offset`、`needTotalCount`、`tempTotalCount` 不属于客户端输入。`totalPages` 只有目标 mapper / contract evidence 证明后才进入响应契约。
+
+### 3. CommandDTO.java & QueryDTO.java
+
+**位置**: `../assets/CommandDTO.java`, `../assets/QueryDTO.java`
+
+基础 DTO 抽象类，用于区分命令（写操作）和查询（读操作）对象。
+
+- **CommandDTO**: 实现 `Serializable` 接口，所有命令参数应继承此类。
+- **QueryDTO**: 继承自 `CommandDTO`，所有查询参数应继承此类。
+
+## 使用场景
+
+1. **API 响应**: 所有 Controller 方法应返回 `Result` 或其子类（如 `PageResult`, `SingleResult`）。
+2. **分页查询**: Controller 接收分页请求时，参数类应继承 `PageQuery`。MyBatis 分页插件会自动识别并处理。
+3. **参数封装**: 使用 `CommandDTO` 封装增删改参数，使用 `QueryDTO` 封装查询参数，保持代码语义清晰。

package/template/.cursor/skills/yss-dto/references/openapi-wire-profile.yaml

@@ -0,0 +1,181 @@
+schema_version: 1
+kind: yss-dto-openapi-wire-profile
+
+# This profile is the reusable mapping source consumed by the OpenAPI skills.
+# It describes the public HTTP/JSON shape, not every Java field or getter.
+canonical:
+  java_package: com.yss.cloud.dto.result
+  type_parameter:
+    name: T
+    java_bound: java.io.Serializable
+  openapi:
+    response_meta_schema: YssResultMeta
+    concrete_schema_composition: allOf
+    response_wrapper_extension: x-yss-response-wrapper
+    literal_java_generic_schema: false
+
+compatibility_packages:
+  - java_package: com.yss.cloud.dto.response
+    status: legacy-or-compatibility
+    use_for_new_contracts: false
+    policy: do-not-introduce-in-new-contracts
+
+common_response:
+  schema_name: YssResultMeta
+  fields:
+    success:
+      direction: response
+      wire_types: [boolean]
+      nullable: false
+      required: true
+    dataType:
+      direction: response
+      wire_types: [string, "null"]
+      nullable: true
+      required: true
+    code:
+      direction: response
+      wire_types: [string, integer, "null"]
+      nullable: true
+      required: true
+      policy: do-not-widen-global-wrapper
+    message:
+      direction: response
+      wire_types: [string, "null"]
+      nullable: true
+      required: true
+    tips:
+      direction: response
+      wire_types: [string, "null"]
+      nullable: true
+      required: true
+
+wrappers:
+  SingleResult:
+    java_type: com.yss.cloud.dto.result.SingleResult<T>
+    response_kind: single
+    data:
+      direction: response
+      wire_shape: endpoint-schema-or-null
+      nullable: true
+      required: true
+  MultiResult:
+    java_type: com.yss.cloud.dto.result.MultiResult<T>
+    response_kind: non-page-list
+    data:
+      direction: response
+      wire_types: [array]
+      items: endpoint-schema
+      nullable: false
+      required: true
+      empty_value: []
+  PageResult:
+    java_type: com.yss.cloud.dto.result.PageResult<T>
+    response_kind: page
+    fields:
+      totalCount:
+        direction: response
+        wire_types: [integer]
+        format: int64
+        minimum: 0
+        nullable: false
+        required: true
+      pageSize:
+        direction: response
+        wire_types: [integer]
+        format: int32
+        minimum: 1
+        nullable: false
+        required: true
+      pageIndex:
+        direction: response
+        wire_types: [integer]
+        format: int32
+        minimum: 1
+        nullable: false
+        required: true
+      data:
+        direction: response
+        wire_types: [array]
+        items: endpoint-schema
+        nullable: false
+        required: true
+        empty_value: []
+    computed_fields:
+      totalPages:
+        java_getter: getTotalPages
+        status: mapper-dependent
+        policy: include-only-with-target-wire-evidence
+
+page_query:
+  java_type: com.yss.cloud.dto.page.PageQuery
+  request_direction: query
+  fields:
+    pageIndex:
+      direction: request
+      wire_types: [integer]
+      format: int32
+      minimum: 1
+      default: 1
+      nullable: false
+      required: false
+    pageSize:
+      direction: request
+      wire_types: [integer]
+      format: int32
+      minimum: 1
+      default: 10
+      nullable: false
+      required: false
+    orderBy:
+      direction: request
+      wire_types: [string, "null"]
+      nullable: true
+      required: false
+      policy: endpoint-whitelist-required
+    orderDirection:
+      direction: request
+      wire_types: [string]
+      enum: [ASC, DESC]
+      default: DESC
+      nullable: false
+      required: false
+    groupBy:
+      direction: request
+      wire_types: [string, "null"]
+      nullable: true
+      required: false
+      policy: endpoint-whitelist-required
+  forbidden_client_fields:
+    - offset
+    - needTotalCount
+    - tempTotalCount
+  computed_fields:
+    offset:
+      java_getter: getOffset
+      status: computed
+      policy: exclude-from-client-input
+    needTotalCount:
+      java_getter: isNeedTotalCount
+      status: internal-or-ignored
+      policy: exclude-from-client-input
+    tempTotalCount:
+      java_getter: getTempTotalCount
+      status: internal-or-ignored
+      policy: exclude-from-client-input
+
+request_bases:
+  command:
+    java_type: com.yss.cloud.dto.CommandDTO
+    direction: request
+  query:
+    java_type: com.yss.cloud.dto.QueryDTO
+    direction: request
+    extends: command
+
+wire_evidence:
+  required_before_freeze:
+    - target-http-mapper-identity
+    - representative-serialization-fixtures
+    - contract-test-or-equivalent-http-evidence
+  rule: Java fields and computed getters are not public wire facts until target-boundary evidence confirms them.

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

@@ -0,0 +1,55 @@
+# yss-dto 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-dto` (existed when indexed)
+
+## Documentation Files
+
+- `yss-microservice-components/yss-component-dto/readme.md`
+
+## Maven Modules
+
+- `yss-microservice-components/yss-component-dto`
+
+## Key Java Entry Points
+
+- `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/SystemIdEnum.java`
+- `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/cache/CacheKey.java`
+- `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/cache/CacheKeyCode.java`
+- `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/cache/CacheType.java`
+- `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/CommandDTO.java`
+- `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/QueryDTO.java`
+- `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/audit/message/AuditMessage.java`
+- `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/audit/message/AuditOperationType.java`
+- `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/audit/message/AuditResourceType.java`
+- `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/audit/message/EventMessage.java`
+- `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/page/PageQuery.java`
+- `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/page/PageRequestFactory.java`
+- `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/response/MultiResult.java`
+- `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/response/PageResult.java`
+- `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/response/Result.java`
+- `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/response/SingleResult.java`
+- `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/result/MultiResult.java`
+- `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/result/PageResult.java`
+- `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/result/Result.java`
+- `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/result/SingleResult.java`
+- `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/support/DicMapUtil.java`
+- `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/upload/FileInfo.java`
+- `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/user/UserInfo.java`
+- `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/sankuai/GenerationTypeSeq.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-excel-mvc/SKILL.md

@@ -0,0 +1,66 @@
+---
+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-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/.cursor/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/.cursor/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/.cursor/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 "";
+}