create-yss-spec 3.0.1 → 3.1.0

package/template/.claude/skills/yss-mvc-data-analysis-project-initializer/scripts/generate_project.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { cp, lstat, mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { generate, parseArgs } from "../../yss-layered-mvc-scaffold-generator/scripts/generate_scaffold.mjs";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../..");
+const skillId = "yss-mvc-data-analysis-project-initializer";
+const digest = (value) => `sha256:${createHash("sha256").update(value).digest("hex")}`;
+async function present(target) { try { await lstat(target); return true; } catch (error) { if (error.code === "ENOENT") return false; throw error; } }
+async function put(target, text) { await mkdir(path.dirname(target), { recursive: true }); await writeFile(target, `${text.trimEnd()}\n`); }
+function within(parent, target) { const relative = path.relative(parent, target); return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative)); }
+
+async function sharedTools(outputDir, contract) {
+  const destination = path.join(outputDir, "skillUtils");
+  if (!contract.allowed_write_paths.some((item) => within(path.resolve(outputDir, item), destination))) throw new Error("skillUtils 不在批准写范围内");
+  const lock = await readFile(path.join(root, "skills-lock.json"));
+  if (await present(destination)) {
+    if (!await present(path.join(destination, "skill-utils.yaml")) || !lock.equals(await readFile(path.join(destination, "skills-lock.json")))) throw new Error("已有 skillUtils 不匹配；须独立批准刷新，初始化不会覆盖");
+    return digest(lock);
+  }
+  const staging = await mkdtemp(path.join(outputDir, ".skillUtils.staging-"));
+  try {
+    for (const relative of [".agents/skills", ".codex/skills", ".claude/skills", ".cursor/skills", ".pi/skills", ".qoder/skills", ".trae/skills", "scripts", "docs/agents", "docs/process", "AGENTS.md", "skills-lock.json"]) {
+      await mkdir(path.dirname(path.join(staging, relative)), { recursive: true });
+      await cp(path.join(root, relative), path.join(staging, relative), { recursive: true });
+    }
+    await put(path.join(staging, "skill-utils.yaml"), "schema_version: 1\nkind: yss-skill-utils\ncompatibility: skill-utils-v1\ncanonical_root: .agents/skills");
+    await rename(staging, destination);
+  } catch (error) { await rm(staging, { recursive: true, force: true }); throw error; }
+  return digest(lock);
+}
+
+export async function initialize(options) {
+  // Shared generation validates approval, decision, target and write scope before invoking this callback.
+  return generate(options, { skillId, architectureProfile: "mvc-data-analysis-v1", finalize: async ({ projectRoot, contract, architectureIdentity }) => {
+    if (!contract.context_handoff_ref || !contract.context_handoff_digest) throw new Error("缺少批准的 context_handoff_ref/context_handoff_digest");
+    const handoffPath = path.resolve(path.dirname(path.resolve(options.contractFile)), contract.context_handoff_ref);
+    const context = await readFile(handoffPath);
+    if (digest(context) !== contract.context_handoff_digest || !/^---\r?\ncontext_schema_version: 1\r?\n---/m.test(context.toString())) throw new Error("CONTEXT handoff schema/digest 不匹配");
+    if (spawnSync("git", ["--version"]).status !== 0) throw new Error("Git 不可用");
+    for (const relative of ["docs/agents", "docs/process", "docs/templates", "docs/architecture/templates"]) {
+      await mkdir(path.dirname(path.join(projectRoot, relative)), { recursive: true });
+      await cp(path.join(root, relative), path.join(projectRoot, relative), { recursive: true });
+    }
+    await put(path.join(projectRoot, "CONTEXT.md"), context.toString());
+    const agents = (await readFile(path.join(root, "AGENTS.md"), "utf8"))
+      .replace(/## 4\. `template-source` 模板维护路由[\s\S]*?(?=## 5\.)/, "## 4. 模板维护\n\n本仓为 project-instance；模板维护回上游执行。\n\n")
+      .replaceAll(".agents/skills", "../skillUtils/.agents/skills");
+    await put(path.join(projectRoot, "AGENTS.md"), agents);
+    await put(path.join(projectRoot, "yss-project.yaml"), "schema_version: 1\nrepository_mode: project-instance");
+    await put(path.join(projectRoot, ".artifact-workspace.yaml"), `schema_version: 1\nkind: service\nservice_id: ${options.projectName}`);
+    await cp(path.join(root, "scripts/lib"), path.join(projectRoot, "scripts/lib"), { recursive: true });
+    await cp(path.join(root, "scripts/vendor"), path.join(projectRoot, "scripts/vendor"), { recursive: true });
+    for (const name of ["repository-mode", "implementation-path-policy", "repository-scope-policy", "generate-lifecycle-artifacts", "node-generate-lifecycle-artifacts.mjs", "verify-lifecycle-registry", "node-verify-lifecycle-registry.mjs", "verify-lifecycle-checkpoint", "verify-context-reconciliation", "verify-approval-record", "verify-user-decision", "verify-digital-human-task-package", "verify-yss-dto-openapi-profile", "verify-frontend-implementation-evidence"]) {
+      await cp(path.join(root, "scripts", name), path.join(projectRoot, "scripts", name));
+    }
+    const lockDigest = await sharedTools(path.resolve(options.outputDir), contract);
+    await put(path.join(projectRoot, "skills-lock.json"), JSON.stringify({ version: 1, distribution: { mode: "sibling-directory", skillUtilsDir: "../skillUtils", required: true, compatibility: "skill-utils-v1", lock_digest: lockDigest } }, null, 2));
+    await put(path.join(projectRoot, "docs/process/engineering-baseline.json"), JSON.stringify({ schema_version: 1, architecture_identity: architectureIdentity, platform_profile: contract.profiles.platform, scaffold_completion: "generated" }, null, 2));
+    await put(path.join(projectRoot, "docs/process/implementation-repo-registry.yaml"), JSON.stringify({ schema_version: 1, projects: [{ project_type: "backend", project_name: options.projectName, project_root: ".", git_root: ".", repository_scope: "external-repository", scaffold_status: "initialized", default_branch: "main", architecture_identity: architectureIdentity, allowed_write_paths: ["."], verification_commands: contract.verification_commands, expected_evidence_files: contract.expected_evidence_files, ci: "not-configured", rollback_point: "initial-empty-repository" }] }, null, 2));
+    await put(path.join(projectRoot, "docs/process/service-initialization.json"), JSON.stringify({ work_unit: "work-unit.service-project-initialization", context_handoff_ref: contract.context_handoff_ref, context_handoff_digest: contract.context_handoff_digest, contract_id: contract.contract_id, architecture_identity: architectureIdentity, status: "generated" }, null, 2));
+    await put(path.join(projectRoot, ".gitignore"), "target/\n**/target/\n.idea/\n*.iml\n.env\n.env.*\n.local/");
+    const git = spawnSync("git", ["init", "--initial-branch=main"], { cwd: projectRoot, encoding: "utf8" });
+    if (git.status !== 0) throw new Error(`Git 初始化失败: ${git.stderr}`);
+  } });
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  try {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) process.stdout.write("使用批准的 MVC schema v3 合同与 Maven 坐标参数；输出独立数据分析项目，无数据库/Mock 选项。\n");
+    else await initialize(options);
+  } catch (error) { process.stderr.write(`数据分析项目初始化失败: ${error.message}\n`); process.exitCode = 1; }
+}

package/template/.claude/skills/yss-mvc-data-analysis-project-initializer/scripts/run_scaffold_verification.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { run } from "../../yss-ddd-scaffold-generator/scripts/run_scaffold_verification.mjs";
+try {
+  const [projectRoot, evidenceDir] = process.argv.slice(2);
+  if (!projectRoot || !evidenceDir) throw new Error("用法: run_scaffold_verification.mjs <project-root> <evidence-dir>");
+  const report = await run(projectRoot, evidenceDir);
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  process.exitCode = report.status === "passed" ? 0 : 1;
+} catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }

package/template/.claude/skills/yss-mvc-scaffold-generator/SKILL.md

@@ -1,87 +1,8 @@
 ---
 name: yss-mvc-scaffold-generator
-description: 从空目录初始化独立 Git 管理的 YSS Java 8 MVC 数据分析 project-instance，生成固定六模块、YSS 标准组件、Oracle/OceanBase Oracle 与 Mock HTTP API；不用于通用 DDD 服务。
+description: 已退役的数据分析 MVC 初始化旧入口；仅用于识别历史合同并指引重新批准，不执行生成或自动迁移。
 ---
 
-# YSS MVC Scaffold Generator
+# 已退役入口
 
-本 Skill 是 YSS MVC 数据分析项目的确定性机械生成器。它生成独立 `project-instance`、独立 Git 仓库，并将项目根直接作为 Maven 工程根，包含 `server`、`core`、`client`、`repository`、`adapter`、`feign-client` 六模块；业务功能仍须回到 `yss-product-lifecycle` 与 `yss-implementation-contract-compiler` 按垂直切片实现。
-
-生成器编排入口位于 `scripts/generate_project.mjs`，参数与环境解析、skillUtils 文件操作、项目治理封装和 Maven/Java 模板分别位于 `scripts/lib/`。初始化阶段只写入 staging 目录并在成功后原子重命名，不执行 Maven 或网络依赖下载。
-
-用户以“初始化新项目”进入时，由 `product-service-artifacts` 调用本生成器并默认附加 `docs/service/` 服务级研发产物；不要要求用户在提示词中另行说明“初始化产物”。未提供职责时生成 `skeleton`，不阻断工程创建。
-
-## 输入
-
-- `project-name`：小写连字符项目名。
-- `base-package`：合法 Java 包名。
-- `target-dir`：最终项目根目录，必须显式给出。
-- `database`：支持 `oracle`、`oceanbase-oracle`，默认 `oracle`。
-- `with-mock`：生成 `mock` Profile、Mock 执行器及 HTTP 冒烟测试。
-- `maven-settings`：可选的外部 Maven settings 绝对路径，仅用于后续验证；未显式提供时依次读取 `YSS_MAVEN_SETTINGS` 和用户目录 `.m2/settings.xml`。不复制进项目、不写入生成清单。
-
-## 执行
-
-先预演：
-
-```bash
-node scripts/generate_project.mjs --project-name mvc-analysis-item1 --base-package com.yss.dataanalysis.item1 --target-dir /path/to/mvc-analysis-item1 --database oracle --with-mock --maven-settings /path/to/settings.xml --dry-run
-```
-
-确认目标目录后去掉 `--dry-run`。生成后运行：
-
-```bash
-node scripts/verify_project.mjs --project-root /path/to/mvc-analysis-item1
-cd /path/to/mvc-analysis-item1
-./mvnw validate
-./mvnw test
-./mvnw package
-./mvnw spring-boot:run -pl mvc-analysis-item1-server -Dspring-boot.run.profiles=mock
-```
-
-Windows 使用 `mvnw.cmd`。指定外部 settings 时，Maven 命令必须加 `-s <settings.xml>`。启动后对 `POST /api/analysis/query` 执行 HTTP 冒烟测试。
-
-生成项目进入 API/Controller 实现后，登记命令必须包含 Java Web/Javadoc 检查、`fmt:check`、测试和构建。Smart-doc 仅作为人工按需从 Controller 生成辅助文档的工具，不属于默认 AI Coding 验证链路；只有用户明确要求生成 Smart-doc 文档时才执行对应 goal。
-
-生成结果包含根 `yss-project.yaml`、`AGENTS.md`、`CONTEXT.md`、生命周期事实源、共享 skills、本地 Ticket 入口、`external-repository` 实现仓库登记和 `.gitignore`。生成器执行 `git init --initial-branch=main`；旧版 Git自动回退到 `git init` 后重命名分支。只初始化仓库，不创建 commit 或 remote。
-
-## 硬约束
-
-- `target-dir` 是最终项目根，不在其下再次创建项目名目录。
-- Windows 下优先使用纯 ASCII、长度可控且不属于其他项目 Git 根的父目录（例如 `C:\\projects`）；旧 Maven 插件在非 ASCII 长路径上可能产生 reactor classpath 编码错误。
-- 非空目标目录拒绝生成；本 Skill 不提供隐式覆盖或删除。
-- 目标目录必须成为独立 Git 根；生成前必须能执行 `git --version`，生成后必须验证 Git 根等于 `target-dir`、分支为 `main`、commit 数为零且 remote 为空。
-- 生成前必须从 `git config --get user.name` 读取非空作者名；作者名包含换行或 `*/` 时拒绝生成。生成的 Controller 类和公开接口方法以该值填写 `@author`，不得固定为 `system`。
-- 项目根同时是 Maven 工程根和独立 Git 根，固定登记为 `repository_scope: external-repository`、`project_root: .`；六模块直接位于项目根目录。
-- 生成内容先写入同父目录 staging，全部步骤成功后再原子重命名；失败时只清理本次 staging，不留下不可重试的半成品。Maven 依赖解析明确延后到验证阶段；settings 缺失只记录 `maven-default` / `maven_settings_available=false`，不会压缩或截断生成的文件结构。
-- 每个项目持有自己的 `project-instance` 身份与业务资产；不得为了新项目改写模板工具仓库的项目名称或业务上下文。
-- 模块名固定使用正确拼写 `feign-client`；旧项目中的 `fegin-client` 只作为迁移来源，不继续传播。
-- Mock 与 Oracle 使用同一 Controller 和 DTO 契约，只替换 `AnalysisQueryExecutor` 实现。
-- Mock 仅用于本地联调和契约验证，不得携带真实凭据或生产数据。
-- 启用 Mock 时必须生成 `bootstrap-mock.yml`，并在 Spring Cloud Bootstrap 阶段同时禁用 Nacos Discovery、Nacos Config 和 Config import-check；不能只在 `application-mock.yml` 中禁用。
-- `bootstrap.yml` 的默认顺序为 `${app.env:dev},datasource,nacos,<database-profile>,mock`，`mock` 必须最后以覆盖 Nacos Bootstrap 配置，且 profile 列表不得有尾随逗号。未启用 Mock 时不生成、不激活 `mock`。
-- Mock 与数据库 profile 同时出现时，Mock 执行器优先；数据库执行器使用 `<database-profile> & !mock` 表达式，禁止两个 `AnalysisQueryExecutor` 同时注册。
-- Mock 的 `application-mock.yml` 必须关闭 Leaf Segment/Snowflake，并在 `spring.autoconfigure.exclude` 中排除 `DataSourceAutoConfiguration`、`MybatisPlusConfiguration` 和 `LeafDataSourceConfiguration`；组件扫描同时排除 `com.yss.cloud.mybatis..*`、`com.yss.cloud.sankuai..*`，`@EnableDistributedId` 与 `MapperConfiguration` 只允许在 `!mock` 配置类中加载，确保无数据库时 Mock 测试和 HTTP 冒烟可运行。
-- Oracle Adapter 只保留可编译 seam；连接信息通过环境变量注入，生成器不写真实账号密码。
-- 工程版本、YSS 父 POM 和组件 BOM 固定为 `2.0.0-SNAPSHOT`，运行时固定 Java 8。
-- 标准能力默认包含审计日志、分布式 ID、Excel、Nacos、Redis Cache、OpenFeign、Smart-doc、用户信息和 Actuator。
-- server POM 必须保留 `spring-boot-maven-plugin`和默认激活的 `nacos` profile；Nacos 依赖只在该 profile 中声明。
-- `bootstrap-nacos.yml` 默认使用 `${nacosserver:192.168.165.58:8848}`、`${nacos_group:yss-dm}` 和 `${namespace:yss-datamiddle}`，Discovery/Config 在 `nacos` profile 中开启，并由 `bootstrap-mock.yml` 在 Mock 模式覆盖关闭。
-- Smart-doc 使用 `assets/smart-doc.json.template`的完整配置并动态生成项目名、Controller 包和修订时间；Torna Token 与内网地址不进入生成项目。Smart-doc 插件保留跨模块 `includes`，但不绑定 Maven `executions`，不进入默认 `validate` / `test` / `package` / CI / AI Coding 验证命令。
-- Logback 使用 `assets/logback-spring.xml.template`；`dev,mock` 与 `uat,pro,oracle,oceanbase-oracle` 必须是并列 profile，项目名和基础包动态替换。
-- Controller 类和公开接口方法必须按真实业务语义生成 Javadoc，`@author` 使用生成时读取的 Git 用户名，`@date` 使用 `yyyy/MM/dd HH:mm`，方法按签名完整生成 `@param`和 `@return`。
-- API 实现不得交付单行 Javadoc block tag、Mapping 注解/方法同行或方法体单行压缩代码；相关规范由生成项目中的工程约定和实际验证命令约束。
-- API 完成证据必须包含 `yss-skill-execution-result.yaml` 和 `fresh-verification.md`，并记录 Controller 路由、DTO、响应 Wrapper、错误响应及契约测试与冻结 OpenAPI 的一致性。Smart-doc 输出不是 OpenAPI Freeze、契约审查或功能完成证据。
-- Maven settings 始终是项目外部的私密输入；不得复制到目标目录、写入 README/生成清单或提交 Git。
-- 持久层固定使用 YSS MyBatis-Plus；标准 CRUD 使用 MP，复杂 SQL 写入 mapper.xml，主键策略为 `IdType.ASSIGN_ID`。
-- 生成范围仅包含工程骨架、示例 Mock seam 和验证测试，不声称业务 Spec、OpenAPI Freeze 或 Slice Implementation Contract 已批准。
-- 完成结论必须包含结构验证，以及实际执行的 Maven 命令；无法下载依赖时如实记录环境阻塞。
-
-模块职责和依赖方向见 [references/architecture.md](references/architecture.md)。
-
-## API 契约与人工文档边界
-
-- 冻结的 OpenAPI 3.1 YAML 是接口契约的唯一事实来源；`yss-openapi-governance` 负责契约治理与 Freeze，`yss-openapi-draft-review` 负责冻结前审查，`yss-web-controller` 负责按冻结契约实现 Controller。
-- Smart-doc 是人工可选的源码文档工具。其输出只用于查看当前 Controller 实现，不得反向定义、覆盖或批准冻结 OpenAPI。
-- AI 默认不执行 `smart-doc:html`、`smart-doc:openapi` 或 `smart-doc:torna-rest`。`torna-rest` 涉及外部写入，执行前还必须获得对应授权。
-- 本生成器只用于空目录初始化。生成项目使用已物化的 `project-instance` 资产和实现 skills 开发后续需求；其共享 `skillUtils` 不应再分发 `yss-mvc-scaffold-generator` 本身。
+本 ID 为 deprecated，只读保留历史合同解释。通用 MVC 使用 yss-layered-mvc-scaffold-generator；独立数据分析项目使用 yss-mvc-data-analysis-project-initializer。旧 Oracle/Mock 合同不得静默别名或重放；经生命周期确认 Profile 与 H2 新合同后才执行新入口。历史说明位于 references/history/skill.md，不是现行执行规范。

package/template/.claude/skills/yss-mvc-scaffold-generator/references/history/generate_project.mjs.txt

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+// Historical source only; not an executable entrypoint.
+/** YSS MVC 脚手架编排入口；参数、文件、模板和项目治理分别位于 scripts/lib。 */
+import { cp, mkdir, mkdtemp, rename, rm, rmdir } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  MODULES,
+  SHARED_SKILLS_ROOT,
+  fail,
+  parseArgs,
+  assertGitAvailable,
+  resolveGitAuthor,
+  resolveMavenSettings,
+  initializeGit,
+  exists,
+} from "./lib/runtime.mjs";
+import { assertEmpty, ensureSkillUtils, put, renderAsset } from "./lib/storage.mjs";
+import { writeProjectEnvelope } from "./lib/envelope.mjs";
+import { modulePom, parentPom, writeJavaSources } from "./lib/templates.mjs";
+
+const SKILL_ID = "yss-mvc-scaffold-generator";
+let generatedJavadocAuthor;
+
+function usage() {
+  console.log(`YSS MVC 脚手架生成器\n\n用法: node scripts/generate_project.mjs --project-name <name> --base-package <package> --target-dir <dir> [选项]\n\n选项: --database oracle|oceanbase-oracle --with-mock --maven-settings <path> --dry-run`);
+}
+
+async function writeGenerated(root, relative, content) {
+  await put(root, relative, content, generatedJavadocAuthor);
+}
+
+async function copyWrapper(root) {
+  const source = path.join(SHARED_SKILLS_ROOT, "yss-ddd-scaffold-generator", "assets", "wrapper");
+  if (!await exists(source)) fail(`Maven Wrapper 资产不存在: ${source}`);
+  await cp(source, root, { recursive: true });
+}
+
+function buildPlan(o, skillUtils, mavenSettings) {
+  const driver = o.database === "oceanbase-oracle" ? "com.oceanbase:oceanbase-client:2.4.3" : "com.oracle.database.jdbc:ojdbc8:19.8.0.0";
+  return {
+    project_name: o.projectName,
+    project_version: "2.0.0-SNAPSHOT",
+    base_package: o.basePackage,
+    target_dir: o.targetDir,
+    backend_root: ".",
+    skill_utils_dir: path.relative(o.targetDir, skillUtils.path).replaceAll(path.sep, "/"),
+    skill_utils_created: skillUtils.created,
+    skill_utils_refreshed: skillUtils.refreshed,
+    skill_utils_backup: skillUtils.backup,
+    repository_scope: "external-repository",
+    database: o.database,
+    database_driver: driver,
+    runtime_java: "8",
+    parent_pom: "com.yss.cloud:yss-cloud-microservice:2.0.0-SNAPSHOT",
+    components_bom: "com.yss.cloud:yss-components-bom:2.0.0-SNAPSHOT",
+    persistence_profile: "yss-mybatis-plus",
+    id_strategy: "ASSIGN_ID",
+    javadoc_author: o.gitAuthor,
+    maven_settings_mode: "external",
+    maven_settings_source: mavenSettings.source,
+    maven_settings_available: mavenSettings.available,
+    maven_settings_required: mavenSettings.available,
+    dependency_resolution: "deferred",
+    network_access_during_generation: "disabled",
+    features: ["audit", "distributed-id", "excel", "nacos", "redis", "openfeign", "smart-doc", "userinfo", "actuator"],
+    modules: MODULES,
+    mock_enabled: o.withMock,
+    project_instance: true,
+    git_initialized: true,
+    default_branch: "main",
+    endpoint: o.withMock ? "POST /api/analysis/query" : null
+  };
+}
+
+async function generate(o) {
+  await assertEmpty(o.targetDir);
+  const skillUtils = await ensureSkillUtils(o.targetDir, { apply: !o.dryRun });
+  assertGitAvailable();
+  o.gitAuthor = resolveGitAuthor();
+  generatedJavadocAuthor = o.gitAuthor;
+  const mavenSettings = await resolveMavenSettings(o);
+  const plan = buildPlan(o, skillUtils, mavenSettings);
+  if (o.dryRun) {
+    console.log(JSON.stringify({ mode: "dry-run", ...plan }, null, 2));
+    return;
+  }
+
+  const targetParent = path.dirname(o.targetDir);
+  await mkdir(targetParent, { recursive: true });
+  const staging = await mkdtemp(path.join(targetParent, `.${path.basename(o.targetDir)}.staging-`));
+  const work = { ...o, targetDir: staging, modules: MODULES };
+  try {
+    for (const module of MODULES) {
+      await writeGenerated(work.targetDir, `${module}/pom.xml`, modulePom(work, module));
+      await mkdir(path.join(work.targetDir, module, "src/main/resources"), { recursive: true });
+    }
+    await writeGenerated(work.targetDir, "pom.xml", parentPom(work));
+    await writeJavaSources(work, writeGenerated);
+    const activeProfiles = `\${app.env:dev},datasource,nacos,${o.database === "oceanbase-oracle" ? "oceanbase-oracle" : "oracle"}${o.withMock ? ",mock" : ""}`;
+    await writeGenerated(work.targetDir, "server/src/main/resources/bootstrap.yml", `server:\n  port: \${SERVER_PORT:8080}\nspring:\n  application:\n    name: \${APP_NAME:${o.projectName}}\n  profiles:\n    active: ${activeProfiles}\n  main:\n    allow-bean-definition-overriding: true\n  servlet:\n    multipart:\n      max-file-size: \${MAX_FILE_SIZE:100MB}\n      max-request-size: \${MAX_REQUEST_SIZE:100MB}`);
+    await writeGenerated(work.targetDir, "server/src/main/resources/bootstrap-nacos.yml", `spring:\n  cloud:\n    nacos:\n      discovery:\n        server-addr: \${nacosserver:192.168.165.58:8848}\n        group: \${nacos_group:yss-dm}\n        namespace: \${namespace:yss-datamiddle}\n        enabled: true\n      config:\n        import-check:\n          enabled: false\n        server-addr: \${nacosserver:192.168.165.58:8848}\n        namespace: \${namespace:yss-datamiddle}\n        group: \${nacos_group:yss-dm}\n        file-extension: yml\n        enabled: true`);
+    if (o.withMock) await writeGenerated(work.targetDir, "server/src/main/resources/bootstrap-mock.yml", `spring:\n  cloud:\n    nacos:\n      discovery:\n        enabled: false\n      config:\n        enabled: false\n        import-check:\n          enabled: false`);
+    await writeGenerated(work.targetDir, "server/src/main/resources/application-mock.yml", `spring:\n  autoconfigure:\n    exclude:\n      - org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration\n      - com.yss.cloud.mybatis.MybatisPlusConfiguration\n      - com.yss.cloud.sankuai.config.LeafDataSourceConfiguration\n  leaf:\n    leafSegmentEnable: false\n    leafSnowflakeEnable: false\nyss:\n  audit:\n    enabled: false`);
+    const driver = o.database === "oceanbase-oracle" ? "com.oceanbase.jdbc.Driver" : "oracle.jdbc.OracleDriver";
+    await writeGenerated(work.targetDir, `server/src/main/resources/application-${o.database}.yml`, `spring:\n  datasource:\n    driver-class-name: ${driver}\n    url: \${DB_URL:}\n    username: \${DB_USERNAME:}\n    password: \${DB_PASSWORD:}\nyss:\n  id:\n    strategy: ASSIGN_ID`);
+    await writeGenerated(work.targetDir, "server/src/main/resources/logback-spring.xml", await renderAsset("logback-spring.xml.template", { PROJECT_NAME: o.projectName, BASE_PACKAGE: o.basePackage }));
+    await writeGenerated(work.targetDir, "server/src/main/resources/smart-doc.json", await renderAsset("smart-doc.json.template", { PROJECT_NAME: o.projectName, BASE_PACKAGE: o.basePackage, GENERATED_AT: new Date().toISOString() }));
+    await writeGenerated(staging, "README.md", `# ${o.projectName}\n\n项目根即 Maven 后端工程根，固定模块：${MODULES.join("、")}。\n\n## 依赖解析\n\n初始化阶段只生成文件和 Git 根，不执行 Maven，不下载依赖。未提供 settings 时仍会完整生成；后续验证时请使用 \`mvnw.cmd -s <settings.xml> validate\`（Windows）或 \`./mvnw -s <settings.xml> validate\`（Unix）。`);
+    await writeProjectEnvelope(work);
+    await copyWrapper(work.targetDir);
+    if (process.env.NODE_ENV === "test" && process.env.YSS_SCAFFOLD_TEST_FAIL_AFTER_STAGING === "1") fail("测试注入：staging 后失败");
+    initializeGit(staging);
+    await writeGenerated(staging, ".yss/scaffold-generation.json", JSON.stringify({ schema_version: 1, skill: SKILL_ID, generation_mode: "controlled-generation", generated_at: new Date().toISOString(), ...plan }, null, 2));
+    if (process.env.NODE_ENV === "test" && process.env.YSS_SCAFFOLD_TEST_WRITE_TARGET_DURING_STAGING === "1") await writeGenerated(o.targetDir, "keep.txt", "concurrent content");
+    if (await exists(o.targetDir)) await rmdir(o.targetDir);
+    await rename(staging, o.targetDir);
+  } catch (error) {
+    if (await exists(staging)) await rm(staging, { recursive: true, force: true });
+    throw error;
+  }
+  console.log(JSON.stringify({ mode: "generated", ...plan }, null, 2));
+}
+
+async function main() {
+  try {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) { usage(); return 0; }
+    await generate(options);
+    return 0;
+  } catch (error) {
+    process.stderr.write(`\n❌ 生成失败: ${error.message}\n`);
+    return 1;
+  }
+}
+
+process.exitCode = await main();