create-yss-spec 2.2.8 → 2.2.10

package/template/.hermes/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/.hermes/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/.hermes/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/.hermes/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/.hermes/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/.hermes/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/.hermes/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/.kiro/settings/mcp.json

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

package/template/.mcp.json

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

package/template/.pi/skills/code-review/references/yss-review-standards.md

@@ -12,10 +12,10 @@
 2. Slice Implementation Contract 的 `required_skills`：对每个技能读取 `.agents/skills/<id>/SKILL.md` 及该 skill 指明的 references。
 3. 影响面专项检查输入（与合同并集，不得互相替代）：
    - 后端：`alibaba-java-code-style`、`yss-domain`、`yss-application`、`yss-repository`、`yss-web-controller`、`yss-dto`、`mapstruct`、`lombok`
-   - UI：`yss-ui`、`yss-design-system`、`yss-page-module-development`
+   - UI：`yss-ui`、`yss-design-system`、`yss-ui-business-page-generation`、`yss-page-module-development`
 4. 报告模板中的后端 / 前端门禁表。空着的适用行视为 `missing_evidence`。
 
-YSS 页面模块约定（YTable、YssFormily、页面骨架等）走 Standards，不并入 UI fidelity。UI fidelity 只核原型与状态矩阵。
+YSS 页面模块约定（YTable、YFormily、页面骨架等）走 Standards，不并入 UI fidelity。UI fidelity 只核原型与状态矩阵。
 
 审查者只读这些 skill，不得用它们写实现路径。`role.test-engineer` 任务包禁止 `implement` 与脚手架生成器。
 
@@ -51,4 +51,4 @@ YSS 页面模块约定（YTable、YssFormily、页面骨架等）走 Standards
 | `violation`、机器检查失败、适用行空白、`missing_evidence` | 实现者在**原合同允许路径**内修复；任何修复使候选失效，必须重新捕获并重跑 Standards、Spec、UI fidelity（若命中）和 fresh verification |
 | `drift`、`new_impacts`、`required_skills` 与真实影响不一致 | 合同标 `stale`，回 Router 或更早生命周期阶段；禁止在旧合同上继续编码 |
 
-`not-applicable` 仅当影响面未命中。命中后的 mandatory 不得豁免；只允许修复，或写完整 `seam-deferred`（风险、责任人、后续 Ticket、验证计划、目标版本或发布日期）。禁止为日常 Alibaba / YSS 新增生物人豁免门禁；安全 / 公共 API 仍走既有 `TODO-HUMAN-REVIEW` 与生物人门禁。
+`not-applicable` 仅当影响面未命中。命中后的 mandatory 不得豁免；只允许修复，或写完整 `seam-deferred`（风险、责任人、后续 Ticket、验证计划、目标版本或发布日期）。禁止为日常 Alibaba / YSS 新增生物人豁免门禁；安全 / 公共 API 仍走既有 `TODO-HUMAN-REVIEW` 与生物人门禁。

package/template/.pi/skills/component-selection-imports/SKILL.md

@@ -19,8 +19,8 @@ description: 指导 YSS UI 业务页面、CRUD、列表页、表单页和组件
 
 1. 当前会话可用 yss-ui MCP 时，先用 `list_components` 确认组件、Hook 或 Utils 是否真实存在，再用 `get_component_docs` 确认名称、导出包、Props、Events 和 Slots，不只看 demo 标签名。
 2. `get_component_docs` 未命中时，先用 `search_docs` 和 `list_components` 校正别名与归属，不得立即判定为未封装。
-3. MCP 工具不可用、调用失败或校正后仍无结果时，读取当前上下文中的最新 `llms-full.txt`；上下文没有时读取 `http://192.168.164.27:3200/llms-full.txt`。
-4. 必要时读取 `../yss-page-module-development/references/component-map.md`、`hooks-map.md`、`utils-map.md` 快速缩小范围；文档与当前项目依赖版本不一致时，最终以当前源码和可编译导出为准。
+3. MCP 工具不可用、调用失败或校正后仍无结果时，读取当前上下文或文档站的最新 `llms-full.txt`。
+4. 必要时读取 `../yss-ui-business-page-generation/references/component-map.md`、`hooks-map.md`、`utils-map.md` 快速缩小范围；文档与当前项目依赖版本不一致时，最终以当前源码和可编译导出为准。
 5. 已导出的 YSS 能力优先从 `@yss-ui/components`、`@yss-ui/hooks`、`@yss-ui/utils` 导入；确认未封装后才从 `ant-design-vue` 导入原组件。
 6. 若文档与导出源码不一致，记录差异并按当前仓库可编译的导出处理，不猜测 API。
 

package/template/.pi/skills/frontend-commit/SKILL.md

@@ -14,7 +14,7 @@ description: 分析并提交 Vue、React、TypeScript、JavaScript、Vite、微
 
 ## 不适用场景
 
-- yss-ui 组件库仓库自身的提交与发版：使用 `../commit-linting/SKILL.md`。
+- yss-ui 组件库仓库自身的提交与发版：回到 yss-ui 源仓库使用其 `categories.library` 提交流程；该类 skill 不随业务模板分发。
 - Java、Spring Boot、Maven、Gradle 后端仓库：使用 `../java-backend-commit/SKILL.md`。
 - 仅请求代码实现，不涉及提交信息或 `git commit` 操作。
 - 无代码改动，或改动内容与提交请求不匹配。