create-yss-spec 3.0.1 → 3.1.0

package/template/.qoder/skills/yss-layered-mvc-scaffold-generator/scripts/generate_scaffold.mjs

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+/** 依据生命周期批准的 schema v3 合同生成纯机械 YSS 分层 MVC 后端骨架。 */
+import { assertScaffoldUserDecision } from "../../../../scripts/lib/user-decision.mjs";
+import { createHash } from "node:crypto";
+import { chmod, cp, lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { parseDocument } from "../../../../scripts/vendor/yaml.mjs";
+import { findGitRoot, gitSubmoduleScaffoldViolation, overlayMountViolation } from "../../../../scripts/lib/repository-scope-policy.mjs";
+import { assertLocalDatabaseProfile, localDatabaseConfiguration, scaffoldArchitectureIdentity } from "../../../../scripts/lib/scaffold-local-database.mjs";
+import { validateArchitectureIdentity } from "../../../../scripts/lib/backend-architecture.mjs";
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const SKILL_ROOT = path.resolve(SCRIPT_DIR, "..");
+const REPOSITORY_ROOT = path.resolve(SCRIPT_DIR, "../../../..");
+const SKILL_ID = "yss-layered-mvc-scaffold-generator";
+const COMMANDS = ["./mvnw validate", "./mvnw test", "./mvnw package"];
+const MODULE_ORDER = ["server", "service", "repository", "adapter", "client", "feign-client"];
+const CORE_MODULES = ["server", "service", "repository"];
+const CAPABILITIES = Object.freeze({
+  "external-integration": ["adapter"],
+  "published-client": ["client"],
+  "feign-client": ["client", "feign-client"]
+});
+
+function fail(message) { throw new Error(message); }
+function isPresent(value) { return value !== undefined && value !== null && value !== "" && (!Array.isArray(value) || value.length > 0); }
+function sha256(content) { return `sha256:${createHash("sha256").update(content).digest("hex")}`; }
+function rawSha256(content) { return createHash("sha256").update(content).digest("hex"); }
+function isWithin(parent, target) { const relative = path.relative(parent, target); return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative)); }
+function xml(value) { return String(value).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;"); }
+function toUpperCamel(value) { return value.split("-").map((part) => `${part[0].toUpperCase()}${part.slice(1)}`).join(""); }
+function orderedModules(requested) {
+  const modules = new Set(CORE_MODULES);
+  for (const capability of requested) {
+    if (!CAPABILITIES[capability]) fail(`unsupported MVC capability: ${capability}`);
+    for (const module of CAPABILITIES[capability]) modules.add(module);
+  }
+  return MODULE_ORDER.filter((module) => modules.has(module));
+}
+async function exists(target) { try { await lstat(target); return true; } catch (error) { if (error.code === "ENOENT") return false; throw error; } }
+async function put(root, relative, content) { const target = path.join(root, relative); await mkdir(path.dirname(target), { recursive: true }); await writeFile(target, content.endsWith("\n") ? content : `${content}\n`, "utf8"); }
+async function fileEntries(root, excluded = new Set()) {
+  const entries = [];
+  async function visit(directory) {
+    for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+      const target = path.join(directory, entry.name);
+      const relative = path.relative(root, target).split(path.sep).join("/");
+      if (entry.name === ".git") continue;
+      if (excluded.has(relative)) continue;
+      if (entry.isDirectory()) await visit(target);
+      else if (entry.isFile()) entries.push({ target, relative });
+    }
+  }
+  await visit(root);
+  return entries;
+}
+async function treeDigest(root) {
+  const hash = createHash("sha256");
+  async function visit(directory) {
+    for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+      const target = path.join(directory, entry.name);
+      if (entry.isDirectory()) await visit(target);
+      else if (entry.isFile()) hash.update(path.relative(root, target)).update("\0").update(await readFile(target)).update("\0");
+    }
+  }
+  await visit(root);
+  return `sha256:${hash.digest("hex")}`;
+}
+
+export function parseArgs(argv) {
+  const options = { force: false };
+  const mapping = new Map([
+    ["--project-name", "projectName"], ["--base-package", "basePackage"], ["--output-dir", "outputDir"],
+    ["--contract-file", "contractFile"], ["--contract-id", "contractId"], ["--contract-version", "contractVersion"],
+    ["--approval-ref", "approvalRef"], ["--compiler-draft-ref", "compilerDraftRef"], ["--persisted-ref", "persistedRef"],
+    ["--group-id", "groupId"], ["--project-version", "projectVersion"], ["--parent-group-id", "parentGroupId"],
+    ["--parent-artifact-id", "parentArtifactId"], ["--parent-version", "parentVersion"], ["--yss-components-version", "yssComponentsVersion"]
+  ]);
+  for (let index = 0; index < argv.length; index += 1) {
+    let token = argv[index];
+    if (token === "--help" || token === "-h") { options.help = true; continue; }
+    if (token === "--force") { options.force = true; continue; }
+    const equal = token.indexOf("=");
+    let value;
+    if (equal >= 0) { value = token.slice(equal + 1); token = token.slice(0, equal); }
+    if (!mapping.has(token)) fail(`不支持的参数: ${token}`);
+    if (value === undefined) value = argv[++index];
+    if (!value || value.startsWith("--")) fail(`参数 ${token} 缺少值`);
+    options[mapping.get(token)] = value;
+  }
+  if (options.help) return options;
+  for (const key of mapping.values()) if (!isPresent(options[key])) fail(`缺少必填参数: ${key}`);
+  if (!/^[a-z][a-z0-9-]*$/.test(options.projectName)) fail("--project-name 必须是 kebab-case");
+  if (!/^[a-z](?:[a-z0-9]*)(?:\.[a-z](?:[a-z0-9]*)?)*$/.test(options.basePackage)) fail("--base-package 不是合法 Java 包名");
+  if (!/^\d+$/.test(options.contractVersion) || Number(options.contractVersion) < 1) fail("--contract-version 必须为正整数");
+  options.contractVersion = Number(options.contractVersion);
+  if (options.force) fail("unsupported: initialize-only 脚手架禁止 --force");
+  return options;
+}
+
+function dependency(groupId, artifactId, version = null, scope = null) {
+  return `<dependency><groupId>${xml(groupId)}</groupId><artifactId>${xml(artifactId)}</artifactId>${version ? `<version>${xml(version)}</version>` : ""}${scope ? `<scope>${scope}</scope>` : ""}</dependency>`;
+}
+
+function parentPom(contract, modules) {
+  const c = contract.maven_coordinates;
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <parent><groupId>${xml(c.parent.group_id)}</groupId><artifactId>${xml(c.parent.artifact_id)}</artifactId><version>${xml(c.parent.version)}</version><relativePath/></parent>
+  <groupId>${xml(c.group_id)}</groupId><artifactId>${xml(contract.project_name)}</artifactId><version>${xml(c.project_version)}</version><packaging>pom</packaging>
+  <properties><java.version>1.8</java.version><maven.compiler.source>1.8</maven.compiler.source><maven.compiler.target>1.8</maven.compiler.target><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><yss-components.version>${xml(c.yss_components_version)}</yss-components.version></properties>
+  <modules>${modules.map((module) => `<module>${contract.project_name}-${module}</module>`).join("")}</modules>
+  <dependencyManagement><dependencies>${dependency("com.yss.cloud", "yss-components-bom", "${yss-components.version}", "import").replace("</dependency>", "<type>pom</type></dependency>")}</dependencies></dependencyManagement>
+  <build><pluginManagement><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>3.11.0</version><configuration><source>1.8</source><target>1.8</target><annotationProcessorPaths><path><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><version>1.18.30</version></path><path><groupId>org.mapstruct</groupId><artifactId>mapstruct-processor</artifactId><version>1.5.5.Final</version></path><path><groupId>org.projectlombok</groupId><artifactId>lombok-mapstruct-binding</artifactId><version>0.2.0</version></path></annotationProcessorPaths></configuration></plugin></plugins></pluginManagement></build>
+</project>`;
+}
+
+function modulePom(contract, module, modules) {
+  const applicationModule = modules.includes("core") ? "core" : "service";
+  const own = (name) => dependency(contract.maven_coordinates.group_id, `${contract.project_name}-${name}`, "${project.version}");
+  const dependencies = [];
+  if (module === "server") {
+    dependencies.push(own(applicationModule), dependency("org.springframework.boot", "spring-boot-starter-web"), dependency("org.springframework.boot", "spring-boot-starter-validation"), dependency("org.springframework.boot", "spring-boot-starter-test", null, "test"), dependency("com.tngtech.archunit", "archunit-junit5", "1.2.1", "test"));
+    if (modules.includes("client")) dependencies.push(own("client"));
+    dependencies.push(dependency("com.h2database", "h2", null, "test"), dependency("org.mapstruct", "mapstruct", "1.5.5.Final"), dependency("com.yss.cloud", "yss-component-dto"));
+  }
+  if (module === applicationModule) {
+    dependencies.push(own("repository"), dependency("org.springframework", "spring-tx"), dependency("com.yss.cloud", "yss-component-dto"), dependency("org.springframework.boot", "spring-boot-starter-test", null, "test"));
+    if (modules.includes("adapter")) dependencies.push(own("adapter"));
+  }
+  if (module === "repository") {
+    dependencies.push(dependency("com.yss.cloud", "yss-component-mybatis-plus-starter"), dependency("org.mapstruct", "mapstruct", "1.5.5.Final"), dependency("org.springframework.boot", "spring-boot-starter-test", null, "test"), dependency("com.h2database", "h2", null, "test"));
+  }
+  if (module === "adapter") {
+    dependencies.push(dependency("org.springframework", "spring-context"));
+    if (modules.includes("feign-client")) dependencies.push(own("feign-client"));
+  }
+  if (module === "client") dependencies.push(dependency("com.yss.cloud", "yss-component-dto"), dependency("javax.validation", "validation-api"));
+  if (["server", "service", "core", "client", "repository"].includes(module)) dependencies.push(dependency("org.projectlombok", "lombok", "1.18.30", "provided"));
+  if (module === "feign-client") dependencies.push(own("client"), dependency("org.springframework.cloud", "spring-cloud-openfeign-core"));
+  const plugin = module === "server" ? `<profiles><profile><id>scaffold-local</id><dependencies>${dependency("com.h2database", "h2", null, "runtime")}</dependencies></profile></profiles><build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin></plugins></build>` : "";
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"><modelVersion>4.0.0</modelVersion><parent><groupId>${xml(contract.maven_coordinates.group_id)}</groupId><artifactId>${xml(contract.project_name)}</artifactId><version>${xml(contract.maven_coordinates.project_version)}</version></parent><artifactId>${xml(contract.project_name)}-${module}</artifactId><dependencies>${dependencies.join("")}</dependencies>${plugin}</project>`;
+}
+
+async function validateContract(options, skillId, architectureProfile) {
+  const contractFile = path.resolve(options.contractFile);
+  const contractText = await readFile(contractFile, "utf8").catch(() => fail(`脚手架合同不可读取: ${contractFile}`));
+  let contract;
+  try { contract = JSON.parse(contractText); } catch { fail("脚手架合同必须是 JSON 对象"); }
+  if (contract.schema_version !== 3) fail(`unsupported: 新生成只接受 scaffold contract schema v3，收到 v${contract.schema_version}`);
+  const required = ["contract_id", "contract_version", "scaffold_request_id", "status", "compiler_draft_ref", "lifecycle_approval_ref", "persisted_ref", "current_version", "implementation_repository", "backend_repository", "scaffold_status", "project_name", "target_output_dir", "base_package", "architecture_family", "generator_skill", "decision_ref", "decision_id", "decision_digest", "maven_coordinates", "profiles", "module_profile", "allowed_write_paths", "expected_evidence_files", "verification_commands", "approval", "work_unit", "generation_policy"];
+  const missing = required.filter((field) => !isPresent(contract[field]));
+  if (missing.length) fail(`脚手架合同缺少字段: ${missing.join(", ")}`);
+  if (contract.status !== "approved" || contract.current_version !== contract.contract_version) fail("脚手架合同必须已批准且为当前版本");
+  if (contract.contract_id !== options.contractId || contract.contract_version !== options.contractVersion || contract.compiler_draft_ref !== options.compilerDraftRef || contract.lifecycle_approval_ref !== options.approvalRef || contract.persisted_ref !== options.persistedRef) fail("命令行合同元数据与批准合同不一致");
+  if (contract.scaffold_status !== "required" || contract.architecture_family !== "layered-mvc" || contract.generator_skill !== skillId) fail("合同必须绑定 layered-mvc 与本生成器");
+  if (contract.project_name !== options.projectName || contract.base_package !== options.basePackage || path.resolve(contract.target_output_dir) !== path.resolve(options.outputDir)) fail("项目身份或输出目录与合同不一致");
+  if (!["allowed_write_paths", "expected_evidence_files", "verification_commands"].every((field) => Array.isArray(contract[field]) && contract[field].length)) fail("allowed_write_paths、expected_evidence_files、verification_commands 必须为非空数组");
+  const finalProjectRoot = path.join(path.resolve(options.outputDir), options.projectName);
+  const allowedRoots = contract.allowed_write_paths.map((item) => path.resolve(options.outputDir, String(item)));
+  if (!allowedRoots.some((root) => isWithin(root, finalProjectRoot))) fail("实际项目根不在合同 allowed_write_paths 内");
+  const expectedProfiles = { architecture: "layered-mvc", persistence: "mybatis-plus", platform: "spring-boot-2.7-jdk8", validation_namespace: "javax", repository: "yss-internal" };
+  for (const [field, value] of Object.entries(expectedProfiles)) if (contract.profiles?.[field] !== value) fail(`unsupported profile ${field}: ${contract.profiles?.[field]}`);
+  assertLocalDatabaseProfile(contract.profiles);
+  if (contract.architecture_profile !== architectureProfile) fail(`合同必须显式绑定 ${architectureProfile} Profile`);
+  const requested = contract.module_profile?.requested_capabilities;
+  if (!Array.isArray(requested)) fail("module_profile.requested_capabilities 必须是数组");
+  const resolved = architectureProfile === "mvc-data-analysis-v1" ? ["server", "core", "client", "repository", "adapter", "feign-client"] : orderedModules(requested);
+  if (contract.module_profile.resolution_version !== 1 || JSON.stringify(contract.module_profile.resolved_modules) !== JSON.stringify(resolved)) fail("MVC 能力闭包与 resolution_version=1 不一致");
+  if (JSON.stringify(contract.verification_commands) !== JSON.stringify(COMMANDS)) fail("验证命令必须固定为三条 ./mvnw 命令");
+  if (!contract.expected_evidence_files.includes(".yss/scaffold-generation.json")) fail("expected_evidence_files 必须包含 Manifest");
+  const work = contract.work_unit;
+  if (work?.primary_skill !== skillId || work?.tdd_mode !== "controlled-generation" || work?.controlled_generation !== true) fail("工作单元必须绑定本生成器和 controlled-generation");
+  if (!Array.isArray(work.allowed_write_paths) || !Array.isArray(work.expected_evidence) || !Array.isArray(work.verification_commands) || JSON.stringify(work.allowed_write_paths) !== JSON.stringify(contract.allowed_write_paths) || JSON.stringify(work.verification_commands) !== JSON.stringify(contract.verification_commands)) fail("工作单元与根级写路径或验证命令不一致");
+  const approval = contract.approval;
+  if (!approval || ["approval_ref", "approver", "persisted_ref", "current_version"].some((field) => !isPresent(approval[field])) || approval.approval_ref !== options.approvalRef || approval.persisted_ref !== options.persistedRef || approval.current_version !== options.contractVersion) fail("approval 记录不完整或不是当前合同版本");
+  const policy = contract.generation_policy;
+  if (policy?.mode !== "initialize-only" || policy?.existing_target !== "unsupported" || policy?.old_project_migration !== "unsupported" || policy?.template_upgrade !== "unsupported") fail("generation_policy 不符合 initialize-only");
+  const coordinates = contract.maven_coordinates;
+  const coordinateValues = [coordinates?.group_id, coordinates?.project_version, coordinates?.parent?.group_id, coordinates?.parent?.artifact_id, coordinates?.parent?.version, coordinates?.yss_components_version];
+  const optionValues = [options.groupId, options.projectVersion, options.parentGroupId, options.parentArtifactId, options.parentVersion, options.yssComponentsVersion];
+  if (coordinateValues.some((value) => !isPresent(value)) || JSON.stringify(coordinateValues) !== JSON.stringify(optionValues)) fail("Maven 坐标与合同不一致");
+  if (coordinateValues.some((value) => !/^[A-Za-z0-9_.-]+$/.test(String(value)))) fail("Maven 坐标只能包含字母、数字、点、下划线和连字符");
+  const decisionPath = path.isAbsolute(contract.decision_ref) ? contract.decision_ref : path.resolve(path.dirname(contractFile), contract.decision_ref);
+  const decisionText = await readFile(decisionPath, "utf8").catch(() => fail(`架构决策文件不可读取: ${decisionPath}`));
+  if (sha256(decisionText) !== contract.decision_digest) fail("架构决策文件 digest 与合同不一致");
+  const document = parseDocument(decisionText, { maxAliasCount: 0, uniqueKeys: true });
+  if (document.errors.length) fail(`架构决策 YAML 无效: ${document.errors[0].message}`);
+  const decisionSet = document.toJS({ maxAliasCount: 0 });
+  if (decisionSet?.kind !== "scaffold-architecture-decisions" || decisionSet?.template !== false || decisionSet?.status !== "current") fail("架构决策文件必须是 current 的正式 scaffold-architecture-decisions 记录");
+  const decisions = decisionSet.decisions ?? [];
+  const decision = decisions.find((item) => item.decision_id === contract.decision_id);
+  if (!decision || decision.status !== "lifecycle-approved" || decision.confirmed_architecture !== "layered-mvc" || decision.project_id !== contract.project_name) fail("架构决策未批准、项目不匹配或不是 layered-mvc");
+  if (decision.platform_profile !== contract.profiles.platform || decision.architecture_profile !== contract.architecture_profile || decision.verification_database !== "h2" || decision.production_database !== "not-bound" || Object.hasOwn(decision, "database_profile") || JSON.stringify(decision.requested_capabilities) !== JSON.stringify(contract.module_profile.requested_capabilities) || JSON.stringify(decision.resolved_modules) !== JSON.stringify(contract.module_profile.resolved_modules)) fail("架构决策的 Profile 或模块闭包与脚手架合同不一致");
+  if (!decision.user_confirmation || Object.values(decision.user_confirmation).some((value) => !isPresent(value))) fail("架构决策缺少完整用户确认记录");
+  assertScaffoldUserDecision(decision);
+  validateArchitectureIdentity(scaffoldArchitectureIdentity(contract, sha256(contractText)));
+  return { contract, contractText, modules: resolved };
+}
+
+async function validateOutputLayout(outputDir, projectName) {
+  const target = path.join(path.resolve(outputDir), projectName);
+  const relative = path.relative(REPOSITORY_ROOT, path.resolve(outputDir));
+  if (!relative.startsWith("..") && !path.isAbsolute(relative)) {
+    const parts = relative.split(path.sep).filter(Boolean);
+    if (!(parts.length === 2 && parts[0] === "apps" && parts[1] === "backend")) fail("Harness 内后端脚手架输出父目录必须是 apps/backend");
+  }
+  const gitRoot = findGitRoot(target) || findGitRoot(outputDir) || REPOSITORY_ROOT;
+  const violation = gitSubmoduleScaffoldViolation(gitRoot, path.resolve(outputDir), projectName, { force: false }) || overlayMountViolation(gitRoot, target, { force: true });
+  if (violation) fail(violation);
+  if (await exists(target)) fail(`unsupported: 目标已存在 ${target}`);
+}
+
+export async function generate(options, { skillId = SKILL_ID, architectureProfile = "layered-mvc-service", finalize } = {}) {
+  if (!((skillId === SKILL_ID && architectureProfile === "layered-mvc-service") || (skillId === "yss-mvc-data-analysis-project-initializer" && architectureProfile === "mvc-data-analysis-v1"))) fail("unsupported MVC generator/Profile pair");
+  await validateOutputLayout(options.outputDir, options.projectName);
+  const { contract, contractText, modules } = await validateContract(options, skillId, architectureProfile);
+  const outputDir = path.resolve(options.outputDir);
+  await mkdir(outputDir, { recursive: true });
+  const staging = await mkdtemp(path.join(outputDir, `.${options.projectName}.staging-`));
+  const projectRoot = path.join(staging, options.projectName);
+  const packagePath = options.basePackage.replaceAll(".", "/");
+  try {
+    await mkdir(projectRoot, { recursive: true });
+    await put(projectRoot, "pom.xml", parentPom(contract, modules));
+    for (const module of modules) {
+      const moduleRoot = `${options.projectName}-${module}`;
+      await put(projectRoot, `${moduleRoot}/pom.xml`, modulePom(contract, module, modules));
+      await put(projectRoot, `${moduleRoot}/src/main/java/${packagePath}/${module.replaceAll("-", "/")}/package-info.java`, `/** ${module} mechanical package boundary. */\npackage ${options.basePackage}.${module.replaceAll("-", ".")};`);
+    }
+    const applicationClass = `${toUpperCamel(options.projectName)}Application`;
+    const serverRoot = `${options.projectName}-server`;
+    await put(projectRoot, `${serverRoot}/src/main/java/${packagePath}/${applicationClass}.java`, `package ${options.basePackage};\n\nimport org.springframework.boot.SpringApplication;\nimport org.springframework.boot.autoconfigure.SpringBootApplication;\n\n/** Mechanical Spring Boot entrypoint. */\n@SpringBootApplication\npublic class ${applicationClass} {\n    public static void main(String[] args) {\n        SpringApplication.run(${applicationClass}.class, args);\n    }\n}`);
+    await put(projectRoot, `${serverRoot}/src/main/resources/application.yml`, `spring:\n  application:\n    name: ${options.projectName}`);
+    await put(projectRoot, `${serverRoot}/src/main/resources/application-scaffold-local.yml`, localDatabaseConfiguration(options.projectName));
+    await put(projectRoot, `${serverRoot}/src/test/resources/application-scaffold-test.yml`, localDatabaseConfiguration(`${options.projectName}_test`));
+    await put(projectRoot, `${serverRoot}/src/test/java/${packagePath}/${applicationClass}Test.java`, `package ${options.basePackage};\n\nimport org.junit.jupiter.api.Test;\nimport org.springframework.boot.test.context.SpringBootTest;\nimport org.springframework.test.context.ActiveProfiles;\n\n@SpringBootTest\n@ActiveProfiles("scaffold-test")\nclass ${applicationClass}Test {\n    @Test\n    void contextLoads() {\n    }\n}`);
+    await put(projectRoot, `${serverRoot}/src/test/java/${packagePath}/architecture/LayeredMvcArchitectureTest.java`, `package ${options.basePackage}.architecture;\n\nimport static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;\n\nimport com.tngtech.archunit.core.importer.ImportOption;\nimport com.tngtech.archunit.junit.AnalyzeClasses;\nimport com.tngtech.archunit.junit.ArchTest;\nimport com.tngtech.archunit.lang.ArchRule;\n\n@AnalyzeClasses(packages = "${options.basePackage}", importOptions = ImportOption.DoNotIncludeTests.class)\nclass LayeredMvcArchitectureTest {\n    @ArchTest\n    static final ArchRule repositoryDoesNotDependOnUpperLayers = noClasses().that().resideInAPackage("..repository..").should().dependOnClassesThat().resideInAnyPackage("..service..", "..server..");\n}`);
+    const wrapper = path.join(REPOSITORY_ROOT, ".agents/skills/yss-ddd-scaffold-generator/assets/wrapper");
+    await cp(wrapper, projectRoot, { recursive: true });
+    await chmod(path.join(projectRoot, "mvnw"), 0o755);
+    if (finalize) await finalize({ projectRoot, contract, architectureIdentity: scaffoldArchitectureIdentity(contract, sha256(contractText)) });
+    await put(projectRoot, "README.md", `# ${options.projectName}\n\n该工程由 ${skillId} 根据批准的 schema v3 合同生成。模块：${modules.join("、")}。不包含业务 API、SQL 或生产数据库绑定。\n\n本地运行需同时显式启用 Maven -Pscaffold-local 和 Spring scaffold-local Profile；测试独立使用 H2。生产数据库须由后续已批准存储工作单元接入。`);
+    const generatedFiles = [];
+    for (const entry of await fileEntries(projectRoot, new Set([".yss/scaffold-generation.json"]))) generatedFiles.push({ path: entry.relative, owner: "generator", sha256: rawSha256(await readFile(entry.target)) });
+    const architectureRuleset = `${serverRoot}/src/test/java/${packagePath}/architecture/LayeredMvcArchitectureTest.java`;
+    const downstream = {};
+    for (const skill of ["yss-application", "yss-repository", "yss-mybatis", "yss-web-controller", "yss-dto", "yss-exception", "yss-validation", "mapstruct", "lombok", "alibaba-java-code-style"]) downstream[skill] = (await treeDigest(path.join(REPOSITORY_ROOT, ".agents/skills", skill))).replace(/^sha256:/, "");
+    const manifest = {
+      schema_version: 3,
+      kind: architectureProfile === "mvc-data-analysis-v1" ? "service-project-initialization" : "backend-scaffold",
+      architecture_profile: contract.architecture_profile,
+      architecture_identity: scaffoldArchitectureIdentity(contract, sha256(contractText)),
+      contract_id: contract.contract_id,
+      contract_version: contract.contract_version,
+      scaffold_request_id: contract.scaffold_request_id,
+      architecture_family: "layered-mvc",
+      generator_skill: skillId,
+      decision_id: contract.decision_id,
+      decision_digest: contract.decision_digest,
+      decision_ref: contract.decision_ref,
+      contract_digest: sha256(contractText),
+      contract_file_ref: path.resolve(options.contractFile),
+      approval_ref: options.approvalRef,
+      approver: contract.approval.approver,
+      lifecycle_approval_ref: contract.lifecycle_approval_ref,
+      compiler_draft_ref: contract.compiler_draft_ref,
+      persisted_ref: contract.persisted_ref,
+      current_version: contract.current_version,
+      allowed_write_paths: contract.allowed_write_paths,
+      expected_evidence_files: contract.expected_evidence_files,
+      profiles: contract.profiles,
+      module_profile: contract.module_profile,
+      maven_coordinates: contract.maven_coordinates,
+      maven_coordinates_source: "approved-contract",
+      project_name: contract.project_name,
+      base_package: contract.base_package,
+      bootstrap_main_class: `${options.basePackage}.${applicationClass}`,
+      bootstrap_main_source: `${serverRoot}/src/main/java/${packagePath}/${applicationClass}.java`,
+      generation_mode: "controlled-generation",
+      completion_level: "generated",
+      generation_policy: contract.generation_policy,
+      verification_commands: COMMANDS,
+      generator: { id: skillId, template_digest: await treeDigest(SKILL_ROOT) },
+      ownership: { generated_files: generatedFiles, user_owned_globs: ["**/src/main/java/**", "**/src/test/java/**", "db/**"] },
+      readiness: { downstream_skills: downstream, contracts: { architecture_profiles: rawSha256(await readFile(path.join(REPOSITORY_ROOT, "docs/agents/backend-architecture-profiles.md"))), compiler_contract: rawSha256(await readFile(path.join(REPOSITORY_ROOT, ".agents/skills/yss-implementation-contract-compiler/references/compiler-contract.yaml"))) }, architecture_ruleset: rawSha256(await readFile(path.join(projectRoot, architectureRuleset))) },
+      generated_at: new Date().toISOString()
+    };
+    await put(projectRoot, ".yss/scaffold-generation.json", JSON.stringify(manifest, null, 2));
+    await rename(projectRoot, path.join(outputDir, options.projectName));
+    await rm(staging, { recursive: true, force: true });
+    process.stdout.write(`${JSON.stringify({ status: "generated", project_root: path.join(outputDir, options.projectName), modules }, null, 2)}\n`);
+  } catch (error) {
+    await rm(staging, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+async function main() {
+  try {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) { process.stdout.write("Use --project-name --base-package --output-dir and approved contract metadata. Local/test database is H2; production is not bound.\n"); return 0; }
+    await generate(options);
+    return 0;
+  } catch (error) {
+    process.stderr.write(`❌ MVC 脚手架生成失败: ${error.message}\n`);
+    return 1;
+  }
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) process.exitCode = await main();

package/template/.qoder/skills/yss-layered-mvc-scaffold-generator/scripts/run_scaffold_verification.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/** 复用统一 Manifest v3 / Maven Wrapper 验证协议。 */
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+import { run as runUnifiedVerification } from "../../yss-ddd-scaffold-generator/scripts/run_scaffold_verification.mjs";
+
+export async function run(projectRoot, evidenceDir, environment = process.env) {
+  return runUnifiedVerification(path.resolve(projectRoot), path.resolve(evidenceDir), environment);
+}
+
+async function main() {
+  const [projectRoot, evidenceDir] = process.argv.slice(2);
+  if (!projectRoot || !evidenceDir) {
+    process.stderr.write("用法: node run_scaffold_verification.mjs <project-root> <evidence-dir>\n");
+    return 1;
+  }
+  try {
+    const report = await run(projectRoot, evidenceDir);
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return report.status === "passed" ? 0 : 1;
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    return 1;
+  }
+}
+
+const currentFile = fileURLToPath(import.meta.url);
+if (process.argv[1] && path.resolve(process.argv[1]) === currentFile) process.exitCode = await main();

package/template/.qoder/skills/yss-layered-mvc-scaffold-generator/scripts/scaffold-generator.test.mjs

@@ -0,0 +1,159 @@
+import { attachScaffoldDecisionFixture } from "../../../../scripts/fixtures/user-decision/build-fixture.mjs";
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { mkdtemp, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const script = path.join(path.dirname(fileURLToPath(import.meta.url)), "generate_scaffold.mjs");
+const digest = (value) => `sha256:${createHash("sha256").update(value).digest("hex")}`;
+const capabilityModules = {
+  basic: { capabilities: [], modules: ["server", "service", "repository"] },
+  adapter: { capabilities: ["external-integration"], modules: ["server", "service", "repository", "adapter"] },
+  client: { capabilities: ["published-client"], modules: ["server", "service", "repository", "client"] },
+  feign: { capabilities: ["feign-client"], modules: ["server", "service", "repository", "client", "feign-client"] },
+  combined: { capabilities: ["external-integration", "feign-client"], modules: ["server", "service", "repository", "adapter", "client", "feign-client"] }
+};
+
+async function fixture(t, { profile = capabilityModules.basic, architectureProfile = "layered-mvc-service", skillId = "yss-layered-mvc-scaffold-generator" } = {}) {
+  const root = await mkdtemp(path.join(os.tmpdir(), "yss-layered-mvc-"));
+  t.after(() => rm(root, { recursive: true, force: true }));
+  const output = path.join(root, "backend");
+  await mkdir(output);
+  let decisionText = `${JSON.stringify({ schema_version: 1, kind: "scaffold-architecture-decisions", template: false, status: "current", decisions: [{ decision_id: "scaffold-decision.demo-service", project_id: "demo-service", parent_project_id: null, status: "lifecycle-approved", recommended_architecture: "layered-mvc", recommendation_reasons: ["薄 CRUD 服务"], confirmed_architecture: "layered-mvc", override_reason: null, inheritance_mode: "root-default", inherited_from: null, platform_profile: "spring-boot-2.7-jdk8", architecture_profile: architectureProfile, verification_database: "h2", production_database: "not-bound", requested_capabilities: profile.capabilities, resolved_modules: profile.modules, resolution_version: 1, user_confirmation: { confirmed_by: "tester", channel: "test", confirmation_ref: "test://confirmation", confirmed_at: "2026-09-05T00:00:00Z", normalized_text: "确认使用 MVC" }, decision_inputs_digest: `sha256:${"1".repeat(64)}` }] }, null, 2)}\n`;
+  const decisionSet = JSON.parse(decisionText);
+  decisionSet.decisions = decisionSet.decisions.map((decision) => attachScaffoldDecisionFixture(path.join(root, "user-decision"), decision));
+  decisionText = JSON.stringify(decisionSet, null, 2) + "\n";
+  const decisionFile = path.join(root, "scaffold-architecture-decisions.yaml");
+  await writeFile(decisionFile, decisionText);
+  const contract = {
+    schema_version: 3,
+    contract_id: "scaffold.demo-service.v1",
+    contract_version: 1,
+    scaffold_request_id: "request.demo-service",
+    status: "approved",
+    compiler_draft_ref: "compiler://demo/1",
+    lifecycle_approval_ref: "approval://demo/1",
+    persisted_ref: "contract://demo/1",
+    current_version: 1,
+    implementation_repository: "external",
+    backend_repository: "external",
+    scaffold_status: "required",
+    project_name: "demo-service",
+    target_output_dir: output,
+    base_package: "com.yss.demo",
+    architecture_family: "layered-mvc", architecture_profile: architectureProfile,
+    generator_skill: skillId,
+    decision_ref: decisionFile,
+    decision_id: "scaffold-decision.demo-service",
+    decision_digest: digest(decisionText),
+    maven_coordinates: { group_id: "com.yss.demo", project_version: "1.0.0-SNAPSHOT", parent: { group_id: "com.yss.cloud", artifact_id: "yss-cloud-microservice", version: "2.0.0-SNAPSHOT" }, yss_components_version: "2.0.0-SNAPSHOT" },
+    profiles: { architecture: "layered-mvc", persistence: "mybatis-plus", verification_database: "h2", production_database: "not-bound", platform: "spring-boot-2.7-jdk8", validation_namespace: "javax", repository: "yss-internal" },
+    module_profile: { requested_capabilities: profile.capabilities, resolved_modules: profile.modules, resolution_version: 1 },
+    allowed_write_paths: ["."],
+    expected_evidence_files: [".yss/scaffold-generation.json"],
+    verification_commands: ["./mvnw validate", "./mvnw test", "./mvnw package"],
+    approval: { approval_ref: "approval://demo/1", approver: "lifecycle", persisted_ref: "contract://demo/1", current_version: 1 },
+    work_unit: { id: "scaffold.demo", behavior: "project-scaffold", primary_skill: skillId, supporting_skills: ["yss-implementation-contract-compiler"], tdd_mode: "controlled-generation", allowed_write_paths: ["."], expected_evidence: [".yss/scaffold-generation.json"], verification_commands: ["./mvnw validate", "./mvnw test", "./mvnw package"], controlled_generation: true },
+    generation_policy: { mode: "initialize-only", existing_target: "unsupported", old_project_migration: "unsupported", template_upgrade: "unsupported" }
+  };
+  const contractFile = path.join(root, "contract.json");
+  await writeFile(contractFile, `${JSON.stringify(contract, null, 2)}\n`);
+  const args = ["--project-name", "demo-service", "--base-package", "com.yss.demo", "--output-dir", output, "--contract-file", contractFile, "--contract-id", contract.contract_id, "--contract-version", "1", "--approval-ref", contract.lifecycle_approval_ref, "--compiler-draft-ref", contract.compiler_draft_ref, "--persisted-ref", contract.persisted_ref, "--group-id", "com.yss.demo", "--project-version", "1.0.0-SNAPSHOT", "--parent-group-id", "com.yss.cloud", "--parent-artifact-id", "yss-cloud-microservice", "--parent-version", "2.0.0-SNAPSHOT", "--yss-components-version", "2.0.0-SNAPSHOT"];
+  return { root, output, decisionFile, contractFile, contract, args, project: path.join(output, "demo-service") };
+}
+
+test("数据分析初始化生成 H2 六模块和独立治理信封", async (t) => {
+  const skillId = "yss-mvc-data-analysis-project-initializer";
+  const data = await fixture(t, { architectureProfile: "mvc-data-analysis-v1", skillId, profile: { capabilities: [], modules: ["server", "core", "client", "repository", "adapter", "feign-client"] } });
+  const context = "---\ncontext_schema_version: 1\n---\n# 业务上下文\n\n## 业务术语\n\n| 术语 | 含义 | 英文标识 | 适用业务责任区 | 避免 / 备注 |\n|---|---|---|---|---|\n";
+  await writeFile(path.join(data.root, "context-handoff.md"), context);
+  data.contract.context_handoff_ref = "context-handoff.md";
+  data.contract.context_handoff_digest = digest(context);
+  await writeFile(data.contractFile, JSON.stringify(data.contract));
+  const initializer = path.resolve(path.dirname(script), `../../${skillId}/scripts/generate_project.mjs`);
+  const result = spawnSync(process.execPath, [initializer, ...data.args], { encoding: "utf8" });
+  assert.equal(result.status, 0, result.stderr);
+  const manifest = JSON.parse(await readFile(path.join(data.project, ".yss/scaffold-generation.json"), "utf8"));
+  assert.equal(manifest.architecture_identity.architecture_profile, "mvc-data-analysis-v1");
+  assert.equal(manifest.generator_skill, skillId);
+  assert.equal(await readFile(path.join(data.project, "CONTEXT.md"), "utf8"), context);
+  await stat(path.join(data.project, ".git"));
+  await stat(path.join(data.output, "skillUtils/skills-lock.json"));
+  assert.ok(!manifest.ownership.generated_files.some((entry) => entry.path.startsWith(".git/")));
+  const core = await readFile(path.join(data.project, "demo-service-core/pom.xml"), "utf8");
+  assert.doesNotMatch(core, /demo-service-client|spring-web|ojdbc|mysql-connector/);
+});
+
+test("旧数据库和 Mock 参数在写入前被拒绝", async (t) => {
+  const data = await fixture(t);
+  for (const args of [["--database", "mysql"], ["--with-mock"]]) {
+    const result = spawnSync(process.execPath, [script, ...data.args, ...args], { encoding: "utf8" });
+    assert.notEqual(result.status, 0);
+    await assert.rejects(stat(data.project), { code: "ENOENT" });
+  }
+});
+
+test("可选离线 Maven 可行性检查（不替代受控仓库验收）", { skip: process.env.YSS_BACKEND_OFFLINE_PROBE !== "1" }, async (t) => {
+  const data = await fixture(t);
+  const generated = spawnSync(process.execPath, [script, ...data.args], { encoding: "utf8" });
+  assert.equal(generated.status, 0, generated.stderr);
+  for (const phase of ["validate", "test", "package"]) {
+    const result = spawnSync(path.join(data.project, "mvnw"), ["-o", phase], { cwd: data.project, encoding: "utf8", timeout: 60_000 });
+    t.diagnostic(`./mvnw -o ${phase}: exit=${result.status}; ${result.error?.message ?? ""}`);
+    assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+  }
+});
+
+for (const database of ["h2"]) {
+  test(`生成 ${database} 基础 Profile`, async (t) => {
+    const data = await fixture(t, { database });
+    const result = spawnSync(process.execPath, [script, ...data.args], { encoding: "utf8" });
+    assert.equal(result.status, 0, result.stderr);
+    const manifest = JSON.parse(await readFile(path.join(data.project, ".yss/scaffold-generation.json"), "utf8"));
+    assert.equal(manifest.schema_version, 3);
+    assert.equal(manifest.architecture_family, "layered-mvc");
+    assert.equal(manifest.profiles.verification_database, database);
+    assert.equal(manifest.profiles.production_database, "not-bound");
+    assert.equal(manifest.architecture_identity.architecture_profile, "layered-mvc-service");
+    const config = await readFile(path.join(data.project, "demo-service-server/src/main/resources/application.yml"), "utf8");
+    assert.doesNotMatch(config, /datasource|profiles|jdbc:/);
+    const local = await readFile(path.join(data.project, "demo-service-server/src/main/resources/application-scaffold-local.yml"), "utf8");
+    assert.match(local, /jdbc:h2:mem:/);
+    assert.deepEqual(manifest.module_profile.resolved_modules, capabilityModules.basic.modules);
+    await stat(path.join(data.project, "demo-service-server/src/main/java/com/yss/demo/DemoServiceApplication.java"));
+    await assert.rejects(stat(path.join(data.project, "demo-service-server/src/main/java/com/yss/demo/server/controller")), { code: "ENOENT" });
+  });
+}
+
+for (const [name, profile] of Object.entries(capabilityModules)) {
+  test(`能力闭包 ${name}`, async (t) => {
+    const data = await fixture(t, { profile });
+    const result = spawnSync(process.execPath, [script, ...data.args], { encoding: "utf8" });
+    assert.equal(result.status, 0, result.stderr);
+    const pom = await readFile(path.join(data.project, "pom.xml"), "utf8");
+    for (const module of profile.modules) assert.match(pom, new RegExp(`<module>demo-service-${module}</module>`));
+    for (const module of ["adapter", "client", "feign-client"].filter((item) => !profile.modules.includes(item))) assert.doesNotMatch(pom, new RegExp(`<module>demo-service-${module}</module>`));
+  });
+}
+
+test("选择缺失、digest 漂移和非空目标均阻断", async (t) => {
+  const missing = await fixture(t);
+  missing.contract.decision_id = "decision.missing";
+  await writeFile(missing.contractFile, `${JSON.stringify(missing.contract)}\n`);
+  assert.notEqual(spawnSync(process.execPath, [script, ...missing.args], { encoding: "utf8" }).status, 0);
+
+  const drift = await fixture(t);
+  drift.contract.decision_digest = `sha256:${"0".repeat(64)}`;
+  await writeFile(drift.contractFile, `${JSON.stringify(drift.contract)}\n`);
+  assert.notEqual(spawnSync(process.execPath, [script, ...drift.args], { encoding: "utf8" }).status, 0);
+
+  const existing = await fixture(t);
+  await mkdir(existing.project);
+  const blocked = spawnSync(process.execPath, [script, ...existing.args], { encoding: "utf8" });
+  assert.notEqual(blocked.status, 0);
+  assert.match(blocked.stderr, /目标已存在/);
+});

package/template/.qoder/skills/yss-mvc-data-analysis-project-initializer/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: yss-mvc-data-analysis-project-initializer
+description: 在生命周期批准的初始化合同下创建独立 Git 管理的数据分析 project-instance；固定 mvc-data-analysis-v1 六模块、Java 8 和本地测试 H2。
+---
+
+# 数据分析 MVC 项目初始化
+
+这是 `work-unit.service-project-initialization` 的执行器，不是通用 MVC 脚手架。通用 MVC 使用 `yss-layered-mvc-scaffold-generator`；DDD 使用 `yss-ddd-scaffold-generator`。旧 `yss-mvc-scaffold-generator` 已退役且不提供自动别名。
+
+## 执行合同
+
+- 必须有生命周期批准且当前的 schema v3 scaffold contract，绑定 `architecture_profile=mvc-data-analysis-v1`、本生成器及已批准的架构决策。
+- 固定 server/core/client/repository/adapter/feign-client；core 是薄应用层，规则见 `docs/agents/backend-architecture-profiles.md`。不生成业务接口、SQL、DDL、Mock、生产数据库配置或额外数据源。
+- `verification_database=h2` / `production_database=not-bound`；Java 8 / Boot 2.7 / javax。目标不存在，禁止覆盖、迁移、自动提交和推送。
+- 合同必须包含 `context_handoff_ref`、`context_handoff_digest`：批准交接的完整根 CONTEXT.md（含 schema frontmatter），不得用跨仓路径替代本仓词汇表。初始化只复制已确认内容，不创造业务术语；父项目只保留服务引用和 handoff 证据。
+- `allowed_write_paths` 必须覆盖目标项目及同级 skillUtils。已有 skillUtils 锁不匹配即 blocked，不替换别的项目正在使用的工具包。
+
+## 命令与结果
+
+`node scripts/generate_project.mjs` 使用通用 MVC 生成器相同的批准合同与 Maven 坐标参数（`--output-dir` 是父容器）；无 `--database`、`--with-mock` 或交互选项。
+
+输出独立 project-instance、初始化但未提交的 main Git、生命周期资产、完整锁定 skillUtils、架构身份及 Manifest。使用共享 `run_scaffold_verification.mjs <project> <evidence>` 实跑三条 Wrapper 命令；只在实际成功后报告 empty-scaffold-verified。Profile 仍须独立首切片 fixture 达标才能晋升 supported。