create-yss-spec 2.1.10 → 2.1.13

package/template/.cursor/skills/yss-distributed-id/assets/EnableDistributedId.java

@@ -0,0 +1,25 @@
+package com.yss.cloud;
+
+import com.yss.cloud.sankuai.config.LeafConf;
+import com.yss.cloud.sankuai.config.LeafDataSourceConfiguration;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.context.annotation.Import;
+
+import java.lang.annotation.*;
+
+@Target({ElementType.TYPE})
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@Inherited
+@Import({LeafDataSourceConfiguration.class, EnableDistributedImportSelector.class})
+@EnableConfigurationProperties(LeafConf.class)
+public @interface EnableDistributedId {
+  /**
+   * 默认自动装载leaf配置，设置默认启用状态
+   */
+  boolean autoRegister() default true;
+  /**
+   * 是否启用cosid模式
+   */
+  boolean cosid() default false;
+}

package/template/.cursor/skills/yss-distributed-id/assets/LeafConf.java

@@ -0,0 +1,36 @@
+package com.yss.cloud.sankuai.config;
+
+import org.springframework.boot.context.properties.ConfigurationProperties;
+
+@ConfigurationProperties(prefix = "spring.leaf", ignoreInvalidFields = true)
+public class LeafConf {
+  private boolean leafSegmentEnable;
+  private boolean leafSnowflakeEnable;
+
+  public boolean isLeafSegmentEnable() {
+    return leafSegmentEnable;
+  }
+
+  public void setLeafSegmentEnable(boolean leafSegmentEnable) {
+    this.leafSegmentEnable = leafSegmentEnable;
+  }
+
+  public boolean isLeafSnowflakeEnable() {
+    return leafSnowflakeEnable;
+  }
+
+  public void setLeafSnowflakeEnable(boolean leafSnowflakeEnable) {
+    this.leafSnowflakeEnable = leafSnowflakeEnable;
+  }
+
+  @Override
+  public String toString() {
+    return "LeafConf{"
+        + "leafSegmentEnable="
+        + leafSegmentEnable
+        + ", leafSnowflakeEnable="
+        + leafSnowflakeEnable
+        + ", leafSnowflakePort="
+        + '}';
+  }
+}

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 + "]";
+  }
+
+}