create-yss-spec 2.2.9 → 3.0.0

package/template/.hermes/skills/yss-domain/references/domain-layer-guide.md

@@ -1,274 +1,101 @@
-本 Skill 提供了 YSS 数据质量管理服务 **Domain (领域层)** 的开发规范。Domain 层是系统的核心，包含业务逻辑、领域模型和接口定义。
+# YSS Domain Target Profile 指南
 
-## 1. 核心职责 (Core Responsibilities)
+本指南只定义新 DDD `target-domain-model`。历史 DTO/VO 型 Gateway、`core/client/repository` 和贫血对象均为 `unsupported`，不存在旧架构 Profile 或迁移分支。
 
-- **定义业务模型 (Model)**: 包含实体 (Entity)、值对象 (VO)、聚合根 (Aggregate Root)。
-- **定义服务接口 (Gateway/Service)**: 定义与 Infrastructure 层交互的接口 (Gateway) 以及领域内部服务 (Domain Service)。
-- **定义数据契约 (DTO)**: 定义 Command (增删改), Query (查询), VO (视图) 等数据传输对象。
-- **业务逻辑实现**: 核心业务规则的校验和处理。
+## 1. Domain 所有权
 
-## 2. 代码结构 (Code Structure)
+Domain 只拥有：
 
-```
-com.yss.{module}
-├── client                  # 对外暴露的数据契约 (DTOs)
-│   ├── dto
-│   │   ├── cmd             # Command: 写操作参数 (e.g., QualityRuleAddCmd)
-│   │   └── query           # Query: 读操作参数 (e.g., QualityRulePage)
-│   └── vo                  # Value Object: 返回结果 (e.g., QualityBusinessRuleVO)
-└── domain                  # 领域核心实现
-    └── {domain_name}       # 具体的领域模块 (e.g., user, metadata)
-        ├── gateway         # 网关接口定义 (e.g., UserGateway)
-        ├── model           # 领域实体/枚举 (e.g., User, UserType)
-        └── service         # 领域服务 (e.g., UserService)
-```
-
-## 3. 开发规范 (Development Guidelines)
-
-### 3.1 数据传输对象 (DTO)
-
-- **Command (Cmd)**: 用于数据修改 (Create/Update/Delete)。
-  - 继承 `com.yss.cloud.dto.CommandDTO`。
-  - 按 `lombok` skill 选择 `@Getter` / `@Setter` / 构造器等最小注解；不默认使用 `@Data`。
-  - 必须使用 JSR-303/380 注解进行参数校验 (`@NotBlank`, `@NotNull`, `@Size` 等)。
-  - **示例**: `QualityRuleAddCmd`
-
-- **Query**: 用于数据查询。
-  - 分页查询继承 `com.yss.cloud.dto.page.PageQuery`。
-  - 普通查询继承 `com.yss.cloud.dto.QueryDTO`。
-  - **示例**: `QualityRulePage`
-
-- **View Object (VO)**: 用于展示层返回数据。
-  - 纯 POJO 仍按 `lombok` skill 选择最小注解；涉及身份、关系、敏感字段或懒加载时不得默认使用 `@Data`。
-  - **示例**: `QualityBusinessRuleVO`
-
-### 3.2 网关接口 (Gateway)
-
-Gateway 定义了领域层对外的依赖接口，通常由 Infrastructure 层实现。
-
-- **命名**: `DomainName` + `Gateway` (e.g., `QualityTemplateGateway`)。
-- **方法定义规范**:
-  - **分页查询**: `PageResult<VO> pageXxx(Query query)`
-  - **列表查询**: `List<VO> listXxx(Query query)`
-  - **单条查询**: `VO getXxxById(Long id)` 或 `VO getXxxByCode(String code)`
-  - **新增**: `Long/ResultVO addXxx(Cmd cmd)` (返回 ID 或 结果对象)
-  - **更新**: `void/ResultVO updateXxx(Cmd cmd)`
-  - **删除**: `void deleteXxx(Cmd cmd)`
-
-### 3.3 领域服务 (Domain Service)
-
-当业务逻辑涉及多个聚合根或不适合放入单一实体时，使用 Domain Service。
-
-- **命名**: `DomainName` + `Service` (e.g., `QualityTemplateService`)。
-- **职责**: 编排领域逻辑，调用 Gateway。
-
-### 3.4 常用类与注解
-
-- **分页结果**: `com.yss.cloud.dto.result.PageResult<T>`
-- **校验注解**: `javax.validation.constraints.*` (`@NotNull`, `@NotBlank`)
-- **Lombok**: 按对象语义选择 `@Getter`, `@Setter`, `@Builder`, `@NoArgsConstructor`, `@AllArgsConstructor`，不默认使用聚合式 `@Data`。
-
-## 4. 详细案例 (Detailed Examples)
-
-### 4.1 Command (新增命令)
-
-```java
-package com.yss.quality.client.dto.cmd;
-
-import com.yss.cloud.dto.CommandDTO;
-import com.yss.quality.domain.QualityRuleTemplateType;
-import com.yss.quality.domain.QualityType;
-import com.yss.quality.domain.datasource.entity.DatabaseType;
-import com.yss.quality.domain.rule.entity.QualityRuleType;
-import lombok.Getter;
-import lombok.Setter;
-
-import javax.validation.constraints.NotBlank;
-import javax.validation.constraints.NotEmpty;
-import javax.validation.constraints.NotNull;
-import java.util.List;
-import java.util.Map;
-
-/**
- * 数据质量规则模板新增命令对象
- */
-@Getter
-@Setter
-public class QualityTemplateAddCmd extends CommandDTO {
-
-    @NotBlank(message = "模板名称不能为空")
-    private String templateName;
-
-    @NotBlank(message = "模板编码不能为空")
-    private String templateCode;
+- Aggregate Root、Entity、Value Object。
+- 领域行为、不变量、状态转换和 Domain Event。
+- 聚合持久化及外部领域能力所需的 Gateway/Port。
+- 稳定的领域错误标识与错误参数。
 
-    @NotEmpty(message = "数据库类型不能为空")
-    private List<DatabaseType> databaseType;
+Domain 不拥有：
 
-    @NotNull(message = "模板类型不能为空")
-    private QualityRuleTemplateType templateType;
+- HTTP Cmd/Query/VO、YSS `PageQuery` / `PageResult`。
+- Repository PO、Mapper、SQL、Controller。
+- HTTP status、YSS Result 包装或公开错误消息。
 
-    @NotNull(message = "模板规则类型不能为空")
-    private QualityType ruleType;
+## 2. 包结构
 
-    private String description;
-
-    @NotBlank(message = "异常SQL不能为空")
-    private String exceptionCountSql;
-
-    @NotNull
-    private String resultLabel;
-
-    private Boolean defaultFlag;
-
-    Map<String, Object> ruleTemplateParam;
-}
+```text
+{base_package}.domain.{segment}
+├── model
+├── gateway
+├── service
+└── event
 ```
 
-### 4.2 Query (分页查询)
-
-```java
-package com.yss.quality.client.dto.query;
-
-import com.yss.cloud.dto.page.PageQuery;
-import com.yss.quality.domain.QualityRuleTemplateType;
-import com.yss.quality.domain.QualityType;
-import lombok.Getter;
-import lombok.Setter;
-
-import javax.validation.constraints.NotNull;
+DTO/VO 位于 `{base_package}.rest.dto`。独立 client Maven module 对当前 Target Profile 为 `unsupported`；不得放回 Domain module。
 
-/**
- * 数据质量规则模板查询对象
- */
-@Getter
-@Setter
-public class QualityTemplatePage extends PageQuery {
-    /**
-     * 模板类型
-     */
-    private QualityRuleTemplateType templateType;
+## 3. Aggregate 与行为
 
-    /**
-     * 规则类型
-     */
-    @NotNull
-    private QualityType ruleType;
+- Aggregate Root 是一致性边界，不按表数量机械拆分。
+- Entity identity 使用明确类型；Value Object 按值相等并尽量不可变。
+- 对外暴露业务动作，例如 `publish()`、`cancel()`，不要让 Application 任意修改状态字段。
+- 每个批准不变量必须有 `behavior-tdd` 测试；测试通过聚合公开方法观察结果。
+- 没有真实行为时保持简单模型，不为了“看起来像 DDD”制造空 Domain Service。
 
-    /**
-     * 模板名称
-     */
-    private String templateName;
+## 4. Gateway
 
-    private Integer status;
-}
-```
+Gateway 描述领域能力，只交换 Domain Model、领域值和领域标识。例如：
 
-### 4.3 Gateway (网关接口)
+Gateway interface 的签名由批准战术模型决定，并由 `yss-domain` 唯一创建和维护；Infrastructure / `yss-repository` 只能实现该接口。若实现所需能力超出既有签名，返回 `new_impacts` 并重路由，不得从 DDL 反向扩写 Domain 合同。
 
 ```java
 package com.yss.quality.domain.template.gateway;
 
-import com.yss.cloud.dto.result.PageResult;
-import com.yss.quality.client.dto.cmd.QualityTemplateAddCmd;
-import com.yss.quality.client.dto.cmd.QualityTemplateDeleteCmd;
-import com.yss.quality.client.dto.cmd.QualityTemplateUpdateCmd;
-import com.yss.quality.client.dto.query.QualityTemplatePage;
-import com.yss.quality.client.vo.QualityTemplateVO;
+import com.yss.quality.domain.template.model.QualityTemplate;
+import com.yss.quality.domain.template.model.QualityTemplateId;
+import java.util.Optional;
 
-/**
- * 数据质量规则模板网关接口
- */
 public interface QualityTemplateGateway {
-
-    /**
-     * 分页查询数据质量规则模板
-     */
-    PageResult<QualityTemplateVO> pageQualityTemplate(QualityTemplatePage query);
-
-    /**
-     * 根据ID查询数据质量规则模板
-     */
-    QualityTemplateVO getQualityTemplateById(Long id);
-
-    /**
-     * 新增数据质量规则模板
-     */
-    Long addQualityTemplate(QualityTemplateAddCmd cmd);
-
-    /**
-     * 更新数据质量规则模板
-     */
-    void updateQualityTemplate(QualityTemplateUpdateCmd cmd);
-
-    /**
-     * 删除数据质量规则模板
-     */
-    void deleteQualityTemplate(QualityTemplateDeleteCmd cmd);
+    Optional<QualityTemplate> findById(QualityTemplateId id);
+    void save(QualityTemplate template);
 }
 ```
 
-### 4.4 Domain Service (领域服务)
+禁止在 Domain Gateway 中出现：
 
-```java
-package com.yss.quality.domain.template.service;
+- `*AddCmd`、`*UpdateCmd`、HTTP request。
+- `*VO`、`PageResult`、Repository PO。
+- MyBatis、Spring MVC、Jackson、Swagger 类型。
 
-import com.yss.cloud.dto.result.PageResult;
-import com.yss.quality.client.dto.cmd.QualityTemplateAddCmd;
-import com.yss.quality.client.dto.query.QualityTemplatePage;
-import com.yss.quality.client.vo.QualityTemplateVO;
+分页、列表和投影查询由 Application Query Port 定义，Infrastructure 实现。
 
-/**
- * 数据质量规则模板服务接口
- */
-public interface QualityTemplateService {
+## 5. Domain Error
 
-    PageResult<QualityTemplateVO> pageQualityTemplate(QualityTemplatePage query);
+领域错误携带稳定标识和参数，不决定 HTTP 行为：
 
-    QualityTemplateVO getQualityTemplateById(Long id);
+```java
+public final class QualityTemplateNameConflict extends RuntimeException {
+    private final String templateName;
 
-    Long addQualityTemplate(QualityTemplateAddCmd cmd);
+    public QualityTemplateNameConflict(String templateName) {
+        super("quality-template-name-conflict");
+        this.templateName = templateName;
+    }
 
-    // 更多业务方法...
+    public String templateName() {
+        return templateName;
+    }
 }
 ```
 
-### 4.5 Value Object (视图对象)
+Web Exception Translator 再将它映射为批准的状态码、错误码和消毒消息。Domain 不直接依赖 YSS `BizException`。
 
-```java
-package com.yss.quality.client.vo;
-
-import lombok.Getter;
-import lombok.Setter;
-import java.io.Serializable;
-import java.util.Map;
-
-/**
- * 数据质量规则模板值对象
- */
-@Getter
-@Setter
-public class QualityTemplateVO implements Serializable {
-    private Long id;
-    private String templateName;
-    private String templateCode;
-    private String resultLabel;
-    private String databaseType;
-    private String qualityRuleType;
-    private String qualityType;
-    private Map<String,Object> ruleTemplateParam;
-    private Boolean defaultFlag;
-}
-```
+## 6. 依赖门禁
 
-## 5. 注意事项 (Notes)
+生成工程的 ArchUnit 规则必须证明：
 
-1.  **依赖倒置**: Domain 层**不应依赖** Infrastructure 层或 Web 层。所有外部交互通过 Gateway 接口定义。
-2.  **贫血模型 vs 充血模型**: 虽然目前主要是贫血模型 (DTO/VO)，但鼓励将核心业务逻辑下沉到 Domain Model 中。
-3.  **参数校验**: 必须在 Cmd 对象中使用注解进行严格的参数校验，Gateway 实现层应进行 `@Valid` 校验。
+- Domain 不依赖 Application、Infrastructure、Repository 或 Web。
+- Domain 不依赖 YSS DTO/Exception、Jackson、Swagger 或 Validation。
+- 负例 fixture 中的 Domain → Web DTO 引用会使验证失败。
 
-## 6. 阶段 7 合同
+## 7. 生命周期证据
 
-- 领域规则、状态机和不变量必须使用 `behavior-tdd`；只允许 DTO/VO/接口等机械骨架使用受控生成。
-- 消费批准后的合同和 work unit，写入允许路径，并返回统一 `YSS Skill Execution Result`。
-- 发现新的状态机、权限、数据模型、API 或跨上下文影响时返回 `new_impacts` 并暂停。
+- 消费批准且当前的 Tactical Design 与 Slice Implementation Contract。
+- 返回 YSS Skill Execution Result，包含 Domain 文件、行为测试、ArchUnit 结果及实际 `./mvnw ...` 证据。
+- 新聚合、不变量、状态机或跨上下文影响进入 `new_impacts` 并暂停。
+- 检测到旧架构时返回 `unsupported`；如需现代化，退出 scaffold 工作流并单独立项评估。

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

@@ -1,6 +1,6 @@
 ---
 name: yss-dto
-description: Use when YSS `Result`, `SingleResult`, `MultiResult`, `PageResult`, `PageQuery`, `CommandDTO`, `QueryDTO`, pagination, or response-wrapper compatibility is involved.
+description: Use when YSS `Result`, `SingleResult`, `MultiResult`, `PageResult`, `PageQuery`, `CommandDTO`, `QueryDTO`, pagination, or response-wrapper boundaries are involved.
 ---
 
 # yss-dto
@@ -9,6 +9,12 @@ description: Use when YSS `Result`, `SingleResult`, `MultiResult`, `PageResult`,
 
 本 skill 同时负责把中台 DTO 映射到公开 HTTP/JSON 边界。`references/openapi-wire-profile.yaml` 是可复用的机器可读映射源；OpenAPI 治理和 Draft Review 必须消费它，不得各自复制一份 wrapper 或分页字段表。
 
+## 所有权边界
+
+- `Result` / `SingleResult` / `MultiResult` / `PageResult`、`CommandDTO` / `QueryDTO` / `PageQuery` 的 canonical package、工厂方法、字段语义、默认值、枚举和禁用字段由本 skill 及 `references/openapi-wire-profile.yaml` 唯一持有。
+- Web skill 只生成 endpoint-specific Page Request、Request/Response 与 Convertor，并通过批准合同中的 profile 引用和 digest 消费上述协议；不得生成 wrapper/page base，也不得维护分页字段或默认值副本。
+- OpenAPI skill 只把该 profile 组合进 endpoint schema；不得从 Java getter 或本地常量反向建立第二份 wire 协议。
+
 ## 何时使用
 
 - 用户要定义新的分页查询对象。
@@ -20,7 +26,7 @@ description: Use when YSS `Result`, `SingleResult`, `MultiResult`, `PageResult`,
 
 1. 优先沿用项目现有 DTO 体系，不重复造返回包装类。
 2. 涉及真实类名、返回结构、分页字段或排障时，先读 `references/source-index.md`，再定位源码或文档。
-3. 先确认当前项目用的是哪一套结果封装和实际 import；新契约的 canonical 包是 `com.yss.cloud.dto.result`，`com.yss.cloud.dto.response` 只能作为 legacy / compatibility 线索，不能在新契约中引入。
+3. 新 Target Profile 的 canonical 包固定为 `com.yss.cloud.dto.result`；`com.yss.cloud.dto.response` 为 `unsupported`，不得在新契约或脚手架输出中引入。检测到旧包时只报告边界，不自动改写；旧项目现代化须单独立项。
 4. 需要设计或审查 API 时，先校验 `references/openapi-wire-profile.yaml`，再把 endpoint 的具体 DTO/VO schema 组合到 wrapper；Java 泛型不是 OpenAPI schema。
 5. 只围绕当前 DTO 结构回答，不泛化到整个微服务理论。
 
@@ -36,8 +42,8 @@ description: Use when YSS `Result`, `SingleResult`, `MultiResult`, `PageResult`,
 ## 使用规则
 
 - 写操作参数优先继承 `CommandDTO`。
-- 读操作参数优先继承 `QueryDTO` 或 `PageQuery`。
-- 分页查询优先继承 `PageQuery`，不要自行发明分页字段名。
+- Application/Infrastructure 内部读参数可按项目 Profile 使用 `QueryDTO` 或 `PageQuery`。
+- 公开 HTTP Page Request 默认不继承 `PageQuery`，只复制冻结 OpenAPI 允许的分页字段，再由 WebConvertor 转为 Application Query；避免继承的 `offset`、`needTotalCount`、`tempTotalCount` 进入绑定面。
 - Controller 返回优先使用项目既有的 `Result` 或派生结果对象。
 - 单对象返回优先 `SingleResult`，列表返回优先 `MultiResult`，分页返回优先 `PageResult`，前提是当前项目已采用这套体系。
 - 三种泛型结果要求 `T extends Serializable`；生成的 VO/响应类型必须满足该编译约束。
@@ -54,7 +60,7 @@ description: Use when YSS `Result`, `SingleResult`, `MultiResult`, `PageResult`,
 
 - 分页字段名是否和框架约定一致。
 - `orderBy` / `groupBy` 是否经过 Repository 白名单映射，禁止直接拼接 SQL。
-- Service / Repository 是否真的接收到了 `PageQuery`。
+- Application Query Port / Infrastructure 是否收到批准的分页语义；Domain Gateway 不接收 `PageQuery`。
 - 新增 DTO 是否与现有序列化和校验方式兼容。
 - 返回结构是否和前端或上游调用方契约一致。
 - 是否通过 `scripts/verify-yss-dto-openapi-profile`，并引用 profile 版本。

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

@@ -46,7 +46,7 @@
 
 ## HTTP/JSON 映射边界
 
-- 新契约使用 `com.yss.cloud.dto.result`；`com.yss.cloud.dto.response` 只作为 legacy / compatibility 线索。
+- 新 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 证明后才进入响应契约。
@@ -63,5 +63,5 @@
 ## 使用场景
 
 1. **API 响应**: 所有 Controller 方法应返回 `Result` 或其子类（如 `PageResult`, `SingleResult`）。
-2. **分页查询**: Controller 接收分页请求时，参数类应继承 `PageQuery`。MyBatis 分页插件会自动识别并处理。
+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

@@ -14,11 +14,11 @@ canonical:
     response_wrapper_extension: x-yss-response-wrapper
     literal_java_generic_schema: false
 
-compatibility_packages:
+unsupported_packages:
   - java_package: com.yss.cloud.dto.response
-    status: legacy-or-compatibility
+    status: unsupported
     use_for_new_contracts: false
-    policy: do-not-introduce-in-new-contracts
+    policy: reject-in-new-contracts-no-auto-migration
 
 common_response:
   schema_name: YssResultMeta
@@ -54,6 +54,9 @@ wrappers:
   SingleResult:
     java_type: com.yss.cloud.dto.result.SingleResult<T>
     response_kind: single
+    java_factory:
+      method: of
+      arguments: [data]
     data:
       direction: response
       wire_shape: endpoint-schema-or-null
@@ -72,6 +75,9 @@ wrappers:
   PageResult:
     java_type: com.yss.cloud.dto.result.PageResult<T>
     response_kind: page
+    java_factory:
+      method: of
+      arguments: [data, totalCount, pageSize, pageIndex]
     fields:
       totalCount:
         direction: response

package/template/.hermes/skills/yss-exception/SKILL.md

@@ -24,6 +24,7 @@ Read `references/source-index.md` as a path-hint index whenever the task depends
 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.
+6. In the `target-domain-model` profile, Domain owns stable error meaning and parameters but does not depend directly on YSS `BizException` or HTTP. Translate at the Web boundary after verifying the component handler precedence.
 
 ## Current Source Behavior
 
@@ -47,6 +48,7 @@ Read `references/source-index.md` as a path-hint index whenever the task depends
 - 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`.
+- Endpoint contract tests cover business, known-system, and unknown/runtime failures; unknown public messages never expose `getLocalizedMessage()`.
 
 ## Do Not
 

package/template/.hermes/skills/yss-formily/SKILL.md

@@ -15,7 +15,7 @@ description: 指导在 YSS UI 业务页面中正确使用 @yss-ui/components 的
 
 - 页面只有普通列表，不涉及表单：使用 `../page-list-module/SKILL.md`。
 - 只处理表格操作列或分页：使用 `../ytable-usage/SKILL.md`。
-- 组件库内部改造 YFormily 源码：使用 `../component-development/SKILL.md`。
+- 组件库内部改造 YFormily 源码：回到 yss-ui 源仓库，使用其 `categories.library` 维护流程；该类 skill 不随业务模板分发。
 
 ## 文档检索
 

package/template/.hermes/skills/yss-mybatis/SKILL.md

@@ -16,7 +16,7 @@ description: 用于 YSS MyBatis 与 MyBatis-Plus 持久层规范、配置和排
 
 ## 工作方式
 
-1. 先确认项目使用的是通用 MyBatis 还是 MyBatis-Plus。
+1. 先读取批准的 `persistence_profile`。新 DDD scaffold 当前只支持 `mybatis-plus`；普通 MyBatis 必须有独立 fixture 和批准 Profile，禁止自动猜测或混用。
 2. 涉及真实类名、配置项、模块依赖或排障时，先读 `references/source-index.md`，再定位源码或文档。
 3. 先复用现有基类与配置，不手搓新的基础设施。
 4. 涉及分页时，先验证 `PageQuery` 传递链路和拦截器是否生效。
@@ -35,7 +35,7 @@ description: 用于 YSS MyBatis 与 MyBatis-Plus 持久层规范、配置和排
 - MP 模式优先继承项目既有的 `BasePlusRepository`
 - 批量导入优先使用真正的 SQL 级批量方法，不要默认循环单条插入
 - 多数据源问题优先先看配置和扫描范围，再怀疑业务代码
-- 分页查询优先沿用 `PageQuery` 传递链路，不要在 Repository 内临时发明分页参数。
+- 分页查询经 Application Query Port 进入 Infrastructure；可以在适配层转换为组件所需 `PageQuery`，但不得把 `PageQuery` 带入 Domain Gateway，也不得在 Repository 内临时发明分页参数。
 - 生成或重构持久层时，先看当前模块已有 Repository/Mapper 命名、包路径、XML 位置。
 
 ## 检查清单

package/template/.hermes/skills/yss-page-module-development/SKILL.md

@@ -5,6 +5,8 @@ description: 指导创建标准 Vue 3 YSS 业务页面模块，覆盖 CRUD、列
 
 # YSS Page Module Development
 
+> **核心路由说明**：新页面生成开发请优先以 `../yss-ui-business-page-generation/SKILL.md` 为统一主规则与硬约束。当前会话可用 yss-ui MCP 时，生成业务代码前必须先调用 `get_codegen_rules`。本技能作为兼容旧触发名与流程编排入口保留。
+
 Use this skill when the user asks for a business page, CRUD module, tree-table page, detail page, or any standard YSS Vue 3 page module.
 
 ## Authoritative Docs And Skill Boundaries

package/template/.hermes/skills/yss-product-lifecycle/SKILL.md

@@ -31,7 +31,7 @@ Matt 的 `grill-with-docs`、`to-spec`、`to-tickets`、`implement` 等保留为
 | 主阶段 | 必需产物/门禁 | 原生工作单元与技能 | 通过条件 |
 |---|---|---|---|
 | 入口分诊 `stage.entry-triage` | 身份、影响面、最近可信阶段 | `work-unit.entry-triage`；`yss-product-lifecycle` | `yss-project.yaml` 合法且影响面可解释 |
-| Discovery `stage.discovery` | Discovery、用户/MVP/非目标/成功标准、测试 seam；命中 DDD 影响时补充领域战略设计与阶段决策包 | `work-unit.discovery-opportunity` + `work-unit.discovery-requirements` + `work-unit.domain-strategy-design` + `work-unit.stage-decision`；市场/竞品事实用 `competitive-intelligence`，技术/标准事实用 `research`；需求澄清用 `grilling`，领域建模用 `domain-modeling` / `yss-stage-decision`；`grill-with-docs` 为兼容入口 | 未决事实已 research 或 handoff，领域边界和统一语言可审查，阶段决策包完成必要批准；`gate.domain-strategy-approved`、`gate.stage-decision-package-approved` |
+| Discovery `stage.discovery` | Discovery、用户/MVP/非目标/成功标准、测试 seam；命中 DDD 影响时补充领域战略设计与阶段决策包 | `work-unit.discovery-opportunity` + `work-unit.discovery-requirements` + `work-unit.domain-strategy-design` + `work-unit.stage-decision`；市场/竞品事实用 `competitive-intelligence`，技术/标准事实用 `yss-research:technical-evidence`，领域战略与阶段决策证据用 `yss-research:strategy-evidence`；需求澄清用 `grilling`，领域建模用 `domain-modeling` / `yss-stage-decision`；`grill-with-docs` 为兼容入口 | 未决事实已由 `yss-research` 核验或 handoff，进入战略 / 阶段门禁的决策证据已 `evidence-audited`，领域边界和统一语言可审查，阶段决策包完成必要批准；`gate.domain-strategy-approved`、`gate.stage-decision-package-approved` |
 | Spec / 功能架构 `stage.spec-architecture` | Spec、产品总体设计、功能架构；必要时 Spec Delta | 原生 `work-unit.spec-synthesis`；`to-spec` 为兼容入口 | 初稿先为 `ready-for-human`；只有 Spec baseline 会签批准后资产才为 `approved` 并进入下游 |
 | 产品设计 `stage.product-design` | 交互说明、低保真、状态矩阵、高保真 HTML、评审记录 | `work-unit.prototype-design`；`yss-prototype-stage` 为主合同，依次消费 `yss-design-system`、独立 `prototype-review`、`yss-antd-design` pre-build facts、Codex `product-design:index` focused workflow、post-build/浏览器/无障碍验证（非 Codex 交付等价合同）。前端落地改用 `yss-ui` | `gate.prototype-reviewed`、`gate.prototype-verified`、`gate.user-confirmation` 均有 schema v2 证据 |
 | 系统 / 数据架构与工程契约 `stage.system-data-engineering` | OpenAPI Draft/Freeze、数据架构、工程基线、架构审查；按领域影响执行 Tactical DDD Check | `work-unit.technical-analysis`；`yss-router` + `yss-openapi-governance` / `yss-openapi-draft-review`、`codebase-design`、`implementation-repo-onboarding`、`yss-tactical-design`；用户或合同明确要求架构可视化时条件追加 `archify` | API/架构契约冻结；无 API 影响有明确记录；战术模型无未解释冲突；脚手架策略满足；Archify 图只作派生审查证据；`gate.openapi-draft-reviewed`、`gate.design-reviewed`、`gate.openapi-frozen`、`gate.engineering-baseline-accepted`、`gate.architecture-reviewed` |

package/template/.hermes/skills/yss-product-lifecycle/references/matt-yss-adapter.md

@@ -20,7 +20,7 @@ Matt skills 决定如何工作；YSS 生命周期决定是否允许推进；YSS
 | 需求澄清 | `grill-with-docs`（用户显式）或 `grilling`、`domain-modeling`（生命周期原语） | 按退出判定检查未决项和回流 |
 | 信息在其他人手中 | `to-questionnaire` | 使用 `external-input-required` 暂停；答案回流后记录 response、重新分类影响面，再进入 `grill-with-docs` 或 `to-spec` |
 | 大型模糊工作 | `wayfinder`（可选） | 仅在跨会话 / 跨 Agent 或 frontier 不清晰时启用；map 真正完成后 `handoff → to-spec` |
-| 技术事实 | `research` | 一手资料回填 Spec/OpenAPI/架构/ADR |
+| 技术或战略事实 | `yss-research`（`research` 为 deprecated alias） | `technical-evidence` 核验一手技术资料；`strategy-evidence` 为领域战略和阶段决策提供可审计证据；研究包不得自行修改或批准下游资产 |
 | runnable 问题 | `prototype` | 生成单文件可分享 HTML，保留 `prototype/<name>` 分支作为主来源；必须 source/return handoff 和结论回填，不得替代阶段 4 的低保真评审、Ant Design v6 高保真 HTML、AntD CLI 证据和用户确认 |
 | Spec 综合 | 原生 `work-unit.spec-synthesis`；`to-spec`（用户显式兼容） | 初稿进入 `ready-for-human`，不得直接实现 |
 | 切片 | 原生 `work-unit.ticket-decomposition`；`to-tickets`（用户显式兼容） | 仅在冻结/无影响记录后拆垂直切片，初始 Ticket 状态为 `ready-for-human` |
@@ -72,7 +72,7 @@ Router 状态映射为：`draft → completed`、`blocked → blocked`、`ready-
 | `to-tickets`（用户显式） | OpenAPI Freeze 或 `no-api-impact` 记录、必要门禁、垂直切片范围和阻塞边均已明确 | 生命周期只准备/验收；只能生成垂直切片 Ticket，初始统一为 `ready-for-human`；必须留下 `ticket_decomposition_result_ref` 和 `vertical_slice_ticket_ref` |
 | `implement`（用户显式） | `ready-for-agent` 公式、Ticket 正式化结果、垂直切片引用/类型/状态、Contract 已批准/持久化/版本一致、Build Architecture Checklist、实现仓库/分支/CI/验证命令/回滚点，以及后端 Contract（适用时）均满足 | 生命周期只准备/验收；单会话实现同样适用，不得绕过门禁；父 Ticket、`ready-for-human` 切片或跳过 Ticket 正式化的 `next_route` 必须 `blocked` |
 
-`grill_exit` 不是“已经聊过”的自然语言声明。它必须同时证明 frontier 为空、事实已解决或分别路由到 `research` / prototype / external input、用户决策已确认、双方共同理解已确认，并且没有未回流的 runnable blocker。
+`grill_exit` 不是“已经聊过”的自然语言声明。它必须同时证明 frontier 为空、事实已解决或分别路由到 `yss-research` / prototype / external input、用户决策已确认、双方共同理解已确认，并且没有未回流的 runnable blocker。
 
 ## Review 候选与 Git 授权