create-yss-spec 1.0.0

package/template/.codex/skills/yss-ddd-scaffold-generator/references/USAGE_EXAMPLES.md

@@ -0,0 +1,424 @@
+# 使用示例
+
+## 1. 快速开始
+
+### 1.1 生成基础项目
+
+```bash
+# 进入脚手架目录
+cd yss-datamiddle-scaffold
+
+# 生成项目
+python .trae/skills/yss-ddd-scaffold-generator/scripts/generate_scaffold.py \
+  --project-name user-service \
+  --base-package com.yss.user \
+  --output-dir ./output
+```
+
+### 1.2 生成的项目结构
+
+```
+output/user-service/
+├── pom.xml
+├── README.md
+├── user-service-domain/
+├── user-service-application/
+├── user-service-infrastructure/
+├── user-service-adapter/
+│   └── user-service-web/
+└── user-service-bootstrap/
+```
+
+## 2. 编译和运行
+
+### 2.1 编译项目
+
+```bash
+cd output/user-service
+./mvnw clean compile
+```
+
+### 2.2 运行项目
+
+```bash
+# 方式1: 使用 Maven 插件
+./mvnw spring-boot:run -pl user-service-bootstrap
+
+# 方式2: 打包后运行
+./mvnw clean package -DskipTests
+java -jar user-service-bootstrap/target/user-service-bootstrap-1.0.0-SNAPSHOT.jar
+```
+
+### 2.3 访问应用
+
+```bash
+# 健康检查
+curl http://localhost:8080/actuator/health
+
+# 查询用户列表
+curl -X POST http://localhost:8080/api/users/page \
+  -H "Content-Type: application/json" \
+  -d '{
+    "pageNum": 1,
+    "pageSize": 10
+  }'
+
+# 新增用户
+curl -X POST http://localhost:8080/api/users \
+  -H "Content-Type: application/json" \
+  -d '{
+    "username": "zhangsan",
+    "email": "zhangsan@example.com"
+  }'
+
+# 查询用户详情
+curl http://localhost:8080/api/users/1
+
+# 更新用户
+curl -X PUT http://localhost:8080/api/users \
+  -H "Content-Type: application/json" \
+  -d '{
+    "id": 1,
+    "username": "zhangsan",
+    "email": "zhangsan@yss.com",
+    "status": 1
+  }'
+
+# 删除用户
+curl -X DELETE http://localhost:8080/api/users/1
+```
+
+## 3. 添加新实体
+
+### 3.1 创建 Domain 层对象
+
+**ProductAddCmd.java**:
+```java
+package com.yss.user.client.dto.cmd;
+
+import com.yss.cloud.dto.CommandDTO;
+import lombok.Data;
+import javax.validation.constraints.NotBlank;
+
+@Data
+public class ProductAddCmd extends CommandDTO {
+    @NotBlank(message = "产品名称不能为空")
+    private String productName;
+    
+    private String description;
+    private Double price;
+}
+```
+
+**ProductVO.java**:
+```java
+package com.yss.user.client.vo;
+
+import lombok.Data;
+import java.io.Serializable;
+
+@Data
+public class ProductVO implements Serializable {
+    private Long id;
+    private String productName;
+    private String description;
+    private Double price;
+}
+```
+
+**ProductGateway.java**:
+```java
+package com.yss.user.domain.gateway;
+
+import com.yss.cloud.dto.result.PageResult;
+import com.yss.user.client.dto.cmd.ProductAddCmd;
+import com.yss.user.client.vo.ProductVO;
+
+public interface ProductGateway {
+    Long addProduct(ProductAddCmd cmd);
+    ProductVO getProductById(Long id);
+    PageResult<ProductVO> pageProduct(ProductPageQuery query);
+}
+```
+
+### 3.2 创建 Application 层服务
+
+**ProductService.java**:
+```java
+package com.yss.user.core.service;
+
+public interface ProductService {
+    Long addProduct(ProductAddCmd cmd);
+    ProductVO getProductById(Long id);
+}
+```
+
+**ProductServiceImpl.java**:
+```java
+package com.yss.user.core.service.impl;
+
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+@Service
+@RequiredArgsConstructor
+public class ProductServiceImpl implements ProductService {
+    
+    private final ProductGateway productGateway;
+    
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public Long addProduct(ProductAddCmd cmd) {
+        return productGateway.addProduct(cmd);
+    }
+    
+    @Override
+    public ProductVO getProductById(Long id) {
+        return productGateway.getProductById(id);
+    }
+}
+```
+
+### 3.3 创建 Infrastructure 层实现
+
+**ProductPO.java**:
+```java
+package com.yss.user.repository.entity;
+
+import com.baomidou.mybatisplus.annotation.*;
+import com.yss.cloud.mybatis.entity.AuditableEntity;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+
+@Data
+@EqualsAndHashCode(callSuper = true)
+@TableName("t_product")
+public class ProductPO extends AuditableEntity {
+    @TableId(value = "id", type = IdType.ASSIGN_ID)
+    private Long id;
+    
+    @TableField("product_name")
+    private String productName;
+    
+    @TableField("description")
+    private String description;
+    
+    @TableField("price")
+    private Double price;
+}
+```
+
+**ProductRepository.java**:
+```java
+package com.yss.user.repository;
+
+import com.yss.cloud.mybatis.support.BasePlusRepository;
+import com.yss.user.repository.entity.ProductPO;
+
+public interface ProductRepository extends BasePlusRepository<ProductPO> {
+}
+```
+
+**ProductGatewayImpl.java**:
+```java
+package com.yss.user.repository.gateway.impl;
+
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Repository;
+
+@Repository
+@RequiredArgsConstructor
+public class ProductGatewayImpl implements ProductGateway {
+    
+    private final ProductRepository productRepository;
+    
+    @Override
+    public Long addProduct(ProductAddCmd cmd) {
+        ProductPO po = ProductConvertor.INSTANCE.cmdToPO(cmd);
+        productRepository.insert(po);
+        return po.getId();
+    }
+    
+    @Override
+    public ProductVO getProductById(Long id) {
+        ProductPO po = productRepository.selectById(id);
+        return ProductConvertor.INSTANCE.toVO(po);
+    }
+}
+```
+
+### 3.4 创建 Adapter 层控制器
+
+**ProductController.java**:
+```java
+package com.yss.user.rest;
+
+import com.yss.cloud.dto.result.SingleResult;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.*;
+import javax.validation.Valid;
+
+@RestController
+@RequestMapping("/api/products")
+@RequiredArgsConstructor
+public class ProductController {
+    
+    private final ProductService productService;
+    
+    @PostMapping
+    public SingleResult<Long> add(@Valid @RequestBody ProductAddCmd cmd) {
+        return SingleResult.of(productService.addProduct(cmd));
+    }
+    
+    @GetMapping("/{id}")
+    public SingleResult<ProductVO> getById(@PathVariable Long id) {
+        return SingleResult.of(productService.getProductById(id));
+    }
+}
+```
+
+### 3.5 创建数据库表
+
+```sql
+CREATE TABLE `t_product` (
+  `id` bigint(20) NOT NULL COMMENT '主键ID',
+  `product_name` varchar(100) NOT NULL COMMENT '产品名称',
+  `description` varchar(500) DEFAULT NULL COMMENT '描述',
+  `price` decimal(10,2) DEFAULT NULL COMMENT '价格',
+  `deleted` tinyint(4) NOT NULL DEFAULT '0' COMMENT '删除标记',
+  `created_by` varchar(50) DEFAULT NULL COMMENT '创建人',
+  `created_date` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+  `last_modified_by` varchar(50) DEFAULT NULL COMMENT '最后修改人',
+  `last_modified_date` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '最后修改时间',
+  PRIMARY KEY (`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='产品表';
+```
+
+## 4. 集成其他功能
+
+### 4.1 添加 Redis 缓存
+
+**1. 添加依赖**:
+```xml
+<dependency>
+    <groupId>com.yss.cloud</groupId>
+    <artifactId>yss-component-cache-starter</artifactId>
+</dependency>
+```
+
+**2. 配置 Redis**:
+```yaml
+spring:
+  redis:
+    host: localhost
+    port: 6379
+    database: 0
+```
+
+**3. 使用缓存**:
+```java
+@Service
+public class UserServiceImpl implements UserService {
+    
+    @Cacheable(value = "user", key = "#id")
+    public UserVO getUserById(Long id) {
+        return userGateway.getUserById(id);
+    }
+    
+    @CacheEvict(value = "user", key = "#id")
+    public void deleteUser(Long id) {
+        userGateway.deleteUser(id);
+    }
+}
+```
+
+### 4.2 添加 Swagger 文档
+
+**1. 添加依赖**:
+```xml
+<dependency>
+    <groupId>io.springfox</groupId>
+    <artifactId>springfox-boot-starter</artifactId>
+    <version>3.0.0</version>
+</dependency>
+```
+
+**2. 配置 Swagger**:
+```java
+@Configuration
+@EnableOpenApi
+public class SwaggerConfig {
+    @Bean
+    public Docket api() {
+        return new Docket(DocumentationType.OAS_30)
+                .select()
+                .apis(RequestHandlerSelectors.basePackage("com.yss.user.rest"))
+                .paths(PathSelectors.any())
+                .build();
+    }
+}
+```
+
+**3. 访问文档**:
+```
+http://localhost:8080/swagger-ui/index.html
+```
+
+## 5. 常见问题
+
+### 5.1 如何修改端口？
+
+修改 `application.yml`:
+```yaml
+server:
+  port: 9090
+```
+
+### 5.2 如何配置多环境？
+
+创建多个配置文件：
+- `application-dev.yml` (开发环境)
+- `application-test.yml` (测试环境)
+- `application-prod.yml` (生产环境)
+
+启动时指定环境：
+```bash
+java -jar app.jar --spring.profiles.active=prod
+```
+
+### 5.3 如何添加全局异常处理？
+
+```java
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+    
+    @ExceptionHandler(BizException.class)
+    public SingleResult<Void> handleBizException(BizException e) {
+        return SingleResult.fail(e.getCode(), e.getMessage());
+    }
+    
+    @ExceptionHandler(Exception.class)
+    public SingleResult<Void> handleException(Exception e) {
+        return SingleResult.fail("SYSTEM_ERROR", "系统异常");
+    }
+}
+```
+
+## 6. 性能优化建议
+
+### 6.1 数据库优化
+- 合理使用索引
+- 避免 N+1 查询
+- 使用分页查询
+- 开启 MyBatis Plus 的性能分析插件
+
+### 6.2 缓存优化
+- 热点数据使用 Redis 缓存
+- 合理设置缓存过期时间
+- 使用缓存预热
+
+### 6.3 代码优化
+- 使用异步处理耗时操作
+- 合理使用线程池
+- 避免大事务

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

@@ -0,0 +1,199 @@
+---
+name: "yss-backend-scaffold-adapter"
+description: "YSS 后端开发脚手架的适配器层开发框架和技术指南。在实现 Web 控制器、调度器或外部系统适配器时调用。"
+---
+
+# Adapter Layer Development Guide
+
+本技能为开发 YSS 后端开发脚手架服务的**适配器层**（接口层）提供指导和框架。
+适配器层负责处理外部请求（HTTP、计划任务），并将其适配到应用层，以及为外部系统（连接器、执行器）实现插件式适配器。
+
+## 1. 核心职责 (Core Responsibilities)
+
+The Adapter Layer serves as the entry point and integration point of the system:
+
+- **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).
+
+## 2. 代码结构 (Code Structure)
+
+Depending on the module type (Web Application or Plugin), the structure varies:
+
+### 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";
+    }
+}
+```

package/template/.codex/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-adapter/agents/openai.yaml

@@ -0,0 +1,5 @@
+version: 1
+interface:
+  display_name: "YSS Scaffold Adapter"
+  short_description: "YSS 后端脚手架适配器层与接口接入设计落地标准规范"
+  default_prompt: "Use $yss-backend-scaffold-adapter to implement the adapter layer for a YSS backend scaffold module."