create-yss-spec 2.1.9 → 2.1.11

package/template/.cursor/skills/yss-distributed-id/references/README.md

@@ -0,0 +1,51 @@
+# 参考资料
+
+本文档详细介绍了 `yss-component-distributed-id` 框架的核心组件和实现原理。
+
+## 核心类 (Core Classes)
+
+### 1. AutoIdInterceptor.java
+**位置**: `../assets/AutoIdInterceptor.java`
+
+MyBatis 拦截器，是实现自动 ID 注入的核心。
+
+**拦截逻辑**:
+- **拦截点**: `StatementHandler.prepare` 方法。
+- **判断条件**: 仅拦截 `INSERT` 语句。
+- **处理流程**:
+  1. 获取 SQL 绑定的参数对象 (`parameterObject`)。
+  2. 支持处理单对象、`List`、`Array` 和 `Map` (MyBatis 多参数封装)。
+  3. 遍历参数对象的实体类，检查是否有 `@Entity` (JPA) 或 `@TableName` (MP) 注解。
+  4. 扫描实体字段，查找 `@GeneratedValue` 或 `@TableId` 注解。
+  5. 根据注解指定的策略 (`segment`, `snowflake`, `cosid_segment` 等)，调用对应的 ID 生成器获取 ID。
+  6. 通过反射将 ID 设置到实体的相应字段中。
+
+### 2. EnableDistributedId.java
+**位置**: `../assets/EnableDistributedId.java`
+
+开启分布式 ID 功能的注解。
+
+**属性**:
+- `autoRegister`: 是否自动注册配置，默认为 `true`。
+- `cosid`: 是否开启 CosId 模式，默认为 `false` (即默认使用 Leaf 模式)。
+
+**作用**:
+- 导入 `LeafDataSourceConfiguration` 和 `EnableDistributedImportSelector`，从而根据配置加载相应的 Bean。
+
+### 3. LeafConf.java
+**位置**: `../assets/LeafConf.java`
+
+Leaf 模式的配置类，对应 `spring.leaf` 配置项。
+
+**属性**:
+- `leafSegmentEnable`: 是否开启号段模式。
+- `leafSnowflakeEnable`: 是否开启雪花算法模式。
+
+## ID 生成策略详解
+
+| 策略名称 | 依赖组件 | 描述 | 适用场景 |
+| :--- | :--- | :--- | :--- |
+| **Leaf Segment** | DB (MySQL) | 基于数据库号段，每次从 DB 获取一个号段到内存，高性能，ID 趋势递增。 | 大多数业务场景，高可用要求高。 |
+| **Leaf Snowflake** | Zookeeper | 基于 Twitter 雪花算法，依赖 ZK 进行 WorkerID 管理。 | 对 ID 生成速度要求极高，且不依赖 DB 的场景。 |
+| **CosId Segment** | DB (MySQL) | CosId 的号段模式实现，支持更丰富的配置（如步长动态调整）。 | 需要 CosId 特性或作为 Leaf 的替代方案。 |
+| **UUID** | JDK | 标准 UUID。 | 无需有序、不关心存储空间的场景。 |

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

@@ -0,0 +1,86 @@
+# yss-distributed-id 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-distributed-id` (existed when indexed)
+- `yss-microservice-components/yss-component-leaf` (existed when indexed)
+
+## Documentation Files
+
+- `yss-microservice-components/yss-component-distributed-id/readme.md`
+- `yss-microservice-components/yss-component-leaf/README.md`
+- `yss-microservice-components/yss-component-leaf/TECHNICAL_DESIGN.md`
+
+## Maven Modules
+
+- `yss-microservice-components/yss-component-distributed-id`
+- `yss-microservice-components/yss-component-leaf`
+- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-feign`
+- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc-lib`
+- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc`
+- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-rest`
+
+## Key Java Entry Points
+
+- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/EnableDistributedId.java`
+- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/EnableDistributedImportSelector.java`
+- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/ApplicationContextHelper.java`
+- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/SegmentContextHelper.java`
+- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/SnowflakeContextHelper.java`
+- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/config/DistributedIdInjectionModeGuard.java`
+- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/config/DistributedIdProperties.java`
+- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/config/LeafConf.java`
+- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/config/LeafDataSourceConfiguration.java`
+- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/config/LeafDatabaseType.java`
+- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/config/LeafSegmentProperties.java`
+- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/config/MissingTagPolicy.java`
+- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/config/SnowflakeProperties.java`
+- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/exception/LeafIdErrorCode.java`
+- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/exception/LeafIdException.java`
+- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/exception/LeafServerException.java`
+- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/health/LeafSegmentHealth.java`
+- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/inf/leaf/common/PropertyFactory.java`
+- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/inf/leaf/common/Result.java`
+- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/inf/leaf/common/Status.java`
+- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/inf/leaf/segment/dao/IDAllocMapper.java`
+- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/inf/leaf/segment/model/LeafAlloc.java`
+- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/inf/leaf/snowflake/SnowflakeNodeIdentity.java`
+- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/inf/leaf/snowflake/SnowflakeNodeIdentityResolver.java`
+- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/metrics/LeafSegmentMetrics.java`
+- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/mybatis/AutoIdInterceptor.java`
+- `yss-microservice-components/yss-component-distributed-id/src/main/java/com/yss/cloud/sankuai/mybatis/DistributedIdIdentifierGenerator.java`
+- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-feign/src/main/java/com/yss/cloud/leaf/conf/YssCloudLeafAutoConfiguration.java`
+- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-feign/src/main/java/com/yss/cloud/leaf/context/RestGenIdContextHelper.java`
+- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-feign/src/main/java/com/yss/cloud/leaf/feign/YssIdGenFeign.java`
+- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-feign/src/main/java/com/yss/cloud/leaf/mybatis/FeignAutoIdInterceptor.java`
+- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc-lib/src/main/java/com/yss/cloud/grpc/protobuf/GenerateUniqueIdRequest.java`
+- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc-lib/src/main/java/com/yss/cloud/grpc/protobuf/GenerateUniqueIdRequestOrBuilder.java`
+- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc-lib/src/main/java/com/yss/cloud/grpc/protobuf/GenerateUniqueIdResponse.java`
+- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc-lib/src/main/java/com/yss/cloud/grpc/protobuf/GenerateUniqueIdResponseOrBuilder.java`
+- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc-lib/src/main/java/com/yss/cloud/grpc/protobuf/IdGenType.java`
+- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc-lib/src/main/java/com/yss/cloud/grpc/protobuf/UniqueIdProto.java`
+- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc-lib/src/main/java/com/yss/cloud/grpc/protobuf/UniqueIdServiceGrpc.java`
+- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc-lib/src/main/java/com/yss/cloud/leaf/context/GrpcClientService.java`
+- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc-lib/src/main/java/com/yss/cloud/leaf/context/GrpcGenIdContextHelper.java`
+- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc/src/main/java/com/yss/cloud/leaf/conf/YssCloudLeafAutoConfiguration.java`
+- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc/src/main/java/com/yss/cloud/leaf/service/UniqueIdService.java`
+- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-rest/src/main/java/com/yss/cloud/leaf/conf/YssLeafRestConfiguration.java`
+- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-rest/src/main/java/com/yss/cloud/leaf/controller/IdGenController.java`
+- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-rest/src/main/java/com/yss/cloud/leaf/controller/LeafIdRestResponseFactory.java`
+- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-rest/src/main/java/com/yss/cloud/leaf/health/LeafSegmentHealthIndicator.java`
+- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-rest/src/main/java/com/yss/cloud/leaf/health/LeafSnowflakeHealthIndicator.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-domain/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: yss-domain
+description: 用于构建或重构 YSS 领域层代码。当用户要求设计聚合、Entity、Domain Gateway、领域规则、状态流转或先做领域建模再补持久层时调用。
+---
+
+# yss-domain
+
+这是一个建模型 skill。核心目标是先把领域语义和边界建立清楚，再落代码。
+
+默认输出是新 DDD target profile；现有 YSS 组件仓库常见 `core/client/repository`、贫血对象和 VO 型 Gateway 只是 legacy profile，不得静默复制成新模块架构。
+
+## 何时使用
+
+- 用户要求先做 Domain、先抽象实体或聚合。
+- 用户要补 `Entity`、`Gateway`、领域规则或状态机。
+- 用户给出页面流程、业务规则、DDL，希望先沉淀领域模型。
+
+## 不适用
+
+- 只生成持久层时，优先 `yss-repository`。
+- 只生成 Controller 时，优先 `yss-web-controller`。
+- 只初始化项目骨架时，优先 `yss-ddd-scaffold-generator`。
+
+## 工作方式
+
+1. 先抽业务术语、聚合边界和状态变化。
+2. 数据库字段只做补充，不直接决定领域对象结构。
+3. 先定义领域行为，再决定 Gateway 边界。
+4. 规则不清晰时，保留显式假设，不要静默猜测。
+
+## 产物范围
+
+- `domain/{segment}/model/*Entity.java`
+- `domain/{segment}/gateway/*Gateway.java`
+- DTO/VO 属于 client/web 契约，转交 `yss-dto` / `yss-web-controller`；Domain skill 不顺带生成。
+
+## 建模约束
+
+- Domain 层不依赖 Repository、Mapper、Controller。
+- 领域行为放在模型方法，不要放在 Web 层。
+- Gateway 只暴露领域能力，不暴露持久化细节。
+- 对关键状态流转给出明确方法，如 `publish()`、`cancel()`、`terminate()`。
+- 明确 Aggregate Root、Entity identity、Value Object、不变量、Domain Event 和一致性边界；没有业务行为时不要伪造富领域模型。
+- 发现 legacy profile 时先记录迁移/兼容决策，不把 Repository Entity 当 Domain Entity。
+
+## 质量要求
+
+- 命名体现业务语义，不照抄表名缩写。
+- 生成代码应可编译，且没有跨层依赖泄漏。
+- 对不确定规则写出假设或 TODO，不要伪装成已确认事实。
+
+## 协同顺序
+
+- 需要用例编排时，再接 `yss-application`
+- 需要持久层时，再接 `yss-repository`
+- 需要 Web 层时，再接 `yss-web-controller`
+- 需要完整工程时，先 `yss-ddd-scaffold-generator`
+
+## 分层开发规范
+
+脚手架生成或进入 Domain 实现前，必须加载 `references/domain-layer-guide.md`：其中定义 DTO/Gateway/Domain Service 包结构、命名、校验与示例，与本 skill 的建模约束一并生效。
+
+## 阶段 7 合同
+
+- 只消费生命周期已批准的 `Slice Implementation Contract` 和当前 `work_unit`；不得扩大 `allowed_write_paths`。
+- 领域规则、状态机和不变量必须使用 `behavior-tdd`，先形成失败测试，再实现最小行为。
+- 完成后按 `yss-router/references/yss-skill-execution-result.md` 返回统一 `YSS Skill Execution Result`：changed files、领域/测试证据、实际验证结果、偏离和新增影响。
+- 发现新 API、权限、状态机、数据模型或架构影响时填入 `new_impacts` 并暂停，不得静默扩张切片。

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

@@ -0,0 +1,5 @@
+version: 1
+interface:
+  display_name: "YSS Domain"
+  short_description: "领域建模、聚合根、规则与网关设计实践落地标准化规范"
+  default_prompt: "Use $yss-domain to design aggregates, entities, domain gateways, and business rules for a YSS domain model."

package/template/{.hermes/skills/yss-backend-scaffold-domain/SKILL.md → .cursor/skills/yss-domain/references/domain-layer-guide.md}

@@ -1,10 +1,3 @@
----
-name: "yss-backend-scaffold-domain"
-description: "YSS 管理服务领域层的脚手架和最佳实践。在实现业务逻辑、定义数据网关或创建领域模型时调用。"
----
-
-# Domain 层开发规范 (Domain Layer Development Guide)
-
 本 Skill 提供了 YSS 数据质量管理服务 **Domain (领域层)** 的开发规范。Domain 层是系统的核心，包含业务逻辑、领域模型和接口定义。
 
 ## 1. 核心职责 (Core Responsibilities)

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

@@ -0,0 +1,86 @@
+---
+name: yss-dto
+description: Use when YSS `Result`, `SingleResult`, `MultiResult`, `PageResult`, `PageQuery`, `CommandDTO`, `QueryDTO`, pagination, or response-wrapper compatibility is involved.
+---
+
+# yss-dto
+
+用于处理 `yss-component-dto` 的使用规范和代码接入。
+
+本 skill 同时负责把中台 DTO 映射到公开 HTTP/JSON 边界。`references/openapi-wire-profile.yaml` 是可复用的机器可读映射源；OpenAPI 治理和 Draft Review 必须消费它，不得各自复制一份 wrapper 或分页字段表。
+
+## 何时使用
+
+- 用户要定义新的分页查询对象。
+- 用户要统一接口返回结构。
+- 用户提到 `Result`、`PageQuery`、`CommandDTO`、`QueryDTO`。
+- 用户在排查分页参数、返回结构或 DTO 继承不一致问题。
+
+## 工作方式
+
+1. 优先沿用项目现有 DTO 体系，不重复造返回包装类。
+2. 涉及真实类名、返回结构、分页字段或排障时，先读 `references/source-index.md`，再定位源码或文档。
+3. 先确认当前项目用的是哪一套结果封装和实际 import；新契约的 canonical 包是 `com.yss.cloud.dto.result`，`com.yss.cloud.dto.response` 只能作为 legacy / compatibility 线索，不能在新契约中引入。
+4. 需要设计或审查 API 时，先校验 `references/openapi-wire-profile.yaml`，再把 endpoint 的具体 DTO/VO schema 组合到 wrapper；Java 泛型不是 OpenAPI schema。
+5. 只围绕当前 DTO 结构回答，不泛化到整个微服务理论。
+
+## 源码索引
+
+- 源码位置不要假设固定目录；先按 `yss-source-index/references/source-location.md` 定位。
+- 当前技能索引：`references/source-index.md`
+- OpenAPI wire profile：`references/openapi-wire-profile.yaml`
+- 重点源码入口通常包括 `CommandDTO`、`QueryDTO`、`PageQuery`、`PageRequestFactory`、`Result`、`SingleResult`、`MultiResult`、`PageResult`。
+
+当组件源码变化后，用 `yss-source-index` 刷新索引；刷新或读取前先按源码定位策略确认真实位置。
+
+## 使用规则
+
+- 写操作参数优先继承 `CommandDTO`。
+- 读操作参数优先继承 `QueryDTO` 或 `PageQuery`。
+- 分页查询优先继承 `PageQuery`，不要自行发明分页字段名。
+- Controller 返回优先使用项目既有的 `Result` 或派生结果对象。
+- 单对象返回优先 `SingleResult`，列表返回优先 `MultiResult`，分页返回优先 `PageResult`，前提是当前项目已采用这套体系。
+- 三种泛型结果要求 `T extends Serializable`；生成的 VO/响应类型必须满足该编译约束。
+- OpenAPI 响应以 `YssResultMeta` 表达公共字段，并用 `allOf` 叠加 endpoint-specific `data` / page 字段；每个响应声明 `x-yss-response-wrapper: SingleResult|MultiResult|PageResult`，不得把 `SingleResult<T>` 文字写成 schema。
+- wire shape 不是 Java 字段清单：`success` 为 boolean，`dataType` 为 `string|null`，`code` 只允许 `string|integer|null`；不得把全局 `code` 放宽为任意 object。
+- `MultiResult.data` 和 `PageResult.data` 对外是数组，空值按 `[]` 建模；`SingleResult.data` 按 endpoint schema 建模并显式处理 nullability。
+- `PageResult` 当前稳定公共字段为 `totalCount/pageSize/pageIndex/data[]`；`totalPages` 是计算 getter，只有目标 HTTP mapper / contract fixture 证明后才能进入具体契约。
+- `PageQuery` 客户端输入只允许 `pageIndex/pageSize/orderBy/orderDirection/groupBy`（后四项按 profile 的 optional / whitelist 规则）；`orderDirection` 只能是 `ASC|DESC`。`offset`、`needTotalCount`、`tempTotalCount` 是计算或内部协作字段，禁止成为客户端输入。
+- `buildSuccess(...)` 各重载设置 code 的行为并不一致；冻结契约必须测试 `success/code/message/tips/dataType`、nullability 和三种 data shape，不能只测试 data。
+- Java getter、Lombok、`@JsonIgnore` 或默认 Jackson 结果都不是目标 HTTP wire fact；冻结前必须记录 mapper identity、代表性序列化 fixture 和 contract-test / 等价 HTTP 证据。
+- DTO 只表达接口契约，不承载 Repository PO 或领域对象的持久化细节。
+
+## 检查清单
+
+- 分页字段名是否和框架约定一致。
+- `orderBy` / `groupBy` 是否经过 Repository 白名单映射，禁止直接拼接 SQL。
+- Service / Repository 是否真的接收到了 `PageQuery`。
+- 新增 DTO 是否与现有序列化和校验方式兼容。
+- 返回结构是否和前端或上游调用方契约一致。
+- 是否通过 `scripts/verify-yss-dto-openapi-profile`，并引用 profile 版本。
+- wrapper extension、`YssResultMeta`、`allOf`、具体 data schema 和方向性是否逐 endpoint 对齐。
+- 是否有针对 `offset` / `needTotalCount` / `tempTotalCount` 的负向断言，以及对 `totalPages` 的目标 mapper 证据。
+- Controller、Application Service、Domain、Repository 之间是否存在 DTO/VO/DO/PO 混穿。
+- 前端 Orval 或调用方是否依赖当前返回包装结构。
+
+## 修改约束
+
+- 不要在一个项目里混用多套返回包装类。
+- 不要新建与 `PageQuery` 含义重叠的分页基类。
+- 不要把 `com.yss.cloud.dto.response` 作为新 API 的 canonical 包，也不要从 Java getter 机械生成 wire schema。
+- 不要把 `offset`、`needTotalCount`、`tempTotalCount` 作为客户端分页输入；不要无证据把 `totalPages` 写入所有分页响应。
+- 若项目已有 `SingleResult`、`PageResult`、`MultiResult` 体系，优先保持一致。
+
+## 按需读取
+
+- 源码索引：`references/source-index.md`
+- DTO 基类示例：`assets/CommandDTO.java`、`assets/QueryDTO.java`
+- 分页基类：`assets/PageQuery.java`
+- 返回结构：`assets/Result.java`
+- HTTP/JSON 映射：`references/openapi-wire-profile.yaml`
+
+## 阶段 7 合同
+
+- DTO/VO 必须消费冻结 OpenAPI/no-impact record 和批准合同，写入合同允许路径。
+- POJO 样板可 `controlled-generation`；校验、权限输入、错误结构和序列化行为必须由对应 `behavior-tdd` 工作单元覆盖。
+- 必须加载合同要求的 `lombok`、`mapstruct` 和 `alibaba-java-code-style`，并按统一 `YSS Skill Execution Result` 返回文件、契约测试和偏离。

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

@@ -0,0 +1,5 @@
+version: 1
+interface:
+  display_name: "YSS DTO"
+  short_description: "统一响应、分页查询、Command 与 DTO 设计规范"
+  default_prompt: "Use $yss-dto to define YSS-style DTOs, page queries, commands, unified response models, and their OpenAPI HTTP/JSON wire shapes."

package/template/.cursor/skills/yss-dto/assets/CommandDTO.java

@@ -0,0 +1,8 @@
+package com.yss.cloud.dto;
+
+import java.io.Serializable;
+
+public abstract class CommandDTO implements Serializable {
+
+  private static final long serialVersionUID = 1L;
+}

package/template/.cursor/skills/yss-dto/assets/PageQuery.java

@@ -0,0 +1,133 @@
+package com.yss.cloud.dto.page;
+
+import com.fasterxml.jackson.annotation.JsonIgnore;
+import com.yss.cloud.dto.QueryDTO;
+
+public class PageQuery extends QueryDTO {
+
+  private static final long serialVersionUID = 1L;
+
+  public static final String ASC = "ASC";
+
+  public static final String DESC = "DESC";
+
+  private static final int DEFAULT_PAGE_SIZE = 10;
+  /**
+   * 每页显示
+   * @mock 10
+   */
+  private int pageSize = DEFAULT_PAGE_SIZE;
+
+  /**
+   * 当前页
+   * @mock 1
+   */
+  private int pageIndex = 1;
+
+  /**
+   * 排序字段
+   * @mock id
+   */
+  private String orderBy;
+
+  /**
+   * 默认倒序
+   * @mock DESC
+   */
+  private String orderDirection = DESC;
+
+  /** 分组字段 */
+  private String groupBy;
+
+  /**
+   * 是否需要总数
+   * @apiNote 暂时未实现
+   * @mock true
+   */
+  @JsonIgnore
+  private boolean needTotalCount = true;
+
+  /**
+   * 总数dto临时字段，忽略即可
+   * @mock 0
+   */
+  @JsonIgnore
+  private long tempTotalCount = 0;
+
+  public int getPageIndex() {
+    return Math.max(pageIndex, 1);
+  }
+
+  public PageQuery setPageIndex(int pageIndex) {
+    this.pageIndex = pageIndex;
+    return this;
+  }
+
+  public int getPageSize() {
+    if (pageSize < 1) {
+      pageSize = DEFAULT_PAGE_SIZE;
+    }
+    return pageSize;
+  }
+
+  public PageQuery setPageSize(int pageSize) {
+    if (pageSize < 1) {
+      pageSize = DEFAULT_PAGE_SIZE;
+    }
+    this.pageSize = pageSize;
+    return this;
+  }
+
+  public int getOffset() {
+    return (getPageIndex() - 1) * getPageSize();
+  }
+
+  public String getOrderBy() {
+    return orderBy;
+  }
+
+  public PageQuery setOrderBy(String orderBy) {
+    this.orderBy = orderBy;
+    return this;
+  }
+
+  public String getOrderDirection() {
+    return orderDirection;
+  }
+
+  public PageQuery setOrderDirection(String orderDirection) {
+    if (ASC.equalsIgnoreCase(orderDirection) || DESC.equalsIgnoreCase(orderDirection)) {
+      this.orderDirection = orderDirection;
+    }
+    return this;
+  }
+
+  public long getTempTotalCount() {
+    return tempTotalCount;
+  }
+
+  public void setTempTotalCount(long tempTotalCount) {
+    this.tempTotalCount = tempTotalCount;
+  }
+
+  public String getGroupBy() {
+    return groupBy;
+  }
+
+  public void setGroupBy(String groupBy) {
+    this.groupBy = groupBy;
+  }
+
+  public boolean isNeedTotalCount() {
+    return needTotalCount;
+  }
+
+  public void setNeedTotalCount(boolean needTotalCount) {
+    this.needTotalCount = needTotalCount;
+  }
+
+  @Override
+  public String toString() {
+    return "PageQuery(" + "pageSize=" + pageSize + ", pageIndex=" + pageIndex + ')';
+  }
+}

package/template/.cursor/skills/yss-dto/assets/QueryDTO.java

@@ -0,0 +1,6 @@
+package com.yss.cloud.dto;
+
+public abstract class QueryDTO extends CommandDTO {
+
+  private static final long serialVersionUID = 1L;
+}

package/template/.cursor/skills/yss-dto/assets/Result.java

@@ -0,0 +1,105 @@
+package com.yss.cloud.dto.result;
+
+import java.io.Serializable;
+
+/**
+ * @author zhudaoming
+ */
+public class Result implements Serializable {
+
+  private static final long serialVersionUID = 2405172041950251807L;
+
+  private static final String DEFAULT_MESSAGE = "数据返回正常";
+  private static final String DEFAULT_TIPS = "信息返回正常";
+
+  /** 状态 */
+  private boolean success;
+  /** 返回数据格式 */
+  private String dataType;
+  /** 返回状态码 */
+  private Object code;
+  /** 返回消息 */
+  private String message = DEFAULT_MESSAGE;
+  /** 返回提示消息 */
+  private String tips = DEFAULT_TIPS;
+  public Object getCode() {
+    return code;
+  }
+
+  public Result setCode(Object code) {
+    this.code = code;
+    return this;
+  }
+
+  public String getMessage() {
+    return message;
+  }
+
+  public Result setMessage(String message) {
+    this.message = message;
+    return this;
+  }
+
+  public String getTips() {
+    return tips;
+  }
+
+  public void setTips(String tips) {
+    this.tips = tips;
+  }
+
+  public boolean isSuccess() {
+    return success;
+  }
+
+  public void setSuccess(boolean success) {
+    this.success = success;
+  }
+
+  public String getDataType() {
+    return dataType;
+  }
+
+  public void setDataType(String dataType) {
+    this.dataType = dataType;
+  }
+
+  public static Result buildSuccess() {
+    Result response = new Result();
+    response.setSuccess(true);
+    response.setCode("DM-A0001");
+    return response;
+  }
+
+  public static Result buildSuccess(String message) {
+    Result response = new Result();
+    response.setSuccess(true);
+    response.setMessage(message);
+    return response;
+  }
+  public static Result buildSuccess(String code,String message) {
+    Result response = new Result();
+    response.setSuccess(true);
+    response.setCode(code);
+    response.setMessage(message);
+    return response;
+  }
+  public static Result buildFailure(String message) {
+    Result response = new Result();
+    response.setSuccess(false);
+    response.setMessage(message);
+    return response;
+  }
+  public static Result buildFailure(String errCode,String message) {
+    Result response = new Result();
+    response.setSuccess(false);
+    response.setCode(errCode);
+    response.setMessage(message);
+    return response;
+  }
+  @Override
+  public String toString() {
+    return "Response [success=" + success + "]";
+  }
+
+}

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` 封装查询参数，保持代码语义清晰。