create-yss-spec 2.1.9 → 2.1.11

package/template/.trae/skills/yss-repository/references/infrastructure-layer-guide.md

@@ -0,0 +1,192 @@
+本 Skill 提供了 YSS **Infrastructure (基础设施层)** 的通用开发规范。Infrastructure 层负责实现 Domain 层定义的网关接口，处理数据持久化、外部服务调用和配置管理。
+
+## 1. 核心职责 (Core Responsibilities)
+
+- **实现网关接口 (Gateway Implementation)**: 实现 Domain 层定义的 `Gateway` 接口。
+- **数据持久化 (Persistence)**: 定义 `Repository` 接口和 `PO` (Persistent Object) 实体，操作数据库。
+- **对象转换 (Conversion)**: 使用 MapStruct 实现 PO 与 Domain Model/DTO 之间的转换。
+- **外部适配 (External Adapters)**: 集成外部服务 (如文件存储、消息队列)。
+
+## 2. 代码结构 (Code Structure)
+
+```
+com.yss.{module}.repository
+├── entity                  # 持久化对象 (PO)
+├── gateway.impl            # Domain Gateway 接口实现
+├── convertor               # MapStruct 转换器
+├── util                    # 工具类
+└── {Domain}Repository.java # MyBatis Plus Repository 接口
+```
+
+## 3. 开发规范 (Development Guidelines)
+
+### 3.1 持久化对象 (PO)
+
+- **命名**: `DomainName` + `PO` (e.g., `QualityTemplatePO`)。
+- **继承**: 推荐继承 `AuditableEntity` 以自动处理审计字段 (`created_by`, `created_date` 等)，但非强制要求。
+- **注解**:
+  - `@TableName("t_table_name")`: 指定数据库表名。
+  - `@TableId(value = "id", type = IdType.ASSIGN_ID)`: 指定主键策略 (雪花算法)。
+  - `@TableField("column_name")`: 指定字段映射。
+  - 按 `lombok` skill 选择最小注解；PO 默认使用 `@Getter` / `@Setter`，不得无条件使用 `@Data`。继承基类时再审查 `equals/hashCode/toString` 风险。
+
+### 3.2 Repository 接口
+
+- **继承**: `com.yss.cloud.mybatis.support.BasePlusRepository<PO>`。
+- **位置**: 直接位于 `com.yss.{module}.repository` 包下。
+- **Mapper XML**: 对应的 XML 文件位于 `src/main/resources/mappers`。
+
+### 3.3 Gateway 实现
+
+- **位置**: `com.yss.{module}.repository.gateway.impl`。
+- **注解**: `@Repository` 或 `@Service`。
+- **依赖注入**: 使用 `@RequiredArgsConstructor` (Lombok) 或 `@Autowired` 注入 Repository。
+- **查询逻辑**: 使用 `Wrappers.lambdaQuery()` 构建类型安全的查询条件。
+- **分页处理**: 使用 `PageUtil.page(query)` 构建分页对象，返回 `PageResult.of(...)`。
+
+### 3.4 对象转换 (Convertor)
+
+- **工具**: MapStruct。
+- **位置**: `com.yss.{module}.repository.convertor`。
+- **命名**: `DomainName` + `Convertor` (e.g., `QualityTemplateConvertor`)。
+- **规范**: 定义 `INSTANCE` 常量，使用 `Mappers.getMapper(...)` 获取实例。
+
+## 4. 详细案例 (Detailed Examples)
+
+### 4.1 Persistent Object (PO)
+
+```java
+package com.yss.quality.repository.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableField;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Getter;
+import lombok.Setter;
+import lombok.EqualsAndHashCode;
+
+@Getter
+@Setter
+@EqualsAndHashCode(callSuper = true)
+@TableName("t_quality_template")
+public class QualityTemplatePO extends AuditableEntity {
+
+    @TableId(value = "id", type = IdType.ASSIGN_ID)
+    private Long id;
+
+    @TableField("template_name")
+    private String templateName;
+
+    @TableField("template_code")
+    private String templateCode;
+
+    @TableField("status")
+    private Integer status;
+}
+```
+
+### 4.2 Repository Interface
+
+```java
+package com.yss.quality.repository;
+
+import com.yss.cloud.mybatis.support.BasePlusRepository;
+import com.yss.quality.repository.entity.QualityTemplatePO;
+
+public interface QualityTemplateRepository extends BasePlusRepository<QualityTemplatePO> {
+}
+```
+
+### 4.3 Gateway Implementation
+
+```java
+package com.yss.quality.repository.gateway.impl;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.core.metadata.IPage;
+import com.baomidou.mybatisplus.core.toolkit.Wrappers;
+import com.yss.cloud.dto.result.PageResult;
+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.repository.QualityTemplateRepository;
+import com.yss.quality.repository.convertor.QualityTemplateConvertor;
+import com.yss.quality.repository.entity.QualityTemplatePO;
+import com.yss.quality.repository.util.PageUtil;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Repository;
+import org.springframework.util.StringUtils;
+
+import java.util.List;
+
+@Repository
+@RequiredArgsConstructor
+public class QualityTemplateGatewayImpl implements QualityTemplateGateway {
+
+    private final QualityTemplateRepository qualityTemplateRepository;
+
+    @Override
+    public PageResult<QualityTemplateVO> pageQualityTemplate(QualityTemplatePage query) {
+        LambdaQueryWrapper<QualityTemplatePO> wrapper = Wrappers.lambdaQuery(QualityTemplatePO.class);
+
+        // 构建查询条件
+        if (StringUtils.hasText(query.getTemplateName())) {
+            wrapper.like(QualityTemplatePO::getTemplateName, query.getTemplateName());
+        }
+        if (query.getStatus() != null) {
+            wrapper.eq(QualityTemplatePO::getStatus, query.getStatus());
+        }
+
+        wrapper.orderByDesc(QualityTemplatePO::getCreatedDate);
+
+        // 执行分页查询
+        IPage<QualityTemplatePO> result = qualityTemplateRepository.selectPage(PageUtil.page(query), wrapper);
+
+        // 转换结果
+        List<QualityTemplateVO> records = QualityTemplateConvertor.INSTANCE.toQualityTemplateVOList(result.getRecords());
+
+        return PageResult.of(
+                records,
+                result.getTotal(),
+                result.getSize(),
+                result.getCurrent()
+        );
+    }
+}
+```
+
+### 4.4 Convertor (MapStruct)
+
+```java
+package com.yss.quality.repository.convertor;
+
+import com.yss.quality.client.vo.QualityTemplateVO;
+import com.yss.quality.repository.entity.QualityTemplatePO;
+import org.mapstruct.Mapper;
+import org.mapstruct.factory.Mappers;
+
+import java.util.List;
+
+@Mapper
+public interface QualityTemplateConvertor {
+    QualityTemplateConvertor INSTANCE = Mappers.getMapper(QualityTemplateConvertor.class);
+
+    QualityTemplateVO toQualityTemplateVO(QualityTemplatePO po);
+
+    List<QualityTemplateVO> toQualityTemplateVOList(List<QualityTemplatePO> pos);
+}
+```
+
+## 5. 注意事项 (Notes)
+
+1.  **AuditableEntity**: 推荐业务 PO 继承此基类，以便自动维护审计信息。
+2.  **Lombok 使用**: 使用 `@RequiredArgsConstructor` 进行构造器注入是推荐的最佳实践。
+3.  **Wrapper 使用**: 优先使用 `Wrappers.lambdaQuery()` 而不是字符串列名，以提高重构安全性。
+4.  **分页工具**: 使用 `PageUtil` 统一处理分页参数，避免手动计算 offset。
+
+## 6. 阶段 7 合同
+
+- 前置条件是批准的数据架构、Repository 策略和 Slice Contract。
+- PO/Repository/Convertor 骨架可受控生成；复杂查询、分页语义、数据源、事务、迁移和并发使用 `behavior-tdd`。
+- 返回统一 `YSS Skill Execution Result`，证据包含实际文件、集成测试、MapStruct/Lombok 配置和 `./mvnw ...` 结果。

package/template/.trae/skills/yss-router/references/boundaries.md

@@ -22,8 +22,8 @@ Default for a new page: first verify the approved product design, state matrix,
 ## Backend Boundaries
 
 - `yss-ddd-scaffold-generator`: Create a whole multi-module backend skeleton.
-- `yss-domain`: Domain modeling and domain gateway contracts.
-- `yss-backend-scaffold-application`: Application use cases, transaction boundaries, and cross-aggregate orchestration.
+- `yss-domain`: Domain modeling, domain gateway contracts, and domain-layer conventions.
+- `yss-application`: Application use cases, transaction boundaries, and cross-aggregate orchestration.
 - `yss-repository`: Persistence implementation, PO, Repository, Convertor, GatewayImpl.
 - `yss-web-controller`: REST adapter layer, request/response DTOs, VO, web convertor.
 - `yss-mybatis`: Framework behavior for MyBatis/MyBatis-Plus, BaseRepository, pagination, mapper scanning, batch, datasource issues.
@@ -39,11 +39,7 @@ Default for end-to-end backend CRUD: include Domain, Application, Infrastructure
 - `yss-audit-log`: Audit annotations, SpEL summaries, async publication, subscribers.
 - `yss-excel-mvc`: Spring MVC Excel import/export annotations and handlers.
 - `yss-distributed-id`: ID strategies, AutoIdInterceptor, Leaf/CosId/Snowflake, batch ID injection.
-- `yss-jdbc`: Hutool Db, dynamic datasource JDBC, JdbcSqlUtil, batch SQL execution.
-- `yss-dictionary`: Dictionary/domain item APIs and dictionary component integration.
-- `yss-log`: DEBUG request-parameter/success-latency logging, starter auto-configuration, and centralized collection; current `CatchAndLog` is not exception logging.
 - `yss-resilience4j`: Circuit breaker, fallback, and gateway resilience integration.
-- `yss-taskflow`: Task flow definition/execution component behavior.
 - `yss-validation`: Validation engine and JSR-303 integration.
 - `yss-security-algorithm`: RSA/AES/SM/JWT/JWK/password-encoding compatibility and production key-management safety gates.
 - `yss-userinfo`: Current-user info propagation and starter integration.

package/template/.trae/skills/yss-router/references/router-contract.yaml

@@ -1,6 +1,9 @@
 schema_version: 1
 allowed_statuses: [draft, blocked, ready-for-lifecycle-review]
 forbidden_statuses: [approved, ready-for-agent, completed]
+skill_aliases:
+  api-integration: yss-api-integration
+  microapp-commit: yss-microapp-commit
 implementation_path_policy:
   applies_to: harness-resident-runtime-code
   project_roots:
@@ -120,24 +123,22 @@ dependency_closure:
   yss-ddd-scaffold-generator:
     always: [yss-backend-scaffold-parent, alibaba-java-code-style]
   yss-domain:
-    always: [yss-backend-scaffold-domain, alibaba-java-code-style]
+    always: [alibaba-java-code-style]
     when_modeling: [domain-modeling]
     when_pojo: [lombok]
-  yss-backend-scaffold-application:
+  yss-application:
     always: [alibaba-java-code-style]
     when_conversion: [mapstruct, lombok]
   yss-repository:
-    always: [yss-backend-scaffold-infrastructure, mapstruct, lombok, alibaba-java-code-style]
+    always: [mapstruct, lombok, alibaba-java-code-style]
     when_mybatis: [yss-mybatis]
   yss-web-controller:
-    always: [yss-dto, yss-backend-scaffold-web, mapstruct, lombok, alibaba-java-code-style]
+    always: [yss-dto, mapstruct, lombok, alibaba-java-code-style]
   yss-userinfo:
     always: [yss-dto]
     when_cache_lookup: [yss-cache]
   yss-audit-log:
     always: [yss-userinfo, yss-dto]
-  yss-log:
-    always: []
   yss-validation:
     always: [yss-exception]
   yss-security-algorithm:
@@ -156,7 +157,6 @@ component_impact_values:
   - current-user-context
   - user-cache-lookup
   - audit-event
-  - technical-request-logging
   - request-validation
   - error-mapping
   - encryption-or-signing
@@ -165,20 +165,16 @@ component_impact_routing:
   current-user-context: [yss-userinfo]
   user-cache-lookup: [yss-userinfo, yss-cache]
   audit-event: [yss-audit-log, yss-userinfo, yss-dto]
-  technical-request-logging: [yss-log]
   request-validation: [yss-validation, yss-exception]
   error-mapping: [yss-exception, yss-dto]
   encryption-or-signing: [yss-security-algorithm, yss-exception]
 
 end_to_end_backend_required:
   - yss-domain
-  - yss-backend-scaffold-domain
-  - yss-backend-scaffold-application
+  - yss-application
   - yss-repository
-  - yss-backend-scaffold-infrastructure
   - yss-web-controller
   - yss-dto
-  - yss-backend-scaffold-web
   - mapstruct
   - lombok
   - alibaba-java-code-style

package/template/.trae/skills/yss-source-index/references/source-map-config.md

@@ -12,11 +12,7 @@ The refresh script maps component source path hints to skill references. These p
 | `yss-audit-log` | `yss-microservice-components/yss-component-audit-log` |
 | `yss-excel-mvc` | `yss-microservice-components/yss-component-excel-mvc`, `yss-microservice-components/yss-component-excel-starter` |
 | `yss-distributed-id` | `yss-microservice-components/yss-component-distributed-id`, `yss-microservice-components/yss-component-leaf` |
-| `yss-jdbc` | `yss-microservice-components/yss-component-jdbc` |
-| `yss-dictionary` | `yss-microservice-components/yss-component-dictionary-parent` |
-| `yss-log` | `yss-microservice-components/yss-component-log-starter` |
 | `yss-resilience4j` | `yss-microservice-components/yss-component-resilience4j-starter` |
-| `yss-taskflow` | `yss-microservice-components/yss-component-taskflow` |
 | `yss-validation` | `yss-microservice-components/yss-component-validation-engine-parent`, `yss-microservice-components/yss-component-validation-jsr303` |
 | `yss-security-algorithm` | `yss-microservice-components/yss-component-security-algorithm` |
 | `yss-userinfo` | `yss-microservice-components/yss-component-userinfo-starter` |

package/template/.trae/skills/yss-source-index/scripts/refresh-yss-skill-index.mjs

@@ -5,7 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-const BACKEND = {"yss-cache":["yss-microservice-components/yss-component-cache-parent"],"yss-mybatis":["yss-microservice-components/yss-component-persistence"],"yss-dto":["yss-microservice-components/yss-component-dto"],"yss-audit-log":["yss-microservice-components/yss-component-audit-log"],"yss-excel-mvc":["yss-microservice-components/yss-component-excel-mvc","yss-microservice-components/yss-component-excel-starter"],"yss-distributed-id":["yss-microservice-components/yss-component-distributed-id","yss-microservice-components/yss-component-leaf"],"yss-jdbc":["yss-microservice-components/yss-component-jdbc"],"yss-dictionary":["yss-microservice-components/yss-component-dictionary-parent"],"yss-log":["yss-microservice-components/yss-component-log-starter"],"yss-resilience4j":["yss-microservice-components/yss-component-resilience4j-starter"],"yss-taskflow":["yss-microservice-components/yss-component-taskflow"],"yss-validation":["yss-microservice-components/yss-component-validation-engine-parent","yss-microservice-components/yss-component-validation-jsr303"],"yss-security-algorithm":["yss-microservice-components/yss-component-security-algorithm"],"yss-userinfo":["yss-microservice-components/yss-component-userinfo-starter"],"yss-exception":["yss-microservice-components/yss-component-exception"]};
+const BACKEND = {"yss-cache":["yss-microservice-components/yss-component-cache-parent"],"yss-mybatis":["yss-microservice-components/yss-component-persistence"],"yss-dto":["yss-microservice-components/yss-component-dto"],"yss-audit-log":["yss-microservice-components/yss-component-audit-log"],"yss-excel-mvc":["yss-microservice-components/yss-component-excel-mvc","yss-microservice-components/yss-component-excel-starter"],"yss-distributed-id":["yss-microservice-components/yss-component-distributed-id","yss-microservice-components/yss-component-leaf"],"yss-resilience4j":["yss-microservice-components/yss-component-resilience4j-starter"],"yss-validation":["yss-microservice-components/yss-component-validation-engine-parent","yss-microservice-components/yss-component-validation-jsr303"],"yss-security-algorithm":["yss-microservice-components/yss-component-security-algorithm"],"yss-userinfo":["yss-microservice-components/yss-component-userinfo-starter"],"yss-exception":["yss-microservice-components/yss-component-exception"]};
 const FRONTEND={"yss-ui":["components","hooks","skills"],"yss-components":["components"],"yss-hook":["hooks"],"yss-page-module-development":["components","hooks","skills"],"yss-use-table-height":["hooks"],"yss-use-tree-height":["hooks"]};
 const URLS={components:"http://192.168.164.27:3200/components",hooks:"http://192.168.164.27:3200/hooks",skills:"http://192.168.164.27:3200/skills"};
 const KEYS=["Audit","Cache","Clear","Command","Configuration","Controller","DTO","Data","Enable","Excel","Handler","Interceptor","Jdbc","Mapper","Mybatis","Page","Properties","Query","Repository","Request","Response","Result","Update","Aspect","Leaf","Id","Dir","Dic","Dictionary","File","Upload","Log","Message","Mail","Liquibase","Circuit","Breaker","Sql","Tpl","Tag","Task","Flow","Report","Validation","Validator","Security","Crypto","User","Variable","Quality","Search","Similarity","Scheduler","Runner","Duck","Dynamic","Factory","Client","Feign","Gateway","Convertor","Adapter","Advice","Bridge","Route","Uploader","Sftp","Minio","Parser","Express","Rule","Template","Generator","Importer","Engine","Event","Submitter","Executor","Context","Status","Type","State"];

package/template/.trae/skills/yss-web-controller/SKILL.md

@@ -63,6 +63,7 @@ node scripts/generate_controller.mjs \
 
 ## 按需读取
 
+- 分层开发规范：`references/web-adapter-layer-guide.md`
 - 生成脚本：`scripts/generate_controller.mjs`
 - Controller 模板：`assets/templates/Controller.java.template`
 - Convertor 模板：`assets/templates/WebConvertor.java.template`

package/template/.trae/skills/yss-web-controller/references/web-adapter-layer-guide.md

@@ -0,0 +1,168 @@
+本技能为开发 YSS 服务的**Web 适配器层**（REST API）提供指导和框架。
+Web 适配器负责通过 HTTP 公开业务功能、处理输入验证和格式化响应。
+
+## 1. 核心职责 (Core Responsibilities)
+
+- **Request Handling**: Map HTTP requests (GET, POST, PUT, DELETE) to Java methods.
+- **Input Validation**: Validate request bodies and parameters using JSR-303/380 annotations (`@Valid`, `@NotNull`, etc.).
+- **Response Formatting**: Wrap business results into standard `Result` objects (`SingleResult`, `PageResult`, `MultiResult`).
+- **Orchestration Delegation**: Delegate business logic to the **Application Service**. Simple queries can be delegated directly to the **Domain Gateway** (CQRS pattern).
+
+## 2. 代码结构 (Code Structure)
+
+Web Adapters are typically located in the `bootstrap` module or a dedicated `web` module.
+
+```
+com.yss.{module}.rest
+├── {Domain}Controller.java      # Main REST Controller
+└── {Domain}ReportController.java # Optional: For reporting/stats APIs
+```
+
+## 3. 开发规范 (Development Guidelines)
+
+### 3.1 Controller 定义
+
+- **注解**: 使用 `@RestController`。
+- **路径**: `@RequestMapping("/api/{module}/{domain}")` (e.g., `/api/quality/rule`).
+- **依赖注入**: 使用 Lombok `@RequiredArgsConstructor` 进行构造器注入。
+- **命名**: `{Domain}Controller` (e.g., `QualityRuleController`).
+
+### 3.2 依赖注入原则
+
+- **写操作/复杂逻辑**: 必须注入 **Application Service** (`XxxService`)。
+- **读操作 (Query)**: 允许直接注入 **Domain Gateway** (`XxxGateway`) 以减少样板代码 (CQRS)。
+
+### 3.3 参数与响应
+
+- **Command (写)**: 使用 `@PostMapping`/`@PutMapping` + `@RequestBody` + `{Domain}Cmd` 对象。
+- **Query (读)**: 使用 `@PostMapping` (for complex search) + `@RequestBody` + `{Domain}Page/Query` 对象。
+- **Wrapper**:
+  - `SingleResult<T>`: 单个对象或基本类型。
+  - `MultiResult<T>`: 列表。
+  - `PageResult<T>`: 分页数据。
+- **Validation**: 必须在参数前添加 `@Valid` 注解。
+
+### 3.4 异常处理
+
+- **不要**在 Controller 中捕获通用异常 (`Exception`)。
+- 让全局异常处理器 (`GlobalExceptionHandler`) 统一处理运行时异常。
+- 仅在需要特定 HTTP 状态码转换时捕获特定异常。
+
+## 4. 代码示例 (Code Examples)
+
+### 4.1 标准 CRUD Controller
+
+```java
+package com.yss.{module}.rest;
+
+import com.yss.cloud.dto.result.MultiResult;
+import com.yss.cloud.dto.result.PageResult;
+import com.yss.cloud.dto.result.SingleResult;
+import com.yss.{module}.client.dto.cmd.{Domain}AddCmd;
+import com.yss.{module}.client.dto.cmd.{Domain}UpdateCmd;
+import com.yss.{module}.client.dto.cmd.{Domain}StatusCmd;
+import com.yss.{module}.client.dto.query.{Domain}Page;
+import com.yss.{module}.client.vo.{Domain}VO;
+import com.yss.{module}.core.service.{Domain}Service;
+// Optional: Import Gateway for direct queries
+// import com.yss.{module}.domain.gateway.{Domain}Gateway;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.*;
+
+import javax.validation.Valid;
+
+/**
+ * {Domain} 管理控制器
+ *
+ * @author {User}
+ */
+@RestController
+@RequestMapping("/api/{module}/{domain-path}")
+@RequiredArgsConstructor
+public class {Domain}Controller {
+
+    private final {Domain}Service {domainVar}Service;
+    // private final {Domain}Gateway {domainVar}Gateway; // For CQRS if needed
+
+    /**
+     * 分页查询 {Domain}
+     *
+     * @param query 查询条件
+     * @return 分页结果
+     */
+    @PostMapping("/page")
+    public PageResult<{Domain}VO> page(@Valid @RequestBody {Domain}Page query) {
+        return {domainVar}Service.page(query);
+    }
+
+    /**
+     * 根据ID查询详情
+     *
+     * @param id 主键ID
+     * @return 详情对象
+     */
+    @GetMapping("/detail/{id}")
+    public SingleResult<{Domain}VO> detail(@PathVariable String id) {
+        return SingleResult.of({domainVar}Service.detail(id));
+    }
+
+    /**
+     * 新增 {Domain}
+     *
+     * @param cmd 新增命令
+     * @return 新增结果 (通常是ID或完整对象)
+     */
+    @PostMapping
+    public SingleResult<Long> add(@Valid @RequestBody {Domain}AddCmd cmd) {
+        return SingleResult.of({domainVar}Service.add(cmd));
+    }
+
+    /**
+     * 更新 {Domain}
+     *
+     * @param cmd 更新命令
+     * @return 更新结果
+     */
+    @PutMapping
+    public SingleResult<Boolean> update(@Valid @RequestBody {Domain}UpdateCmd cmd) {
+        {domainVar}Service.update(cmd);
+        return SingleResult.of(true);
+    }
+
+    /**
+     * 状态变更 (启用/禁用)
+     *
+     * @param cmd 状态命令
+     * @return 变更后的状态
+     */
+    @PostMapping("/enabled")
+    public SingleResult<Integer> switchStatus(@Valid @RequestBody {Domain}StatusCmd cmd) {
+        {domainVar}Service.switchStatus(cmd);
+        return SingleResult.of(cmd.getStatus());
+    }
+}
+```
+
+### 4.2 复杂业务操作示例
+
+```java
+    /**
+     * 执行业务操作 (e.g. 立即运行检查)
+     *
+     * @param cmd 执行命令
+     * @return 执行结果ID
+     */
+    @PostMapping("/execute")
+    public SingleResult<String> execute(@Valid @RequestBody {Domain}ExecuteCmd cmd) {
+        // 调用 Service 处理复杂业务逻辑
+        return SingleResult.of(
+                {domainVar}Service.execute(cmd)
+        );
+    }
+```
+
+## 5. 阶段 7 合同
+
+- 只消费冻结 OpenAPI/no-impact record 和批准合同；Controller 不得穿透 Application/Domain 边界。
+- Controller/DTO/Convertor 骨架可受控生成；权限、校验、错误映射和接口行为使用 `behavior-tdd`。
+- 返回统一 `YSS Skill Execution Result`，包含代码、契约/API 测试、实际验证和新增 API/权限影响。

package/template/AGENTS.md

@@ -22,6 +22,7 @@
 | 影响面触发与 `not-applicable` | `docs/process/harness-process-tailoring.md` |
 | 模板维护强度触发与最低等级 | `docs/process/maintenance-intensity.yaml` |
 | 技能清单、来源、版本、哈希和投影目标      | `skills-lock.json`                          |
+| 技能分层、别名、默认可发现性和运行时入口 | `docs/agents/yss-skill-registry.yaml`（当前 `status: shadow`，不作为 Router / 生命周期运行时入口） |
 
 README、用户指南和其他说明文档只引用或解释上述事实，不重复定义同一规则。
 
@@ -37,7 +38,7 @@ README、用户指南和其他说明文档只引用或解释上述事实，不
 按“影响面 → 单一事实来源 → 投影 / 派生资产 → 分级证据”维护。强度分级、最低证据和 checkpoint 合同见 `docs/process/harness-process-tailoring.md`。
 
 - 创建、修改或退役 skill 时使用 `maintaining-skills`，并先按 `docs/process/harness-process-tailoring.md` 判定 L1 / L2 / L3；只有 L3 必须保留完整基线失败、压力场景、修订后验证和正式独立审查证据。
-- `.agents/skills` 是跨 Agent 共享技能的权威内容；`.claude/skills`、`.codex/skills`、`.hermes/skills`、`.pi/skills`、`.qoder/skills`、`.trae/skills` 中的共享技能是生成投影，禁止分别手工修改。
+- `.agents/skills` 是跨 Agent 共享技能的权威内容；`.claude/skills`、`.codex/skills`、`.cursor/skills`、`.hermes/skills`、`.pi/skills`、`.qoder/skills`、`.trae/skills` 中的共享技能是生成投影，禁止分别手工修改。Cursor 的契约运行时入口是 `.cursor/skills`；不得把 canonical `.agents/skills` 与某个平台投影当作同权双入口。
 - `scripts/verify-template` 是模板发布阻断门禁。模板与外部 `create-yss-spec` 的跨仓库契约未完成集成验证时，不得声称可发布。
 
 ## 5. `project-instance` 产品研发路由
@@ -47,10 +48,10 @@ README、用户指南和其他说明文档只引用或解释上述事实，不
 - 生命周期注册表中的条件门禁全部按影响面强制。命中触发条件时必须完成；未命中时只记录 `not-applicable` 及原因，不生成空文档；不得把产物、工作单元或证据统称为门禁。
 - 安全 / 权限不设独立生命周期资料或专属门禁。日常功能不做额外登记、`not-applicable` 或推导校验；只有需求或冻结资产明确要求改变认证、授权、租户隔离、敏感数据或合规行为时，才把该行为写入普通 Spec、API、架构、验收和测试 seam，并仅按实际 UI、API、Backend、Data、High-risk 影响触发既有门禁。普通 action 注册、沿用既有认证中间件、未变化的 `401` / `403`、一般字段、SQL / DDL / 迁移和上传 / 下载本身不构成安全 / 权限专项。
 - `seam-deferred` 只能显式记录风险、责任人、后续 Ticket、验证计划和目标版本或发布日期。
-- 新功能或较大变更先用 `grill-with-docs` 澄清，再用 `to-spec` 形成 Spec；Spec 基线和产品设计影响的完整判定以注册表和裁剪规则为准。
+- 新功能或较大变更先进入 `yss-product-lifecycle` 的原生 Discovery / 需求分析工作单元；`grill-with-docs` 与 `to-spec` 仅作为用户显式兼容入口，Spec 基线和产品设计影响的完整判定以注册表和裁剪规则为准。
 - API 契约变更先形成 OpenAPI 3.1 Draft，经必要的工程基线、系统 / 数据架构和设计审查后 Freeze，再进入实现。
 - Spec Delta 只记录相对既有冻结 Spec 基线的高风险行为差异；全新产品、全新模块和低风险调整不生成 Spec Delta。
-- OpenAPI Freeze 或无 API 影响记录完成后，使用 `to-tickets` 拆成可独立验证的窄垂直切片，禁止只按 Adapter / Application / Domain / Infrastructure 横向拆分。
+- OpenAPI Freeze 或无 API 影响记录完成后，由生命周期原生 Ticket 正式化工作单元拆成可独立验证的窄垂直切片；用户显式 `to-tickets` 仅作为兼容入口，禁止只按 Adapter / Application / Domain / Infrastructure 横向拆分。
 
 ## 6. Ticket 与状态
 
@@ -105,3 +106,15 @@ README、用户指南和其他说明文档只引用或解释上述事实，不
 ## 12. 测试质量基线
 
 模板推荐值为 Domain / Application `>= 90%`、API `>= 80%`、前端组件 `>= 75%`、已明确的关键流程 `100% E2E`。只有项目实例在测试策略中明确采纳或覆盖后才构成 CI 门禁；未定义关键流程清单时，不声称其 E2E 覆盖率达到 100%。
+
+## Cursor Cloud specific instructions
+
+本仓库是 `template-source` Harness / 研发管理仓库，没有前端 / 后端运行时应用；可运行、可测试的表面只有 Node 工具链与治理校验脚本。
+
+- 依赖与工具链：Node `>=22 <27`（`.nvmrc` 固定 22）；`pnpm` 通过 `packageManager` 字段由 corepack 自动切换到 `10.15.0`，无需手工切换。Node 依赖只装在 `.template-source/tooling/node`，仓库根没有 `package.json`。
+- 测试：`pnpm --dir .template-source/tooling/node test`（`node --test`，共 15 个用例）。
+- 构建 / lint：`pnpm --dir .template-source/tooling/node build:vendor` 与 `check:vendor` 维护 `scripts/vendor/*.mjs`；顶层 lint 是 `verify-template` 内对所有脚本执行的 `node --check`。
+- 完整发布门禁（相当于"运行应用"）：`scripts/verify-template`，成功输出 `模板发布校验通过`。它串联证据索引、`pnpm test`、`check:vendor` 和全部 `scripts/verify-*` 场景校验。
+- 非显然的坑：`scripts/verify-lifecycle-registry`（及其对应测试 `Node lifecycle registry verifier ...`）会 shell out 到 `python3` 并 `import jsonschema` 做 JSON Schema 校验。缺少该 Python 模块时测试会以 `ModuleNotFoundError: No module named 'jsonschema'` 失败，而不是代码问题；update script 已负责 `pip3 install jsonschema`。
+- `pnpm install` 输出的 `Ignored build scripts: esbuild` 警告可忽略：esbuild 0.28.2 在本平台自带二进制，`build:vendor` / `check:vendor` 无需 `pnpm approve-builds`。
+- 常用只读入口：`scripts/repository-mode`（返回仓库身份）、`scripts/generate-lifecycle-artifacts`（从 `docs/process/lifecycle-registry.yaml` 派生产物，输出应无 diff）、`scripts/export-yss-skills --output <dir>`（导出公开技能）。

package/template/CONTEXT.md

@@ -10,6 +10,8 @@
 | Agent 入口规则 | Agent 启动任务时必须先遵守的全局路由、硬门禁和禁止事项。 | 不作为 YSS 后端、前端或其他专项编码规范的完整手册。 |
 | 标准文档语言 | 面向业务、产品、架构、实施、审查、发布和复盘的持久化文档所使用的默认语言。 | 统一使用简体中文；英文专有名词、代码标识、API 路径、schema、文件名和协议 metadata 保持原样。 |
 | Matt Engineering Skills | 来自 `mattpocock/skills` 的轻量工程流程技能集合。 | 用于澄清、Spec、Ticket、实现、TDD、诊断、审查和架构治理，不替代 YSS 专项规范。 |
+| 上游技能基线 | 从外部技能源锁定的可追溯 revision 及其未经项目适配的原始内容。 | 不等同于项目当前实际生效的 skill；上游更新不得直接覆盖 YSS 适配。 |
+| YSS 技能适配 | 在上游技能基线之上，为 YSS 仓库身份、门禁、状态、授权和专项规范保留的可追溯差异。 | 必须同时保留上游内容哈希、有效内容哈希和适配依据，不作无记录的直接 fork。 |
 | YSS skills | 本项目内置的 YSS 工程规范技能。 | 用于 DDD、UI、OpenAPI、Repository、Controller、DTO、组件和编码规范。 |
 | 技能投影 | 从权威共享技能生成、供特定 Agent root 加载的同步副本。 | 投影不是独立维护的技能源，不应在各 Agent root 中分别修改。 |
 | Spec | 记录用户问题、解决方案、用户故事、关键决策、验收标准和测试 seam 的产品研发规格。 | 新资产统一使用 Spec；旧规格称谓只在迁移记录中保留。 |
@@ -26,6 +28,7 @@
 | UI 影响 | 会改变用户可见页面、导航、交互流程、状态呈现或权限体验的功能影响。 | 纯后端、API、批处理或数据变更不自动构成 UI 影响。 |
 | 产品设计影响 | UI 变化触及主流程、导航、权限体验、异常 / 恢复状态、状态流转或 API 反推，需要页面流、状态矩阵和原型校准。 | 文案、token、颜色、间距和无行为变化的孤立视觉修复属于 UI 影响，但不自动构成产品设计影响。 |
 | 高保真 HTML 原型 | 低保真原型评审通过后，用于在浏览器中审查真实视觉密度、交互状态和页面流的产品设计资产。 | 不等同于生产前端实现，也不替代 OpenAPI、Spec 校准或垂直切片。 |
+| Visual Baseline Contract | 为生产前端还原冻结页面、视口、交互状态、参考图像和允许差异的可验收合同。 | 不是仅有一张原型截图或绝对像素匹配；每个基线必须可定位到同一视口和同一状态复验。 |
 | 垂直切片（Vertical Slice） | 贯穿所有受影响层、可独立验证的窄功能路径。 | 优先使用垂直切片，避免只按层拆分的横向任务。 |
 | Slice Implementation Contract | 阶段 7 进入实现前，由 `yss-router` 根据冻结资产和垂直切片编译、再由生命周期编排器批准的实现合同，包含 Common、Frontend、Backend、Contract 和 Cross-repo 子合同。 | Router 只能生成草案，不能自行批准、设置 `ready-for-agent` 或宣布完成；Backend 子合同仍保留额外强约束。 |
 | YSS Skill Execution Result | YSS 专项 skill 完成工作单元后返回的结构化执行证据，记录合同版本、变更文件、证据文件、实际验证、延期 seam、偏离和新增影响。 | 实现者自报 `implemented` 不构成最终通过，必须由 Router、生命周期编排器和独立 Reviewer 复核。 |
@@ -44,13 +47,16 @@
 | Harness 工程 | 串联研发生命周期阶段、门禁、产物、Agent/Skill 编排和追踪证据的工程化治理载体。 | 不等同于单个 CI 流水线或零散提示词集合。 |
 | YSS 研发操作系统 | 由生命周期控制、通用工作流、YSS 专项技能、证据反馈和技能供应链共同构成的可版本化研发治理体系。 | 不等同于单个主控 skill、某个 Agent 客户端或运行时代码平台。 |
 | 生命周期注册表 | 结构化定义主阶段、门禁、产物、工作单元、证据及其稳定标识和关系的机器可读权威资产。 | Markdown 地图、数量说明和验证 fixture 是其派生产物，不应分别维护同一结构事实。 |
+| 生命周期编排器 | 持有阶段、影响面、产物状态、门禁裁决、工作单元路由和恢复条件的研发流程控制平面。 | 不替代专项技能执行业务实现，也不以文件存在或执行者自述宣布完成。 |
+| 前端实现还原验证 | 证明生产前端相对冻结 Spec、交互说明、状态矩阵和高保真原型不存在未解释差异的独立验证。 | 不是绝对像素复刻、普通 type-check 或原型评审；UI 影响切片需覆盖关键视觉、状态、交互和工程证据。 |
 | 生命周期稳定 ID | 以对象类型命名空间和英文标识唯一指向一个生命周期对象的兼容身份。 | 中文名称、展示顺序和数量可以变化；已发布 ID 不得复用来表达另一种语义。 |
 | 派生产物 | 根据生命周期注册表确定性生成的结构表、数量、索引、依赖图或测试 fixture。 | 不承载需要人工解释的原理、取舍或实践建议，禁止脱离注册表分别维护。 |
 | 核心技能（Core Skill） | 默认可发现、负责生命周期控制或通用研发入口的稳定技能。 | 不包含只在特定技术影响下才需要的专项实现规则。 |
 | 专项技能（Specialist Skill） | 由 Router 根据影响面和实现合同按需选择的前端、后端、OpenAPI 或组件技能。 | 不作为所有任务的平级默认入口。 |
-| 试验 / 兼容技能 | 尚未达到默认支持成熟度，或仅为旧流程迁移保留的受限技能。 | 必须显式授权使用，不得进入 Router 默认技能闭包。 |
+| 试验技能 | 尚未达到项目默认支持成熟度的技能。 | 只在明确试验范围内使用，不进入 Router 默认技能闭包。 |
+| 显式兼容入口 | 为已有用户操作习惯保留的 user-invoked 工作流入口，写入前由生命周期编排器预检，结果回交其验收。 | 不是默认路径、过时别名或可以越过门禁的第二套生命周期。 |
 | 技能成熟度 | 描述技能从 `draft`、`verified`、`supported` 到 `deprecated` 的治理状态。 | 不等同于文件存在、已被投影或能够安装。 |
-| 技能注册表 | 记录技能身份、别名、分层、适用影响面、成熟度、新鲜度、验证和公开状态的机器可读路由资产。 | 不替代 `skills-lock.json` 的来源、hash 和投影完整性职责。 |
+| 技能注册表 | 记录技能身份、别名、分层、适用影响面、成熟度、默认可发现性和 Agent 运行时入口的机器可读路由资产。 | 不替代 `skills-lock.json` 的来源、hash 和投影完整性职责。当前 `docs/agents/yss-skill-registry.yaml` 为 `shadow`，Router 与生命周期不得按其裁剪发现面。 |
 | 生态发布清单 | 关联模板 schema 与 commit、CLI 版本与快照、公开技能来源与导出 hash 的跨仓发布证据。 | 不要求尚未生成的仓库 commit 互相循环引用。 |
 | 研发管理仓库 | 承载 Spec、OpenAPI、架构、Ticket、验证、发布和复盘等研发管理资产的仓库。 | 不等同于前端 / 后端代码 monorepo。 |
 | 实现仓库 | 承载前端、后端或其他运行时代码及其 Git、CI、MR / PR、测试命令和发布流水线的仓库。 | 不要把实现仓库的源码所有权混入研发管理仓库。 |
@@ -59,8 +65,6 @@
 | 模板实例仓库（`project-instance`） | 由模板初始化后生成、承载某个具体产品研发生命周期资产的仓库身份。 | 不作为通用流程模板的权威来源。 |
 | 模板实例分发面 | 模板源中应随 CLI 快照进入 `project-instance` 的共享生命周期、模板、用户指南和验证资产集合。 | 不包含模板源审查、研究、发布路线或源仓库专属 ADR。 |
 | 模板源治理区 | 仅供 `template-source` 使用、保存审查证据、研究记录、跨仓契约、发布路线和源仓库治理决策的归档区域。 | 不随 CLI 分发；不等于产品实例的研发管理资产。 |
-| 目标平台单文件二进制 | 随模板快照分发、只适用于一个受支持 OS/架构组合的可执行文件。 | 不等同于跨平台通用文件，也不等同于运行时下载或 `cargo install`。 |
-| 原生模板实例运行时 | 在模板实例中执行原有治理和验证公共操作、且不依赖 Node.js 的目标平台原生运行时。 | 不等同于模板维护侧的构建工具，也不等同于仅创建模板的安装器。 |
 | 仓库身份清单 | 显式声明仓库身份和清单结构版本的机器可读资产。 | 不承载项目名称、团队规模、Tracker 或其他易变业务配置。 |
 
 只有在计划、分诊、调试或架构讨论中明确沉淀出稳定语言时，才新增术语。

package/template/README.md

@@ -11,7 +11,8 @@
 ```text
 ├── .agents/                 ← 跨 Agent 共享 skills 的权威内容
 ├── .claude/                 ← Claude skills 投影与平台专属 skills
-├── .codex/                  ← Codex skills 投影与平台专属 YSS skills
+├── .codex/                  ← Codex skills 投影与平台专属 skills
+├── .cursor/                 ← Cursor skills 投影
 ├── .hermes/                 ← Hermes skills 投影与平台专属 skills
 ├── .pi/                     ← Pi skills 投影与平台专属 skills
 ├── .qoder/                  ← Qoder skills 投影与平台专属 skills

package/template/docs/adr/0007-lifecycle-native-work-units.md

@@ -0,0 +1,5 @@
+# ADR-0007: 生命周期使用原生工作单元并保留 Matt 兼容入口
+
+`yss-product-lifecycle` 作为 YSS 研发生命周期的唯一默认入口，持有阶段、产物状态、门禁和正式资产所有权。Spec 综合、Ticket 正式化和切片实现使用生命周期注册表中的原生工作单元；`to-spec`、`to-tickets`、`implement` 保留为用户显式调用的兼容输入，结果必须回交生命周期验收，生命周期不得自动调用这些 user-invoked skills。
+
+该选择避免用户手动记忆阶段切换，也避免 Matt 默认的 `ready-for-agent`、commit 等行为越过 YSS 门禁和授权。代价是生命周期需要维护原生工作单元路由和兼容适配，但两者在 `work_unit_routes` 中共享一个稳定工作单元身份、使用互斥的 `native` / `compatibility` 路由，不再形成两套执行定义。

package/template/docs/agents/README.md

@@ -6,9 +6,10 @@
 
 | 路径 | 用途 |
 |---|---|
-| `.agents/` | Agent 可加载的 Engineering Skills、脚本、prompt 和参考材料 |
-| `.codex/skills/` | Codex 项目级 skills，包含 YSS、Matt、Ticket 等能力 |
-| `docs/agents/` | 人和 AI 都可读的协作说明、标签约定、维护规范 |
+| `.agents/` | 共享技能的权威内容 |
+| `.cursor/skills/` | Cursor 的契约运行时投影 |
+| `.codex/skills/` | Codex 投影与平台专属 skills |
+| `docs/agents/` | 人和 AI 都可读的协作说明、标签约定、维护规范和技能路由注册表 |
 
 ## 当前文档
 
@@ -18,6 +19,7 @@
 | `triage-labels.md` | 标准五态 triage 标签与含义 |
 | `domain.md` | 领域文档读取和维护规则 |
 | `skills-maintenance.md` | Engineering Skills 的安装、升级和验证说明 |
+| `yss-skill-registry.yaml` | 技能分层、别名与运行时入口（shadow，不替代锁文件） |
 | `gitlab-workflow-skills.md` | GitLab、MR、CI 和自动 gitworks 的技能配置与使用规则 |
 
-当 `AGENTS.md` 或某个 skill 提到本目录时，应优先把这里当作项目协作规则读取；真正的 skill 执行入口仍在 `.agents/` 或 `.codex/skills/`。
+当 `AGENTS.md` 或某个 skill 提到本目录时，应优先把这里当作项目协作规则读取；真正的 skill 执行入口是各平台投影根，Cursor 为 `.cursor/skills`。