create-yss-spec 2.1.9 → 2.1.11

package/template/.pi/skills/wait-what/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: wait-what
-description: Stop. That last message did not land — re-pitch it.
+description: "Stop. That last message did not land: re-pitch it."
 disable-model-invocation: true
 ---
 
-Wait — I don't understand where you've got to here. Re-pitch that: give me a little bit of context, talk in ASD-STE100 Simplified Technical English, and use the ubiquitous language from `CONTEXT.md`.
+Wait, I don't understand where you've got to here. Re-pitch that: give me a little bit of context, talk in ASD-STE100 Simplified Technical English, and use the ubiquitous language from `CONTEXT.md` (follow `CONTEXT-MAP.md` to the right one if the repo has more than one).

package/template/.pi/skills/wayfinder/SKILL.md

@@ -22,7 +22,7 @@ The map is a single issue on this repo's issue tracker, labelled `wayfinder:map`
 
 The map is an **index**, not a store. It lists the decisions made and points at the tickets that hold their detail; a decision lives in exactly one place — its ticket — so the map never restates it, only gists it and links.
 
-**Where the map, its child tickets, blocking, and frontier queries physically live is tracker-specific.** The issue tracker should have been provided to you — run `/setup-matt-pocock-skills` if not. Consult the tracker doc's "Wayfinding operations" section for how _this_ repo expresses them. If no tracker has been provided, default to the local-markdown tracker.
+**Where the map, its child tickets, blocking, and frontier queries physically live is tracker-specific.** The issue tracker should have been provided to you. If not, tell the user to run `/setup-matt-pocock-skills`. Consult the tracker doc's "Wayfinding operations" section for how _this_ repo expresses them. If no tracker has been provided, default to the local-markdown tracker.
 
 ### The map body
 

package/template/.pi/skills/yss-api-integration/SKILL.md

@@ -5,6 +5,8 @@ description: Guide AI to correctly use Orval-generated API clients in Vue 3 micr
 
 # API 集成 Skill
 
+目录与锁文件身份是 `yss-api-integration`；Agent 发现名与 Router 闭包键是 `api-integration`。二者指向同一技能，注册表以 alias 对齐。
+
 ## 📋 目标
 
 帮助 AI 正确使用基于 **Orval** 生成的 API 客户端：

package/template/.pi/skills/yss-application/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: yss-application
+description: Use when implementing YSS application use cases, transaction boundaries, cross-aggregate orchestration, idempotency, or application-level DTO conversion.
+---
+
+# yss-application
+
+Application 层用例编排 skill。负责协调 Domain 与 Gateway，定义事务边界和跨聚合流程，不承载核心领域规则。
+
+## 何时使用
+
+- 用户要实现 Application Service、用例编排或 `@Transactional` 边界。
+- 用户要补 App 层 MapStruct Convertor 或跨聚合协调逻辑。
+- 脚手架生成完成后进入业务实现，Router 按 `backend_impact` 加载本 skill。
+
+## 不适用
+
+- 只做领域建模时，优先 `yss-domain`。
+- 只做持久层时，优先 `yss-repository`。
+- 只做 Controller 时，优先 `yss-web-controller`。
+
+## 工作方式
+
+1. 先探测工程是新 DDD `application/domain/infrastructure/adapter` 还是 legacy `core/client/repository` profile。
+2. 确认 Use Case、Application 边界、事务边界已在批准合同中写明。
+3. 实现 AppService 时调用 Domain Service / Gateway，核心规则下沉 Domain。
+4. 涉及 POJO 样板加载 `lombok`；涉及 App 层转换加载 `mapstruct`。
+5. 详细包结构、注解、示例和 legacy 兼容说明见 `references/application-layer-guide.md`。
+
+## 产物范围
+
+- `application/.../service/*Service.java`（或 legacy `core/service`）
+- `application/.../service/impl/*ServiceImpl.java`
+- `application/.../service/convertor/*Convertor.java`（MapStruct）
+
+## 协同顺序
+
+- 领域建模：`yss-domain`
+- 持久层：`yss-repository`
+- Web 适配：`yss-web-controller`
+- DTO 契约：`yss-dto`
+
+## 阶段 7 合同
+
+- 只消费批准后的 `Slice Implementation Contract` 和当前 `work_unit`。
+- AppService 骨架可 `controlled-generation`；用例编排、事务、幂等、权限和失败行为必须 `behavior-tdd`。
+- 按 `yss-router/references/yss-skill-execution-result.md` 返回统一 `YSS Skill Execution Result`。
+- 发现新 API、权限、状态机或跨上下文影响时填入 `new_impacts` 并暂停。
+
+## 按需读取
+
+- 分层开发规范：`references/application-layer-guide.md`

package/template/.pi/skills/yss-application/agents/openai.yaml

@@ -0,0 +1,5 @@
+version: 1
+interface:
+  display_name: "YSS Application Layer"
+  short_description: "YSS Application 层用例编排、事务边界与跨聚合协调规范"
+  default_prompt: "Use $yss-application to implement the application layer for a YSS backend module."

package/template/.pi/skills/yss-application/references/application-layer-guide.md

@@ -0,0 +1,132 @@
+本 Skill 约束 Application 层的用例边界。它是目标 DDD 架构规则，不等同于现有 YSS 组件仓库中所有 `core/service` 的历史实现；先探测工程布局并记录兼容 profile。
+
+## 1. 核心职责 (Core Responsibilities)
+
+- **业务用例编排 (Use Case Orchestration)**: 协调 Domain Service 和 Gateway 完成复杂的业务流程。
+- **服务接口实现 (Service Implementation)**: 实现 Application Service 接口，对外提供业务能力。
+- **DTO 转换 (DTO Conversion)**: 只在合同指定时负责 Domain/Application model 与 client/web DTO/VO 的转换；不得把 Repository PO 带入 Application。
+- **事务控制 (Transaction Management)**: 在应用层进行 `@Transactional` 事务管理。
+
+## 2. 代码结构 (Code Structure)
+
+```
+com.yss.{module}.core
+├── service                 # 应用服务接口
+│   ├── impl                # 应用服务实现
+│   └── convertor           # MapStruct 转换器 (App 层专用)
+├── component               # 业务组件 (Exporter, Handler)
+└── job                     # 任务执行逻辑 (Runner, Func)
+```
+
+## 3. 开发规范 (Development Guidelines)
+
+### 3.1 应用服务实现 (AppServiceImpl)
+
+- **位置**: 新 DDD 工程优先 `application/.../service/impl`；legacy profile 才使用 `core/service/impl`。
+- **注解**: `@Service`，通常配合 `@RequiredArgsConstructor` 进行构造器注入。
+- **事务**: 只在已确认的用例边界添加 `@Transactional(rollbackFor = Exception.class)`；读用例明确 `readOnly` 与总数策略。
+- **逻辑**: 主要负责调用 Domain Service 或 Gateway，**不应包含核心领域逻辑**（应下沉到 Domain 层）。
+
+### 3.2 对象转换 (Convertor)
+
+- **工具**: MapStruct。
+- **位置**: `com.yss.{module}.core.service.convertor`。
+- **职责**: 将 `Domain Object` (VO/Entity) 转换为 `Application VO` 或 `Client VO`。
+- **规范**: 定义 `INSTANCE` 常量，使用 `Mappers.getMapper(...)` 获取实例。
+
+### 3.3 异常处理
+
+- **业务异常**: 使用 `ExceptionFactory.bizException(...)` 或项目已批准的 `BizException` 错误码。
+- **已知系统异常**: 使用 `ExceptionFactory.sysException(...)` 并保留 cause；未知异常交由全局处理器兜底，不在 Application 吞并或改写。
+
+## 4. Legacy 参考形状（不可复制）
+
+以下 `QualityTemplate*` 代码只是说明 legacy `core/service` 形状的占位示例，不是当前参考源码中已验证存在的通用模块，也不定义新模块的包名、接口或返回模型。新 DDD profile 必须由批准合同生成中性 Application 接口，不能复制这些名称或 DTO/VO Gateway 泄漏。
+
+### 4.1 Application Service Implementation
+
+```java
+package com.yss.quality.core.service.impl;
+
+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;
+import com.yss.quality.domain.template.gateway.QualityTemplateGateway;
+import com.yss.quality.domain.template.service.QualityTemplateService;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.List;
+
+/**
+ * 数据质量规则模板应用服务实现类
+ */
+@Service
+@RequiredArgsConstructor
+@Slf4j
+public class QualityTemplateServiceImpl implements QualityTemplateService {
+
+    private final QualityTemplateGateway qualityTemplateGateway;
+
+    @Override
+    public PageResult<QualityTemplateVO> pageQualityTemplate(QualityTemplatePage query) {
+        // 直接调用 Domain Gateway
+        return qualityTemplateGateway.pageQualityTemplate(query);
+    }
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public Long addQualityTemplate(QualityTemplateAddCmd cmd) {
+        // 可以在此进行简单的应用层校验或编排
+        log.info("Adding quality template");
+        return qualityTemplateGateway.addQualityTemplate(cmd);
+    }
+}
+```
+
+### 4.2 Convertor (MapStruct)
+
+```java
+package com.yss.quality.core.service.convertor;
+
+import com.yss.quality.client.vo.QualityTechTemplateVO;
+import com.yss.quality.client.vo.QualityTemplateVO;
+import com.yss.quality.params.base.PluginParams;
+import org.mapstruct.Mapper;
+import org.mapstruct.NullValueCheckStrategy;
+import org.mapstruct.NullValuePropertyMappingStrategy;
+import org.mapstruct.factory.Mappers;
+
+import java.util.List;
+
+@Mapper(
+    nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE,
+    nullValueCheckStrategy = NullValueCheckStrategy.ALWAYS
+)
+public interface QualityTechTemplateConvertor {
+    QualityTechTemplateConvertor INSTANCE = Mappers.getMapper(QualityTechTemplateConvertor.class);
+
+    // 将 Domain VO 和 PluginParams 组合转换为 TechTemplateVO
+    QualityTechTemplateVO useQualityTechTemplateVO(QualityTemplateVO qualityTemplateVO, List<PluginParams> pluginParams);
+}
+```
+
+## 5. 注意事项 (Notes)
+
+1.  **职责分离**: Application 层关注“做什么”（流程编排），Domain 层关注“怎么做”（业务规则）。
+2.  **依赖方向**: Application 层依赖 Domain 层，不应依赖 Adapter 层（Web/Job）。
+3.  **事务边界**: 一个用例一个边界；跨聚合写入、幂等键、事件发布时点必须写入合同并用 `behavior-tdd` 验证。
+4.  **上下文能力**: 当前用户、审计、普通技术日志、校验和异常是条件依赖，按 `yss-router` 影响闭包加载，不在 AppService 内手工解析 Header/JWT。
+
+## 6. 架构探测门禁
+
+先确认工程是新 DDD `application/domain/infrastructure/adapter`，还是 legacy `core/client/repository`。没有 `backend_repository`、Maven Wrapper 和已批准合同版本时输出 `blocked`；不得用示例包名推断真实接口。
+
+## 7. 阶段 7 合同
+
+- 明确当前 Use Case、Application 边界、事务边界、跨聚合协调和异常映射，只消费批准后的合同版本。
+- AppService 骨架可受控生成；用例编排、事务、幂等、权限和失败行为必须使用 `behavior-tdd`。
+- 返回统一 `YSS Skill Execution Result`，证据至少包含 Application 代码、测试、MapStruct/Lombok 条件和实际 `./mvnw ...` 结果。

package/template/.pi/skills/yss-ddd-scaffold-generator/SKILL.md

@@ -67,7 +67,7 @@ node scripts/generate_scaffold.mjs \
 - Harness 内多项目布局必须使用 `apps/backend/<project>/`；`apps/backend/` 只能是生成器的父容器，`app/backend/`、`app/frontend/` 及其子路径一律拒绝。
 - 不要在 skill 里硬编码用户业务字段或真实连接信息。
 - 生成后要检查依赖关系是否仍符合分层约束。
-- 生成后必须继续使用 `yss-backend-scaffold-parent` 校验工程基线，再按垂直切片加载 `yss-domain`、`yss-repository`、`yss-web-controller` 等局部技能。
+- 生成后必须继续使用 `yss-backend-scaffold-parent` 校验工程基线，再按垂直切片加载 `yss-domain`、`yss-application`、`yss-repository`、`yss-web-controller` 等行为 skill；各 skill 的 `references/*-layer-guide.md` 承载分层开发规范。
 - 当前脚手架第一阶段仅支持经过验证的 `mysql`；未提供完整模板和验证的数据库类型不得伪装成已支持。
 - 生成后的后端工程必须使用项目根目录 `./mvnw ...` 执行构建、测试、运行和 CI 验证；不得在 README、实施记录、Ticket、Review 或 Release 中默认写裸 `mvn ...`。既有仓库确实无法使用 wrapper 时，必须记录受控例外。
 - 原型确认后，`scaffold_status=required` 才能进入本 skill；本 skill 的生成边界是工程结构、POM、配置、Wrapper 和机械模板，不是业务实现。

package/template/.pi/skills/yss-ddd-scaffold-generator/references/ARCHITECTURE.md

@@ -188,7 +188,7 @@ Controller -> Service -> Gateway -> Repository -> Database
 ## 7. 参考资料
 
 - [YSS 后端开发规范](./yss-backend-scaffold-parent/SKILL.md)
-- [Domain 层开发指南](./yss-backend-scaffold-domain/SKILL.md)
-- [Application 层开发指南](./yss-backend-scaffold-application/SKILL.md)
-- [Infrastructure 层开发指南](./yss-backend-scaffold-infrastructure/SKILL.md)
-- [Web Adapter 开发指南](./yss-backend-scaffold-web/SKILL.md)
+- [Domain 层开发指南](./yss-backend-scaffold-domain/SKILL.md) → `yss-domain`
+- [Application 层开发指南](./yss-backend-scaffold-application/SKILL.md) → `yss-application`
+- [Infrastructure 层开发指南](./yss-backend-scaffold-infrastructure/SKILL.md) → `yss-repository`
+- [Web Adapter 开发指南](./yss-backend-scaffold-web/SKILL.md) → `yss-web-controller`

package/template/.pi/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-application/SKILL.md

@@ -1,8 +1,8 @@
 ---
-name: yss-backend-scaffold-application-reference
+name: yss-application-layer-reference
 description: Use when the YSS DDD scaffold workflow reaches Application-layer implementation and needs the shared Application skill.
 ---
 
 # Application Layer Reference
 
-**REQUIRED SUB-SKILL:** Use `yss-backend-scaffold-application` as the single authoritative Application-layer implementation guide. Do not maintain a second copy under the scaffold generator.
+**REQUIRED SUB-SKILL:** Use `yss-application` as the single authoritative Application-layer implementation guide (`references/application-layer-guide.md`). Do not maintain a second copy under the scaffold generator.

package/template/.pi/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-application/agents/openai.yaml

@@ -2,4 +2,4 @@ version: 1
 interface:
   display_name: "YSS Scaffold Application"
   short_description: "YSS 后端脚手架应用层、用例编排与 DTO 规范"
-  default_prompt: "Use $yss-backend-scaffold-application to implement the application layer for a YSS backend scaffold module."
+  default_prompt: "Use $yss-application to implement the application layer for a YSS backend scaffold module."

package/template/.pi/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-domain/SKILL.md

@@ -1,8 +1,8 @@
 ---
-name: yss-backend-scaffold-domain-reference
+name: yss-domain-layer-reference
 description: Use when the YSS DDD scaffold workflow reaches Domain-layer implementation and needs the shared Domain skill.
 ---
 
 # Domain Layer Reference
 
-**REQUIRED SUB-SKILL:** Use `yss-backend-scaffold-domain` as the single authoritative Domain-layer implementation guide. Do not maintain a second copy under the scaffold generator.
+**REQUIRED SUB-SKILL:** Use `yss-domain` as the single authoritative Domain-layer implementation guide (`references/domain-layer-guide.md`). Do not maintain a second copy under the scaffold generator.

package/template/.pi/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-domain/agents/openai.yaml

@@ -2,4 +2,4 @@ version: 1
 interface:
   display_name: "YSS Scaffold Domain"
   short_description: "YSS 后端脚手架领域层、聚合与规则建模实践落地规范"
-  default_prompt: "Use $yss-backend-scaffold-domain to implement the domain layer for a YSS backend scaffold module."
+  default_prompt: "Use $yss-domain to implement the domain layer for a YSS backend scaffold module."

package/template/.pi/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-infrastructure/SKILL.md

@@ -1,8 +1,8 @@
 ---
-name: yss-backend-scaffold-infrastructure-reference
-description: Use when the YSS DDD scaffold workflow reaches Infrastructure-layer implementation and needs the shared Infrastructure skill.
+name: yss-infrastructure-layer-reference
+description: Use when the YSS DDD scaffold workflow reaches Infrastructure-layer implementation and needs the shared Repository skill.
 ---
 
 # Infrastructure Layer Reference
 
-**REQUIRED SUB-SKILL:** Use `yss-backend-scaffold-infrastructure` as the single authoritative Infrastructure-layer implementation guide. Do not maintain a second copy under the scaffold generator.
+**REQUIRED SUB-SKILL:** Use `yss-repository` as the single authoritative Infrastructure-layer implementation guide (`references/infrastructure-layer-guide.md`). Do not maintain a second copy under the scaffold generator.

package/template/.pi/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-infrastructure/agents/openai.yaml

@@ -2,4 +2,4 @@ version: 1
 interface:
   display_name: "YSS Scaffold Infrastructure"
   short_description: "YSS 后端脚手架基础设施层与持久化实现设计落地规范"
-  default_prompt: "Use $yss-backend-scaffold-infrastructure to implement the infrastructure layer for a YSS backend scaffold module."
+  default_prompt: "Use $yss-repository to implement the infrastructure layer for a YSS backend scaffold module."

package/template/.pi/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-web/SKILL.md

@@ -1,8 +1,8 @@
 ---
-name: yss-backend-scaffold-web-reference
-description: Use when the YSS DDD scaffold workflow reaches Web-layer implementation and needs the shared Web skill.
+name: yss-web-layer-reference
+description: Use when the YSS DDD scaffold workflow reaches Web Adapter implementation and needs the shared Web Controller skill.
 ---
 
-# Web Layer Reference
+# Web Adapter Layer Reference
 
-**REQUIRED SUB-SKILL:** Use `yss-backend-scaffold-web` as the single authoritative Web-layer implementation guide. Do not maintain a second copy under the scaffold generator.
+**REQUIRED SUB-SKILL:** Use `yss-web-controller` as the single authoritative Web-layer implementation guide (`references/web-adapter-layer-guide.md`). Do not maintain a second copy under the scaffold generator.

package/template/.pi/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-web/agents/openai.yaml

@@ -2,4 +2,4 @@ version: 1
 interface:
   display_name: "YSS Scaffold Web"
   short_description: "YSS 后端脚手架 Web 层、DTO 与控制器规范"
-  default_prompt: "Use $yss-backend-scaffold-web to implement the web adapter layer for a YSS backend scaffold module."
+  default_prompt: "Use $yss-web-controller to implement the web adapter layer for a YSS backend scaffold module."

package/template/.pi/skills/yss-domain/SKILL.md

@@ -51,10 +51,15 @@ description: 用于构建或重构 YSS 领域层代码。当用户要求设计
 
 ## 协同顺序
 
+- 需要用例编排时，再接 `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`。

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

@@ -0,0 +1,274 @@
+本 Skill 提供了 YSS 数据质量管理服务 **Domain (领域层)** 的开发规范。Domain 层是系统的核心，包含业务逻辑、领域模型和接口定义。
+
+## 1. 核心职责 (Core Responsibilities)
+
+- **定义业务模型 (Model)**: 包含实体 (Entity)、值对象 (VO)、聚合根 (Aggregate Root)。
+- **定义服务接口 (Gateway/Service)**: 定义与 Infrastructure 层交互的接口 (Gateway) 以及领域内部服务 (Domain Service)。
+- **定义数据契约 (DTO)**: 定义 Command (增删改), Query (查询), VO (视图) 等数据传输对象。
+- **业务逻辑实现**: 核心业务规则的校验和处理。
+
+## 2. 代码结构 (Code Structure)
+
+```
+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;
+
+    @NotEmpty(message = "数据库类型不能为空")
+    private List<DatabaseType> databaseType;
+
+    @NotNull(message = "模板类型不能为空")
+    private QualityRuleTemplateType templateType;
+
+    @NotNull(message = "模板规则类型不能为空")
+    private QualityType ruleType;
+
+    private String description;
+
+    @NotBlank(message = "异常SQL不能为空")
+    private String exceptionCountSql;
+
+    @NotNull
+    private String resultLabel;
+
+    private Boolean defaultFlag;
+
+    Map<String, Object> ruleTemplateParam;
+}
+```
+
+### 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;
+
+/**
+ * 数据质量规则模板查询对象
+ */
+@Getter
+@Setter
+public class QualityTemplatePage extends PageQuery {
+    /**
+     * 模板类型
+     */
+    private QualityRuleTemplateType templateType;
+
+    /**
+     * 规则类型
+     */
+    @NotNull
+    private QualityType ruleType;
+
+    /**
+     * 模板名称
+     */
+    private String templateName;
+
+    private Integer status;
+}
+```
+
+### 4.3 Gateway (网关接口)
+
+```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;
+
+/**
+ * 数据质量规则模板网关接口
+ */
+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);
+}
+```
+
+### 4.4 Domain Service (领域服务)
+
+```java
+package com.yss.quality.domain.template.service;
+
+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;
+
+/**
+ * 数据质量规则模板服务接口
+ */
+public interface QualityTemplateService {
+
+    PageResult<QualityTemplateVO> pageQualityTemplate(QualityTemplatePage query);
+
+    QualityTemplateVO getQualityTemplateById(Long id);
+
+    Long addQualityTemplate(QualityTemplateAddCmd cmd);
+
+    // 更多业务方法...
+}
+```
+
+### 4.5 Value Object (视图对象)
+
+```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;
+}
+```
+
+## 5. 注意事项 (Notes)
+
+1.  **依赖倒置**: Domain 层**不应依赖** Infrastructure 层或 Web 层。所有外部交互通过 Gateway 接口定义。
+2.  **贫血模型 vs 充血模型**: 虽然目前主要是贫血模型 (DTO/VO)，但鼓励将核心业务逻辑下沉到 Domain Model 中。
+3.  **参数校验**: 必须在 Cmd 对象中使用注解进行严格的参数校验，Gateway 实现层应进行 `@Valid` 校验。
+
+## 6. 阶段 7 合同
+
+- 领域规则、状态机和不变量必须使用 `behavior-tdd`；只允许 DTO/VO/接口等机械骨架使用受控生成。
+- 消费批准后的合同和 work unit，写入允许路径，并返回统一 `YSS Skill Execution Result`。
+- 发现新的状态机、权限、数据模型、API 或跨上下文影响时返回 `new_impacts` 并暂停。

package/template/.pi/skills/yss-microapp-commit/SKILL.md

@@ -5,6 +5,8 @@ description: Use when committing or analyzing changes in a YSS micro-frontend ap
 
 # 微应用提交规范 Skill
 
+目录与锁文件身份是 `yss-microapp-commit`；Agent 发现名是 `microapp-commit`。二者指向同一技能，注册表以 alias 对齐。
+
 ## 📋 目标
 
 帮助 AI 为微应用项目生成符合 **Conventional Commits** 规范的 Git 提交信息，支持智能分析变更内容并处理复杂提交场景。