create-yss-spec 2.2.10 → 3.0.1

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

@@ -1,67 +0,0 @@
-# 参考资料
-
-本文档详细介绍了 `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 映射边界
-
-- 新 Target Profile 只使用 `com.yss.cloud.dto.result`；`com.yss.cloud.dto.response` 为 `unsupported`，不得由新契约或脚手架引入，也不自动迁移旧项目。
-- 公共响应 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. **分页查询**: `PageQuery` 用于 Application/Infrastructure 内部协作；公开 HTTP Page Request 默认只声明冻结 OpenAPI 允许的字段，再由 WebConvertor 转换，避免内部字段被继承到绑定面。MyBatis 拦截器所需形状必须由 Query Port 集成测试证明。
-3. **参数封装**: 使用 `CommandDTO` 封装增删改参数，使用 `QueryDTO` 封装查询参数，保持代码语义清晰。

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

@@ -1,181 +0,0 @@
-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
-
-unsupported_packages:
-  - java_package: com.yss.cloud.dto.response
-    status: unsupported
-    use_for_new_contracts: false
-    policy: reject-in-new-contracts-no-auto-migration
-
-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/.hermes/skills/yss-dto/references/source-index.md

@@ -1,55 +0,0 @@
-# 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/.hermes/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-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/.hermes/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/.hermes/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/.hermes/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 "";
-}