create-yss-spec 1.0.0

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

@@ -0,0 +1,64 @@
+---
+name: yss-ddd-scaffold-generator
+description: 用于生成完整的 YSS DDD 多模块后端脚手架。当用户要求从零创建符合 YSS 规范的 Domain、Application、Infrastructure、Adapter、Bootstrap 工程骨架时调用。
+---
+
+# yss-ddd-scaffold-generator
+
+这是一个脚手架生成型 skill。优先运行脚本和模板，不要手工拼装整套多模块工程。
+
+在产品生命周期中，本 skill 属于 Engineering Baseline / YSS DDD Review 阶段：用于从零创建后端服务骨架，或为架构设计提供标准模块边界输入。它不是业务实现阶段的替代品。
+
+## 何时使用
+
+- 用户要求从零创建新的 YSS 后端服务。
+- 用户要求一次性生成完整多模块工程骨架。
+- 用户需要标准的 Domain、Application、Infrastructure、Adapter、Bootstrap 目录和基础模板。
+
+## 不适用
+
+- 只补单个领域模型时，优先 `yss-domain`。
+- 只补持久层时，优先 `yss-db2mybatis` 或 `yss-repository`。
+- 只补 Web 层时，优先 `yss-web-controller`。
+
+## 优先流程
+
+1. 确认项目名、基础包名、输出目录、数据库类型。
+2. 运行 `scripts/generate_scaffold.py` 生成骨架。
+3. 检查生成的模块名、POM、配置文件和包路径。
+4. 如需继续细化，再追加其他 YSS skill 补全领域、仓储和 Web。
+
+## 推荐命令
+
+```bash
+python3 scripts/generate_scaffold.py \
+  --project-name my-service \
+  --base-package com.yss.myservice \
+  --output-dir ./output \
+  --database mysql
+```
+
+## 生成结果应包含
+
+- 父工程 POM
+- `*-domain`
+- `*-application`
+- `*-infrastructure`
+- `*-adapter`
+- `*-bootstrap`
+- 基础配置、模板代码、构建脚本
+
+## 使用约束
+
+- 先生成骨架，再做业务化定制，不要直接把脚手架当最终代码交付。
+- 若仓库已经存在相同工程，先核对覆盖范围。
+- 不要在 skill 里硬编码用户业务字段或真实连接信息。
+- 生成后要检查依赖关系是否仍符合分层约束。
+- 生成后必须继续使用 `yss-backend-scaffold-parent` 校验工程基线，再按垂直切片加载 `yss-domain`、`yss-repository`、`yss-web-controller` 等局部技能。
+- 涉及 API 契约时，先确认 `docs/api/specs/` 中的 OpenAPI Draft / Freeze 状态；不要用脚手架生成结果反向替代产品契约设计。
+
+## 按需读取
+
+- 主脚本：`scripts/generate_scaffold.py`
+- 模板目录：`assets/templates/`
+- 分层细化参考：`references/yss-backend-scaffold-parent/` 及其子 skill

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

@@ -0,0 +1,5 @@
+version: 1
+interface:
+  display_name: "YSS DDD Scaffold"
+  short_description: "生成多模块 YSS DDD 后端脚手架与工程骨架规范"
+  default_prompt: "Use $yss-ddd-scaffold-generator to create a standard YSS DDD backend scaffold with domain, application, infrastructure, adapter, and bootstrap modules."

package/template/.codex/skills/yss-ddd-scaffold-generator/assets/templates/adapter/UserController.java.template

@@ -0,0 +1,84 @@
+package {{base_package}}.rest;
+
+import com.yss.cloud.dto.result.PageResult;
+import com.yss.cloud.dto.result.SingleResult;
+import {{base_package}}.client.dto.cmd.UserAddCmd;
+import {{base_package}}.client.dto.cmd.UserUpdateCmd;
+import {{base_package}}.client.dto.query.UserPageQuery;
+import {{base_package}}.client.vo.UserVO;
+import {{base_package}}.core.service.UserService;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.*;
+
+import javax.validation.Valid;
+
+/**
+ * 用户管理控制器
+ *
+ * @author {{author}}
+ * @date {{date}}
+ */
+@RestController
+@RequestMapping("/api/users")
+@RequiredArgsConstructor
+public class UserController {
+
+    private final UserService userService;
+
+    /**
+     * 分页查询用户
+     *
+     * @param query 查询条件
+     * @return 分页结果
+     */
+    @PostMapping("/page")
+    public PageResult<UserVO> page(@Valid @RequestBody UserPageQuery query) {
+        return userService.pageUser(query);
+    }
+
+    /**
+     * 根据ID查询用户详情
+     *
+     * @param id 用户ID
+     * @return 用户详情
+     */
+    @GetMapping("/{id}")
+    public SingleResult<UserVO> getById(@PathVariable Long id) {
+        return SingleResult.of(userService.getUserById(id));
+    }
+
+    /**
+     * 新增用户
+     *
+     * @param cmd 新增命令
+     * @return 用户ID
+     */
+    @PostMapping
+    public SingleResult<Long> add(@Valid @RequestBody UserAddCmd cmd) {
+        return SingleResult.of(userService.addUser(cmd));
+    }
+
+    /**
+     * 更新用户
+     *
+     * @param cmd 更新命令
+     * @return 更新结果
+     */
+    @PutMapping
+    public SingleResult<Boolean> update(@Valid @RequestBody UserUpdateCmd cmd) {
+        userService.updateUser(cmd);
+        return SingleResult.of(true);
+    }
+
+    /**
+     * 删除用户
+     *
+     * @param id 用户ID
+     * @return 删除结果
+     */
+    @DeleteMapping("/{id}")
+    public SingleResult<Boolean> delete(@PathVariable Long id) {
+        userService.deleteUser(id);
+        return SingleResult.of(true);
+    }
+}

package/template/.codex/skills/yss-ddd-scaffold-generator/assets/templates/application/UserConvertor.java.template

@@ -0,0 +1,21 @@
+package {{base_package}}.core.service.convertor;
+
+import {{base_package}}.client.dto.cmd.UserAddCmd;
+import {{base_package}}.client.dto.cmd.UserUpdateCmd;
+import {{base_package}}.domain.user.model.User;
+import org.mapstruct.Mapper;
+import org.mapstruct.NullValueCheckStrategy;
+import org.mapstruct.NullValuePropertyMappingStrategy;
+import org.mapstruct.factory.Mappers;
+
+@Mapper(
+        nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE,
+        nullValueCheckStrategy = NullValueCheckStrategy.ALWAYS)
+public interface UserConvertor {
+
+    UserConvertor INSTANCE = Mappers.getMapper(UserConvertor.class);
+
+    User toDomain(UserAddCmd cmd);
+
+    User toDomain(UserUpdateCmd cmd);
+}

package/template/.codex/skills/yss-ddd-scaffold-generator/assets/templates/application/UserService.java.template

@@ -0,0 +1,48 @@
+package {{base_package}}.core.service;
+
+import com.yss.cloud.dto.result.PageResult;
+import {{base_package}}.client.dto.cmd.UserAddCmd;
+import {{base_package}}.client.dto.cmd.UserUpdateCmd;
+import {{base_package}}.client.dto.query.UserPageQuery;
+import {{base_package}}.client.vo.UserVO;
+
+public interface UserService {
+
+    /**
+     * 分页查询用户列表
+     *
+     * @param query 查询条件
+     * @return 用户分页结果
+     */
+    PageResult<UserVO> pageUser(UserPageQuery query);
+
+    /**
+     * 根据主键ID查询用户
+     *
+     * @param id 用户ID
+     * @return 用户详情
+     */
+    UserVO getUserById(Long id);
+
+    /**
+     * 新增用户并返回主键ID
+     *
+     * @param cmd 新增命令
+     * @return 新增用户ID
+     */
+    Long addUser(UserAddCmd cmd);
+
+    /**
+     * 根据命令更新用户信息
+     *
+     * @param cmd 更新命令
+     */
+    void updateUser(UserUpdateCmd cmd);
+
+    /**
+     * 根据主键ID删除用户
+     *
+     * @param id 用户ID
+     */
+    void deleteUser(Long id);
+}

package/template/.codex/skills/yss-ddd-scaffold-generator/assets/templates/application/UserServiceImpl.java.template

@@ -0,0 +1,87 @@
+package {{base_package}}.core.service.impl;
+
+import com.yss.cloud.dto.result.PageResult;
+import {{base_package}}.client.dto.cmd.UserAddCmd;
+import {{base_package}}.client.dto.cmd.UserUpdateCmd;
+import {{base_package}}.client.dto.query.UserPageQuery;
+import {{base_package}}.client.vo.UserVO;
+import {{base_package}}.core.service.UserService;
+import {{base_package}}.domain.user.gateway.UserGateway;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+/**
+ * 用户应用服务实现类
+ *
+ * @author {{author}}
+ * @date {{date}}
+ */
+@Service
+@RequiredArgsConstructor
+@Slf4j
+public class UserServiceImpl implements UserService {
+    private final UserGateway userGateway;
+
+    /**
+     * 分页查询用户
+     *
+     * @param query 查询条件
+     * @return 分页结果
+     */
+    @Override
+    public PageResult<UserVO> pageUser(UserPageQuery query) {
+        log.debug("分页查询用户, query: {}", query);
+        return userGateway.pageUser(query);
+    }
+
+    /**
+     * 根据ID查询用户
+     *
+     * @param id 用户ID
+     * @return 用户信息
+     */
+    @Override
+    public UserVO getUserById(Long id) {
+        log.debug("根据ID查询用户, id: {}", id);
+        return userGateway.getUserById(id);
+    }
+
+    /**
+     * 新增用户
+     *
+     * @param cmd 新增命令
+     * @return 用户ID
+     */
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public Long addUser(UserAddCmd cmd) {
+        log.info("新增用户, username: {}", cmd.getUsername());
+        return userGateway.addUser(cmd);
+    }
+
+    /**
+     * 更新用户
+     *
+     * @param cmd 更新命令
+     */
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public void updateUser(UserUpdateCmd cmd) {
+        log.info("更新用户, id: {}", cmd.getId());
+        userGateway.updateUser(cmd);
+    }
+
+    /**
+     * 删除用户
+     *
+     * @param id 用户ID
+     */
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public void deleteUser(Long id) {
+        log.info("删除用户, id: {}", id);
+        userGateway.deleteUser(id);
+    }
+}

package/template/.codex/skills/yss-ddd-scaffold-generator/assets/templates/bootstrap/YssDatamiddleApplication.java.template

@@ -0,0 +1,28 @@
+package {{base_package}};
+
+import com.yss.cloud.EnableDistributedId;
+import com.yss.cloud.cache.EnableYssCloudRedisCache;
+import com.yss.excel.mvc.annotation.EnableExcelMvc;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
+import org.springframework.context.annotation.EnableAspectJAutoProxy;
+import org.springframework.scheduling.annotation.EnableAsync;
+import org.springframework.boot.SpringApplication;
+
+@EnableAsync
+@EnableDiscoveryClient
+// @EnableYssCloudRedisCache // 请在确认 Redis 配置后取消注释
+@EnableAspectJAutoProxy
+// @EnableDistributedId // 请在确认分布式 ID 配置后取消注释
+@EnableExcelMvc
+@SpringBootApplication(scanBasePackages = {"com.yss.datamiddle", "com.yss.cloud"})
+public class YssDatamiddleApplication {
+    /**
+     * 应用程序入口方法，启动 Spring Boot 应用
+     *
+     * @param args 启动参数
+     */
+    public static void main(String[] args) {
+        SpringApplication.run(YssDatamiddleApplication.class, args);
+    }
+}

package/template/.codex/skills/yss-ddd-scaffold-generator/assets/templates/config/application.yml.template

@@ -0,0 +1,37 @@
+server:
+  port: 8080
+
+spring:
+  application:
+    name: {{project_name}}
+  
+  datasource:
+    primary:
+      url: {{jdbc_url}}
+      username: {{db_username}}
+      password: {{db_password}}
+      driver-class-name: {{driver_class}}
+      hikari:
+        maximum-pool-size: 20
+        minimum-idle: 5
+        connection-timeout: 30000
+        idle-timeout: 600000
+        max-lifetime: 1800000
+
+mybatis-plus:
+  configuration:
+    map-underscore-to-camel-case: true
+    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
+  global-config:
+    db-config:
+      id-type: assign_id
+      logic-delete-field: deleted
+      logic-delete-value: 1
+      logic-not-delete-value: 0
+
+logging:
+  level:
+    {{base_package}}: DEBUG
+    org.springframework.jdbc: DEBUG
+  pattern:
+    console: "%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n"

package/template/.codex/skills/yss-ddd-scaffold-generator/assets/templates/config/data.sql.template

@@ -0,0 +1,2 @@
+INSERT INTO t_user (id, username, email, status, description, deleted, created_by, created_date, last_modified_by, last_modified_date)
+VALUES (1, 'admin', 'admin@example.com', 1, 'default admin', 0, 'system', CURRENT_TIMESTAMP, 'system', CURRENT_TIMESTAMP);

package/template/.codex/skills/yss-ddd-scaffold-generator/assets/templates/config/logback-spring.xml.template

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<configuration>
+    <springProperty scope="context" name="appName" source="spring.application.name"/>
+    <property name="LOG_PATTERN" value="%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n"/>
+
+    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
+        <encoder>
+            <pattern>${LOG_PATTERN}</pattern>
+        </encoder>
+    </appender>
+
+    <root level="INFO">
+        <appender-ref ref="CONSOLE"/>
+    </root>
+</configuration>

package/template/.codex/skills/yss-ddd-scaffold-generator/assets/templates/config/parent-pom.xml.template

@@ -0,0 +1,84 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
+         http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <parent>
+        <groupId>com.yss.datamiddle</groupId>
+        <artifactId>yss-datamiddle-parent</artifactId>
+        <version>2.0.0-SNAPSHOT</version>
+        <relativePath/>
+    </parent>
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>{{group_id}}</groupId>
+    <artifactId>{{project_name}}-parent</artifactId>
+    <version>1.0.0-SNAPSHOT</version>
+    <packaging>pom</packaging>
+
+    <name>{{project_name}}-parent</name>
+    <description>{{project_description}}</description>
+
+    <properties>
+        <yss-components.version>2.0.0-SNAPSHOT</yss-components.version>
+        <mapstruct.version>1.5.5.Final</mapstruct.version>
+    </properties>
+
+    <modules>
+        <module>{{project_name}}-domain</module>
+        <module>{{project_name}}-application</module>
+        <module>{{project_name}}-infrastructure</module>
+        <module>{{project_name}}-adapter</module>
+        <module>{{project_name}}-bootstrap</module>
+    </modules>
+
+    <dependencyManagement>
+        <dependencies>
+            <dependency>
+                <groupId>com.yss.cloud</groupId>
+                <artifactId>yss-components-bom</artifactId>
+                <version>${yss-components.version}</version>
+                <type>pom</type>
+                <scope>import</scope>
+            </dependency>
+
+            <!-- 内部模块依赖 -->
+            <dependency>
+                <groupId>{{group_id}}</groupId>
+                <artifactId>{{project_name}}-domain</artifactId>
+                <version>${project.version}</version>
+            </dependency>
+            <dependency>
+                <groupId>{{group_id}}</groupId>
+                <artifactId>{{project_name}}-application</artifactId>
+                <version>${project.version}</version>
+            </dependency>
+            <dependency>
+                <groupId>{{group_id}}</groupId>
+                <artifactId>{{project_name}}-infrastructure</artifactId>
+                <version>${project.version}</version>
+            </dependency>
+        </dependencies>
+    </dependencyManagement>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-source-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>attach-sources</id>
+                        <goals>
+                            <goal>jar</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+</project>

package/template/.codex/skills/yss-ddd-scaffold-generator/assets/templates/config/schema.sql.template

@@ -0,0 +1,27 @@
+-- 用户表
+CREATE TABLE `t_user` (
+  `id` bigint(20) NOT NULL COMMENT '主键ID',
+  `username` varchar(50) NOT NULL COMMENT '用户名',
+  `email` varchar(100) DEFAULT NULL COMMENT '邮箱',
+  `status` tinyint(4) NOT NULL DEFAULT '1' COMMENT '状态：1-启用，0-禁用',
+  `description` varchar(500) DEFAULT NULL COMMENT '描述',
+  `deleted` tinyint(4) NOT NULL DEFAULT '0' COMMENT '删除标记：0-未删除，1-已删除',
+  `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`),
+  UNIQUE KEY `uk_username` (`username`),
+  KEY `idx_status` (`status`),
+  KEY `idx_created_date` (`created_date`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户表';
+
+-- Leaf Alloc 表
+CREATE TABLE `leaf_alloc` (
+  `biz_tag` varchar(128) NOT NULL COMMENT '业务标签',
+  `max_id` bigint(20) NOT NULL COMMENT '当前最大ID',
+  `step` int(11) NOT NULL COMMENT '步长',
+  `description` varchar(256) DEFAULT NULL COMMENT '描述',
+  `update_time` varchar(256) DEFAULT NULL COMMENT '更新时间',
+  PRIMARY KEY (`biz_tag`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='Leaf号段分配表';

package/template/.codex/skills/yss-ddd-scaffold-generator/assets/templates/domain/User.java.template

@@ -0,0 +1,17 @@
+package {{base_package}}.domain.user.model;
+
+import lombok.Data;
+
+@Data
+public class User {
+
+    private Long id;
+
+    private String username;
+
+    private String email;
+
+    private Integer status;
+
+    private String description;
+}

package/template/.codex/skills/yss-ddd-scaffold-generator/assets/templates/domain/UserAddCmd.java.template

@@ -0,0 +1,27 @@
+package {{base_package}}.client.dto.cmd;
+
+import com.yss.cloud.dto.CommandDTO;
+import lombok.Data;
+
+import javax.validation.constraints.Email;
+import javax.validation.constraints.NotBlank;
+import javax.validation.constraints.Size;
+
+/**
+ * 用户新增命令对象
+ *
+ * @author {{author}}
+ * @date {{date}}
+ */
+@Data
+public class UserAddCmd extends CommandDTO {
+
+    @NotBlank(message = "用户名不能为空")
+    @Size(min = 3, max = 50, message = "用户名长度必须在3-50之间")
+    private String username;
+
+    @Email(message = "邮箱格式不正确")
+    private String email;
+
+    private String description;
+}

package/template/.codex/skills/yss-ddd-scaffold-generator/assets/templates/domain/UserGateway.java.template

@@ -0,0 +1,54 @@
+package {{base_package}}.domain.user.gateway;
+
+import com.yss.cloud.dto.result.PageResult;
+import {{base_package}}.client.dto.cmd.UserAddCmd;
+import {{base_package}}.client.dto.cmd.UserUpdateCmd;
+import {{base_package}}.client.dto.query.UserPageQuery;
+import {{base_package}}.client.vo.UserVO;
+
+/**
+ * 用户网关接口
+ *
+ * @author {{author}}
+ * @date {{date}}
+ */
+public interface UserGateway {
+
+    /**
+     * 分页查询用户
+     *
+     * @param query 查询条件
+     * @return 分页结果
+     */
+    PageResult<UserVO> pageUser(UserPageQuery query);
+
+    /**
+     * 根据ID查询用户
+     *
+     * @param id 用户ID
+     * @return 用户信息
+     */
+    UserVO getUserById(Long id);
+
+    /**
+     * 新增用户
+     *
+     * @param cmd 新增命令
+     * @return 用户ID
+     */
+    Long addUser(UserAddCmd cmd);
+
+    /**
+     * 更新用户
+     *
+     * @param cmd 更新命令
+     */
+    void updateUser(UserUpdateCmd cmd);
+
+    /**
+     * 删除用户
+     *
+     * @param id 用户ID
+     */
+    void deleteUser(Long id);
+}

package/template/.codex/skills/yss-ddd-scaffold-generator/assets/templates/domain/UserPageQuery.java.template

@@ -0,0 +1,12 @@
+package {{base_package}}.client.dto.query;
+
+import com.yss.cloud.dto.page.PageQuery;
+import lombok.Data;
+
+@Data
+public class UserPageQuery extends PageQuery {
+
+    private String username;
+
+    private Integer status;
+}

package/template/.codex/skills/yss-ddd-scaffold-generator/assets/templates/domain/UserUpdateCmd.java.template

@@ -0,0 +1,21 @@
+package {{base_package}}.client.dto.cmd;
+
+import com.yss.cloud.dto.CommandDTO;
+import lombok.Data;
+
+import javax.validation.constraints.NotNull;
+import javax.validation.constraints.Size;
+
+@Data
+public class UserUpdateCmd extends CommandDTO {
+
+    @NotNull(message = "ID不能为空")
+    private Long id;
+
+    @Size(max = 50, message = "用户名长度不能超过50")
+    private String username;
+
+    private Integer status;
+
+    private String description;
+}