create-yss-spec 2.2.9 → 2.2.10

package/template/.trae/skills/yss-web-controller/assets/templates/web/dto/CreateRequest.java.template

@@ -0,0 +1,19 @@
+package ${base_package}.rest.dto.request;
+
+import com.yss.cloud.dto.CommandDTO;
+import lombok.Getter;
+import lombok.Setter;
+import ${validation_namespace}.validation.constraints.NotBlank;
+import ${validation_namespace}.validation.constraints.NotNull;
+import java.util.Date;
+import java.math.BigDecimal;
+import java.time.LocalDateTime;
+import java.time.LocalDate;
+
+/** ${domain_desc}新增请求。字段来自批准的 OpenAPI allowlist。 */
+@Getter
+@Setter
+public class ${domain_class}CreateRequest extends CommandDTO {
+
+${field_declarations}
+}

package/template/.trae/skills/yss-web-controller/assets/templates/web/dto/PageRequest.java.template

@@ -0,0 +1,24 @@
+package ${base_package}.rest.dto.request;
+
+import com.yss.cloud.dto.QueryDTO;
+import lombok.Getter;
+import lombok.Setter;
+import java.util.Date;
+import java.math.BigDecimal;
+import java.time.LocalDateTime;
+import java.time.LocalDate;
+
+/**
+ * ${domain_desc}分页请求。仅暴露已冻结的 HTTP 查询字段。
+ */
+@Getter
+@Setter
+public class ${domain_class}PageRequest extends QueryDTO {
+    private int pageIndex = 1;
+    private int pageSize = 20;
+    private String orderBy;
+    private String orderDirection;
+    private String groupBy;
+
+${field_declarations}
+}

package/template/.trae/skills/yss-web-controller/assets/templates/web/dto/Response.java.template

@@ -0,0 +1,18 @@
+package ${base_package}.rest.dto.response;
+
+import lombok.Getter;
+import lombok.Setter;
+import java.io.Serializable;
+import java.util.Date;
+import java.math.BigDecimal;
+import java.time.LocalDateTime;
+import java.time.LocalDate;
+
+/** ${domain_desc}公开响应。字段来自批准的 OpenAPI allowlist。 */
+@Getter
+@Setter
+public class ${domain_class}Response implements Serializable {
+    private static final long serialVersionUID = 1L;
+
+${field_declarations}
+}

package/template/.trae/skills/yss-web-controller/assets/templates/web/dto/UpdateRequest.java.template

@@ -0,0 +1,19 @@
+package ${base_package}.rest.dto.request;
+
+import com.yss.cloud.dto.CommandDTO;
+import lombok.Getter;
+import lombok.Setter;
+import ${validation_namespace}.validation.constraints.NotBlank;
+import ${validation_namespace}.validation.constraints.NotNull;
+import java.util.Date;
+import java.math.BigDecimal;
+import java.time.LocalDateTime;
+import java.time.LocalDate;
+
+/** ${domain_desc}更新请求。字段来自批准的 OpenAPI allowlist。 */
+@Getter
+@Setter
+public class ${domain_class}UpdateRequest extends CommandDTO {
+
+${field_declarations}
+}

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

@@ -1,168 +1,84 @@
-本技能为开发 YSS 服务的**Web 适配器层**（REST API）提供指导和框架。
-Web 适配器负责通过 HTTP 公开业务功能、处理输入验证和格式化响应。
+# YSS Web Adapter Target Profile 指南
 
-## 1. 核心职责 (Core Responsibilities)
+Web Adapter 负责 HTTP 边界、Wire DTO、校验、YSS Result 包装、WebConvertor 和异常翻译。它只调用 Application，不直接访问 Domain Gateway、Repository 或 PO。
 
-- **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.
+## 1. 包结构
 
+```text
+{base_package}.rest
+├── dto
+│   ├── request
+│   └── response
+├── convertor
+├── exception
+└── *Controller.java
 ```
-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)。
+DTO 固定属于 Web module。独立 client module 与把 client DTO 放进 Domain module 均为 `unsupported`；如未来确需发布复用制品，必须另行设计并批准新的 Target Profile，不能由当前脚手架推断或回退。
 
-### 3.3 参数与响应
+## 2. Wire 合同
 
-- **Command (写)**: 使用 `@PostMapping`/`@PutMapping` + `@RequestBody` + `{Domain}Cmd` 对象。
-- **Query (读)**: 使用 `@PostMapping` (for complex search) + `@RequestBody` + `{Domain}Page/Query` 对象。
-- **Wrapper**:
-  - `SingleResult<T>`: 单个对象或基本类型。
-  - `MultiResult<T>`: 列表。
-  - `PageResult<T>`: 分页数据。
-- **Validation**: 必须在参数前添加 `@Valid` 注解。
+- Request/Response 字段必须来自冻结 OpenAPI 和批准 allowlist。
+- 数据库 metadata 只补充 Java 类型候选，不能自行扩大公开字段。
+- Web Page Request 不继承含内部协作字段的 `PageQuery`；只暴露批准的 `pageIndex/pageSize/orderBy/orderDirection/groupBy` 及业务查询字段。
+- `orderBy` / `groupBy` 必须在 Application/Infrastructure 映射到数据库列白名单。
+- `offset`、`needTotalCount`、`tempTotalCount` 禁止进入 HTTP 绑定面。
 
-### 3.4 异常处理
-
-- **不要**在 Controller 中捕获通用异常 (`Exception`)。
-- 让全局异常处理器 (`GlobalExceptionHandler`) 统一处理运行时异常。
-- 仅在需要特定 HTTP 状态码转换时捕获特定异常。
-
-## 4. 代码示例 (Code Examples)
-
-### 4.1 标准 CRUD Controller
+## 3. 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}")
+@RequestMapping("/api/quality/quality-rule")
 @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));
-    }
+@Tag(name = "质量规则管理")
+public class QualityRuleController {
+    private final QualityRuleService service;
+    private final QualityRuleWebConvertor webConvertor;
 
-    /**
-     * 新增 {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());
+    public SingleResult<Long> create(@Valid @RequestBody QualityRuleCreateRequest request) {
+        return SingleResult.of(service.create(webConvertor.toCreateCommand(request)));
     }
 }
 ```
 
-### 4.2 复杂业务操作示例
+- 只使用 OpenAPI 3 `io.swagger.v3.oas.annotations`；Swagger 2 为 `unsupported`，不存在 legacy Profile。
+- Controller 不捕获通用 `Exception`，不写业务规则，不手工执行持久化分页。
+- Controller seam 只出现 Web Request/Response 和 Application Service。
+
+## 4. WebConvertor
 
 ```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)
-        );
-    }
+@Mapper(componentModel = "spring")
+public interface QualityRuleWebConvertor {
+    QualityRuleCreateCommand toCreateCommand(QualityRuleCreateRequest source);
+    QualityRuleResponse toResponse(QualityRuleResult source);
+}
 ```
 
-## 5. 阶段 7 合同
+- 使用构造器注入，不定义静态 `INSTANCE`。
+- Request → Application Command/Query；Application Result → Response。
+- 不导入 Domain Model 或 Repository PO。
+- 父 POM 必须配置 MapStruct processor、Lombok 与 `lombok-mapstruct-binding`，验证生成实现真实编译。
+
+## 5. Exception Translator
+
+- Domain/Application 错误经专门 Translator 映射为冻结 API 的 HTTP status、YSS error code 和消毒后的公开消息。
+- known business、known system、unknown/runtime 三类都必须有 MockMvc/HTTP contract test。
+- unknown/runtime 保留内部 cause/stack 用于日志，但公开响应禁止返回 `getLocalizedMessage()`。
+- 复用 YSS global handler 前必须实测 auto-configuration 和 precedence；未经验证不能仅凭依赖存在宣称生效。
+
+## 6. 生成门禁
+
+- `generate_controller.mjs` 必须消费 `status=approved` 的 Web generation contract。
+- 合同必须声明 `base_package`、`module_name`、`domain_segment`、`target-domain-model`、平台/validation Profile、`dto_placement=web`、OpenAPI Freeze 引用和每张表的 create/update/query/response allowlist；CLI 身份必须逐项匹配。
+- 生成器是 initialize-only，必须在写入前规划全部目标；任一文件已存在或传入 `--force` 时整体阻断，不允许“跳过已有文件后继续生成”的部分成功。
+- 权限、校验语义、异常行为和复杂查询仍使用 `behavior-tdd`，不能由 metadata 猜测。
+
+## 7. 验证
 
-- 只消费冻结 OpenAPI/no-impact record 和批准合同；Controller 不得穿透 Application/Domain 边界。
-- Controller/DTO/Convertor 骨架可受控生成；权限、校验、错误映射和接口行为使用 `behavior-tdd`。
-- 返回统一 `YSS Skill Execution Result`，包含代码、契约/API 测试、实际验证和新增 API/权限影响。
+- Controller 只依赖 Application。
+- WebConvertor 无 Domain/Infrastructure import，并由 Spring 注入。
+- Wire forbidden fields 无法绑定。
+- OpenAPI 3 注解、YSS Result wrapper、Validation namespace 与平台 Profile 一致。
+- 执行项目根 `./mvnw test/package`，并保留 HTTP/serialization/exception 证据。

package/template/.trae/skills/yss-web-controller/scripts/generate_controller.mjs

@@ -4,18 +4,22 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 const TYPE_MAPPING = { bigint: "Long", int: "Integer", integer: "Integer", smallint: "Integer", tinyint: "Integer", number: "Long", numeric: "BigDecimal", decimal: "BigDecimal", float: "Float", double: "Double", real: "Float", varchar: "String", varchar2: "String", nvarchar2: "String", char: "String", nchar: "String", text: "String", clob: "String", nclob: "String", date: "LocalDateTime", datetime: "LocalDateTime", timestamp: "LocalDateTime", "timestamp with time zone": "LocalDateTime", boolean: "Boolean", bool: "Boolean", bit: "Boolean", json: "String", jsonb: "String", uuid: "String" };
-const required = ["metadata-file", "base-package", "module-name", "domain-segment"];
-const valued = new Set([...required, "output-dir", "domain-project-dir", "web-project-dir", "domain-output-dir", "web-output-dir", "author", "application-service-package", "validation-namespace"]);
+const PLATFORM_VALIDATION_NAMESPACES = {
+  "spring-boot-2.7-jdk8": "javax",
+  "spring-boot-3-jdk17": "jakarta"
+};
+const required = ["metadata-file", "contract-file", "base-package", "module-name", "domain-segment"];
+const valued = new Set([...required, "output-dir", "web-project-dir", "web-output-dir", "author", "application-service-package", "validation-namespace"]);
 
 function usage() {
-  return "Usage: node generate_controller.mjs --metadata-file FILE --base-package PACKAGE --module-name NAME --domain-segment SEGMENT [--output-dir DIR] [--domain-project-dir DIR] [--web-project-dir DIR] [--domain-output-dir DIR] [--web-output-dir DIR] [--author NAME] [--force] [--application-service-package PACKAGE] [--validation-namespace javax|jakarta]";
+  return "Usage: node generate_controller.mjs --metadata-file FILE --contract-file FILE --base-package PACKAGE --module-name NAME --domain-segment SEGMENT [--output-dir DIR] [--web-project-dir DIR] [--web-output-dir DIR] [--author NAME] [--application-service-package PACKAGE] [--validation-namespace javax|jakarta]";
 }
 export function parseArgs(argv) {
   const args = { "output-dir": "./output", author: "System", "validation-namespace": "javax", force: false };
   for (let index = 0; index < argv.length; index += 1) {
     const token = argv[index];
     if (token === "--help" || token === "-h") return { help: true };
-    if (token === "--force") { args.force = true; continue; }
+    if (token === "--force") throw new Error("unsupported: initialize-only Web 生成禁止 --force、已有目标覆盖和旧项目迁移");
     if (!token.startsWith("--") || !valued.has(token.slice(2))) throw new Error(`unrecognized argument: ${token}`);
     const value = argv[++index];
     if (!value || value.startsWith("--")) throw new Error(`argument ${token} requires a value`);
@@ -32,9 +36,11 @@ const packagePath = (value) => value.replaceAll(".", path.sep);
 const ensureSubdir = (root, name) => path.basename(path.normalize(root)) === name ? root : path.join(root, name);
 const javaType = (sqlType = "") => TYPE_MAPPING[sqlType.toLowerCase().split("(")[0]] || "String";
 
-function fields(columns, { skipPk = false, command = false, skipAudit = true } = {}) {
-  const audit = new Set(["create_time", "update_time", "create_by", "update_by", "deleted", "version"]);
-  return columns.filter((column) => !(skipPk && column.primary) && !(skipAudit && audit.has(String(column.name).toLowerCase()))).map((column) => {
+function fields(columns, selected, { command = false } = {}) {
+  const byName = new Map(columns.map((column) => [String(column.name), column]));
+  return selected.map((field) => {
+    const column = byName.get(field);
+    if (!column) throw new Error(`approved field is absent from metadata: ${field}`);
     const type = javaType(column.sql_type);
     const name = lowerCamel(column.name);
     const comment = column.comment || "";
@@ -48,30 +54,52 @@ async function exists(target) { try { await access(target); return true; } catch
 
 export async function generate(args, logger = console) {
   if (!await exists(args["metadata-file"])) throw new Error(`Metadata file not found: ${args["metadata-file"]}`);
+  if (!await exists(args["contract-file"])) throw new Error(`Contract file not found: ${args["contract-file"]}`);
   let metadata;
   try { metadata = JSON.parse(await readFile(args["metadata-file"], "utf8")); } catch (error) { throw new Error(`Error reading metadata file: ${error.message}`); }
+  let contract;
+  try { contract = JSON.parse(await readFile(args["contract-file"], "utf8")); } catch (error) { throw new Error(`Error reading contract file: ${error.message}`); }
+  if (contract.schema_version !== 1 || contract.status !== "approved") throw new Error("web generation contract must be schema_version=1 and approved");
+  if (contract.architecture_profile !== "target-domain-model" || contract.dto_placement !== "web") throw new Error("web generation only supports target-domain-model with dto_placement=web");
+  if (!contract.openapi_freeze_ref || !contract.fields || typeof contract.fields !== "object") throw new Error("approved web generation contract requires openapi_freeze_ref and fields");
+  if (!contract.base_package || !contract.module_name || !contract.domain_segment) throw new Error("approved web generation contract requires base_package, module_name, and domain_segment");
+  if (contract.base_package !== args["base-package"] || contract.module_name !== args["module-name"] || contract.domain_segment !== args["domain-segment"]) throw new Error("CLI generation identity does not match the approved web generation contract");
+  if (!(contract.platform_profile in PLATFORM_VALIDATION_NAMESPACES)) throw new Error("unsupported platform_profile in approved web generation contract");
+  if (PLATFORM_VALIDATION_NAMESPACES[contract.platform_profile] !== contract.validation_namespace) throw new Error("platform_profile and validation_namespace are inconsistent");
+  if (contract.validation_namespace !== args["validation-namespace"]) throw new Error("--validation-namespace must match the approved web generation contract");
   const tables = metadata.tables || [];
   if (!tables.length) { logger.warn("Warning: No tables found in metadata."); return []; }
   const scriptDir = path.dirname(fileURLToPath(import.meta.url));
   const templatesDir = path.resolve(scriptDir, "../assets/templates");
   const template = async (name) => { const target = path.join(templatesDir, name); if (!await exists(target)) throw new Error(`Template not found: ${target}`); return readFile(target, "utf8"); };
-  const templates = Object.fromEntries(await Promise.all(["Controller.java.template", "WebConvertor.java.template", "domain/vo/VO.java.template", "domain/dto/cmd/AddCmd.java.template", "domain/dto/cmd/UpdateCmd.java.template", "domain/dto/query/PageQuery.java.template"].map(async (name) => [name, await template(name)])));
+  const templateNames = ["Controller.java.template", "WebConvertor.java.template", "web/dto/Response.java.template", "web/dto/CreateRequest.java.template", "web/dto/UpdateRequest.java.template", "web/dto/PageRequest.java.template"];
+  const templates = Object.fromEntries(await Promise.all(templateNames.map(async (name) => [name, await template(name)])));
   const basePath = packagePath(args["base-package"]);
-  const domainBase = args["domain-output-dir"] || (args["domain-project-dir"] ? path.join(args["domain-project-dir"], "src", "main", "java", basePath) : path.join(args["output-dir"], basePath));
   const webBase = args["web-output-dir"] || (args["web-project-dir"] ? path.join(args["web-project-dir"], "src", "main", "java", basePath) : path.join(args["output-dir"], basePath));
-  const domainRoot = ensureSubdir(domainBase, "client");
   const webRoot = ensureSubdir(webBase, "rest");
-  const written = [];
-  const write = async (target, contents) => { await mkdir(path.dirname(target), { recursive: true }); if (!await exists(target) || args.force) { await writeFile(target, contents, "utf8"); logger.log(`Generated: ${target}`); written.push(target); } else logger.log(`Skipped (exists): ${target}`); };
+  const planned = [];
+  const plan = (target, contents) => planned.push({ target, contents });
   for (const table of tables) {
     const domainClass = pascal(table.table_name); const domainVar = lowerCamel(table.table_name); const domainDesc = String(table.table_comment || domainClass).trim().replaceAll("\n", " ");
+    const approvedFields = contract.fields[table.table_name];
+    if (!approvedFields || ["create", "update", "query", "response"].some((name) => !Array.isArray(approvedFields[name]))) throw new Error(`approved web field contract is missing for table: ${table.table_name}`);
     const applicationPackage = args["application-service-package"] || `${args["base-package"]}.application.service`;
-    const context = { base_package: args["base-package"], module_name: args["module-name"], domain_class: domainClass, domain_var: domainVar, domain_desc: domainDesc, domain_url_path: kebab(table.table_name), domain_pkg_name: args["domain-segment"], author: args.author, dto_imports: [`import ${args["base-package"]}.client.dto.cmd.${domainClass}AddCmd;`, `import ${args["base-package"]}.client.dto.cmd.${domainClass}UpdateCmd;`, `import ${args["base-package"]}.client.dto.query.${domainClass}PageQuery;`, `import ${args["base-package"]}.client.vo.${domainClass}VO;`].join("\n"), application_service_import: `import ${applicationPackage}.${domainClass}Service;`, domain_import: `import ${args["base-package"]}.domain.${args["domain-segment"]}.model.${domainClass};`, web_convertor_import: `import ${args["base-package"]}.rest.convertor.${domainClass}WebConvertor;`, web_convertor_class: `${domainClass}WebConvertor`, application_service_field: `private final ${domainClass}Service ${domainVar}Service;`, query_call: `${domainVar}Service.page(query)`, detail_call: `${domainVar}Service.detail(id)`, add_call: `${domainVar}Service.add(cmd)`, update_call: `${domainVar}Service.update(cmd)`, delete_call: `${domainVar}Service.delete(id)`, vo_class: `${domainClass}VO`, add_cmd_class: `${domainClass}AddCmd`, update_cmd_class: `${domainClass}UpdateCmd`, query_class: `${domainClass}PageQuery`, validation_namespace: args["validation-namespace"] };
-    await write(path.join(webRoot, `${domainClass}Controller.java`), render(templates["Controller.java.template"], context));
-    await write(path.join(webRoot, "convertor", `${domainClass}WebConvertor.java`), render(templates["WebConvertor.java.template"], context));
-    for (const [templateName, target, declaration] of [["domain/vo/VO.java.template", path.join(domainRoot, "vo", `${domainClass}VO.java`), fields(table.columns || [], { skipAudit: false })], ["domain/dto/cmd/AddCmd.java.template", path.join(domainRoot, "dto/cmd", `${domainClass}AddCmd.java`), fields(table.columns || [], { skipPk: true, command: true })], ["domain/dto/cmd/UpdateCmd.java.template", path.join(domainRoot, "dto/cmd", `${domainClass}UpdateCmd.java`), fields(table.columns || [], { command: true })], ["domain/dto/query/PageQuery.java.template", path.join(domainRoot, "dto/query", `${domainClass}PageQuery.java`), fields(table.columns || [])]]) await write(target, render(templates[templateName], { ...context, field_declarations: declaration }));
+    const context = { base_package: args["base-package"], module_name: args["module-name"], domain_class: domainClass, domain_var: domainVar, domain_desc: domainDesc, domain_url_path: kebab(table.table_name), domain_pkg_name: args["domain-segment"], author: args.author, dto_imports: [`import ${args["base-package"]}.rest.dto.request.${domainClass}CreateRequest;`, `import ${args["base-package"]}.rest.dto.request.${domainClass}UpdateRequest;`, `import ${args["base-package"]}.rest.dto.request.${domainClass}PageRequest;`, `import ${args["base-package"]}.rest.dto.response.${domainClass}Response;`].join("\n"), application_type_imports: [`import ${args["base-package"]}.application.command.${domainClass}CreateCommand;`, `import ${args["base-package"]}.application.command.${domainClass}UpdateCommand;`, `import ${args["base-package"]}.application.query.${domainClass}PageQuery;`, `import ${args["base-package"]}.application.result.${domainClass}Result;`].join("\n"), application_service_import: `import ${applicationPackage}.${domainClass}Service;`, web_convertor_import: `import ${args["base-package"]}.rest.convertor.${domainClass}WebConvertor;`, web_convertor_class: `${domainClass}WebConvertor`, application_service_field: `private final ${domainClass}Service ${domainVar}Service;`, query_call: `${domainVar}Service.page(webConvertor.toPageQuery(request))`, detail_call: `${domainVar}Service.detail(id)`, add_call: `${domainVar}Service.add(webConvertor.toCreateCommand(request))`, update_call: `${domainVar}Service.update(webConvertor.toUpdateCommand(request))`, delete_call: `${domainVar}Service.delete(id)`, response_class: `${domainClass}Response`, create_request_class: `${domainClass}CreateRequest`, update_request_class: `${domainClass}UpdateRequest`, page_request_class: `${domainClass}PageRequest`, validation_namespace: args["validation-namespace"] };
+    plan(path.join(webRoot, `${domainClass}Controller.java`), render(templates["Controller.java.template"], context));
+    plan(path.join(webRoot, "convertor", `${domainClass}WebConvertor.java`), render(templates["WebConvertor.java.template"], context));
+    for (const [templateName, target, declaration] of [["web/dto/Response.java.template", path.join(webRoot, "dto", "response", `${domainClass}Response.java`), fields(table.columns || [], approvedFields.response)], ["web/dto/CreateRequest.java.template", path.join(webRoot, "dto", "request", `${domainClass}CreateRequest.java`), fields(table.columns || [], approvedFields.create, { command: true })], ["web/dto/UpdateRequest.java.template", path.join(webRoot, "dto", "request", `${domainClass}UpdateRequest.java`), fields(table.columns || [], approvedFields.update, { command: true })], ["web/dto/PageRequest.java.template", path.join(webRoot, "dto", "request", `${domainClass}PageRequest.java`), fields(table.columns || [], approvedFields.query)]]) plan(target, render(templates[templateName], { ...context, field_declarations: declaration }));
   }
-  return written;
+  const targets = planned.map(({ target }) => target);
+  if (new Set(targets).size !== targets.length) throw new Error("approved metadata produces duplicate target files");
+  const existing = [];
+  for (const target of targets) if (await exists(target)) existing.push(target);
+  if (existing.length) throw new Error(`initialize-only Web generation refuses existing targets: ${existing.join(", ")}`);
+  for (const { target, contents } of planned) {
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, contents, "utf8");
+    logger.log(`Generated: ${target}`);
+  }
+  return targets;
 }
 async function main() { try { const args = parseArgs(process.argv.slice(2)); if (args.help) { console.log(usage()); return; } await generate(args); } catch (error) { console.error(`Error: ${error.message}`); process.exitCode = 1; } }
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main();

package/template/.trae/skills/yss-web-controller/scripts/generate_controller.test.mjs

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import test from "node:test";
@@ -8,12 +8,53 @@ import { generate, parseArgs } from "./generate_controller.mjs";
 test("generates application-service controller with requested validation profile", async () => {
   const root = await mkdtemp(path.join(tmpdir(), "yss-controller-"));
   const metadata = path.join(root, "metadata.json");
+  const contract = path.join(root, "web-contract.json");
   await writeFile(metadata, JSON.stringify({ tables: [{ table_name: "quality_rule", table_comment: "质量规则", columns: [{ name: "id", sql_type: "bigint", primary: true, nullable: false }, { name: "rule_name", sql_type: "varchar(64)", nullable: false }] }] }));
-  await generate(parseArgs(["--metadata-file", metadata, "--base-package", "com.yss.demo", "--module-name", "demo", "--domain-segment", "quality", "--output-dir", path.join(root, "out"), "--application-service-package", "com.yss.demo.application.service", "--validation-namespace", "jakarta"]), { log() {}, warn() {} });
+  await writeFile(contract, JSON.stringify({ schema_version: 1, status: "approved", base_package: "com.yss.demo", module_name: "demo", domain_segment: "quality", architecture_profile: "target-domain-model", platform_profile: "spring-boot-3-jdk17", validation_namespace: "jakarta", dto_placement: "web", openapi_freeze_ref: "openapi://quality-rule@1", fields: { quality_rule: { create: ["rule_name"], update: ["id", "rule_name"], query: ["rule_name"], response: ["id", "rule_name"] } } }));
+  await generate(parseArgs(["--metadata-file", metadata, "--contract-file", contract, "--base-package", "com.yss.demo", "--module-name", "demo", "--domain-segment", "quality", "--output-dir", path.join(root, "out"), "--application-service-package", "com.yss.demo.application.service", "--validation-namespace", "jakarta"]), { log() {}, warn() {} });
   const controller = await readFile(path.join(root, "out", "com", "yss", "demo", "rest", "QualityRuleController.java"), "utf8");
+  const convertor = await readFile(path.join(root, "out", "com", "yss", "demo", "rest", "convertor", "QualityRuleWebConvertor.java"), "utf8");
+  const createRequest = await readFile(path.join(root, "out", "com", "yss", "demo", "rest", "dto", "request", "QualityRuleCreateRequest.java"), "utf8");
   assert.match(controller, /import com\.yss\.demo\.application\.service\.QualityRuleService;/);
   assert.match(controller, /import jakarta\.validation\.Valid;/);
-  assert.doesNotMatch(controller, /Gateway/);
+  assert.match(controller, /webConvertor\.toCreateCommand\(request\)/);
+  assert.match(convertor, /@Mapper\(componentModel = "spring"\)/);
+  assert.match(convertor, /application\.command\.QualityRuleCreateCommand/);
+  assert.match(convertor, /application\.result\.QualityRuleResult/);
+  assert.doesNotMatch(`${controller}\n${convertor}`, /Gateway|\.domain\.|Mappers\.getMapper|INSTANCE/);
+  assert.match(createRequest, /private String ruleName;/);
+  assert.doesNotMatch(createRequest, /private Long id;|@Data/);
 });
 
 test("rejects missing required CLI arguments", () => assert.throws(() => parseArgs(["--module-name", "demo"]), /required/));
+
+test("requires an approved target-profile field contract and refuses force overwrite", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "yss-controller-contract-"));
+  const metadata = path.join(root, "metadata.json");
+  const contract = path.join(root, "web-contract.json");
+  await writeFile(metadata, JSON.stringify({ tables: [{ table_name: "quality_rule", columns: [{ name: "id", sql_type: "bigint", primary: true, nullable: false }] }] }));
+  await writeFile(contract, JSON.stringify({ schema_version: 1, status: "draft", base_package: "com.yss.demo", module_name: "demo", domain_segment: "quality", architecture_profile: "target-domain-model", platform_profile: "spring-boot-2.7-jdk8", validation_namespace: "javax", dto_placement: "web", openapi_freeze_ref: "openapi://quality-rule@1", fields: { quality_rule: { create: [], update: ["id"], query: [], response: ["id"] } } }));
+  const base = ["--metadata-file", metadata, "--contract-file", contract, "--base-package", "com.yss.demo", "--module-name", "demo", "--domain-segment", "quality", "--output-dir", path.join(root, "out")];
+  await assert.rejects(() => generate(parseArgs(base), { log() {}, warn() {} }), /approved/);
+  await writeFile(contract, JSON.stringify({ schema_version: 1, status: "approved", base_package: "com.yss.demo", module_name: "demo", domain_segment: "quality", architecture_profile: "target-domain-model", platform_profile: "spring-boot-2.7-jdk8", validation_namespace: "javax", dto_placement: "web", openapi_freeze_ref: "openapi://quality-rule@1", fields: { quality_rule: { create: [], update: ["id"], query: [], response: ["id"] } } }));
+  await writeFile(contract, JSON.stringify({ schema_version: 1, status: "approved", base_package: "com.yss.demo", module_name: "demo", domain_segment: "quality", architecture_profile: "target-domain-model", platform_profile: "spring-boot-3-jdk17", validation_namespace: "javax", dto_placement: "web", openapi_freeze_ref: "openapi://quality-rule@1", fields: { quality_rule: { create: [], update: ["id"], query: [], response: ["id"] } } }));
+  await assert.rejects(() => generate(parseArgs(base), { log() {}, warn() {} }), /platform_profile and validation_namespace/);
+  assert.throws(() => parseArgs([...base, "--force"]), /initialize-only/);
+});
+
+test("binds generation identity to the approved contract and fails before writing when any target exists", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "yss-controller-initialize-only-"));
+  const metadata = path.join(root, "metadata.json");
+  const contract = path.join(root, "web-contract.json");
+  const output = path.join(root, "out");
+  await writeFile(metadata, JSON.stringify({ tables: [{ table_name: "quality_rule", columns: [{ name: "id", sql_type: "bigint", nullable: false }] }] }));
+  await writeFile(contract, JSON.stringify({ schema_version: 1, status: "approved", base_package: "com.yss.demo", module_name: "demo", domain_segment: "quality", architecture_profile: "target-domain-model", platform_profile: "spring-boot-2.7-jdk8", validation_namespace: "javax", dto_placement: "web", openapi_freeze_ref: "openapi://quality-rule@1", fields: { quality_rule: { create: [], update: ["id"], query: [], response: ["id"] } } }));
+  const args = ["--metadata-file", metadata, "--contract-file", contract, "--base-package", "com.yss.demo", "--module-name", "demo", "--domain-segment", "quality", "--output-dir", output];
+  await assert.rejects(() => generate(parseArgs(args.map((value) => value === "demo" ? "other" : value)), { log() {}, warn() {} }), /approved web generation contract/);
+  const existing = path.join(output, "com/yss/demo/rest/QualityRuleController.java");
+  await mkdir(path.dirname(existing), { recursive: true });
+  await writeFile(existing, "user-owned\n");
+  await assert.rejects(() => generate(parseArgs(args), { log() {}, warn() {} }), /initialize-only/);
+  assert.equal(await readFile(existing, "utf8"), "user-owned\n");
+  await assert.rejects(() => readFile(path.join(output, "com/yss/demo/rest/convertor/QualityRuleWebConvertor.java"), "utf8"), /ENOENT/);
+});

package/template/.vscode/mcp.json

@@ -0,0 +1,8 @@
+{
+  "servers": {
+    "yss-ui": {
+      "command": "npx",
+      "args": ["-y", "@yss-ui/mcp"]
+    }
+  }
+}

package/template/README.md

@@ -48,6 +48,8 @@
 
 YSS skills 的公开发布投影维护在 [iloveZzz/yss-spec-dev-skills](https://github.com/iloveZzz/yss-spec-dev-skills)，发布清单和导出命令见 [skills 维护说明](./docs/agents/skills-maintenance.md)。
 
+YSS UI 组件知识同时通过项目级 MCP 配置提供；支持的客户端、Codex 全局安装和自检方法见 [YSS UI MCP 接入](./docs/user-guide/yss-ui-mcp.md)。
+
 ## 模板初始化 CLI
 
 `create-yss-spec` 的目标维护位置是独立 GitHub 仓库 [iloveZzz/create-yss-spec](https://github.com/iloveZzz/create-yss-spec)。本仓库不再包含 CLI 源码、测试、发布配置或开发过程记录。CLI 的使用方法已经合并到统一用户手册：
@@ -113,6 +115,7 @@ scripts/verify-template-fast
 | [docs/process/implementation-repo-integration.md](./docs/process/implementation-repo-integration.md) | 外部前端 / 后端实现仓库接入与跨仓库切片绑定 |
 | [docs/agents/README.md](./docs/agents/README.md) | Agent 协作文档目录说明 |
 | [docs/agents/skills-maintenance.md](./docs/agents/skills-maintenance.md) | Agent skills 安装与维护 |
+| [docs/user-guide/yss-ui-mcp.md](./docs/user-guide/yss-ui-mcp.md) | YSS UI MCP 项目配置、全局安装边界与自检 |
 | [docs/discovery/IDEATION.md](./docs/discovery/IDEATION.md) | 机会构想方法 |
 | [docs/architecture/README.md](./docs/architecture/README.md) | 架构设计 + 审查清单 |
 | [docs/testing/README.md](./docs/testing/README.md) | 测试策略 |

package/template/docs/agents/digital-human-roles.yaml

@@ -137,7 +137,7 @@ roles:
     title: YSS 前端工程师
     stages: [stage.product-design, stage.system-data-engineering, stage.ticket-formalization, stage.vertical-slice-implementation, stage.verification-release-retrospective]
     draft_artifact_ids: [artifact.frontend-implementation-plan]
-    core_skills: [yss-ui, yss-page-module-development, yss-components, yss-formily, formily-foundation, formily-linkage-effects, formily-mode-slot-detail, formily-step-flow, ytable-usage, ytree-usage, yedit-table-usage, yss-api-integration, yss-hook, theme-token-usage, page-skeleton, page-list-module, page-form-module, component-selection-imports, vue3-best-practices, tdd]
+    core_skills: [yss-ui, yss-ui-business-page-generation, yss-page-module-development, yss-components, yss-formily, formily-foundation, formily-linkage-effects, formily-mode-slot-detail, formily-step-flow, ytable-usage, ytree-usage, yedit-table-usage, yss-api-integration, yss-hook, theme-token-usage, page-skeleton, page-list-module, page-form-module, component-selection-imports, vue3-best-practices, tdd]
     forbidden_skills: [yss-domain, yss-application, yss-repository, yss-mybatis, yss-web-controller, yss-ddd-scaffold-generator, java-backend-commit]
     description: >-
       Own Vue page modules, frontend tests, and frontend_implementation_plan.

package/template/docs/agents/skills-maintenance.md

@@ -18,6 +18,7 @@
 | `mattpocock/skills` | `0ab1b63a410a03d3627979a109c8695de27af954` / `skills/engineering` 及锁文件记录的关联路径 | 通用工程流程及关联 skills |
 | `anthropics/knowledge-work-plugins` | `sales/skills/competitive-intelligence` | 竞品与市场事实研究 |
 | `tt-a1i/archify` | `199360cc6687a7857b54dd188d4922b09e466a4b` / `archify` | 条件式、可验证的技术架构图；YSS 适配见 `docs/agents/archify-integration.md` |
+| `iloveZzz/yss-ui` | `.agents/skills/.yss-skills-manifest.json` 锁定的 revision / `packages/skills` | 22 个 `categories.app` 业务前端 skills；排除组件库内部 `categories.library` 和后端提交 skill，适配见 `docs/agents/yss-ui-skills-integration.md` |
 | 项目本地 | `.agents/skills` 或平台专属 root | YSS 适配与项目治理 skills |
 
 `skills-lock.json` 是技能清单、来源、上游哈希、当前有效内容哈希和投影目标的权威记录：
@@ -44,10 +45,11 @@
    scripts/update-skill-lock
    ```
 
-   若来源来自可访问的 Matt checkout，还应显式校验锁定 revision 与每个上游目录哈希：
+   若来源来自可访问的上游 checkout，还应显式校验锁定 revision 与每个上游目录哈希：
 
    ```bash
-   scripts/verify-upstream-skill-source --source-root <matt-skills-checkout>
+   scripts/verify-upstream-skill-source --source=mattpocock/skills --source-root <matt-skills-checkout>
+   scripts/verify-upstream-skill-source --source=iloveZzz/yss-ui --source-root <yss-ui-checkout>
    ```
 
    新增共享 skill 时先显式登记：`scripts/update-skill-lock --add=<skill-name>`；新增平台专属 skill 使用 `scripts/update-skill-lock --add-platform=<root>:<skill-name>`。脚本不会把工作区中偶然出现的未跟踪目录自动纳入发布清单。
@@ -74,8 +76,9 @@
 ```bash
 scripts/sync-skills --check
 scripts/update-skill-lock --check
-# 可选：对照锁文件中的 mattpocock/skills revision 与上游目录哈希
-scripts/verify-upstream-skill-source --source-root <matt-skills-checkout>
+# 可选：对照锁文件中的 source revision 与上游目录哈希
+scripts/verify-upstream-skill-source --source=mattpocock/skills --source-root <matt-skills-checkout>
+scripts/verify-upstream-skill-source --source=iloveZzz/yss-ui --source-root <yss-ui-checkout>
 ```
 
 前者检查所有共享投影是否指向或匹配权威内容，后者检查 `skills-lock.json` 是否与当前完整目录树一致。过时技能不会保留兼容别名；旧 skill 名称和入口按 [`docs/agents/skill-migrations.md`](./skill-migrations.md) 一次性迁移，项目文件升级由 `create-yss-spec attach` / `sync` 处理。

package/template/docs/agents/yss-skill-registry.yaml

@@ -447,7 +447,7 @@ skills:
     layer: specialist
     maturity: supported
     instance_default_discoverable: false
-    aliases: [page-module-development, yss-ui-business-page-generation]
+    aliases: [page-module-development]
     impacts: [frontend]
   - id: yss-product-lifecycle
     layer: core
@@ -503,6 +503,12 @@ skills:
     instance_default_discoverable: false
     aliases: []
     impacts: [frontend]
+  - id: yss-ui-business-page-generation
+    layer: specialist
+    maturity: supported
+    instance_default_discoverable: false
+    aliases: []
+    impacts: [frontend]
   - id: yss-up-springboot3
     layer: specialist
     maturity: supported

package/template/docs/agents/yss-ui-skills-integration.md

@@ -0,0 +1,24 @@
+# YSS UI 前端 Skills 集成合同
+
+本模板以 `iloveZzz/yss-ui` 的 `packages/skills` 为上游来源，以 `.agents/skills/.yss-skills-manifest.json` 冻结来源 revision、包版本、目录映射和上游树哈希。`.agents/skills` 仍是模板内跨 Agent 共享内容的唯一权威目录；其他 Agent root 只接收生成投影。
+
+## 范围
+
+- 只集成 yss-ui `skills.config.json` 中 `categories.app` 的业务项目 skills，并排除后端 `java-backend-commit`，当前共 22 个。
+- `categories.library` 的 10 个组件库内部维护 skills 全部不进入模板；该分组同时位于上游 `excludeFromDefaultSync`。
+- `api-integration`、`page-module-development`、`use-table-height`、`use-tree-height` 在模板中分别映射为 `yss-api-integration`、`yss-page-module-development`、`yss-use-table-height`、`yss-use-tree-height`，旧名称只作为 registry alias。
+- `java-backend-commit` 明确不属于本合同；其内容、路由与锁定信息不随本前端同步更新。
+- 允许模板基于生命周期、组件路由和证据门禁做受控适配；适配后的 `effectiveHash` 与上游 `upstreamHash` 同时进入 `skills-lock.json`。
+
+## 更新步骤
+
+1. 在临时 checkout 中确认 `iloveZzz/yss-ui` 的目标 revision，并更新 `.agents/skills/.yss-skills-manifest.json`。
+2. 将新增或替换内容只写入 `.agents/skills/<canonical-name>`，不得直接编辑平台投影。
+3. 新增 skill 使用 `scripts/update-skill-lock --add=<canonical-name>` 显式登记。
+4. 运行 `scripts/sync-skills` 与 `scripts/update-skill-lock`。
+5. 使用 `scripts/verify-upstream-skill-source --source=iloveZzz/yss-ui --source-root=<checkout>` 验证 revision、清单和树哈希。
+6. 执行 `scripts/verify-template-fast`；首次冻结或正式发布前执行 `scripts/verify-template`。
+
+## MCP
+
+项目级 MCP 配置路径和容器字段同样由 manifest 固定，配置内容必须使用 `npx -y @yss-ui/mcp`。需要全局配置的运行时只提供人工安装说明，模板不得自动修改用户主目录。