birc-generator 0.5.5

package/plopfile.js

@@ -0,0 +1,1358 @@
+const fs = require('fs');
+const path = require('path');
+const { randomInt } = require('node:crypto');
+const VERSIONS = require('./versions');
+const { deriveBasePackage, projectConfigMissingMessage, toPascalCaseName, createDestConflict } = require('./bin/cli-util');
+
+// .env 的 DB 密碼用：6 碼小寫英文，隨機生成，避免 change_me 這種預設值。
+function randomDbPassword() {
+  const letters = 'abcdefghijklmnopqrstuvwxyz';
+  return Array.from({ length: 6 }, () => letters[randomInt(letters.length)]).join('');
+}
+
+function projectRoot() {
+  return process.env.BIRC_PROJECT_ROOT || process.cwd();
+}
+
+function projectConfigPath() {
+  return path.join(projectRoot(), '.bircrc.json');
+}
+
+function loadProjectConfig() {
+  const configPath = projectConfigPath();
+  if (!fs.existsSync(configPath)) {
+    throw new Error(projectConfigMissingMessage());
+  }
+  return JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+}
+
+function detectMultiModule(config) {
+  if (typeof config.multiModule === 'boolean') {
+    return config.multiModule;
+  }
+  if (config.daoPath && String(config.daoPath).includes('database-config')) {
+    return true;
+  }
+  const modulesDir = path.join(projectRoot(), 'modules');
+  if (!fs.existsSync(modulesDir)) {
+    return false;
+  }
+  return fs.readdirSync(modulesDir).some((name) => name.endsWith('-database-config'));
+}
+
+function inferProjectNameKebab(config) {
+  if (config.projectNameKebab) {
+    return config.projectNameKebab;
+  }
+  const modulesDir = path.join(projectRoot(), 'modules');
+  if (fs.existsSync(modulesDir)) {
+    const match = fs.readdirSync(modulesDir).find((name) => name.endsWith('-database-config'));
+    if (match) {
+      return match.replace(/-database-config$/, '');
+    }
+  }
+  return path.basename(projectRoot());
+}
+
+function persistenceLayout(basePackage, { multiModule, projectNameKebab, srcPath }) {
+  const basePackagePath = basePackage.replace(/\./g, '/');
+  const src = srcPath || 'src/main/java';
+  if (multiModule) {
+    const dbRoot = `modules/${projectNameKebab}-database-config/src/main/java/${basePackagePath}/databaseconfig`;
+    return {
+      entityPackage: `${basePackage}.databaseconfig.entity`,
+      daoPackage: `${basePackage}.databaseconfig.dao`,
+      entityRoot: `${dbRoot}/entity`,
+      daoRoot: `${dbRoot}/dao`
+    };
+  }
+  return {
+    entityPackage: `${basePackage}.entity`,
+    daoPackage: `${basePackage}.dao`,
+    entityRoot: `${src}/${basePackagePath}/entity`,
+    daoRoot: `${src}/${basePackagePath}/dao`
+  };
+}
+
+function resolvePersistence(config) {
+  if (config.entityPath && config.daoPath && config.entityPackage && config.daoPackage) {
+    return {
+      entityPackage: config.entityPackage,
+      daoPackage: config.daoPackage,
+      entityRoot: config.entityPath,
+      daoRoot: config.daoPath
+    };
+  }
+  return persistenceLayout(config.basePackage, {
+    multiModule: detectMultiModule(config),
+    projectNameKebab: inferProjectNameKebab(config),
+    srcPath: config.srcPath
+  });
+}
+
+function toKebab(name) {
+  return String(name || '')
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/[\s_]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .toLowerCase();
+}
+
+const JAVA_RESERVED_WORDS = new Set([
+  'abstract', 'assert', 'boolean', 'break', 'byte', 'case', 'catch', 'char', 'class',
+  'const', 'continue', 'default', 'do', 'double', 'else', 'enum', 'exports', 'extends',
+  'false', 'final', 'finally', 'float', 'for', 'goto', 'if', 'implements', 'import',
+  'instanceof', 'int', 'interface', 'long', 'module', 'native', 'new', 'non-sealed',
+  'null', 'open', 'opens', 'package', 'permits', 'private', 'protected', 'provides',
+  'public', 'record', 'requires', 'return', 'sealed', 'short', 'static', 'strictfp',
+  'super', 'switch', 'synchronized', 'this', 'throw', 'throws', 'to', 'transient',
+  'transitive', 'true', 'try', 'uses', 'var', 'void', 'volatile', 'while', 'with',
+  'yield', '_'
+]);
+
+const CREATE_DEFAULTS = Object.freeze({
+  projectName: 'Practice',
+  basePackage: 'tw.edu.ntub.birc.practice'
+});
+
+function validateProjectName(value) {
+  const projectName = toKebab(value);
+  if (!projectName) {
+    return '專案名稱轉成 kebab-case 後不可為空。';
+  }
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(projectName)) {
+    return '專案名稱只能包含英文字母、數字、空白、底線或連字號。';
+  }
+  return true;
+}
+
+function validateJavaPackage(value) {
+  const packageName = String(value || '').trim();
+  if (!packageName) {
+    return 'Base package 不可為空。';
+  }
+  const segments = packageName.split('.');
+  if (segments.some((segment) => !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(segment))) {
+    return 'Base package 的每一段都必須是合法 Java identifier。';
+  }
+  if (segments.some((segment) => JAVA_RESERVED_WORDS.has(segment))) {
+    return 'Base package 不可使用 Java 保留字。';
+  }
+  return true;
+}
+
+function validatePascalCase(value) {
+  return /^[A-Z][A-Za-z0-9]*$/.test(toPascalCaseName(value))
+    ? true
+    : '名稱必須是英文字母開頭，例如 Activity 或 activity。';
+}
+
+function validateMigrationName(value) {
+  const raw = String(value || '').trim();
+  if (!raw) return '遷移名稱不可為空。';
+  // 白名單擋掉 SQL 特殊字元與路徑字元：名稱會進 Flyway SQL 與檔名。
+  return /^[a-zA-Z0-9_]+$/.test(raw)
+    ? true
+    : '遷移名稱只能包含英文字母、數字和底線，例如 create_users_table。';
+}
+
+function parseFields(fields) {
+  if (!fields || !String(fields).trim()) {
+    return [];
+  }
+  return String(fields)
+    .split(',')
+    .map((f) => {
+      const [name, type] = f.split(':');
+      const fieldName = (name || '').trim();
+      return {
+        name: fieldName,
+        type: (type || 'String').trim(),
+        snakeName: fieldName
+          .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+          .replace(/[\s-]+/g, '_')
+          .toLowerCase()
+      };
+    })
+    .filter((f) => f.name);
+}
+
+function isExample(data) {
+  return Boolean(data && data.example) || process.env.BIRC_EXAMPLE === '1';
+}
+
+function includeMapperWithEntity(data) {
+  return Boolean(data && (data.dto || data.mapper))
+    || process.env.BIRC_MAKE_DTO === '1'
+    || process.env.BIRC_MAKE_MAPPER === '1';
+}
+
+function includeModelMigration(data) {
+  return Boolean(data && data.migration) || process.env.BIRC_MAKE_MIGRATION === '1';
+}
+
+function includeModelSeed(data) {
+  return Boolean(data && data.seed) || process.env.BIRC_MAKE_SEED === '1';
+}
+
+function includeModelController(data) {
+  return Boolean(data && data.controller) || process.env.BIRC_MAKE_CONTROLLER === '1';
+}
+
+function includeSoftDelete(data) {
+  return Boolean(data && data.softDelete) || process.env.BIRC_MAKE_SOFT_DELETE === '1';
+}
+
+function toSnakeCase(text) {
+  return String(text || '')
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .replace(/[\s-]+/g, '_')
+    .toLowerCase();
+}
+
+function tableNameFromEntity(entityName) {
+  return toSnakeCase(entityName);
+}
+
+function fieldImports(fields) {
+  const types = new Set((fields || []).map((field) => field.type));
+  const imports = [];
+  if (types.has('LocalDateTime')) imports.push('java.time.LocalDateTime');
+  if (types.has('LocalDate')) imports.push('java.time.LocalDate');
+  if (types.has('BigDecimal')) imports.push('java.math.BigDecimal');
+  return imports;
+}
+
+function resolveMakeFields(data) {
+  const fields = parseFields(data.fields || process.env.BIRC_MAKE_FIELDS);
+  if (fields.length > 0) {
+    return fields;
+  }
+  if (isExample(data)) {
+    return [{ name: 'name', type: 'String', snakeName: 'name' }];
+  }
+  return [];
+}
+
+// 最後防線：prompt 驗證被繞過時（CLI 直呼、程式化呼叫），輸出值也不得
+// 帶 SQL 特殊字元或路徑字元——tableName/columnName 進 Flyway SQL，
+// description 同時進檔名。
+function sanitizeMigrationToken(value) {
+  return String(value || '').replace(/[^a-zA-Z0-9_]/g, '');
+}
+
+function parseMigrationName(name) {
+  const raw = String(name || '').trim();
+  let match = raw.match(/^create_(.+)_table$/i);
+  if (match) {
+    return {
+      kind: 'create',
+      tableName: sanitizeMigrationToken(match[1]),
+      columnName: null,
+      description: sanitizeMigrationToken(raw) || 'migration'
+    };
+  }
+  match = raw.match(/^add_(.+)_to_(.+)_table$/i);
+  if (match) {
+    return {
+      kind: 'add',
+      columnName: sanitizeMigrationToken(match[1]),
+      tableName: sanitizeMigrationToken(match[2]),
+      description: sanitizeMigrationToken(raw) || 'migration'
+    };
+  }
+  match = raw.match(/^remove_(.+)_from_(.+)_table$/i);
+  if (match) {
+    return {
+      kind: 'remove',
+      columnName: sanitizeMigrationToken(match[1]),
+      tableName: sanitizeMigrationToken(match[2]),
+      description: sanitizeMigrationToken(raw) || 'migration'
+    };
+  }
+  const customDescription = sanitizeMigrationToken(raw);
+  return { kind: 'custom', tableName: null, columnName: null, description: customDescription || 'migration' };
+}
+
+function nextMigrationVersion(migrationDir) {
+  if (!fs.existsSync(migrationDir)) {
+    return 1;
+  }
+  const versions = fs
+    .readdirSync(migrationDir)
+    .filter((file) => file.startsWith('V') && file.endsWith('.sql'))
+    .map((file) => {
+      const match = file.match(/^V(\d+)__/);
+      return match ? parseInt(match[1], 10) : 0;
+    });
+  return versions.length ? Math.max(...versions) + 1 : 1;
+}
+
+function migrationTemplate(kind) {
+  if (kind === 'create') return 'templates/migration/create-table.hbs';
+  if (kind === 'add') return 'templates/migration/add-column.hbs';
+  if (kind === 'remove') return 'templates/migration/remove-column.hbs';
+  return 'templates/migration/custom.hbs';
+}
+
+function makeContext(data) {
+  if (data && data.entityName) {
+    data.entityName = toPascalCaseName(data.entityName);
+  }
+  const config = loadProjectConfig();
+  const persistence = resolvePersistence(config);
+  const basePackage = config.basePackage;
+  const srcPath = config.srcPath || 'src/main/java';
+  const root = `${srcPath}/${basePackage.replace(/\./g, '/')}`;
+  const fields = resolveMakeFields(data);
+  const example = isExample(data);
+  const extraImports = fieldImports(fields);
+  const entityImports = extraImports.includes('java.time.LocalDateTime') || !example
+    ? extraImports
+    : extraImports.concat('java.time.LocalDateTime');
+  return {
+    config,
+    persistence,
+    root,
+    gradlePath: config.buildGradlePath || 'build.gradle',
+    templateData: {
+      ...VERSIONS,
+      basePackage,
+      makeFields: fields,
+      extraImports,
+      entityImports,
+      withExample: example,
+      withSoftDelete: includeSoftDelete(data),
+      entityPackage: persistence.entityPackage,
+      daoPackage: persistence.daoPackage
+    }
+  };
+}
+
+function exceptionClassName(name) {
+  const base = toPascalCaseName(name);
+  return /Exception$/i.test(base) ? base.replace(/exception$/i, 'Exception') : `${base}Exception`;
+}
+
+function exceptionSkeletonActions(root, templateData) {
+  return [
+    { type: 'add', path: `${root}/exception/ProjectException.java`, templateFile: 'templates/exception/ProjectException.hbs', data: templateData },
+    { type: 'add', path: `${root}/exception/NotFoundException.java`, templateFile: 'templates/exception/NotFoundException.hbs', data: templateData },
+    { type: 'add', path: `${root}/controller/ExceptionHandleController.java`, templateFile: 'templates/exception/ExceptionHandleController.hbs', data: templateData },
+    { type: 'add', path: `${root}/web/Result.java`, templateFile: 'templates/base/Result.hbs', data: templateData }
+  ];
+}
+
+function serviceSkeletonActions(root, templateData) {
+  return [
+    { type: 'add', path: `${root}/mapper/EntityMapper.java`, templateFile: 'templates/base/EntityMapper.hbs', data: templateData },
+    { type: 'add', path: `${root}/service/BaseService.java`, templateFile: 'templates/base/BaseService.hbs', data: templateData },
+    { type: 'add', path: `${root}/service/impl/BaseServiceImpl.java`, templateFile: 'templates/base/BaseServiceImpl.hbs', data: templateData }
+  ];
+}
+
+function uniqueFeatureKeys(features) {
+  return [...new Set((features || []).filter((featureKey) => FEATURES[featureKey]))];
+}
+
+const YML_ANCHOR = '# birc-generator:config-anchor';
+const GRADLE_ANCHOR = '// birc-generator:dependency-anchor';
+const GRADLE_PLUGIN_ANCHOR = '// birc-generator:plugin-anchor';
+const GRADLE_ALLPROJECTS_ANCHOR = '// birc-generator:allprojects-anchor';
+
+function requireGradleAnchor(errors, featureKey, destBase, gradlePath, anchor) {
+  const target = path.resolve(destBase, gradlePath);
+  if (!fs.existsSync(target)) {
+    errors.push(`${featureKey}: 找不到 ${gradlePath}`);
+  } else if (!fs.readFileSync(target, 'utf8').includes(anchor)) {
+    errors.push(`${featureKey}: ${gradlePath} 沒有 ${anchor}`);
+  }
+}
+
+function gradleAnchorPattern(anchor) {
+  return new RegExp(`${anchor.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\n`);
+}
+
+function isAddForce(data) {
+  return Boolean(data && data.force) || process.env.BIRC_ADD_FORCE === '1';
+}
+
+function isAddSync(data) {
+  return Boolean(data && data.sync) || process.env.BIRC_ADD_SYNC === '1';
+}
+
+function preflightAdd(featureKeys, { destBase, ymlPath, gradlePath }) {
+  const errors = [];
+  for (const featureKey of featureKeys) {
+    const feature = FEATURES[featureKey];
+    if (feature.ymlBlock) {
+      const target = path.resolve(destBase, ymlPath);
+      if (!fs.existsSync(target)) {
+        errors.push(`${featureKey}: 找不到 ${ymlPath}`);
+      } else if (!fs.readFileSync(target, 'utf8').includes(YML_ANCHOR)) {
+        errors.push(`${featureKey}: ${ymlPath} 沒有 ${YML_ANCHOR}`);
+      }
+    }
+    if (feature.gradleDep) {
+      requireGradleAnchor(errors, featureKey, destBase, gradlePath, GRADLE_ANCHOR);
+    }
+    if (feature.gradlePlugin) {
+      requireGradleAnchor(errors, featureKey, destBase, gradlePath, GRADLE_PLUGIN_ANCHOR);
+    }
+    if (feature.gradleAllprojects) {
+      requireGradleAnchor(errors, featureKey, destBase, gradlePath, GRADLE_ALLPROJECTS_ANCHOR);
+    }
+  }
+  if (errors.length > 0) {
+    throw new Error(`add 預檢查失敗，沒有寫任何檔：\n${errors.map((line) => `  ${line}`).join('\n')}`);
+  }
+}
+
+function buildAddActions(data) {
+  const force = isAddForce(data);
+  const syncAll = isAddSync(data);
+  const config = loadProjectConfig();
+  const installed = new Set(config.features || []);
+  const selected = syncAll
+    ? uniqueFeatureKeys(config.features)
+    : uniqueFeatureKeys(data.features);
+  const featuresToAdd = selected.filter((featureKey) => force || syncAll || !installed.has(featureKey));
+  if (featuresToAdd.length === 0) {
+    return [];
+  }
+
+  const basePackage = config.basePackage;
+  const basePackagePath = basePackage.replace(/\./g, '/');
+  const srcPath = config.srcPath || 'src/main/java';
+  const resourcesPath = config.resourcesPath || 'src/main/resources';
+  const ymlPath = config.applicationYmlPath || `${resourcesPath}/application.yml`;
+  const gradlePath = config.buildGradlePath || 'build.gradle';
+  const root = `${srcPath}/${basePackagePath}`;
+  const destBase = projectRoot();
+
+  preflightAdd(featuresToAdd, { destBase, ymlPath, gradlePath });
+
+  const templateData = {
+    ...VERSIONS,
+    basePackage,
+    projectName: config.projectNameKebab || inferProjectNameKebab(config),
+    projectNameKebab: config.projectNameKebab || inferProjectNameKebab(config),
+    gitlabProjectPath: data.gitlabProjectPath || '',
+    dbRootPassword: randomDbPassword(),
+    dbPassword: randomDbPassword()
+  };
+
+  let actions = [];
+  for (const featureKey of featuresToAdd) {
+    const reinstall = installed.has(featureKey);
+    actions = actions.concat(
+      featureActions(featureKey, {
+        root,
+        resourcesRoot: resourcesPath,
+        projectRoot: '.',
+        ymlPath,
+        gradlePath,
+        templateData,
+        overwriteFiles: force || syncAll,
+        skipConfigFragments: reinstall && (force || syncAll)
+      })
+    );
+  }
+
+  actions.push({ type: 'updateProjectFeatures', features: featuresToAdd });
+  return actions;
+}
+
+// 每個 feature 對應：要加哪些檔案、要往 application.yml / build.gradle 的哪個 anchor 插入什麼
+const FEATURES = {
+  email: {
+    label: 'Email（JavaMailSender + Thymeleaf 模板）',
+    files: [
+      { templateFile: 'templates/email/EmailService.hbs', dest: 'service/EmailService.java' },
+      { templateFile: 'templates/email/EmailServiceImpl.hbs', dest: 'service/impl/EmailServiceImpl.java' },
+      { templateFile: 'templates/email/EmailAsyncConfig.hbs', dest: 'config/EmailAsyncConfig.java' }
+    ],
+    resourceFiles: [
+      { templateFile: 'templates/email/sample-template.hbs', dest: 'email/sample.html' }
+    ],
+    ymlBlock: 'templates/email/application-yml-block.hbs',
+    gradleDep: 'templates/email/build-gradle-dep.hbs'
+  },
+  sso: {
+    label: 'SSO（校內單一登入，SsoProperties + AutoConfiguration 原始碼）',
+    files: [
+      { templateFile: 'templates/sso/SsoProperties.hbs', dest: 'security/SsoProperties.java' },
+      { templateFile: 'templates/sso/SsoAutoConfiguration.hbs', dest: 'config/SsoAutoConfiguration.java' }
+    ],
+    resourceFiles: [],
+    ymlBlock: 'templates/sso/application-yml-block.hbs',
+    gradleDep: null
+  },
+  oauth: {
+    label: 'OAuth2 登入（預設範例接 Google，其他 provider 自行調整）',
+    files: [
+      { templateFile: 'templates/oauth/OAuth2LoginSuccessHandler.hbs', dest: 'config/OAuth2LoginSuccessHandler.java' }
+    ],
+    resourceFiles: [],
+    ymlBlock: 'templates/oauth/application-yml-block.hbs',
+    gradleDep: 'templates/oauth/build-gradle-dep.hbs'
+  },
+  scheduling: {
+    label: '排程（Scheduling Tasks，@EnableScheduling + 範例 Job）',
+    files: [
+      { templateFile: 'templates/scheduling/SchedulingConfig.hbs', dest: 'config/SchedulingConfig.java' },
+      { templateFile: 'templates/scheduling/SampleSchedule.hbs', dest: 'schedule/SampleSchedule.java' }
+    ],
+    resourceFiles: [],
+    ymlBlock: 'templates/scheduling/application-yml-block.hbs',
+    gradleDep: null
+  },
+  aop: {
+    label: 'AOP 事件記錄（自訂 @OperationLog 註解 + Aspect）',
+    files: [
+      { templateFile: 'templates/aop/OperationLog.hbs', dest: 'annotation/OperationLog.java' },
+      { templateFile: 'templates/aop/OperationLogAspect.hbs', dest: 'aspect/OperationLogAspect.java' }
+    ],
+    resourceFiles: [],
+    ymlBlock: null,
+    gradleDep: 'templates/aop/build-gradle-dep.hbs'
+  },
+  client: {
+    label: 'Client（呼叫外部 API 的 RestClient 封裝）',
+    files: [
+      { templateFile: 'templates/client/ExternalApiProperties.hbs', dest: 'config/ExternalApiProperties.java' },
+      { templateFile: 'templates/client/ExternalApiClientConfig.hbs', dest: 'config/ExternalApiClientConfig.java' },
+      { templateFile: 'templates/client/ExternalApiClient.hbs', dest: 'client/ExternalApiClient.java' }
+    ],
+    resourceFiles: [],
+    ymlBlock: 'templates/client/application-yml-block.hbs',
+    gradleDep: null
+  },
+  sentry: {
+    label: 'Sentry（錯誤追蹤 + 客戶端例外過濾）',
+    files: [
+      { templateFile: 'templates/sentry/SentryConfig.hbs', dest: 'config/SentryConfig.java' }
+    ],
+    resourceFiles: [],
+    ymlBlock: 'templates/sentry/application-yml-block.hbs',
+    gradleDep: 'templates/sentry/build-gradle-dep.hbs'
+  },
+  log4j2: {
+    label: 'Log4j2（主控台 + rolling file + MDC）',
+    files: [],
+    resourceFiles: [
+      { templateFile: 'templates/log4j2/log4j2-spring.xml.hbs', dest: 'log4j2-spring.xml' }
+    ],
+    ymlBlock: null,
+    gradleDep: 'templates/log4j2/build-gradle-dep.hbs'
+  },
+  openapi: {
+    label: 'OpenAPI（springdoc + Swagger UI + Bearer JWT）',
+    files: [
+      { templateFile: 'templates/openapi/OpenApiConfig.hbs', dest: 'config/OpenApiConfig.java' }
+    ],
+    resourceFiles: [],
+    ymlBlock: null,
+    gradleDep: 'templates/openapi/build-gradle-dep.hbs'
+  },
+  fileUpload: {
+    label: '檔案上傳（本機磁碟儲存，可自行改接 S3 / MinIO）',
+    files: [
+      { templateFile: 'templates/file-upload/FileStorageProperties.hbs', dest: 'config/FileStorageProperties.java' },
+      { templateFile: 'templates/file-upload/FileStorageService.hbs', dest: 'service/FileStorageService.java' },
+      { templateFile: 'templates/file-upload/FileStorageServiceImpl.hbs', dest: 'service/impl/FileStorageServiceImpl.java' },
+      { templateFile: 'templates/file-upload/FileUploadController.hbs', dest: 'controller/FileUploadController.java' },
+      { templateFile: 'templates/file-upload/FileUtils.hbs', dest: 'util/file/FileUtils.java' },
+      { templateFile: 'templates/file-upload/FileExtensionUtils.hbs', dest: 'util/file/FileExtensionUtils.java' },
+      { templateFile: 'templates/file-upload/EmptyFileException.hbs', dest: 'exception/file/EmptyFileException.java' },
+      { templateFile: 'templates/file-upload/FileExtensionIllegalException.hbs', dest: 'exception/file/FileExtensionIllegalException.java' },
+      { templateFile: 'templates/file-upload/InvalidStoredFileException.hbs', dest: 'exception/file/InvalidStoredFileException.java' },
+      { templateFile: 'templates/file-upload/FileTooLargeException.hbs', dest: 'exception/file/FileTooLargeException.java' }
+    ],
+    resourceFiles: [],
+    ymlBlock: 'templates/file-upload/application-yml-block.hbs',
+    gradleDep: null
+  },
+  pagination: {
+    label: '分頁查詢（Specification 動態條件 + PageRequest/PageResponse）',
+    files: [
+      { templateFile: 'templates/pagination/SearchCriteria.hbs', dest: 'specification/SearchCriteria.java' },
+      { templateFile: 'templates/pagination/GenericSpecification.hbs', dest: 'specification/GenericSpecification.java' },
+      { templateFile: 'templates/pagination/SpecificationSupport.hbs', dest: 'specification/SpecificationSupport.java' },
+      { templateFile: 'templates/pagination/PageRequest.hbs', dest: 'dto/PageRequest.java' },
+      { templateFile: 'templates/pagination/PageResponse.hbs', dest: 'dto/PageResponse.java' },
+      { templateFile: 'templates/pagination/Pager.hbs', dest: 'dto/Pager.java' },
+      { templateFile: 'templates/pagination/PageInfo.hbs', dest: 'dto/PageInfo.java' }
+    ],
+    resourceFiles: [],
+    ymlBlock: null,
+    gradleDep: null
+  },
+  validGroup: {
+    label: '驗證群組（ValidGroup：Create / Update / Delete / Submit）',
+    files: [
+      { templateFile: 'templates/valid-group/ValidGroup.hbs', dest: 'validation/ValidGroup.java' }
+    ],
+    resourceFiles: [],
+    ymlBlock: null,
+    gradleDep: null
+  },
+  permission: {
+    label: '權限控管（Spring Security + 自訂 @RequirePermission）',
+    files: [
+      { templateFile: 'templates/permission/RequirePermission.hbs', dest: 'annotation/RequirePermission.java' },
+      { templateFile: 'templates/permission/PermissionAspect.hbs', dest: 'aspect/PermissionAspect.java' }
+    ],
+    resourceFiles: [],
+    ymlBlock: null,
+    gradleDep: 'templates/permission/build-gradle-dep.hbs'
+  },
+  gitlabCi: {
+    label: '.gitlab-ci.yml（Harbor build/push + SSH deploy，對齊 teaching-platform）',
+    files: [],
+    resourceFiles: [],
+    rootFiles: [
+      { templateFile: 'templates/gitlab-ci/gitlab-ci.hbs', dest: '.gitlab-ci.yml' }
+    ],
+    ymlBlock: null,
+    gradleDep: null
+  },
+  docker: {
+    label: 'Docker（多階段 Dockerfile + compose + .env.example）',
+    files: [],
+    resourceFiles: [],
+    rootFiles: [
+      { templateFile: 'templates/docker/Dockerfile.hbs', dest: 'Dockerfile' },
+      { templateFile: 'templates/docker/docker-compose.yml.hbs', dest: 'docker-compose.yml' },
+      { templateFile: 'templates/docker/docker-compose.prod.yml.hbs', dest: 'docker-compose.prod.yml' },
+      { templateFile: 'templates/docker/env.example.hbs', dest: '.env.example' },
+      { templateFile: 'templates/docker/dockerignore.hbs', dest: '.dockerignore' }
+    ],
+    ymlBlock: null,
+    gradleDep: null
+  },
+  spotless: {
+    label: 'Spotless（Eclipse 4.31 格式化，commit 前 ./gradlew spotlessApply）',
+    files: [],
+    resourceFiles: [],
+    rootFiles: [
+      { templateFile: 'templates/spotless/spotless_formatter.xml', dest: 'spotless_formatter.xml' }
+    ],
+    ymlBlock: null,
+    gradleDep: null,
+    gradlePlugin: 'templates/spotless/build-gradle-plugin.hbs',
+    gradleAllprojects: 'templates/spotless/build-gradle-allprojects.hbs'
+  }
+};
+
+const FEATURE_GROUPS = [
+  {
+    title: '常用',
+    keys: ['docker', 'log4j2', 'openapi', 'spotless', 'validGroup', 'pagination', 'fileUpload', 'email', 'client', 'aop']
+  },
+  { title: '登入', keys: ['sso', 'oauth', 'permission'] },
+  { title: '營運', keys: ['gitlabCi', 'sentry', 'scheduling'] }
+];
+const DEFAULT_FEATURES = new Set(['docker', 'log4j2', 'validGroup', 'spotless']);
+
+function groupedFeatureChoices({
+  installed = new Set(),
+  allowInstalled = false,
+  withDefaults = false
+} = {}) {
+  const used = new Set();
+  const choices = [];
+  for (const group of FEATURE_GROUPS) {
+    const keys = group.keys.filter((key) => FEATURES[key]);
+    if (keys.length === 0) continue;
+    choices.push({ type: 'separator', line: `── ${group.title} ──` });
+    for (const key of keys) {
+      used.add(key);
+      choices.push({
+        name: FEATURES[key].label,
+        value: key,
+        checked: withDefaults && DEFAULT_FEATURES.has(key),
+        disabled: !allowInstalled && installed.has(key) ? '已安裝' : false
+      });
+    }
+  }
+  const leftover = Object.keys(FEATURES).filter((key) => !used.has(key));
+  if (leftover.length > 0) {
+    choices.push({ type: 'separator', line: '── 其他 ──' });
+    for (const key of leftover) {
+      choices.push({
+        name: FEATURES[key].label,
+        value: key,
+        checked: withDefaults && DEFAULT_FEATURES.has(key),
+        disabled: !allowInstalled && installed.has(key) ? '已安裝' : false
+      });
+    }
+  }
+  return choices;
+}
+
+// 產生單一 feature 的 plop actions。root / resourcesRoot / ymlPath / gradlePath 都是絕對相對於
+// plop destBasePath 的路徑，create 跟 add 共用同一份邏輯，差別只在 root 前面有沒有專案資料夾。
+function featureActions(featureKey, {
+  root,
+  resourcesRoot,
+  projectRoot,
+  ymlPath,
+  gradlePath,
+  templateData,
+  overwriteFiles = false,
+  skipConfigFragments = false
+}) {
+  const feature = FEATURES[featureKey];
+  if (!feature) {
+    throw new Error(`未知的 feature: ${featureKey}`);
+  }
+  const actions = [];
+
+  for (const f of feature.files) {
+    actions.push({
+      type: 'add',
+      path: `${root}/${f.dest}`,
+      templateFile: f.templateFile,
+      data: templateData,
+      skipIfExists: !overwriteFiles,
+      abortOnFail: true
+    });
+  }
+
+  for (const f of feature.resourceFiles) {
+    actions.push({
+      type: 'add',
+      path: `${resourcesRoot}/${f.dest}`,
+      templateFile: f.templateFile,
+      data: templateData,
+      skipIfExists: !overwriteFiles,
+      abortOnFail: true
+    });
+  }
+
+  // rootFiles：不屬於任何 package、也不進 resources 的檔案（.gitlab-ci.yml、Dockerfile 之類），
+  // 直接放到專案根目錄（create 是新資料夾根目錄，add 是目前目錄）。
+  if (feature.rootFiles) {
+    for (const f of feature.rootFiles) {
+      actions.push({
+        type: 'add',
+        path: `${projectRoot}/${f.dest}`,
+        templateFile: f.templateFile,
+        data: templateData,
+        skipIfExists: !overwriteFiles,
+        abortOnFail: true
+      });
+    }
+  }
+
+  if (feature.ymlBlock && !skipConfigFragments) {
+    actions.push({
+      type: 'appendFragment',
+      path: ymlPath,
+      pattern: new RegExp(`${YML_ANCHOR.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\n`),
+      templateFile: feature.ymlBlock,
+      data: templateData,
+      abortOnFail: true
+    });
+  }
+
+  const gradleFragments = [
+    [feature.gradleDep, GRADLE_ANCHOR],
+    [feature.gradlePlugin, GRADLE_PLUGIN_ANCHOR],
+    [feature.gradleAllprojects, GRADLE_ALLPROJECTS_ANCHOR]
+  ];
+  for (const [templateFile, anchor] of gradleFragments) {
+    if (templateFile && !skipConfigFragments) {
+      actions.push({
+        type: 'appendFragment',
+        path: gradlePath,
+        pattern: gradleAnchorPattern(anchor),
+        templateFile,
+        data: templateData,
+        abortOnFail: true
+      });
+    }
+  }
+
+  return actions;
+}
+
+module.exports = function (plop) {
+  plop.setHelper('pascalCase', (text) => text.charAt(0).toUpperCase() + text.slice(1));
+  plop.setHelper('camelCase', (text) => text.charAt(0).toLowerCase() + text.slice(1));
+  plop.setHelper('lowerCase', (text) => text.toLowerCase());
+  plop.setHelper('dashCase', (text) =>
+    text.replace(/([a-z0-9])([A-Z])/g, '$1-$2').replace(/[\s_]+/g, '-').toLowerCase()
+  );
+  plop.setHelper('snakeCase', toSnakeCase);
+
+  plop.setActionType('copyFile', function (answers, config, plopApi) {
+    const from = path.isAbsolute(config.from) ? config.from : path.join(__dirname, config.from);
+    const to = path.resolve(plopApi.getDestBasePath(), plopApi.renderString(config.path, answers));
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    fs.copyFileSync(from, to);
+    if (config.executable) {
+      fs.chmodSync(to, 0o755);
+    }
+    return path.relative(plopApi.getDestBasePath(), to);
+  });
+
+  plop.setActionType('assertCreateDestFree', function (answers, _config, plopApi) {
+    const error = createDestConflict({
+      cwd: plopApi.getDestBasePath(),
+      projectName: answers.projectName
+    });
+    if (error) {
+      throw new Error(error);
+    }
+    return 'dest 可用';
+  });
+
+  plop.setActionType('copyIfExists', function (answers, config, plopApi) {
+    const destBase = plopApi.getDestBasePath();
+    const from = path.resolve(destBase, plopApi.renderString(config.from, answers));
+    const to = path.resolve(destBase, plopApi.renderString(config.path, answers));
+    if (!fs.existsSync(from)) {
+      return `skipped (missing ${path.relative(destBase, from)})`;
+    }
+    fs.copyFileSync(from, to);
+    return path.relative(destBase, to);
+  });
+
+  plop.setActionType('appendFragment', function (answers, config, plopApi) {
+    const destBase = plopApi.getDestBasePath();
+    const target = path.resolve(destBase, plopApi.renderString(config.path, answers));
+    const templatePath = path.isAbsolute(config.templateFile)
+      ? config.templateFile
+      : path.join(__dirname, config.templateFile);
+    const templateData = { ...answers, ...(config.data || {}) };
+    const fragment = plopApi.renderString(fs.readFileSync(templatePath, 'utf8'), templateData).trim();
+    const contents = fs.readFileSync(target, 'utf8');
+
+    if (contents.includes(fragment)) {
+      return `skipped (already installed ${path.relative(destBase, target)})`;
+    }
+
+    const match = contents.match(config.pattern);
+    if (!match) {
+      throw new Error(`找不到插入 anchor：${path.relative(destBase, target)}`);
+    }
+
+    const next = contents.replace(config.pattern, (anchor) => `${anchor}\n${fragment}\n`);
+    fs.writeFileSync(target, next);
+    return path.relative(destBase, target);
+  });
+
+  plop.setActionType('updateProjectFeatures', function (answers, config, plopApi) {
+    const destBase = plopApi.getDestBasePath();
+    const target = path.resolve(destBase, '.bircrc.json');
+    const projectConfig = JSON.parse(fs.readFileSync(target, 'utf8'));
+    const features = [...new Set([...(projectConfig.features || []), ...(config.features || [])])];
+
+    if (JSON.stringify(features) === JSON.stringify(projectConfig.features || [])) {
+      return 'skipped (.bircrc.json 已是最新)';
+    }
+
+    projectConfig.features = features;
+    fs.writeFileSync(target, `${JSON.stringify(projectConfig, null, 2)}\n`);
+    return '.bircrc.json';
+  });
+
+  const entityNamePrompt = {
+    type: 'input',
+    name: 'entityName',
+    message: '名稱（例如 Activity 或 activity）：',
+    filter: toPascalCaseName,
+    validate: validatePascalCase
+  };
+  const fieldsPrompt = {
+    type: 'input',
+    name: 'fields',
+    message: '欄位定義，用逗號分隔，格式 name:type（例如 title:String,startTime:LocalDateTime）：',
+    when: (answers) => isExample(answers)
+      && !String((answers && answers.fields) || process.env.BIRC_MAKE_FIELDS || '').trim()
+  };
+
+  function makeEntityActions(data) {
+    const { persistence, templateData } = makeContext(data);
+    return [
+      { type: 'add', path: `${persistence.entityRoot}/{{pascalCase entityName}}.java`, templateFile: 'templates/entity.hbs', data: templateData },
+      { type: 'add', path: `${persistence.daoRoot}/{{pascalCase entityName}}DAO.java`, templateFile: 'templates/dao.hbs', data: templateData }
+    ];
+  }
+
+  function makeMapperActions(data) {
+    const { root, gradlePath, templateData } = makeContext(data);
+    return [
+      { type: 'add', path: `${root}/dto/{{pascalCase entityName}}CreateRequest.java`, templateFile: 'templates/dto-request.hbs', data: templateData },
+      { type: 'add', path: `${root}/dto/{{pascalCase entityName}}Response.java`, templateFile: 'templates/dto-response.hbs', data: templateData },
+      { type: 'add', path: `${root}/mapper/{{pascalCase entityName}}Mapper.java`, templateFile: 'templates/mapper.hbs', data: templateData },
+      {
+        type: 'appendFragment',
+        path: gradlePath,
+        pattern: /\/\/ birc-generator:dependency-anchor\n/,
+        templateFile: 'templates/mapper-gradle-dep.hbs',
+        data: templateData,
+        abortOnFail: true
+      }
+    ];
+  }
+
+  function makeServiceActions(data) {
+    const { root, templateData } = makeContext(data);
+    return [
+      { type: 'add', path: `${root}/service/{{pascalCase entityName}}Service.java`, templateFile: 'templates/service.hbs', data: templateData },
+      { type: 'add', path: `${root}/service/impl/{{pascalCase entityName}}ServiceImpl.java`, templateFile: 'templates/serviceImpl.hbs', data: templateData }
+    ];
+  }
+
+  function makeControllerActions(data) {
+    const { root, templateData } = makeContext(data);
+    return [
+      {
+        type: 'add',
+        path: `${root}/web/Result.java`,
+        templateFile: 'templates/base/Result.hbs',
+        data: templateData,
+        skipIfExists: true
+      },
+      { type: 'add', path: `${root}/controller/{{pascalCase entityName}}Controller.java`, templateFile: 'templates/controller.hbs', data: templateData }
+    ];
+  }
+
+  function makeStackActions(data) {
+    return [
+      ...makeEntityActions(data),
+      ...makeMapperActions(data),
+      ...makeServiceActions(data),
+      ...makeControllerActions(data)
+    ];
+  }
+
+  plop.setGenerator('make', {
+    description: '一次產生 Entity + DAO + Mapper + DTO + Service + Controller',
+    prompts: [entityNamePrompt, fieldsPrompt],
+    actions: makeStackActions
+  });
+
+  plop.setGenerator('make:entity', {
+    description: '產生 Entity 與 DAO；--dto / --mapper 加 DTO，--soft-delete 加軟刪',
+    prompts: [entityNamePrompt, fieldsPrompt],
+    actions(data) {
+      const actions = makeEntityActions(data);
+      if (includeMapperWithEntity(data)) {
+        return actions.concat(makeMapperActions(data));
+      }
+      return actions;
+    }
+  });
+
+  plop.setGenerator('make:model', {
+    description: '產生 Entity 與 DAO；--migration / --seed / --controller / --soft-delete',
+    prompts: [entityNamePrompt, fieldsPrompt],
+    actions: makeModelActions
+  });
+
+  plop.setGenerator('make:mapper', {
+    description: '產生 MapStruct Mapper 與對應的 Request / Response DTO',
+    prompts: [entityNamePrompt, fieldsPrompt],
+    actions: makeMapperActions
+  });
+
+  plop.setGenerator('make:service', {
+    description: '產生 XxxService（extends BaseService）與 ServiceImpl',
+    prompts: [entityNamePrompt],
+    actions: makeServiceActions
+  });
+
+  plop.setGenerator('make:controller', {
+    description: '產生 Controller',
+    prompts: [entityNamePrompt],
+    actions: makeControllerActions
+  });
+
+  plop.setGenerator('make:exception', {
+    description: '產生繼承 ProjectException 的例外類別',
+    prompts: [
+      {
+        type: 'input',
+        name: 'exceptionName',
+        message: '例外名稱（例如 DuplicateRegistration 或 NotFoundException）：',
+        filter: toPascalCaseName,
+        validate: validatePascalCase
+      },
+      { type: 'input', name: 'defaultMessage', message: '預設訊息：', default: '發生錯誤' },
+      {
+        type: 'list',
+        name: 'httpStatus',
+        message: 'HTTP status：',
+        choices: ['BAD_REQUEST', 'NOT_FOUND', 'UNAUTHORIZED', 'FORBIDDEN', 'CONFLICT', 'INTERNAL_SERVER_ERROR']
+      }
+    ],
+    actions: function (data) {
+      const { root, templateData } = makeContext(data);
+      const exceptionClass = exceptionClassName(data.exceptionName);
+      const errorCode = exceptionClass.replace(/Exception$/, '');
+      return [
+        {
+          type: 'add',
+          path: `${root}/exception/ProjectException.java`,
+          templateFile: 'templates/exception/ProjectException.hbs',
+          data: templateData,
+          skipIfExists: true
+        },
+        {
+          type: 'add',
+          path: `${root}/controller/ExceptionHandleController.java`,
+          templateFile: 'templates/exception/ExceptionHandleController.hbs',
+          data: templateData,
+          skipIfExists: true
+        },
+        {
+          type: 'add',
+          path: `${root}/web/Result.java`,
+          templateFile: 'templates/base/Result.hbs',
+          data: templateData,
+          skipIfExists: true
+        },
+        {
+          type: 'add',
+          path: `${root}/exception/${exceptionClass}.java`,
+          templateFile: 'templates/exception.hbs',
+          data: {
+            ...templateData,
+            exceptionClass,
+            defaultMessage: data.defaultMessage,
+            errorCode,
+            httpStatus: data.httpStatus,
+            withExample: isExample(data)
+          }
+        }
+      ];
+    }
+  });
+
+  // ---------- add：像 php artisan / ng add，往「既有專案」裡加一個功能模組 ----------
+  plop.setGenerator('add', {
+    description: '在既有專案中加入 email / sso / oauth 等功能模組（會改動 application.yml、build.gradle）',
+    prompts: [
+      {
+        type: 'checkbox',
+        name: 'features',
+        message: '要加入哪些功能？（space 選取，enter 確認，可複選）',
+        choices: () => {
+          const installed = new Set(loadProjectConfig().features || []);
+          return groupedFeatureChoices({
+            installed,
+            allowInstalled: isAddForce()
+          });
+        }
+      },
+      {
+        type: 'input',
+        name: 'gitlabProjectPath',
+        message: 'GitLab 專案路徑（CI 只在這個 repo 跑，例如 general-hospital/campus-activity-backend；可留空）：',
+        when: (answers) => (answers.features || []).includes('gitlabCi'),
+        default: ''
+      }
+    ],
+    actions: function (data) {
+      if (!isAddSync(data) && (!data.features || data.features.length === 0)) {
+        return [];
+      }
+      return buildAddActions(data);
+    }
+  });
+
+  plop.setGenerator('sync', {
+    description: '用目前 template 覆寫已安裝 feature 的檔（不動 application.yml / build.gradle）',
+    prompts: [],
+    actions: function (data) {
+      return buildAddActions({ ...data, force: true, sync: true });
+    }
+  });
+
+  // ---------- create：像 npm create vite@latest，從零建一個新專案資料夾 ----------
+  plop.setGenerator('create', {
+    description: '建立一個新的 BIRC Spring Boot 多模組專案（互動選擇要不要 email / sso / oauth）',
+    prompts: [
+      {
+        type: 'input',
+        name: 'projectName',
+        message: '專案名稱（會建立同名資料夾，例如 campus-activity）：',
+        default: CREATE_DEFAULTS.projectName,
+        validate: validateProjectName
+      },
+      {
+        type: 'input',
+        name: 'basePackage',
+        message: 'Base package（例如 tw.edu.ntub.birc.campus.activity）：',
+        default: (answers) => deriveBasePackage(answers.projectName) || CREATE_DEFAULTS.basePackage,
+        validate: validateJavaPackage
+      },
+      {
+        type: 'checkbox',
+        name: 'features',
+        message: '要內建哪些功能？（space 選取，enter 確認，之後也可以用 birc add 再加）',
+        choices: groupedFeatureChoices({ withDefaults: true })
+      },
+      {
+        type: 'input',
+        name: 'gitlabProjectPath',
+        message: 'GitLab 專案路徑（CI 只在這個 repo 跑，例如 general-hospital/campus-activity-backend；可留空）：',
+        when: (answers) => (answers.features || []).includes('gitlabCi'),
+        default: ''
+      },
+      {
+        type: 'confirm',
+        name: 'injectDocs',
+        message: '要注入 AGENTS.md / PROJECT.md / implement.md / test.md 嗎？（給 AI coding agent 讀）',
+        default: true
+      }
+    ],
+    actions: function (data) {
+      const projectDir = toKebab(data.projectName);
+      const basePackagePath = data.basePackage.replace(/\./g, '/');
+
+      const layout = persistenceLayout(data.basePackage, {
+        multiModule: true,
+        projectNameKebab: projectDir
+      });
+
+      const templateData = {
+        ...VERSIONS,
+        basePackage: data.basePackage,
+        projectName: data.projectName,
+        projectNameKebab: projectDir,
+        multiModule: true,
+        entityPackage: layout.entityPackage,
+        daoPackage: layout.daoPackage,
+        entityPath: layout.entityRoot,
+        daoPath: layout.daoRoot,
+        gitlabProjectPath: data.gitlabProjectPath || '',
+        dbRootPassword: randomDbPassword(),
+        dbPassword: randomDbPassword(),
+        hasDocker: (data.features || []).includes('docker')
+      };
+
+      const srcPath = 'src/main/java';
+      const testSrcPath = 'src/test/java';
+      const resourcesPath = 'src/main/resources';
+      const root = `${projectDir}/${srcPath}/${basePackagePath}`;
+      const testRoot = `${projectDir}/${testSrcPath}/${basePackagePath}`;
+      const resourcesRoot = `${projectDir}/${resourcesPath}`;
+      const ymlPath = `${resourcesRoot}/application.yml`;
+      const gradlePath = `${projectDir}/build.gradle`;
+
+      let actions = [
+        { type: 'assertCreateDestFree', abortOnFail: true },
+        { type: 'add', path: `${root}/Application.java`, templateFile: 'templates/base/Application.hbs', data: templateData },
+        { type: 'add', path: `${testRoot}/ApplicationTests.java`, templateFile: 'templates/base/ApplicationTests.java.hbs', data: templateData },
+        { type: 'add', path: `${projectDir}/src/test/resources/application.yml`, templateFile: 'templates/base/application-test.yml.hbs', data: templateData },
+        { type: 'add', path: gradlePath, templateFile: 'templates/multi-module/build.gradle.hbs', data: templateData },
+        { type: 'add', path: `${projectDir}/settings.gradle`, templateFile: 'templates/multi-module/settings.gradle.hbs', data: templateData },
+        { type: 'add', path: `${resourcesRoot}/application.yml`, templateFile: 'templates/base/application.yml.hbs', data: templateData },
+        { type: 'add', path: `${projectDir}/.gitignore`, templateFile: 'templates/base/gitignore.hbs', data: templateData },
+        { type: 'copyFile', from: 'templates/gradle-wrapper/gradlew', path: `${projectDir}/gradlew`, executable: true },
+        { type: 'copyFile', from: 'templates/gradle-wrapper/gradlew.bat', path: `${projectDir}/gradlew.bat` },
+        {
+          type: 'copyFile',
+          from: 'templates/gradle-wrapper/gradle/wrapper/gradle-wrapper.jar',
+          path: `${projectDir}/gradle/wrapper/gradle-wrapper.jar`
+        },
+        {
+          type: 'copyFile',
+          from: 'templates/gradle-wrapper/gradle/wrapper/gradle-wrapper.properties',
+          path: `${projectDir}/gradle/wrapper/gradle-wrapper.properties`
+        },
+        {
+          type: 'add',
+          path: `${projectDir}/.bircrc.json`,
+          templateFile: 'templates/base/bircrc.hbs',
+          data: { ...templateData, featuresJson: JSON.stringify(data.features) }
+        }
+      ];
+      actions = actions.concat(exceptionSkeletonActions(root, templateData));
+      actions = actions.concat(serviceSkeletonActions(root, templateData));
+
+      const configRoot = `${projectDir}/modules/${projectDir}-config/src/main/java/${basePackagePath}/config`;
+      actions.push(
+        { type: 'add', path: `${projectDir}/modules/${projectDir}-config/build.gradle`, templateFile: 'templates/multi-module/config/build.gradle.hbs', data: templateData },
+        { type: 'add', path: `${configRoot}/Config.java`, templateFile: 'templates/multi-module/config/Config.java.hbs', data: templateData },
+        { type: 'add', path: `${configRoot}/ApplicationConfig.java`, templateFile: 'templates/multi-module/config/ApplicationConfig.java.hbs', data: templateData },
+        { type: 'add', path: `${configRoot}/SecurityConfig.java`, templateFile: 'templates/multi-module/config/SecurityConfig.java.hbs', data: templateData }
+      );
+
+      const dbConfigRoot = `${projectDir}/modules/${projectDir}-database-config/src/main/java/${basePackagePath}/databaseconfig`;
+      actions.push(
+        { type: 'add', path: `${projectDir}/modules/${projectDir}-database-config/build.gradle`, templateFile: 'templates/multi-module/database-config/build.gradle.hbs', data: templateData },
+        { type: 'add', path: `${dbConfigRoot}/Config.java`, templateFile: 'templates/multi-module/database-config/Config.java.hbs', data: templateData },
+        { type: 'add', path: `${dbConfigRoot}/JpaConfig.java`, templateFile: 'templates/multi-module/database-config/JpaConfig.java.hbs', data: templateData },
+        { type: 'add', path: `${projectDir}/${layout.daoRoot}/BaseViewDAO.java`, templateFile: 'templates/multi-module/database-config/BaseViewDAO.java.hbs', data: templateData },
+        { type: 'add', path: `${projectDir}/${layout.daoRoot}/BaseDAO.java`, templateFile: 'templates/multi-module/database-config/BaseDAO.java.hbs', data: templateData }
+      );
+
+      for (const featureKey of data.features) {
+        actions = actions.concat(
+          featureActions(featureKey, {
+            root,
+            resourcesRoot,
+            projectRoot: projectDir,
+            ymlPath,
+            gradlePath,
+            templateData
+          })
+        );
+      }
+
+      actions.push({
+        type: 'add',
+        path: `${projectDir}/README.md`,
+        templateFile: 'templates/base/README.md.hbs',
+        data: templateData,
+        skipIfExists: true
+      });
+
+      if (data.injectDocs) {
+        actions.push(
+          { type: 'add', path: `${projectDir}/AGENTS.md`, templateFile: 'project-docs/AGENTS.md.hbs', data: templateData },
+          { type: 'add', path: `${projectDir}/PROJECT.md`, templateFile: 'project-docs/PROJECT.md.hbs', data: templateData },
+          { type: 'add', path: `${projectDir}/implement.md`, templateFile: 'project-docs/implement.hbs', data: templateData },
+          { type: 'add', path: `${projectDir}/test.md`, templateFile: 'project-docs/test.hbs', data: templateData }
+        );
+      }
+
+      if ((data.features || []).includes('docker')) {
+        actions.push({
+          type: 'copyIfExists',
+          from: `${projectDir}/.env.example`,
+          path: `${projectDir}/.env`
+        });
+      }
+
+      return actions;
+    }
+  });
+
+  // ---------- docs：給 AI coding agent 讀的目錄與規範 ----------
+  plop.setGenerator('docs', {
+    description: '產生 AGENTS.md / PROJECT.md / implement.md / test.md',
+    prompts: [],
+    actions: function () {
+      const config = loadProjectConfig();
+      const projectName = config.projectNameKebab || inferProjectNameKebab(config);
+      const templateData = { projectName, projectNameKebab: projectName };
+      return [
+        { type: 'add', path: 'AGENTS.md', templateFile: 'project-docs/AGENTS.md.hbs', data: templateData, skipIfExists: true },
+        { type: 'add', path: 'PROJECT.md', templateFile: 'project-docs/PROJECT.md.hbs', data: templateData, skipIfExists: true },
+        { type: 'add', path: 'implement.md', templateFile: 'project-docs/implement.hbs', data: templateData, skipIfExists: true },
+        { type: 'add', path: 'test.md', templateFile: 'project-docs/test.hbs', data: templateData, skipIfExists: true }
+      ];
+    }
+  });
+
+  function migrationDir(config) {
+    const resourcesPath = config.resourcesPath || 'src/main/resources';
+    return config.migrationPath || `${resourcesPath}/db/migration`;
+  }
+
+  function makeMigrationActions(data) {
+    const config = loadProjectConfig();
+    const migrationPath = migrationDir(config);
+    const parsed = parseMigrationName(data.description);
+    const version = data.migrationVersion || nextMigrationVersion(path.join(projectRoot(), migrationPath));
+    const example = isExample(data);
+    return [
+      {
+        type: 'add',
+        path: `${migrationPath}/V${version}__${parsed.description}.sql`,
+        templateFile: migrationTemplate(parsed.kind),
+        data: {
+          description: parsed.description,
+          tableName: parsed.tableName,
+          columnName: parsed.columnName,
+          withExample: example,
+          withSoftDelete: includeSoftDelete(data)
+        }
+      }
+    ];
+  }
+
+  function makeSeedActions(data) {
+    const config = loadProjectConfig();
+    const migrationPath = migrationDir(config);
+    const tableName = tableNameFromEntity(data.entityName);
+    const description = sanitizeMigrationToken(`seed_${tableName}`) || 'seed';
+    const version = data.migrationVersion || nextMigrationVersion(path.join(projectRoot(), migrationPath));
+    return [
+      {
+        type: 'add',
+        path: `${migrationPath}/V${version}__${description}.sql`,
+        templateFile: 'templates/migration/seed.hbs',
+        data: {
+          description,
+          tableName,
+          withExample: isExample(data)
+        }
+      }
+    ];
+  }
+
+  function makeModelActions(data) {
+    const actions = makeEntityActions(data);
+    if (includeMapperWithEntity(data)) {
+      actions.push(...makeMapperActions(data));
+    }
+    const config = loadProjectConfig();
+    const migrationPath = migrationDir(config);
+    let version = nextMigrationVersion(path.join(projectRoot(), migrationPath));
+    if (includeModelMigration(data)) {
+      const tableName = tableNameFromEntity(data.entityName);
+      actions.push(
+        ...makeMigrationActions({
+          ...data,
+          description: `create_${tableName}_table`,
+          migrationVersion: version
+        })
+      );
+      version += 1;
+    }
+    if (includeModelSeed(data)) {
+      actions.push(...makeSeedActions({ ...data, migrationVersion: version }));
+    }
+    if (includeModelController(data)) {
+      actions.push(...makeControllerActions(data));
+    }
+    return actions;
+  }
+
+  const migrationPrompts = [
+    {
+      type: 'input',
+      name: 'description',
+      message: '遷移名稱（例如 create_users_table、add_votes_to_users_table）：',
+      validate: validateMigrationName
+    }
+  ];
+
+  plop.setGenerator('make:migration', {
+    description: '新增 Flyway 遷移（Laravel 風格名稱，例如 create_users_table）',
+    prompts: migrationPrompts,
+    actions: makeMigrationActions
+  });
+
+  plop.setGenerator('migration', {
+    description: 'make:migration 的別名',
+    prompts: migrationPrompts,
+    actions: makeMigrationActions
+  });
+};
+
+module.exports.FEATURES = FEATURES;
+module.exports.CREATE_DEFAULTS = CREATE_DEFAULTS;
+module.exports.DEFAULT_FEATURES = DEFAULT_FEATURES;
+module.exports.FEATURE_GROUPS = FEATURE_GROUPS;
+module.exports.groupedFeatureChoices = groupedFeatureChoices;
+module.exports.validateMigrationName = validateMigrationName;
+module.exports.parseMigrationName = parseMigrationName;