adspecs 0.1.18 → 0.1.20

package/src/lib/scaffolder.js

@@ -1,518 +1,518 @@
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const { copyDirFiltered, removeDir, countFiles } = require('./copier');
-const { generateReadme, generateWikiReadme, generateServiceReadme, DOCS_READMES } = require('./readme-gen');
-const { mergeJsonFile, mergeProjectJson } = require('./json-merge');
-const { generatePathsConfig } = require('./paths-defaults');
-
-/**
- * 脚手架核心
- *
- * 接收 per-zone decisions 对象，按决策分支执行（create/recreate/update/skip）。
- * 通过 logger 回调实时输出每阶段状态。
- * 支持子目录决策、模式升级自动补充、skip 场景下 feature.json 属性补全。
- */
-
-// ============================================================
-// 主入口
-// ============================================================
-
-/**
- * 执行脚手架
- *
- * @param {object} opts
- * @param {string} opts.targetDir - 目标项目根目录
- * @param {string} opts.pluginDir - 插件根目录
- * @param {string} opts.mode - 初始化模式
- * @param {string} opts.frontDemo - 前端技术栈（vue/antd/skip）
- * @param {string} opts.project_name
- * @param {string} opts.project_short_name
- * @param {string} opts.project_dir
- * @param {string} opts.company_name
- * @param {string} opts.confidentiality
- * @param {string} opts.modules
- * @param {object} opts.decisions - 每区域决策 { areaKey: 'create'|'recreate'|'update'|'skip' }
- * @param {object} opts.subDecisions - 子目录决策 { conventions, templates }
- * @param {object} opts.modeUpgrade - 模式升级检测 { detected, emptyDirs }
- * @param {function} opts.logger - 实时状态回调 (msg: string) => void
- * @returns {Promise<object>} 执行报告
- */
-async function scaffold(opts) {
-  const {
-    targetDir,
-    pluginDir,
-    mode,
-    frontDemo,
-    project_name,
-    project_short_name,
-    project_dir,
-    company_name,
-    confidentiality,
-    modules,
-    decisions,
-    subDecisions = { conventions: 'skip', templates: 'skip' },
-    modeUpgrade = { detected: false, emptyDirs: [] },
-    logger = () => {},
-  } = opts;
-
-  const report = {
-    targetDir,
-    mode,
-    projectName: project_name,
-    projectShortName: project_short_name,
-    companyName: company_name,
-    confidentiality,
-    stages: [],
-    startedAt: new Date().toISOString(),
-  };
-
-  const FRONT_DEMO_SOURCE = frontDemo === 'antd' ? 'antd-front-demo' : 'front-demo';
-
-  fs.mkdirSync(targetDir, { recursive: true });
-
-  // === 阶段 1: docs/ ===
-  report.stages.push(
-    await scaffoldDocs(targetDir, pluginDir, mode, FRONT_DEMO_SOURCE, decisions.docs, subDecisions, modeUpgrade, logger)
-  );
-
-  // === 阶段 2: wiki/ ===
-  report.stages.push(scaffoldWiki(targetDir, decisions.wiki, logger));
-
-  // === 阶段 3: web-ui/ (full/demo) ===
-  if (mode === 'full' || mode === 'demo') {
-    report.stages.push(await scaffoldWebUi(targetDir, pluginDir, decisions.webUi, logger));
-  }
-
-  // === 阶段 4: service/ (full/demo) ===
-  if (mode === 'full' || mode === 'demo') {
-    report.stages.push(scaffoldService(targetDir, modules, decisions.service, logger));
-  }
-
-  // === 阶段 5: front-demo/ (classic/full/demo，且 frontDemo !== 'skip') ===
-  if (mode !== 'simple' && frontDemo !== 'skip') {
-    report.stages.push(await scaffoldFrontDemo(targetDir, pluginDir, FRONT_DEMO_SOURCE, decisions.frontDemo, logger));
-  } else if (mode !== 'simple' && frontDemo === 'skip') {
-    logger(`⏭ 阶段 5 跳过：用户选择不创建 front-demo/`);
-    report.stages.push({ name: 'front-demo/', status: 'skipped', reason: '用户选择跳过' });
-  }
-
-  // === 阶段 6: .adspecs/ ===
-  report.stages.push(
-    await scaffoldAdspecs(targetDir, pluginDir, decisions.adspecs, subDecisions, logger)
-  );
-
-  // === 阶段 6.5: project.json ===
-  const projectJsonResult = writeProjectJson(targetDir, pluginDir, {
-    project_name,
-    project_short_name,
-    project_dir,
-    company_name,
-    confidentiality,
-  });
-  logger(
-    projectJsonResult.created
-      ? `✅ 阶段 6.5 完成：项目元数据已生成 .adspecs/project.json`
-      : `🔄 阶段 6.5 完成：项目元数据已更新 .adspecs/project.json`
-  );
-  report.stages.push({
-    name: '.adspecs/project.json',
-    status: projectJsonResult.created ? 'created' : 'updated',
-    detail: projectJsonResult,
-  });
-
-  // === 阶段 7: paths.json ===
-  const pathsResult = writePathsJson(targetDir);
-  logger(
-    pathsResult.created
-      ? `✅ 阶段 7 完成：路径配置文件已生成 .adspecs/paths.json`
-      : `⏭ 阶段 7 跳过：.adspecs/paths.json 已存在`
-  );
-  report.stages.push({
-    name: '.adspecs/paths.json',
-    status: pathsResult.created ? 'created' : 'exists',
-  });
-
-  report.completedAt = new Date().toISOString();
-  return report;
-}
-
-// ============================================================
-// 各阶段实现
-// ============================================================
-
-/**
- * 决策前处理：根据 decision 决定目录状态
- *
- * @returns {'created'|'recreated'|'skipped'|'updated'} action
- */
-function prepareDirByDecision(dirPath, decision, logger, areaName) {
-  if (decision === 'skip') {
-    return 'skip';
-  }
-  if (decision === 'recreate') {
-    if (fs.existsSync(dirPath)) {
-      removeDir(dirPath);
-      logger(`🔄 删除旧 ${areaName}/ 并重建...`);
-    }
-    fs.mkdirSync(dirPath, { recursive: true });
-    return 'recreate';
-  }
-  if (decision === 'update') {
-    // update：保留目录，后续操作会覆盖文件
-    fs.mkdirSync(dirPath, { recursive: true });
-    return 'update';
-  }
-  // create：目录原本就不存在
-  fs.mkdirSync(dirPath, { recursive: true });
-  return 'create';
-}
-
-/**
- * 阶段 1: docs/ 目录结构
- */
-async function scaffoldDocs(targetDir, pluginDir, mode, frontDemoSource, decision, subDecisions, modeUpgrade, logger) {
-  const docsDir = path.join(targetDir, 'docs');
-  const stage = { name: 'docs/', dirs: [], files: 0 };
-
-  if (decision === 'skip') {
-    logger(`⏭ 阶段 1 跳过：docs/ 已存在，保留现有内容`);
-
-    // 子决策：conventions
-    if (subDecisions.conventions === 'update') {
-      const frontendStandard = resolveFrontendStandard(frontDemoSource);
-      copyDirFiltered(
-        path.join(pluginDir, 'references', frontendStandard),
-        path.join(docsDir, '40-project_conventions/frontend-standard')
-      );
-      logger(`🔄 阶段 1 补充更新：docs/40-project_conventions/frontend-standard/ 已按前端技术栈更新`);
-      stage.subDecisions = { conventions: 'update' };
-    }
-
-    // 模式升级自动补充
-    if (modeUpgrade.detected) {
-      const frontendStandard = resolveFrontendStandard(frontDemoSource);
-      fs.mkdirSync(path.join(docsDir, '40-project_conventions/frontend-standard'), { recursive: true });
-      copyDirFiltered(
-        path.join(pluginDir, 'references', frontendStandard),
-        path.join(docsDir, '40-project_conventions/frontend-standard')
-      );
-      logger(`📦 补充：检测到 40-project_conventions/ 为空目录（简易模式产物），已按前端技术栈补充 frontend-standard/`);
-      stage.modeUpgrade = modeUpgrade;
-    }
-
-    stage.status = 'skipped';
-    return stage;
-  }
-
-  const action = prepareDirByDecision(docsDir, decision, logger, 'docs');
-
-  // 11 个一级子目录
-  const subdirs = [
-    '00-planning',
-    '00-customer-requirements',
-    '10-architecture',
-    '20-prd',
-    '30-system-design',
-    '40-project_conventions',
-    '70-scripts/depoly',
-    '80-development/800-log',
-    '80-development/801-dev',
-    '80-development/802-test',
-    '100-help',
-    '300-specs',
-  ];
-  for (const sub of subdirs) {
-    fs.mkdirSync(path.join(docsDir, sub), { recursive: true });
-    stage.dirs.push(sub);
-  }
-
-  // 40-project_conventions 按模式处理
-  const convDir = path.join(docsDir, '40-project_conventions');
-  fs.mkdirSync(path.join(convDir, 'frontend-standard'), { recursive: true });
-  fs.mkdirSync(path.join(convDir, 'end-standard'), { recursive: true });
-
-  if (mode === 'demo') {
-    copyDirFiltered(
-      path.join(pluginDir, 'references/ant6-front-standard'),
-      path.join(convDir, 'frontend-standard')
-    );
-    copyDirFiltered(
-      path.join(pluginDir, 'references/python-end-standard'),
-      path.join(convDir, 'end-standard')
-    );
-  } else if (mode === 'classic' || mode === 'full') {
-    const frontendStandard = resolveFrontendStandard(frontDemoSource);
-    copyDirFiltered(
-      path.join(pluginDir, 'references', frontendStandard),
-      path.join(convDir, 'frontend-standard')
-    );
-  }
-
-  // 生成各子目录的 README.md（create/recreate/update 都重新生成）
-  if (decision !== 'skip') {
-    for (const [subdirKey, meta] of Object.entries(DOCS_READMES)) {
-      const readmePath = path.join(docsDir, subdirKey, 'README.md');
-      fs.writeFileSync(readmePath, generateReadme(meta), 'utf8');
-      stage.files++;
-    }
-  }
-
-  stage.fileCount = countFiles(docsDir);
-  stage.status = action === 'recreate' ? 'recreated' : 'created';
-
-  const verb = action === 'recreate' ? '重新创建' : '创建';
-  const convNote =
-    mode === 'demo'
-      ? '，40 按 Python+React 技术栈复制前后端规范'
-      : mode === 'simple'
-        ? '，40 仅创建空目录'
-        : '，其中 40 从 references 复制';
-  logger(`✅ 阶段 1 完成：docs/ 目录结构已${verb}（11 个一级子目录${convNote}）`);
-
-  return stage;
-}
-
-/**
- * 阶段 2: wiki/ 基线文件目录
- */
-function scaffoldWiki(targetDir, decision, logger) {
-  const wikiDir = path.join(targetDir, 'wiki');
-  const stage = { name: 'wiki/' };
-
-  if (decision === 'skip') {
-    logger(`⏭ 阶段 2 跳过：wiki/ 已存在，保留现有内容`);
-    stage.status = 'skipped';
-    return stage;
-  }
-
-  const action = prepareDirByDecision(wikiDir, decision, logger, 'wiki');
-  fs.writeFileSync(path.join(wikiDir, 'README.md'), generateWikiReadme(), 'utf8');
-
-  stage.status = action === 'recreate' ? 'recreated' : 'created';
-  stage.fileCount = 1;
-
-  const verb = action === 'recreate' ? '重新创建' : '创建';
-  logger(`✅ 阶段 2 完成：wiki/ 基线文件目录已${verb}`);
-
-  return stage;
-}
-
-/**
- * 阶段 3: web-ui/ 前端项目（完整/轻量模式）
- */
-async function scaffoldWebUi(targetDir, pluginDir, decision, logger) {
-  const webUiDir = path.join(targetDir, 'web-ui');
-  const stage = { name: 'web-ui/' };
-
-  if (decision === 'skip') {
-    logger(`⏭ 阶段 3 跳过：web-ui/ 已存在，保留现有内容`);
-    stage.status = 'skipped';
-    return stage;
-  }
-
-  const action = prepareDirByDecision(webUiDir, decision, logger, 'web-ui');
-
-  // update / create / recreate 都从 references 复制
-  const result = copyDirFiltered(path.join(pluginDir, 'references/web-ui'), webUiDir);
-
-  stage.fileCount = result.fileCount;
-  stage.skippedDirs = result.skippedDirs;
-  stage.status = action === 'recreate' ? 'recreated' : 'created';
-
-  const verb = action === 'recreate' ? '重新复制' : '复制';
-  logger(`✅ 阶段 3 完成：web-ui/ 前端项目已${verb}（${result.fileCount} 个文件）`);
-
-  return stage;
-}
-
-/**
- * 阶段 4: service/ 后端服务目录（完整/轻量模式）
- */
-function scaffoldService(targetDir, modules, decision, logger) {
-  const serviceDir = path.join(targetDir, 'service');
-  const stage = { name: 'service/' };
-
-  if (decision === 'skip') {
-    logger(`⏭ 阶段 4 跳过：service/ 已存在，保留现有内容`);
-    stage.status = 'skipped';
-    return stage;
-  }
-
-  const action = prepareDirByDecision(serviceDir, decision, logger, 'service');
-  fs.writeFileSync(path.join(serviceDir, 'README.md'), generateServiceReadme(), 'utf8');
-
-  // 按模块列表创建子目录
-  if (modules) {
-    const moduleList = modules.split(',').map((s) => s.trim()).filter(Boolean);
-    for (const mod of moduleList) {
-      // 格式：{port}-crm-{name}:{package}
-      const match = mod.match(/^(\d+)-crm-([^:]+):(.+)$/);
-      if (match) {
-        const [, port, name] = match;
-        const modPath = path.join(serviceDir, `${port}-crm-${name}`, 'service');
-        fs.mkdirSync(modPath, { recursive: true });
-        fs.writeFileSync(path.join(modPath, 'README.md'), generateServiceReadme(), 'utf8');
-      }
-    }
-  }
-
-  stage.fileCount = countFiles(serviceDir);
-  stage.status = action === 'recreate' ? 'recreated' : 'created';
-
-  const verb = action === 'recreate' ? '重新创建' : '创建';
-  logger(`✅ 阶段 4 完成：service 目录已${verb}`);
-
-  return stage;
-}
-
-/**
- * 阶段 5: front-demo/ 前端演示项目（经典/完整/轻量模式）
- */
-async function scaffoldFrontDemo(targetDir, pluginDir, frontDemoSource, decision, logger) {
-  const frontDemoDir = path.join(targetDir, 'front-demo');
-  const stage = { name: 'front-demo/', frontDemoSource };
-
-  if (decision === 'skip') {
-    logger(`⏭ 阶段 5 跳过：front-demo/ 已存在，保留现有内容`);
-    stage.status = 'skipped';
-    return stage;
-  }
-
-  const action = prepareDirByDecision(frontDemoDir, decision, logger, 'front-demo');
-
-  const result = copyDirFiltered(
-    path.join(pluginDir, 'references', frontDemoSource),
-    frontDemoDir
-  );
-
-  stage.fileCount = result.fileCount;
-  stage.skippedDirs = result.skippedDirs;
-  stage.status = action === 'recreate' ? 'recreated' : 'created';
-
-  const techName = frontDemoSource === 'antd-front-demo' ? 'Ant Design React' : 'Vue';
-  const verb = action === 'recreate' ? '重新复制' : '复制';
-  logger(`✅ 阶段 5 完成：front-demo/ 已${verb}（${techName}，${result.fileCount} 个文件）`);
-
-  return stage;
-}
-
-/**
- * 阶段 6: .adspecs/ 配置与脚本目录
- */
-async function scaffoldAdspecs(targetDir, pluginDir, decision, subDecisions, logger) {
-  const adspecsDir = path.join(targetDir, '.adspecs');
-  const stage = { name: '.adspecs/' };
-
-  if (decision === 'skip') {
-    logger(`⏭ 阶段 6 跳过：.adspecs/ 已存在，保留现有内容`);
-
-    // 子决策：templates
-    if (subDecisions.templates === 'update') {
-      copyDirFiltered(
-        path.join(pluginDir, '.adspecs/templates'),
-        path.join(adspecsDir, 'templates')
-      );
-      logger(`🔄 阶段 6 补充更新：.adspecs/templates/ 已从插件根目录更新`);
-      stage.subDecisions = { templates: 'update' };
-    }
-
-    // 属性补全（无论是否更新 templates 都执行）
-    const featureResult = mergeJsonFile(
-      path.join(adspecsDir, 'feature.json'),
-      path.join(pluginDir, '.adspecs/feature.json')
-    );
-    if (featureResult.addedKeys.length > 0) {
-      logger(`🔧 阶段 6 属性补全：feature.json 已补充缺失属性 [${featureResult.addedKeys.join(', ')}]`);
-      stage.featureResult = featureResult;
-    } else {
-      logger(`✅ 阶段 6：feature.json 属性完整，无需补全`);
-    }
-
-    stage.status = 'skipped';
-    return stage;
-  }
-
-  // recreate / update / create
-  let backupFeature = null;
-  let backupProject = null;
-
-  if (decision === 'recreate' && fs.existsSync(adspecsDir)) {
-    // 备份 feature.json / project.json
-    const featurePath = path.join(adspecsDir, 'feature.json');
-    const projectPath = path.join(adspecsDir, 'project.json');
-    if (fs.existsSync(featurePath)) backupFeature = fs.readFileSync(featurePath, 'utf8');
-    if (fs.existsSync(projectPath)) backupProject = fs.readFileSync(projectPath, 'utf8');
-    removeDir(adspecsDir);
-    logger(`🔄 删除旧 .adspecs/ 并重建...`);
-  } else if (decision === 'update') {
-    // update：保留目录，后续覆盖复制
-    fs.mkdirSync(adspecsDir, { recursive: true });
-  }
-
-  // 从插件根目录复制 .adspecs/
-  const result = copyDirFiltered(path.join(pluginDir, '.adspecs'), adspecsDir);
-  stage.fileCount = result.fileCount;
-
-  // recreate 场景：恢复备份并合并
-  if (decision === 'recreate' && (backupFeature || backupProject)) {
-    if (backupFeature) {
-      const featureResult = mergeJsonFile(
-        path.join(adspecsDir, 'feature.json'),
-        path.join(pluginDir, '.adspecs/feature.json')
-      );
-      stage.featureResult = featureResult;
-    }
-    stage.projectJsonBacked = !!backupProject;
-    logger(`🔧 feature.json/project.json 已恢复并补全属性`);
-  }
-
-  stage.status = decision === 'recreate' ? 'recreated' : 'created';
-  const verb = decision === 'recreate' ? '重新复制' : '复制';
-  logger(`✅ 阶段 6 完成：.adspecs/ 配置与脚本目录已${verb}（${result.fileCount} 个文件）`);
-
-  return stage;
-}
-
-/**
- * 阶段 6.5: 生成 .adspecs/project.json
- */
-function writeProjectJson(targetDir, pluginDir, values) {
-  const targetPath = path.join(targetDir, '.adspecs/project.json');
-  const referencePath = path.join(pluginDir, '.adspecs/project.json');
-  const created = !fs.existsSync(targetPath);
-
-  const merged = mergeProjectJson(
-    targetPath,
-    { ...values, created_at: new Date().toISOString().slice(0, 10) },
-    referencePath
-  );
-
-  return { created, merged };
-}
-
-/**
- * 阶段 7: 生成 .adspecs/paths.json
- */
-function writePathsJson(targetDir) {
-  const targetPath = path.join(targetDir, '.adspecs/paths.json');
-  const created = !fs.existsSync(targetPath);
-
-  if (created) {
-    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
-    const config = generatePathsConfig();
-    fs.writeFileSync(targetPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
-  }
-
-  return { created };
-}
-
-/**
- * 根据前端演示源解析前端规范目录名
- */
-function resolveFrontendStandard(frontDemoSource) {
-  return frontDemoSource === 'antd-front-demo' ? 'ant6-front-standard' : 'ecp-front-standard';
-}
-
-module.exports = { scaffold };
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { copyDirFiltered, removeDir, countFiles } = require('./copier');
+const { generateReadme, generateWikiReadme, generateServiceReadme, DOCS_READMES } = require('./readme-gen');
+const { mergeJsonFile, mergeProjectJson } = require('./json-merge');
+const { generatePathsConfig } = require('./paths-defaults');
+
+/**
+ * 脚手架核心
+ *
+ * 接收 per-zone decisions 对象，按决策分支执行（create/recreate/update/skip）。
+ * 通过 logger 回调实时输出每阶段状态。
+ * 支持子目录决策、模式升级自动补充、skip 场景下 feature.json 属性补全。
+ */
+
+// ============================================================
+// 主入口
+// ============================================================
+
+/**
+ * 执行脚手架
+ *
+ * @param {object} opts
+ * @param {string} opts.targetDir - 目标项目根目录
+ * @param {string} opts.pluginDir - 插件根目录
+ * @param {string} opts.mode - 初始化模式
+ * @param {string} opts.frontDemo - 前端技术栈（vue/antd/skip）
+ * @param {string} opts.project_name
+ * @param {string} opts.project_short_name
+ * @param {string} opts.project_dir
+ * @param {string} opts.company_name
+ * @param {string} opts.confidentiality
+ * @param {string} opts.modules
+ * @param {object} opts.decisions - 每区域决策 { areaKey: 'create'|'recreate'|'update'|'skip' }
+ * @param {object} opts.subDecisions - 子目录决策 { conventions, templates }
+ * @param {object} opts.modeUpgrade - 模式升级检测 { detected, emptyDirs }
+ * @param {function} opts.logger - 实时状态回调 (msg: string) => void
+ * @returns {Promise<object>} 执行报告
+ */
+async function scaffold(opts) {
+  const {
+    targetDir,
+    pluginDir,
+    mode,
+    frontDemo,
+    project_name,
+    project_short_name,
+    project_dir,
+    company_name,
+    confidentiality,
+    modules,
+    decisions,
+    subDecisions = { conventions: 'skip', templates: 'skip' },
+    modeUpgrade = { detected: false, emptyDirs: [] },
+    logger = () => {},
+  } = opts;
+
+  const report = {
+    targetDir,
+    mode,
+    projectName: project_name,
+    projectShortName: project_short_name,
+    companyName: company_name,
+    confidentiality,
+    stages: [],
+    startedAt: new Date().toISOString(),
+  };
+
+  const FRONT_DEMO_SOURCE = frontDemo === 'antd' ? 'antd-front-demo' : 'front-demo';
+
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  // === 阶段 1: docs/ ===
+  report.stages.push(
+    await scaffoldDocs(targetDir, pluginDir, mode, FRONT_DEMO_SOURCE, decisions.docs, subDecisions, modeUpgrade, logger)
+  );
+
+  // === 阶段 2: wiki/ ===
+  report.stages.push(scaffoldWiki(targetDir, decisions.wiki, logger));
+
+  // === 阶段 3: web-ui/ (full/demo) ===
+  if (mode === 'full' || mode === 'demo') {
+    report.stages.push(await scaffoldWebUi(targetDir, pluginDir, decisions.webUi, logger));
+  }
+
+  // === 阶段 4: service/ (full/demo) ===
+  if (mode === 'full' || mode === 'demo') {
+    report.stages.push(scaffoldService(targetDir, modules, decisions.service, logger));
+  }
+
+  // === 阶段 5: front-demo/ (classic/full/demo，且 frontDemo !== 'skip') ===
+  if (mode !== 'simple' && frontDemo !== 'skip') {
+    report.stages.push(await scaffoldFrontDemo(targetDir, pluginDir, FRONT_DEMO_SOURCE, decisions.frontDemo, logger));
+  } else if (mode !== 'simple' && frontDemo === 'skip') {
+    logger(`⏭ 阶段 5 跳过：用户选择不创建 front-demo/`);
+    report.stages.push({ name: 'front-demo/', status: 'skipped', reason: '用户选择跳过' });
+  }
+
+  // === 阶段 6: .adspecs/ ===
+  report.stages.push(
+    await scaffoldAdspecs(targetDir, pluginDir, decisions.adspecs, subDecisions, logger)
+  );
+
+  // === 阶段 6.5: project.json ===
+  const projectJsonResult = writeProjectJson(targetDir, pluginDir, {
+    project_name,
+    project_short_name,
+    project_dir,
+    company_name,
+    confidentiality,
+  });
+  logger(
+    projectJsonResult.created
+      ? `✅ 阶段 6.5 完成：项目元数据已生成 .adspecs/project.json`
+      : `🔄 阶段 6.5 完成：项目元数据已更新 .adspecs/project.json`
+  );
+  report.stages.push({
+    name: '.adspecs/project.json',
+    status: projectJsonResult.created ? 'created' : 'updated',
+    detail: projectJsonResult,
+  });
+
+  // === 阶段 7: paths.json ===
+  const pathsResult = writePathsJson(targetDir);
+  logger(
+    pathsResult.created
+      ? `✅ 阶段 7 完成：路径配置文件已生成 .adspecs/paths.json`
+      : `⏭ 阶段 7 跳过：.adspecs/paths.json 已存在`
+  );
+  report.stages.push({
+    name: '.adspecs/paths.json',
+    status: pathsResult.created ? 'created' : 'exists',
+  });
+
+  report.completedAt = new Date().toISOString();
+  return report;
+}
+
+// ============================================================
+// 各阶段实现
+// ============================================================
+
+/**
+ * 决策前处理：根据 decision 决定目录状态
+ *
+ * @returns {'created'|'recreated'|'skipped'|'updated'} action
+ */
+function prepareDirByDecision(dirPath, decision, logger, areaName) {
+  if (decision === 'skip') {
+    return 'skip';
+  }
+  if (decision === 'recreate') {
+    if (fs.existsSync(dirPath)) {
+      removeDir(dirPath);
+      logger(`🔄 删除旧 ${areaName}/ 并重建...`);
+    }
+    fs.mkdirSync(dirPath, { recursive: true });
+    return 'recreate';
+  }
+  if (decision === 'update') {
+    // update：保留目录，后续操作会覆盖文件
+    fs.mkdirSync(dirPath, { recursive: true });
+    return 'update';
+  }
+  // create：目录原本就不存在
+  fs.mkdirSync(dirPath, { recursive: true });
+  return 'create';
+}
+
+/**
+ * 阶段 1: docs/ 目录结构
+ */
+async function scaffoldDocs(targetDir, pluginDir, mode, frontDemoSource, decision, subDecisions, modeUpgrade, logger) {
+  const docsDir = path.join(targetDir, 'docs');
+  const stage = { name: 'docs/', dirs: [], files: 0 };
+
+  if (decision === 'skip') {
+    logger(`⏭ 阶段 1 跳过：docs/ 已存在，保留现有内容`);
+
+    // 子决策：conventions
+    if (subDecisions.conventions === 'update') {
+      const frontendStandard = resolveFrontendStandard(frontDemoSource);
+      copyDirFiltered(
+        path.join(pluginDir, 'references', frontendStandard),
+        path.join(docsDir, '40-project_conventions/frontend-standard')
+      );
+      logger(`🔄 阶段 1 补充更新：docs/40-project_conventions/frontend-standard/ 已按前端技术栈更新`);
+      stage.subDecisions = { conventions: 'update' };
+    }
+
+    // 模式升级自动补充
+    if (modeUpgrade.detected) {
+      const frontendStandard = resolveFrontendStandard(frontDemoSource);
+      fs.mkdirSync(path.join(docsDir, '40-project_conventions/frontend-standard'), { recursive: true });
+      copyDirFiltered(
+        path.join(pluginDir, 'references', frontendStandard),
+        path.join(docsDir, '40-project_conventions/frontend-standard')
+      );
+      logger(`📦 补充：检测到 40-project_conventions/ 为空目录（简易模式产物），已按前端技术栈补充 frontend-standard/`);
+      stage.modeUpgrade = modeUpgrade;
+    }
+
+    stage.status = 'skipped';
+    return stage;
+  }
+
+  const action = prepareDirByDecision(docsDir, decision, logger, 'docs');
+
+  // 11 个一级子目录
+  const subdirs = [
+    '00-planning',
+    '00-customer-requirements',
+    '10-architecture',
+    '20-prd',
+    '30-system-design',
+    '40-project_conventions',
+    '70-scripts/depoly',
+    '80-development/800-log',
+    '80-development/801-dev',
+    '80-development/802-test',
+    '100-help',
+    '300-specs',
+  ];
+  for (const sub of subdirs) {
+    fs.mkdirSync(path.join(docsDir, sub), { recursive: true });
+    stage.dirs.push(sub);
+  }
+
+  // 40-project_conventions 按模式处理
+  const convDir = path.join(docsDir, '40-project_conventions');
+  fs.mkdirSync(path.join(convDir, 'frontend-standard'), { recursive: true });
+  fs.mkdirSync(path.join(convDir, 'end-standard'), { recursive: true });
+
+  if (mode === 'demo') {
+    copyDirFiltered(
+      path.join(pluginDir, 'references/ant6-front-standard'),
+      path.join(convDir, 'frontend-standard')
+    );
+    copyDirFiltered(
+      path.join(pluginDir, 'references/python-end-standard'),
+      path.join(convDir, 'end-standard')
+    );
+  } else if (mode === 'classic' || mode === 'full') {
+    const frontendStandard = resolveFrontendStandard(frontDemoSource);
+    copyDirFiltered(
+      path.join(pluginDir, 'references', frontendStandard),
+      path.join(convDir, 'frontend-standard')
+    );
+  }
+
+  // 生成各子目录的 README.md（create/recreate/update 都重新生成）
+  if (decision !== 'skip') {
+    for (const [subdirKey, meta] of Object.entries(DOCS_READMES)) {
+      const readmePath = path.join(docsDir, subdirKey, 'README.md');
+      fs.writeFileSync(readmePath, generateReadme(meta), 'utf8');
+      stage.files++;
+    }
+  }
+
+  stage.fileCount = countFiles(docsDir);
+  stage.status = action === 'recreate' ? 'recreated' : 'created';
+
+  const verb = action === 'recreate' ? '重新创建' : '创建';
+  const convNote =
+    mode === 'demo'
+      ? '，40 按 Python+React 技术栈复制前后端规范'
+      : mode === 'simple'
+        ? '，40 仅创建空目录'
+        : '，其中 40 从 references 复制';
+  logger(`✅ 阶段 1 完成：docs/ 目录结构已${verb}（11 个一级子目录${convNote}）`);
+
+  return stage;
+}
+
+/**
+ * 阶段 2: wiki/ 基线文件目录
+ */
+function scaffoldWiki(targetDir, decision, logger) {
+  const wikiDir = path.join(targetDir, 'wiki');
+  const stage = { name: 'wiki/' };
+
+  if (decision === 'skip') {
+    logger(`⏭ 阶段 2 跳过：wiki/ 已存在，保留现有内容`);
+    stage.status = 'skipped';
+    return stage;
+  }
+
+  const action = prepareDirByDecision(wikiDir, decision, logger, 'wiki');
+  fs.writeFileSync(path.join(wikiDir, 'README.md'), generateWikiReadme(), 'utf8');
+
+  stage.status = action === 'recreate' ? 'recreated' : 'created';
+  stage.fileCount = 1;
+
+  const verb = action === 'recreate' ? '重新创建' : '创建';
+  logger(`✅ 阶段 2 完成：wiki/ 基线文件目录已${verb}`);
+
+  return stage;
+}
+
+/**
+ * 阶段 3: web-ui/ 前端项目（完整/轻量模式）
+ */
+async function scaffoldWebUi(targetDir, pluginDir, decision, logger) {
+  const webUiDir = path.join(targetDir, 'web-ui');
+  const stage = { name: 'web-ui/' };
+
+  if (decision === 'skip') {
+    logger(`⏭ 阶段 3 跳过：web-ui/ 已存在，保留现有内容`);
+    stage.status = 'skipped';
+    return stage;
+  }
+
+  const action = prepareDirByDecision(webUiDir, decision, logger, 'web-ui');
+
+  // update / create / recreate 都从 references 复制
+  const result = copyDirFiltered(path.join(pluginDir, 'references/web-ui'), webUiDir);
+
+  stage.fileCount = result.fileCount;
+  stage.skippedDirs = result.skippedDirs;
+  stage.status = action === 'recreate' ? 'recreated' : 'created';
+
+  const verb = action === 'recreate' ? '重新复制' : '复制';
+  logger(`✅ 阶段 3 完成：web-ui/ 前端项目已${verb}（${result.fileCount} 个文件）`);
+
+  return stage;
+}
+
+/**
+ * 阶段 4: service/ 后端服务目录（完整/轻量模式）
+ */
+function scaffoldService(targetDir, modules, decision, logger) {
+  const serviceDir = path.join(targetDir, 'service');
+  const stage = { name: 'service/' };
+
+  if (decision === 'skip') {
+    logger(`⏭ 阶段 4 跳过：service/ 已存在，保留现有内容`);
+    stage.status = 'skipped';
+    return stage;
+  }
+
+  const action = prepareDirByDecision(serviceDir, decision, logger, 'service');
+  fs.writeFileSync(path.join(serviceDir, 'README.md'), generateServiceReadme(), 'utf8');
+
+  // 按模块列表创建子目录
+  if (modules) {
+    const moduleList = modules.split(',').map((s) => s.trim()).filter(Boolean);
+    for (const mod of moduleList) {
+      // 格式：{port}-crm-{name}:{package}
+      const match = mod.match(/^(\d+)-crm-([^:]+):(.+)$/);
+      if (match) {
+        const [, port, name] = match;
+        const modPath = path.join(serviceDir, `${port}-crm-${name}`, 'service');
+        fs.mkdirSync(modPath, { recursive: true });
+        fs.writeFileSync(path.join(modPath, 'README.md'), generateServiceReadme(), 'utf8');
+      }
+    }
+  }
+
+  stage.fileCount = countFiles(serviceDir);
+  stage.status = action === 'recreate' ? 'recreated' : 'created';
+
+  const verb = action === 'recreate' ? '重新创建' : '创建';
+  logger(`✅ 阶段 4 完成：service 目录已${verb}`);
+
+  return stage;
+}
+
+/**
+ * 阶段 5: front-demo/ 前端演示项目（经典/完整/轻量模式）
+ */
+async function scaffoldFrontDemo(targetDir, pluginDir, frontDemoSource, decision, logger) {
+  const frontDemoDir = path.join(targetDir, 'front-demo');
+  const stage = { name: 'front-demo/', frontDemoSource };
+
+  if (decision === 'skip') {
+    logger(`⏭ 阶段 5 跳过：front-demo/ 已存在，保留现有内容`);
+    stage.status = 'skipped';
+    return stage;
+  }
+
+  const action = prepareDirByDecision(frontDemoDir, decision, logger, 'front-demo');
+
+  const result = copyDirFiltered(
+    path.join(pluginDir, 'references', frontDemoSource),
+    frontDemoDir
+  );
+
+  stage.fileCount = result.fileCount;
+  stage.skippedDirs = result.skippedDirs;
+  stage.status = action === 'recreate' ? 'recreated' : 'created';
+
+  const techName = frontDemoSource === 'antd-front-demo' ? 'Ant Design React' : 'Vue';
+  const verb = action === 'recreate' ? '重新复制' : '复制';
+  logger(`✅ 阶段 5 完成：front-demo/ 已${verb}（${techName}，${result.fileCount} 个文件）`);
+
+  return stage;
+}
+
+/**
+ * 阶段 6: .adspecs/ 配置与脚本目录
+ */
+async function scaffoldAdspecs(targetDir, pluginDir, decision, subDecisions, logger) {
+  const adspecsDir = path.join(targetDir, '.adspecs');
+  const stage = { name: '.adspecs/' };
+
+  if (decision === 'skip') {
+    logger(`⏭ 阶段 6 跳过：.adspecs/ 已存在，保留现有内容`);
+
+    // 子决策：templates
+    if (subDecisions.templates === 'update') {
+      copyDirFiltered(
+        path.join(pluginDir, '.adspecs/templates'),
+        path.join(adspecsDir, 'templates')
+      );
+      logger(`🔄 阶段 6 补充更新：.adspecs/templates/ 已从插件根目录更新`);
+      stage.subDecisions = { templates: 'update' };
+    }
+
+    // 属性补全（无论是否更新 templates 都执行）
+    const featureResult = mergeJsonFile(
+      path.join(adspecsDir, 'feature.json'),
+      path.join(pluginDir, '.adspecs/feature.json')
+    );
+    if (featureResult.addedKeys.length > 0) {
+      logger(`🔧 阶段 6 属性补全：feature.json 已补充缺失属性 [${featureResult.addedKeys.join(', ')}]`);
+      stage.featureResult = featureResult;
+    } else {
+      logger(`✅ 阶段 6：feature.json 属性完整，无需补全`);
+    }
+
+    stage.status = 'skipped';
+    return stage;
+  }
+
+  // recreate / update / create
+  let backupFeature = null;
+  let backupProject = null;
+
+  if (decision === 'recreate' && fs.existsSync(adspecsDir)) {
+    // 备份 feature.json / project.json
+    const featurePath = path.join(adspecsDir, 'feature.json');
+    const projectPath = path.join(adspecsDir, 'project.json');
+    if (fs.existsSync(featurePath)) backupFeature = fs.readFileSync(featurePath, 'utf8');
+    if (fs.existsSync(projectPath)) backupProject = fs.readFileSync(projectPath, 'utf8');
+    removeDir(adspecsDir);
+    logger(`🔄 删除旧 .adspecs/ 并重建...`);
+  } else if (decision === 'update') {
+    // update：保留目录，后续覆盖复制
+    fs.mkdirSync(adspecsDir, { recursive: true });
+  }
+
+  // 从插件根目录复制 .adspecs/
+  const result = copyDirFiltered(path.join(pluginDir, '.adspecs'), adspecsDir);
+  stage.fileCount = result.fileCount;
+
+  // recreate 场景：恢复备份并合并
+  if (decision === 'recreate' && (backupFeature || backupProject)) {
+    if (backupFeature) {
+      const featureResult = mergeJsonFile(
+        path.join(adspecsDir, 'feature.json'),
+        path.join(pluginDir, '.adspecs/feature.json')
+      );
+      stage.featureResult = featureResult;
+    }
+    stage.projectJsonBacked = !!backupProject;
+    logger(`🔧 feature.json/project.json 已恢复并补全属性`);
+  }
+
+  stage.status = decision === 'recreate' ? 'recreated' : 'created';
+  const verb = decision === 'recreate' ? '重新复制' : '复制';
+  logger(`✅ 阶段 6 完成：.adspecs/ 配置与脚本目录已${verb}（${result.fileCount} 个文件）`);
+
+  return stage;
+}
+
+/**
+ * 阶段 6.5: 生成 .adspecs/project.json
+ */
+function writeProjectJson(targetDir, pluginDir, values) {
+  const targetPath = path.join(targetDir, '.adspecs/project.json');
+  const referencePath = path.join(pluginDir, '.adspecs/project.json');
+  const created = !fs.existsSync(targetPath);
+
+  const merged = mergeProjectJson(
+    targetPath,
+    { ...values, created_at: new Date().toISOString().slice(0, 10) },
+    referencePath
+  );
+
+  return { created, merged };
+}
+
+/**
+ * 阶段 7: 生成 .adspecs/paths.json
+ */
+function writePathsJson(targetDir) {
+  const targetPath = path.join(targetDir, '.adspecs/paths.json');
+  const created = !fs.existsSync(targetPath);
+
+  if (created) {
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    const config = generatePathsConfig();
+    fs.writeFileSync(targetPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+  }
+
+  return { created };
+}
+
+/**
+ * 根据前端演示源解析前端规范目录名
+ */
+function resolveFrontendStandard(frontDemoSource) {
+  return frontDemoSource === 'antd-front-demo' ? 'ant6-front-standard' : 'ecp-front-standard';
+}
+
+module.exports = { scaffold };