create-yss-spec 1.0.0

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

@@ -0,0 +1,132 @@
+---
+name: "yss-backend-scaffold-parent"
+description: "YSS 服务的后端开发脚手架框架和技术指南。在开发后端功能、创建新模块或检查架构标准时需要用到。"
+---
+
+# 赢时胜数据质量管理服务后端开发规范 (YSS Data Quality Backend Dev Guide)
+
+本 Skill 包含了项目的核心技术栈、架构设计原则以及开发规范，旨在帮助开发者快速上手并遵循项目标准。
+
+在产品生命周期中，本 Skill 是后端 Engineering Baseline / YSS DDD Review 的入口。它用于确认技术栈、模块边界、依赖方向、DTO/Gateway/Repository 约定和实现前检查；具体代码仍按垂直切片加载 `yss-domain`、`yss-repository`、`yss-web-controller` 等专项 Skill。
+
+## 1. 技术栈 (Tech Stack)
+
+### 核心框架
+
+- **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` 脚本进行构建)
+
+## 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/api/specs/` 形成 OpenAPI Draft，经工程基线、架构 / OpenSpec / Comet design 和设计审查后 Freeze，再实现 Controller、DTO、前端调用和契约测试。
+
+## 4. 工程基线检查清单
+
+进入实现前至少确认：
+
+- 模块是否采用 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 和安全红线是否已经明确。
+
+## 5. 常用命令
+
+```bash
+# 清理并编译
+./mvnw clean compile
+
+# 打包 (跳过测试)
+./mvnw clean package -DskipTests
+```

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

@@ -0,0 +1,5 @@
+version: 1
+interface:
+  display_name: "YSS Scaffold Parent"
+  short_description: "YSS 后端脚手架父工程、依赖与公共约定实践落地规范"
+  default_prompt: "Use $yss-backend-scaffold-parent to set up the parent project and shared conventions for a YSS backend scaffold."

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

@@ -0,0 +1,169 @@
+---
+name: "yss-backend-scaffold-web"
+description: "YSS 管理服务的 Web Adapter 开发框架和技术指南。在实现 REST API 控制器、请求处理和响应格式化时需要用到。"
+---
+
+# Web Adapter Layer Development Guide
+
+本技能为开发 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)
+        );
+    }
+```

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

@@ -0,0 +1,5 @@
+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."