create-yss-spec 2.2.10 → 3.0.1

package/template/.hermes/skills/yss-web-controller/assets/templates/WebConvertor.java.template

@@ -1,33 +0,0 @@
-package ${base_package}.rest.convertor;
-
-import com.yss.cloud.dto.result.PageResult;
-${application_type_imports}
-import ${base_package}.rest.dto.request.${domain_class}CreateRequest;
-import ${base_package}.rest.dto.request.${domain_class}UpdateRequest;
-import ${base_package}.rest.dto.request.${domain_class}PageRequest;
-import ${base_package}.rest.dto.response.${domain_class}Response;
-import org.mapstruct.Mapper;
-import java.util.List;
-
-@Mapper(componentModel = "spring")
-public interface ${web_convertor_class} {
-
-    ${domain_class}CreateCommand toCreateCommand(${domain_class}CreateRequest source);
-
-    ${domain_class}UpdateCommand toUpdateCommand(${domain_class}UpdateRequest source);
-
-    ${domain_class}PageQuery toPageQuery(${domain_class}PageRequest source);
-
-    ${domain_class}Response toResponse(${domain_class}Result source);
-
-    List<${domain_class}Response> toResponses(List<${domain_class}Result> source);
-
-    default PageResult<${domain_class}Response> toResponsePage(PageResult<${domain_class}Result> source) {
-        return PageResult.of(
-                toResponses(source.getData()),
-                source.getTotalCount(),
-                source.getPageSize(),
-                source.getPageIndex()
-        );
-    }
-}

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

@@ -1,19 +0,0 @@
-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

@@ -1,24 +0,0 @@
-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

@@ -1,18 +0,0 @@
-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

@@ -1,19 +0,0 @@
-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,84 +0,0 @@
-# YSS Web Adapter Target Profile 指南
-
-Web Adapter 负责 HTTP 边界、Wire DTO、校验、YSS Result 包装、WebConvertor 和异常翻译。它只调用 Application，不直接访问 Domain Gateway、Repository 或 PO。
-
-## 1. 包结构
-
-```text
-{base_package}.rest
-├── dto
-│   ├── request
-│   └── response
-├── convertor
-├── exception
-└── *Controller.java
-```
-
-DTO 固定属于 Web module。独立 client module 与把 client DTO 放进 Domain module 均为 `unsupported`；如未来确需发布复用制品，必须另行设计并批准新的 Target Profile，不能由当前脚手架推断或回退。
-
-## 2. Wire 合同
-
-- Request/Response 字段必须来自冻结 OpenAPI 和批准 allowlist。
-- 数据库 metadata 只补充 Java 类型候选，不能自行扩大公开字段。
-- Web Page Request 不继承含内部协作字段的 `PageQuery`；只暴露批准的 `pageIndex/pageSize/orderBy/orderDirection/groupBy` 及业务查询字段。
-- `orderBy` / `groupBy` 必须在 Application/Infrastructure 映射到数据库列白名单。
-- `offset`、`needTotalCount`、`tempTotalCount` 禁止进入 HTTP 绑定面。
-
-## 3. Controller
-
-```java
-@RestController
-@RequestMapping("/api/quality/quality-rule")
-@RequiredArgsConstructor
-@Tag(name = "质量规则管理")
-public class QualityRuleController {
-    private final QualityRuleService service;
-    private final QualityRuleWebConvertor webConvertor;
-
-    @PostMapping
-    public SingleResult<Long> create(@Valid @RequestBody QualityRuleCreateRequest request) {
-        return SingleResult.of(service.create(webConvertor.toCreateCommand(request)));
-    }
-}
-```
-
-- 只使用 OpenAPI 3 `io.swagger.v3.oas.annotations`；Swagger 2 为 `unsupported`，不存在 legacy Profile。
-- Controller 不捕获通用 `Exception`，不写业务规则，不手工执行持久化分页。
-- Controller seam 只出现 Web Request/Response 和 Application Service。
-
-## 4. WebConvertor
-
-```java
-@Mapper(componentModel = "spring")
-public interface QualityRuleWebConvertor {
-    QualityRuleCreateCommand toCreateCommand(QualityRuleCreateRequest source);
-    QualityRuleResponse toResponse(QualityRuleResult source);
-}
-```
-
-- 使用构造器注入，不定义静态 `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. 验证
-
-- 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

@@ -1,105 +0,0 @@
-#!/usr/bin/env node
-import { access, mkdir, readFile, writeFile } from "node:fs/promises";
-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 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 --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") 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`);
-    args[token.slice(2)] = value;
-  }
-  for (const key of required) if (!args[key]) throw new Error(`the following arguments are required: --${key}`);
-  if (!new Set(["javax", "jakarta"]).has(args["validation-namespace"])) throw new Error("--validation-namespace must be javax or jakarta");
-  return args;
-}
-const pascal = (value) => value.toLowerCase().split("_").map((part) => part ? part[0].toUpperCase() + part.slice(1) : "").join("");
-const lowerCamel = (value) => { const output = pascal(value); return output ? output[0].toLowerCase() + output.slice(1) : ""; };
-const kebab = (value) => value.toLowerCase().replaceAll("_", "-");
-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, 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 || "";
-    const documentation = comment ? `    /**\n     * ${comment}\n     */\n` : "";
-    const validation = command && !column.nullable ? `    @${type === "String" ? "NotBlank" : "NotNull"}(message = \"${comment || name}不能为空\")\n` : "";
-    return `${documentation}${validation}    private ${type} ${name};`;
-  }).join("\n\n");
-}
-function render(template, context) { return template.replace(/\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))/g, (_, braced, plain) => { const key = braced || plain; if (!(key in context)) throw new Error(`missing template field: ${key}`); return context[key]; }); }
-async function exists(target) { try { await access(target); return true; } catch { return false; } }
-
-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 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 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 webRoot = ensureSubdir(webBase, "rest");
-  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"]}.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 }));
-  }
-  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,60 +0,0 @@
-import assert from "node:assert/strict";
-import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import path from "node:path";
-import test from "node:test";
-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 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.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/.hermes/skills/ytable-usage/SKILL.md

@@ -1,251 +0,0 @@
----
-name: ytable-usage
-description: 指导 YSS UI 业务列表页、CRUD 表格、远程分页、操作列、气泡确认、列筛选、字典翻译、行拖拽、工具栏和自定义插槽正确使用 @yss-ui/components 的 YTable；当需要配置 YTableColumn、YTableActionConfig、pagination、filter-change 或表格实例方法时使用。
----
-
-# YTable 使用
-
-## 触发条件
-
-- 生成或修改业务列表、CRUD 表格、远程分页、操作列、列筛选、工具栏或行拖拽。
-- 需要配置 `YTableColumn`、`YTableActionConfig`、分页状态或表格实例方法。
-
-## 不适用场景
-
-- 可编辑表格是核心需求：使用 `../yedit-table-usage/SKILL.md`。
-- 页面只有短小静态数据且不需要表格交互。
-
-## 实施流程
-
-1. 当前会话可用 yss-ui MCP 时，先用 `get_component_docs` 查询 `YTable` 的 Props、Events、Slots、Types 与实例方法；需要远程分页、筛选、操作列、拖拽或工具栏时，再用 `get_demo` 获取对应官方 Demo。
-2. MCP 工具不可用、调用失败或用 `search_docs/list_components` 校正后仍无结果时，才读取最新 `llms-full.txt`；若文档与当前项目依赖版本不一致，用当前源码和导出核验。
-3. 把远程数据、`loading`、分页映射、API 调用和事件处理放入 Hook；把列定义和纯配置放入 `constant.ts`。
-4. 在模板中组合 `data/columns/loading/pagination`，并根据真实开启的工具栏和分页配置高度 Hook。
-5. 完成后核对删除确认、远程筛选、分页字段映射和 API 错误处理边界。
-
-## 硬约束（禁止/必须）
-
-- 必须从 `@yss-ui/components` 导入 `YTable`、`YTableColumn`、`YTableActionConfig` 等真实导出，不使用 `a-table` 实现业务主表格。
-- 远程分页状态使用 `current/pageSize/total/remote`，显式设置 `remote: true`；后端 `pageIndex/pageSize/totalCount` 只在 Hook 中映射。
-- 开启内置分页时传 `pageable`，受控更新使用 `v-model:pagination`，请求时机使用 `@page-change="handlePageChange"`。
-- `page-change` 事件参数固定为 `{ current: number, pageSize: number }`；回调必须读取 `current`，禁止写成组件不会派发的 `currentPage`。
-- YTable 没有 `request` 或 `searchParams` Props；远程查询由业务 Hook 管理。`refresh()` 是真实实例方法，内部调用 vxe-table `updateData()` 刷新当前表格数据，不等于重新调用后端接口。
-- 行键使用 `:row-config="{ keyField: 'id', useKey: true }"`，不臆造 `row-key` Prop。
-- 新增、导入、批量操作等主按钮直接放入 `#toolbar-right` 或 `#toolbar-left` 插槽即可自动渲染工具栏；**无需配置 `:toolbar-config="{ custom: true }"`**，避免无端展示列设置图标；**仅在业务明确需要列设置时才传入 `:toolbar-config="{ custom: true }"`**。
-- 删除、启停、发布等危险操作使用 `actionConfig.buttons[].isConfirm = true`，不默认使用 `Modal.confirm`。
-- 列配置超过 10 行时放入 `constant.ts`；需要调用组件 Hook 的操作配置使用工厂函数注入回调，禁止在 `constant.ts` 直接引用组件局部的 `openEdit/deleteItem`。
-- 远程筛选必须提供稳定 `filters`，设置 `filterMethod: () => true` 禁用本地二次过滤，并监听 `filter-change`。
-- 自适应滚动列表绑定 `:height="tableHeight"`；`pageable`、工具栏分别对应 `withPagination: true`、`withToolbar: true`。纯短表不强制引入高度 Hook。
-- `mutator.ts` 已对网络错误和 `success === false` 统一 `message.error` 并 reject。API Hook 不再检查 `success === false`，不在 `else/catch` 重复 `message.error`；用 `finally` 恢复 loading，让异常继续中断流程。
-
-## 标准代码骨架
-
-```typescript
-import type { YTableActionConfig, YTableColumn } from '@yss-ui/components';
-
-/** 列表行数据。 */
-export interface ItemRow {
-  id: string;
-  name: string;
-  status: string;
-}
-
-/** 状态字典。 */
-export const STATUS_OPTIONS = [
-  { label: '启用', value: '1' },
-  { label: '停用', value: '0' },
-];
-
-/** 列表固定列配置。 */
-export const TABLE_COLUMNS: YTableColumn[] = [
-  { type: 'seq', title: '序号', width: 70 },
-  { field: 'name', title: '名称', minWidth: 180 },
-  { field: 'status', title: '状态', width: 120, isTransform: true },
-  { type: 'action', title: '操作', width: 180 },
-];
-
-/** 按组件 Hook 提供的回调创建操作列配置。 */
-export const createActionConfig = (handlers: {
-  onEdit: (row: ItemRow) => void;
-  onDelete: (row: ItemRow) => Promise<void>;
-}): YTableActionConfig => ({
-  width: 180,
-  fixed: 'right',
-  buttons: [
-    { value: 'edit', label: '编辑', type: 'link', click: ({ row }) => handlers.onEdit(row) },
-    {
-      value: 'delete',
-      label: '删除',
-      type: 'link',
-      isConfirm: true,
-      confirmProps: { title: '确认删除该数据吗？', okText: '确定', cancelText: '取消' },
-      click: ({ row }) => handlers.onDelete(row),
-    },
-  ],
-});
-```
-
-## 远程分页 Hook 关键模式
-
-```typescript
-import { ref } from 'vue';
-import type { YTablePagination } from '@yss-ui/components';
-import type { ItemRow } from '../constant';
-
-/** 列表 API 依赖，由当前项目的 Orval 函数适配。 */
-export interface ItemListApi {
-  queryPage: (params: { pageIndex: number; pageSize: number }) => Promise<{
-    list?: ItemRow[];
-    totalCount?: number;
-  }>;
-  deleteItem: (params: { id: string }) => Promise<unknown>;
-}
-
-/** 管理 YTable 远程分页和删除刷新。 */
-export const useItemList = (api: ItemListApi) => {
-  const dataList = ref<ItemRow[]>([]);
-  const loading = ref(false);
-  const pagination = ref<YTablePagination>({ current: 1, pageSize: 20, total: 0, remote: true });
-
-  /** 查询当前页；错误提示由 mutator 统一处理。 */
-  const loadList = async () => {
-    loading.value = true;
-    try {
-      const result = await api.queryPage({
-        pageIndex: pagination.value.current,
-        pageSize: pagination.value.pageSize,
-      });
-      dataList.value = result.list ?? [];
-      pagination.value = { ...pagination.value, total: result.totalCount ?? 0 };
-    } finally {
-      loading.value = false;
-    }
-  };
-
-  /** 同步 YTable 分页状态并重新查询。 */
-  const handlePageChange = async ({ current, pageSize }: { current: number; pageSize: number }) => {
-    pagination.value = { ...pagination.value, current, pageSize };
-    await loadList();
-  };
-
-  /** 删除后刷新列表；不重复弹出 API 错误。 */
-  const handleDelete = async (row: ItemRow) => {
-    await api.deleteItem({ id: row.id });
-    await loadList();
-  };
-
-  return { dataList, loading, pagination, loadList, handlePageChange, handleDelete };
-};
-```
-
-```vue
-<script setup lang="ts">
-import { onMounted, ref } from 'vue';
-import { YButton, YTable } from '@yss-ui/components';
-import { useTableHeight } from '@yss-ui/hooks';
-import { createActionConfig, STATUS_OPTIONS, TABLE_COLUMNS, type ItemRow } from './constant';
-import { useItemList, type ItemListApi } from './hooks/useItemList';
-
-/** 列表实例的 API 依赖。 */
-interface Props {
-  api: ItemListApi;
-}
-
-const props = defineProps<Props>();
-const emit = defineEmits<{
-  create: [];
-  edit: [row: ItemRow];
-}>();
-const tableAreaRef = ref<HTMLDivElement>();
-const { tableHeight } = useTableHeight(tableAreaRef, { withPagination: true, withToolbar: true });
-const { dataList, loading, pagination, loadList, handlePageChange, handleDelete } = useItemList(props.api);
-const actionConfig = createActionConfig({
-  onEdit: row => emit('edit', row),
-  onDelete: handleDelete,
-});
-
-onMounted(loadList);
-</script>
-
-<template>
-  <div ref="tableAreaRef" class="table-area">
-    <YTable
-      :data="dataList"
-      :columns="TABLE_COLUMNS"
-      :action-config="actionConfig"
-      :loading="loading"
-      :options-map="{ status: STATUS_OPTIONS }"
-      :row-config="{ keyField: 'id', useKey: true }"
-      :height="tableHeight"
-      pageable
-      v-model:pagination="pagination"
-      @page-change="handlePageChange"
-    >
-      <template #toolbar-right>
-        <YButton type="primary" @click="emit('create')">新增</YButton>
-      </template>
-    </YTable>
-  </div>
-</template>
-
-<style scoped lang="less">
-@import './style.less';
-</style>
-```
-
-```less
-/* style.less */
-.table-area {
-  height: 100%;
-  min-height: 0;
-  overflow: hidden;
-}
-```
-
-## 表格多选与批量操作标准模式
-
-当业务需要 Checkbox 多选与批量操作（如批量删除、批量导出、批量启用）时，遵循以下规范：
-
-1. **列配置**：首列必须声明 `{ type: 'checkbox', width: 50, fixed: 'left', align: 'center' }`。
-2. **行唯一键**：必须显式指定 `:row-config="{ keyField: 'id', useKey: true }"`（`keyField` 与业务主键如 `userCode` 对齐）。
-3. **受控双向绑定**：推荐优先使用 `v-model:selected-row-keys="selectedRowKeys"` 或 `v-model:selected-rows="selectedRows"`，或者统一监听 `@selection-change`。
-4. **批量操作按钮**：放在 `#toolbar-right`，并配置 `:disabled="selectedRowKeys.length === 0"`。
-5. **清空选中态**：批量操作成功后，直接重置 `selectedRowKeys.value = []` 或调用 `tableRef.value.clearSelection()`。
-
-```vue
-<YTable
-  ref="tableRef"
-  v-model:selected-row-keys="selectedRowKeys"
-  :row-config="{ keyField: 'id', useKey: true }"
-  :data="dataList"
-  :columns="TABLE_COLUMNS"
-  pageable
-  v-model:pagination="pagination"
-  @page-change="handlePageChange"
->
-  <template #toolbar-right>
-    <YButton :disabled="selectedRowKeys.length === 0" @click="handleBatchDelete">批量删除</YButton>
-  </template>
-</YTable>
-```
-
-## 插槽与实例边界
-
-- 优先使用 kebab-case：单元格 `#<field>`、表头 `#<field>-header`、筛选 `#<field>-filter`、工具栏 `#toolbar-left/#toolbar-right`、展开行 `#expand-row`、分组表头 `#group-header`、更多图标 `#action-more-icon`。
-- `getTableInstance()`、`refresh()`、`recalculate()`、`clearSelection()`、`getSelectedRows()`、`getSelectedRowKeys()`、`setSelection()`、`getPaginationInstance()` 是真实暴露方法；只在对应语义下使用。
-
-## 交付检查清单
-
-- [ ] 分页状态和 `page-change` 参数均使用 `current/pageSize`，未使用 `currentPage`；`filter-change` 与 YTable 真实 API 一致。
-- [ ] 多选列已配置 `type: 'checkbox'`，已设置 `:row-config="{ keyField: 'xxx', useKey: true }"`，批量按钮绑定了 `selectedRowKeys.length === 0` 禁用。
-- [ ] 批量操作成功后已重置 `selectedRowKeys` 并调用 `tableRef.clearSelection()`。
-- [ ] 未使用虚构 `request/searchParams/row-key` Props，也未把 `refresh()` 当成远程请求。
-- [ ] 工具栏、字典翻译、操作确认与高度偏移均与实际开关一致。
-- [ ] API Hook 没有 `success === false` 分支或重复 `message.error`。
-
-## 失败兜底策略
-
-- 分页字段混乱时，在 Hook 中分离 YTable 状态和后端参数，不直接把 `pageIndex/totalCount` 绑到组件。
-- 操作过多时使用 `displayLimit` 和更多菜单；远程刷新失效时回到业务 `loadList()`，不把实例 `refresh()` 当成接口请求。
-- API 失败后只在 `finally` 恢复本地 loading，让 mutator 的 reject 继续中断删除后刷新等后续流程。
-