create-yss-spec 2.2.9 → 3.0.0

package/template/.cursor/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-adapter/SKILL.md

@@ -1,199 +1,31 @@
 ---
-name: "yss-backend-scaffold-adapter"
-description: "YSS 后端开发脚手架的适配器层开发框架和技术指南。在实现 Web 控制器、调度器或外部系统适配器时调用。"
+name: yss-backend-scaffold-adapter
+description: Use when the YSS DDD scaffold workflow reaches Web, scheduler, or external-adapter implementation and needs the shared target-profile skills.
 ---
 
-# Adapter Layer Development Guide
+# Adapter Layer Reference
 
-本技能为开发 YSS 后端开发脚手架服务的**适配器层**（接口层）提供指导和框架。
-适配器层负责处理外部请求（HTTP、计划任务），并将其适配到应用层，以及为外部系统（连接器、执行器）实现插件式适配器。
+本文件只负责从脚手架路由到共享权威技能，不维护第二套 Adapter 规范。
 
-## 1. 核心职责 (Core Responsibilities)
+## Web Adapter
 
-The Adapter Layer serves as the entry point and integration point of the system:
+**REQUIRED SUB-SKILL:** 使用 `yss-web-controller` 作为 Web Adapter 的唯一实现指南，并同时消费 `yss-dto`、`yss-exception`：
 
-- **Web Adapter (REST API)**: Handles HTTP requests, validates input, calls Application Services, and formats responses (standard `Result` wrappers).
-- **Job Adapter (Scheduler)**: Adapts scheduled task triggers (e.g., DolphinScheduler, Quartz) to Application logic.
-- **SPI Adapter (Plugins)**: Implements specific technical adapters defined by the Domain or Application layer (e.g., specific Database Connectors, Rule Executors).
+- HTTP Request / Response DTO 默认位于 Web module。
+- Controller 只调用 Application Service，不直连 Domain Gateway 或 Infrastructure。
+- 映射链固定为 Web DTO → Spring MapStruct WebConvertor → Application Command / Query / Result → Domain。
+- HTTP/YSS wrapper/异常脱敏在 Web 边界完成；Domain 只表达领域错误语义。
 
-## 2. 代码结构 (Code Structure)
+## Scheduler / External Adapter
 
-Depending on the module type (Web Application or Plugin), the structure varies:
+- Adapter 只做协议、调度器或外部系统适配，不承载领域规则。
+- 输入先转换为 Application Command / Query，再调用 Application Service。
+- 若实现 Application 或 Domain 声明的端口，端口签名不得泄漏 HTTP DTO、PO、Mapper、第三方 SDK 类型。
+- 具体持久化端口实现继续使用 `yss-repository`；不得把 Repository 规则复制到本文件。
 
-### 2.1 Web Adapter (Usually in `bootstrap` or `web` module)
+## 禁止事项
 
-```
-com.yss.{module}.rest
-├── {Domain}Controller.java      # REST API 控制器
-└── {Domain}ReportController.java # 报表/统计类控制器
-```
-
-### 2.2 Scheduler Adapter (In `adapter/scheduler` module)
-
-```
-com.yss.{module}.scheduler
-└── {Domain}ScheduleServiceImpl.java # 调度服务实现 (实现 API 接口)
-```
-
-### 2.3 Plugin Adapter (In `adapter/connector` or `adapter/executor` modules)
-
-```
-com.yss.{module}.executor
-├── {Tech}Executor.java          # 执行器实现 (e.g., MybatisExecutor)
-└── {Tech}DataSource.java        # 数据源适配实现
-```
-
-## 3. 开发规范 (Development Guidelines)
-
-### 3.1 Web Controller 规范
-
-- **注解**: 使用 `@RestController` 和 `@RequestMapping("/api/{module}/{resource}")`。
-- **依赖注入**: 优先注入 **Application Service** (`XxxService`)。对于简单的查询 (CQRS)，允许直接注入 **Domain Gateway** (`XxxGateway`)。
-- **请求参数**:
-  - `POST`/`PUT` 使用 `@RequestBody` 接收 `Cmd` 对象 (e.g., `QualityRuleAddCmd`)。
-  - `GET` 使用 `Query` 对象或 `@RequestParam` (e.g., `QualityRulePage`)。
-  - 必须使用 `@Valid` 进行参数校验。
-- **响应格式**: 必须使用统一的 `Result` 包装器：
-  - 单个对象: `SingleResult<T>`
-  - 列表对象: `MultiResult<T>`
-  - 分页对象: `PageResult<T>`
-
-### 3.2 Scheduler Adapter 规范
-
-- **接口实现**: 实现 `adapter-api` 定义的接口 (e.g., `QualityScheduleService`)。
-- **条件加载**: 使用 `@ConditionalOnProperty` 支持多调度引擎切换 (e.g., `dolphin`, `quartz`)。
-- **异常处理**: 捕获运行时异常并转换为调度系统可识别的状态。
-
-### 3.3 Plugin Adapter 规范
-
-- **SPI 模式**: 实现核心定义的接口 (Interface)，不包含业务逻辑，仅负责技术适配。
-- **上下文隔离**: 插件应包含自己独立的配置和依赖，避免污染核心上下文。
-
-## 4. 代码示例 (Code Examples)
-
-### 4.1 Web Controller (REST API)
-
-```java
-package com.yss.{module}.rest;
-
-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.query.{Domain}Page;
-import com.yss.{module}.client.vo.{Domain}VO;
-import com.yss.{module}.core.service.{Domain}Service;
-import lombok.RequiredArgsConstructor;
-import org.springframework.web.bind.annotation.*;
-
-import javax.validation.Valid;
-
-/**
- * {Domain} 管理控制器
- */
-@RestController
-@RequestMapping("/api/{module}/{domain}")
-@RequiredArgsConstructor
-public class {Domain}Controller {
-
-    private final {Domain}Service {domain}Service;
-
-    /**
-     * 分页查询
-     */
-    @PostMapping("/page")
-    public PageResult<{Domain}VO> page(@Valid @RequestBody {Domain}Page query) {
-        return {domain}Service.page(query);
-    }
-
-    /**
-     * 新增
-     */
-    @PostMapping
-    public SingleResult<Long> add(@Valid @RequestBody {Domain}AddCmd cmd) {
-        return SingleResult.of({domain}Service.add(cmd));
-    }
-
-    /**
-     * 更新
-     */
-    @PutMapping
-    public SingleResult<Boolean> update(@Valid @RequestBody {Domain}UpdateCmd cmd) {
-        {domain}Service.update(cmd);
-        return SingleResult.of(true);
-    }
-}
-```
-
-### 4.2 Scheduler Adapter (Task Runner)
-
-```java
-package com.yss.{module}.scheduler;
-
-import com.yss.{module}.scheduler.api.QualityScheduleService;
-import lombok.RequiredArgsConstructor;
-import lombok.extern.slf4j.Slf4j;
-import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
-import org.springframework.stereotype.Service;
-
-@Slf4j
-@Service
-@RequiredArgsConstructor
-@ConditionalOnProperty(prefix = "yss.scheduler", name = "plugin", havingValue = "dolphin")
-public class DolphinScheduleServiceImpl implements QualityScheduleService {
-
-    private final QualityScheduleGateway qualityScheduleGateway;
-    // External Scheduler Facade
-    // private final SchedulerFacadeApi schedulerFacadeApi;
-
-    @Override
-    public List<QualityScheduleVO> listSchedules(QualityScheduleQuery query) {
-        return qualityScheduleGateway.list(query);
-    }
-
-    @Override
-    public Long addSchedule(QualityScheduleAddCmd cmd) {
-        // 适配 DolphinScheduler 的创建逻辑
-        // Long code = schedulerFacadeApi.createTask(cmd);
-        // cmd.setScheduleCode(String.valueOf(code));
-        return qualityScheduleGateway.add(cmd);
-    }
-}
-```
-
-### 4.3 Executor Adapter (MyBatis Plugin)
-
-```java
-package com.yss.{module}.executor;
-
-import com.yss.cloud.exception.SysException;
-import com.yss.quality.executor.Executor;
-import com.yss.quality.executor.cmd.QualityRuleResultSingleCmd;
-import lombok.extern.slf4j.Slf4j;
-import org.springframework.stereotype.Component;
-import java.util.LinkedHashMap;
-
-@Component
-@Slf4j
-public class MybatisExecutor implements Executor {
-
-    @Override
-    public LinkedHashMap<String, Object> execute(QualityRuleResultSingleCmd cmd) {
-        try {
-            // 构建 MyBatis 执行上下文
-            // ApiCmd apiCmd = ...
-            // 执行查询
-            // return data;
-            return new LinkedHashMap<>();
-        } catch (Exception e) {
-            log.error("MyBatis execution failed: {}", e.getMessage());
-            throw new SysException("Execution failed: " + e.getMessage());
-        }
-    }
-
-    @Override
-    public String engineType() {
-        return "MYBATIS";
-    }
-}
-```
+- 禁止 Web Controller 直接注入 Domain Gateway。
+- 禁止 `client.dto`、VO、`PageQuery` 进入 Domain。
+- 禁止静态 `Mappers.getMapper(...)` / `INSTANCE`；MapStruct 必须 `componentModel = "spring"` 并构造器注入。
+- 禁止把旧式 Controller 示例当成 `target-domain-model` 的方案。旧架构对新脚手架一律 `unsupported`；旧项目继续在原工程维护，现代化改造必须单独立项。

package/template/.cursor/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-parent/SKILL.md

@@ -1,138 +1,58 @@
 ---
-name: "yss-backend-scaffold-parent"
-description: "YSS 服务的后端开发脚手架框架和技术指南。在开发后端功能、创建新模块或检查架构标准时需要用到。"
+name: yss-backend-scaffold-parent
+description: YSS DDD scaffold Engineering Baseline entry for profile, module, dependency, build, and downstream-skill routing checks.
 ---
 
-# 赢时胜数据质量管理服务后端开发规范 (YSS Data Quality Backend Dev Guide)
+# YSS DDD Scaffold Engineering Baseline
 
-本 Skill 包含了项目的核心技术栈、架构设计原则以及开发规范，旨在帮助开发者快速上手并遵循项目标准。
+本文件只定义脚手架工程基线和路由，不复制 Domain、Application、Repository、Web 的实现细则。
 
-在产品生命周期中，本 Skill 是后端 Engineering Baseline / YSS DDD Review 的入口。它用于确认技术栈、模块边界、依赖方向、DTO/Gateway/Repository 约定和实现前检查；具体代码仍按垂直切片加载 `yss-domain`、`yss-repository`、`yss-web-controller` 等专项 Skill。
+## 当前可验证 Profile
 
-## 1. 技术栈 (Tech Stack)
+- Architecture: `target-domain-model`
+- Persistence: `mybatis-plus`
+- Database: `mysql`
+- Platform: `spring-boot-2.7-jdk8`
+- Validation namespace: `javax`
+- DTO placement: `web`
+- Repository: `yss-internal`
 
-### 核心框架
+未具备独立 fixture、受控合同和真实验证证据的组合统一为 `unsupported`。旧架构不存在可选 Profile，也不能作为回退。
 
-- **JDK**: 8
-- **Spring Boot**: 2.7.18
-- **Spring Framework**: 5.3.x
-- **ORM**: MyBatis Plus (底层封装于 `yss-component-mybatis-starter`)
-- **连接池**: HikariCP
+## 模块与依赖方向
 
-### 数据库支持
-
-- **MySQL**: 8.0+
-- **Oracle**: 12c+
-- **PostgreSQL**: 12+
-- **OpenGauss**
-- **DuckDB**
-
-### 工具库
-
-- **Lombok**: 减少样板代码
-- **Hutool**: Java 通用工具库
-- **MapStruct**: 高性能对象映射
-- **Jackson**: JSON 处理
-- **Guava**: Google 核心库
-
-### 构建工具
-
-- **Maven**: 3.x (必须使用项目根目录下的 `./mvnw` 脚本进行构建、测试、运行和 CI 验证；不要默认使用裸 `mvn ...` 命令)
-
-## 2. 架构设计 (Architecture)
-
-项目采用基于 DDD (领域驱动设计) 的分层架构：
-
-### 分层职责
-
-1.  **Adapter (适配层)**: `adapter`
-    - 处理外部请求 (Web API, Job Runner)
-    - 适配数据库连接器
-2.  **Application (应用层)**: `application`
-    - 业务用例编排
-    - Command/Query/Event Handlers
-3.  **Domain (领域层)**: `domain`
-    - 核心业务逻辑
-    - 包含：聚合根, 实体, 值对象, 领域服务, 仓储接口
-4.  **Infrastructure (基础设施层)**: `infrastructure`
-    - 仓储接口实现 (Repository Impl)
-    - 外部服务适配
-    - 配置管理
-
-### 模块依赖
-
-- `Domain` 是核心层，不依赖 Application、Infrastructure、Adapter 或 Bootstrap。
-- `Application` 依赖 `Domain`，负责用例编排、事务边界和 Command/Query/Event Handler。
-- `Adapter` / Web 层依赖 `Application`，负责协议适配、参数校验、DTO/VO 转换和统一响应。
-- `Infrastructure` 依赖 `Domain`，实现 Domain 中定义的 Gateway / Repository / 外部系统接口。
-- `Bootstrap` 负责组装和启动，不承载业务规则。
-
-依赖方向必须服务于领域核心，不能让 PO、Mapper、HTTP、RPC、Excel、文件、缓存等基础设施细节泄漏到 Domain。
-
-## 3. 开发规范 (Development Guidelines)
-
-### 命名规范
-
-- **PO (Persistent Object)**: 持久化对象，对应数据库表。
-- **VO (Value Object)**: 视图对象，用于 API 返回。
-- **CMD (Command)**: 命令对象，用于增删改操作参数。
-- **Query**: 查询对象，用于查询条件参数。
-
-### 调用链路
-
-标准的调用流向为：
-`Controller / Adapter` -> `Application Use Case / Handler` -> `Domain Aggregate / Domain Service` -> `Gateway / Repository Interface` -> `Infrastructure Implementation` -> `Database / External System`
-
-不要把传统 `Controller -> Service -> Repository` 三层模型作为默认设计。只有当现有工程已经采用 Application Service 命名时，`Service` 才代表应用层用例编排，不应承载领域规则或直接泄漏持久化细节。
-
-数据转换边界：
-`Request DTO / Command / Query` -> `Domain Model` -> `PO / External DTO` -> `Domain Model` -> `Response VO`
-
-### Repository 开发
-
-- 接口继承 `BasePlusRepository<PO>`。
-- 实体类字段使用 `@TableField` 映射。
-- 主键使用 `@TableId(value = "id", type = IdType.ASSIGN_ID)`。
-- 实体类继承 `AuditableEntity` 以自动处理审计字段 (创建人、时间等)。
-
-### 对象转换
-
-- 必须使用 **MapStruct** 进行对象转换。
-- 定义接口并添加 `@Mapper` 注解。
-
-### API 设计
-
-- 遵循 RESTful 风格 (GET/POST/PUT/DELETE)。
-- 使用统一响应包装类：
-  - 单个对象: `SingleResult<T>`
-  - 列表: `MultiResult<T>`
-  - 分页: `PageResult<T>`
-- 涉及新增或变更前后端契约时，先在 `docs/.scratch/<feature>/api/<feature>.yaml` 形成 OpenAPI Draft，经工程基线、架构 / Spec Delta 设计和设计审查后 Freeze，再实现 Controller、DTO、前端调用和契约测试。
-
-## 4. 工程基线检查清单
+```text
+domain <- application <- web
+   ^            ^
+   |            |
+infrastructure-+
+        ^
+     bootstrap
+```
 
-进入实现前至少确认：
+- `domain`：纯 Java 领域模型、领域服务、领域事件、Domain Gateway；不得依赖 YSS DTO/Exception、Web Validation、Jackson、Swagger、MyBatis。
+- `application`：用例编排、Command / Query / Result、事务边界、Application Query Port；可以依赖 Domain 和必要的 YSS result wrapper。
+- `infrastructure`：实现 Domain Gateway / Application Query Port，拥有 PO、Mapper、持久化转换器；依赖 Domain 与 Application。
+- `adapter/web`：拥有 HTTP DTO、Controller、异常翻译、WebConvertor；只依赖 Application。
+- `bootstrap`：装配与启动，不放业务逻辑。
 
-- 模块是否采用 Domain / Application / Infrastructure / Adapter / Bootstrap 分层，或已有工程的等价边界。
-- 新服务是否先由 `yss-ddd-scaffold-generator` 生成骨架；现有服务是否沿用既有模块和包命名。
-- Domain 是否只包含聚合、实体、值对象、领域服务和 Gateway / Repository 接口。
-- Infrastructure 是否只实现 Gateway / Repository，并隔离 PO、Mapper、SQL、外部系统客户端。
-- Web / Adapter 是否只做协议适配、鉴权上下文、参数校验、DTO/VO 转换和响应包装。
-- Application 是否承载用例编排、事务边界和跨聚合协调，不把领域规则下沉到 Controller 或 Mapper。
-- OpenAPI Draft / Freeze、ADR、测试 seam 和已批准的架构约束是否已经明确。
+依赖方向由 Maven Reactor、Maven Enforcer 与 ArchUnit 共同约束。MapStruct 统一使用 Spring component model，父 POM 配置 annotation processor、Lombok 与 `lombok-mapstruct-binding`。
 
-## 5. 常用命令
+## 生成与验证
 
-```bash
-# 清理并编译
-./mvnw clean compile
+- 输入是批准且持久化的服务级 scaffold contract schema v2，身份为 `scaffold_request_id`，不使用 `slice_id`。
+- 生成器严格 initialize-only：目标工程目录必须不存在，`--force`、旧项目迁移和当前模板升级均为 `unsupported`。
+- Maven 内部仓库通过命名 profile `yss-internal` 与环境变量注入；共享模板不写内部 URL 或凭据。
+- Wrapper 必须带 checksum；DEBUG 和 MyBatis stdout SQL 只允许在 `application-local.yml`。
+- `./mvnw validate`、`./mvnw test`、`./mvnw package` 全部成功只得到 `empty-scaffold-verified`。
+- 只有批准且版本当前的 golden first slice 真实组合 Domain/Application/Infrastructure/Web、通过下游 skill tree drift 校验与根 Wrapper，才能由 `run_first_slice_verification.mjs` 写入 `first-slice-verified`。
 
-# 完整验证
-./mvnw clean verify
-```
+## 下游权威技能
 
-## 6. 阶段 7 合同
+- Domain：`yss-domain`
+- Application：`yss-application`
+- Persistence：`yss-repository` + `yss-mybatis`
+- Web：`yss-web-controller` + `yss-dto` + `yss-exception`
+- 横切实现约束：`yss-validation` + `mapstruct` + `lombok` + `alibaba-java-code-style`
 
-- 工程基线校验必须消费批准合同、实现仓库登记和 scaffold 状态。
-- 脚手架只属于 `controlled-generation`；生成后必须重新路由业务 work units，不能把骨架标为业务完成。
-- 输出统一 `YSS Skill Execution Result`，包含模块边界、Wrapper、编译/测试、OpenAPI/CI 证据和所有偏离。
+业务代码必须回到 `yss-router`，消费批准且版本当前的 Slice Implementation Contract，并采用 `behavior-tdd`；脚手架只生成机械工程资产。