birc-generator 0.9.0 → 1.0.0

package/plopfile.js

@@ -1,1056 +1,46 @@
 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 密碼用：16 碼混合大小寫英文 + 數字，隨機生成，避免 change_me 這種預設值。
-function randomDbPassword() {
-  const chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
-  return Array.from({ length: 16 }, () => chars[randomInt(chars.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。';
-}
-
-const DEFAULT_STRING_COLUMN_LENGTH = 50;
-
-function parseFields(fields) {
-  if (!fields || !String(fields).trim()) {
-    return [];
-  }
-  return String(fields)
-    .split(',')
-    .map((f) => {
-      const [name, type] = f.split(':');
-      const fieldName = (name || '').trim();
-      const fieldType = (type || 'String').trim();
-      return {
-        name: fieldName,
-        type: fieldType,
-        snakeName: fieldName
-          .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
-          .replace(/[\s-]+/g, '_')
-          .toLowerCase(),
-        columnLength: fieldType === 'String' ? DEFAULT_STRING_COLUMN_LENGTH : null
-      };
-    })
-    .filter((f) => f.name);
-}
-
-function isExample(data) {
-  return Boolean(data && data.example)
-    || process.env.BIRC_EXAMPLE === '1'
-    || parseFields((data && data.fields) || process.env.BIRC_MAKE_FIELDS).length > 0;
-}
-
-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);
-}
-
-const JAVA_SQL_TYPES = Object.freeze({
-  String: `VARCHAR(${DEFAULT_STRING_COLUMN_LENGTH}) NULL`,
-  Integer: 'INT NULL',
-  int: 'INT NULL',
-  Long: 'BIGINT NULL',
-  long: 'BIGINT NULL',
-  Boolean: 'TINYINT(1) NULL',
-  boolean: 'TINYINT(1) NULL',
-  BigDecimal: 'DECIMAL(19, 2) NULL',
-  LocalDate: 'DATE NULL',
-  LocalDateTime: 'TIMESTAMP NULL',
-  Instant: 'TIMESTAMP NULL',
-  Double: 'DOUBLE NULL',
-  double: 'DOUBLE NULL',
-  Float: 'FLOAT NULL',
-  float: 'FLOAT NULL',
-  Short: 'SMALLINT NULL',
-  short: 'SMALLINT NULL',
-  Byte: 'TINYINT NULL',
-  byte: 'TINYINT NULL'
-});
-
-function sqlTypeForColumn(javaType, columnName) {
-  if (columnName === 'created_at') {
-    return 'TIMESTAMP DEFAULT CURRENT_TIMESTAMP';
-  }
-  if (columnName === 'updated_at') {
-    return 'TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP';
-  }
-  if (columnName === 'deleted_at') {
-    return 'TIMESTAMP NULL';
-  }
-  return JAVA_SQL_TYPES[javaType] || null;
-}
-
-function fieldsToMigrationColumns(fields, options) {
-  const withTimestamps = Boolean(options && options.withTimestamps);
-  const withSoftDelete = Boolean(options && options.withSoftDelete);
-  const columns = [];
-  const seen = new Set();
-
-  function addColumn(name, javaType) {
-    const columnName = sanitizeMigrationToken(name);
-    if (!columnName || columnName === 'id' || seen.has(columnName)) {
-      return;
-    }
-    const sqlType = sqlTypeForColumn(javaType, columnName);
-    if (!sqlType) {
-      return;
-    }
-    seen.add(columnName);
-    columns.push({ name: columnName, sqlType });
-  }
-
-  for (const field of fields || []) {
-    addColumn(field.snakeName || toSnakeCase(field.name), field.type);
-  }
-  if (withTimestamps) {
-    addColumn('created_at', 'LocalDateTime');
-    addColumn('updated_at', 'LocalDateTime');
-  }
-  if (withSoftDelete) {
-    addColumn('deleted_at', 'LocalDateTime');
-  }
-  return columns;
-}
-
-function listJavaFiles(dir, acc = []) {
-  if (!fs.existsSync(dir)) {
-    return acc;
-  }
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    const full = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      listJavaFiles(full, acc);
-    } else if (entry.isFile() && entry.name.endsWith('.java')) {
-      acc.push(full);
-    }
-  }
-  return acc;
-}
-
-function parseEntityColumns(source) {
-  const fields = [];
-  const fieldRe =
-    /((?:@\w+(?:\s*\([^)]*\))?\s*)*)private\s+([A-Za-z][A-Za-z0-9_]*)\s+([A-Za-z_][A-Za-z0-9_]*)\s*;/g;
-  let match = fieldRe.exec(source);
-  while (match) {
-    const annotations = match[1] || '';
-    const type = match[2];
-    const name = match[3];
-    const columnAttr = annotations.match(/@Column\s*\(([^)]*)\)/);
-    let snakeName = toSnakeCase(name);
-    if (columnAttr) {
-      const named = columnAttr[1].match(/name\s*=\s*"([^"]+)"/);
-      if (named) {
-        snakeName = named[1];
-      }
-    }
-    fields.push({ name, type, snakeName });
-    match = fieldRe.exec(source);
-  }
-  return {
-    fields,
-    withSoftDelete: /@SoftDelete\b/.test(source)
-  };
-}
-
-function findEntitySourceForTable(tableName, config) {
-  if (!tableName) {
-    return null;
-  }
-  const persistence = resolvePersistence(config);
-  const entityDir = path.join(projectRoot(), persistence.entityRoot);
-  const files = listJavaFiles(entityDir);
-  const escaped = String(tableName).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  const tableRe = new RegExp(`@Table\\s*\\([^)]*name\\s*=\\s*"${escaped}"`, 'i');
-  for (const file of files) {
-    const source = fs.readFileSync(file, 'utf8');
-    if (tableRe.test(source)) {
-      return source;
-    }
-  }
-  const className = toPascalCaseName(String(tableName).toLowerCase());
-  if (!className) {
-    return null;
-  }
-  const match = files.find((file) => path.basename(file, '.java') === className);
-  if (!match) {
-    return null;
-  }
-  return fs.readFileSync(match, 'utf8');
-}
-
-function javaLiteralForSeed(javaType) {
-  if (javaType === 'String') {
-    return '"example"';
-  }
-  if (javaType === 'LocalDate') {
-    return 'LocalDate.parse("2020-01-01")';
-  }
-  if (javaType === 'LocalDateTime') {
-    return 'LocalDateTime.parse("2020-01-01T00:00:00")';
-  }
-  if (javaType === 'Instant') {
-    return 'Instant.parse("2020-01-01T00:00:00Z")';
-  }
-  if (javaType === 'BigDecimal') {
-    return 'new BigDecimal("0")';
-  }
-  if (javaType === 'Boolean' || javaType === 'boolean') {
-    return 'false';
-  }
-  if (javaType === 'Long' || javaType === 'long') {
-    return '0L';
-  }
-  if (javaType === 'Integer' || javaType === 'int') {
-    return '0';
-  }
-  if (javaType === 'Short' || javaType === 'short') {
-    return '(short) 0';
-  }
-  if (javaType === 'Byte' || javaType === 'byte') {
-    return '(byte) 0';
-  }
-  if (javaType === 'Double' || javaType === 'double') {
-    return '0D';
-  }
-  if (javaType === 'Float' || javaType === 'float') {
-    return '0F';
-  }
-  if (JAVA_SQL_TYPES[javaType]) {
-    return '0';
-  }
-  return null;
-}
-
-const SKIP_SEED_FIELDS = new Set(['id', 'createdAt', 'updatedAt', 'deletedAt', 'created_at', 'updated_at', 'deleted_at']);
-
-function fieldsToSeedFields(fields) {
-  const result = [];
-  const seen = new Set();
-
-  for (const field of fields || []) {
-    const name = String(field.name || '').trim();
-    const snakeName = field.snakeName || toSnakeCase(name);
-    if (!name || SKIP_SEED_FIELDS.has(name) || SKIP_SEED_FIELDS.has(snakeName) || seen.has(name)) {
-      continue;
-    }
-    const literal = javaLiteralForSeed(field.type);
-    if (!literal) {
-      continue;
-    }
-    seen.add(name);
-    result.push({
-      name,
-      type: field.type,
-      setter: `set${name.charAt(0).toUpperCase()}${name.slice(1)}`,
-      literal
-    });
-  }
-  return result;
-}
-
-function resolveSeedFields(data, tableName, config) {
-  const explicitFields = parseFields(data.fields || process.env.BIRC_MAKE_FIELDS);
-  if (explicitFields.length > 0) {
-    return fieldsToSeedFields(explicitFields);
-  }
-  const source = findEntitySourceForTable(tableName, config);
-  if (source) {
-    return fieldsToSeedFields(parseEntityColumns(source).fields);
-  }
-  if (isExample(data)) {
-    return fieldsToSeedFields([{ name: 'name', type: 'String', snakeName: 'name' }]);
-  }
-  return [];
-}
-
-function entityNameForSeeder(data) {
-  const raw = toPascalCaseName((data && data.entityName) || '');
-  return raw.replace(/Seeder$/, '') || raw;
-}
-
-function resolveCreateTableColumns(data, tableName, config) {
-  const example = isExample(data);
-  const flaggedSoftDelete = includeSoftDelete(data);
-  const explicitFields = parseFields(data.fields || process.env.BIRC_MAKE_FIELDS);
-  if (explicitFields.length > 0) {
-    return fieldsToMigrationColumns(explicitFields, {
-      withTimestamps: example,
-      withSoftDelete: flaggedSoftDelete
-    });
-  }
-  const source = findEntitySourceForTable(tableName, config);
-  if (source) {
-    const entity = parseEntityColumns(source);
-    return fieldsToMigrationColumns(entity.fields, {
-      withTimestamps: false,
-      withSoftDelete: flaggedSoftDelete || entity.withSoftDelete
-    });
-  }
-  if (example) {
-    return fieldsToMigrationColumns(
-      [{ name: 'name', type: 'String', snakeName: 'name' }],
-      { withTimestamps: true, withSoftDelete: flaggedSoftDelete }
-    );
-  }
-  return fieldsToMigrationColumns([], {
-    withTimestamps: false,
-    withSoftDelete: flaggedSoftDelete
-  });
-}
-
-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('Instant')) imports.push('java.time.Instant');
-  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',
-      columnLength: DEFAULT_STRING_COLUMN_LENGTH
-    }];
-  }
-  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 seederSkeletonActions(root, templateData, options) {
-  const skipIfExists = Boolean(options && options.skipIfExists);
-  return [
-    { type: 'add', path: `${root}/seeder/Seeder.java`, templateFile: 'templates/seeder/Seeder.hbs', data: templateData, skipIfExists },
-    { type: 'add', path: `${root}/seeder/SeedRunner.java`, templateFile: 'templates/seeder/SeedRunner.hbs', data: templateData, skipIfExists }
-  ];
-}
-
-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;
-}
+const { deriveBasePackage, toPascalCaseName, createDestConflict } = require('./bin/cli-util');
+const {
+  CREATE_DEFAULTS,
+  validateProjectName,
+  validateJavaPackage,
+  validatePascalCase,
+  validateMigrationName,
+  loadProjectConfig,
+  inferProjectNameKebab,
+  fillJwtSecretInEnv,
+  randomJwtSecret,
+  fragmentMarkers
+} = require('./lib/project');
+const {
+  FEATURES,
+  FEATURE_GROUPS,
+  DEFAULT_FEATURES,
+  groupedFeatureChoices,
+  isAddForce,
+  isAddSync,
+  buildAddActions
+} = require('./lib/features');
+const {
+  isExample,
+  parseMigrationName,
+  makeEntityActions,
+  makeMapperActions,
+  makeServiceActions,
+  makeControllerActions,
+  makeStackActions,
+  makeModelActions,
+  makeMigrationActions,
+  makeSeederActions,
+  appendMakeSqlActions,
+  toSnakeCase,
+  includeMapperWithEntity,
+  skipExistingMakeFiles,
+  makeContext,
+  exceptionClassName
+} = require('./lib/make');
+const { buildCreateActions } = require('./lib/create');
 
 module.exports = function (plop) {
   plop.setHelper('pascalCase', (text) => text.charAt(0).toUpperCase() + text.slice(1));
@@ -1083,6 +73,12 @@ module.exports = function (plop) {
     return 'dest 可用';
   });
 
+  plop.setActionType('ensureJwtSecret', function (answers, config, plopApi) {
+    const destBase = plopApi.getDestBasePath();
+    const target = path.resolve(destBase, plopApi.renderString(config.path, answers));
+    return fillJwtSecretInEnv(target, randomJwtSecret());
+  });
+
   plop.setActionType('copyIfExists', function (answers, config, plopApi) {
     const destBase = plopApi.getDestBasePath();
     const from = path.resolve(destBase, plopApi.renderString(config.from, answers));
@@ -1103,8 +99,9 @@ module.exports = function (plop) {
     const templateData = { ...answers, ...(config.data || {}) };
     const fragment = plopApi.renderString(fs.readFileSync(templatePath, 'utf8'), templateData).trim();
     const contents = fs.readFileSync(target, 'utf8');
+    const { begin, end } = fragmentMarkers(config.commentToken, config.marker);
 
-    if (contents.includes(fragment)) {
+    if (contents.includes(begin) || contents.includes(fragment)) {
       return `skipped (already installed ${path.relative(destBase, target)})`;
     }
 
@@ -1113,7 +110,8 @@ module.exports = function (plop) {
       throw new Error(`找不到插入 anchor：${path.relative(destBase, target)}`);
     }
 
-    const next = contents.replace(config.pattern, (anchor) => `${anchor}\n${fragment}\n`);
+    const block = `${begin}\n${fragment}\n${end}`;
+    const next = contents.replace(config.pattern, (anchor) => `${anchor}\n${block}\n`);
     fs.writeFileSync(target, next);
     return path.relative(destBase, target);
   });
@@ -1147,63 +145,14 @@ module.exports = function (plop) {
     when: (answers) => isExample(answers)
       && !String((answers && answers.fields) || process.env.BIRC_MAKE_FIELDS || '').trim()
   };
-
-  function makeEntityActions(data, options) {
-    const { persistence, templateData } = makeContext(data);
-    const skipIfExists = Boolean(options && options.skipIfExists);
-    return [
-      { type: 'add', path: `${persistence.entityRoot}/{{pascalCase entityName}}.java`, templateFile: 'templates/entity.hbs', data: templateData, skipIfExists },
-      { type: 'add', path: `${persistence.daoRoot}/{{pascalCase entityName}}DAO.java`, templateFile: 'templates/dao.hbs', data: templateData, skipIfExists }
-    ];
-  }
-
-  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 appendMakeSqlActions([
-      ...makeEntityActions(data),
-      ...makeMapperActions(data),
-      ...makeServiceActions(data),
-      ...makeControllerActions(data)
-    ], data);
-  }
+  const migrationPrompts = [
+    {
+      type: 'input',
+      name: 'description',
+      message: '遷移名稱（例如 create_users_table、add_votes_to_users_table）：',
+      validate: validateMigrationName
+    }
+  ];
 
   plop.setGenerator('make', {
     description: '一次產生 Entity + DAO + Mapper + DTO + Service + Controller；--migration / --seed',
@@ -1215,10 +164,10 @@ module.exports = function (plop) {
     description: '產生 Entity 與 DAO；--migration / --seed / --dto / --mapper / --soft-delete',
     prompts: [entityNamePrompt, fieldsPrompt],
     actions(data) {
-      const extras = includeModelMigration(data) || includeModelSeed(data);
+      const extras = skipExistingMakeFiles(data);
       const actions = makeEntityActions(data, { skipIfExists: extras });
       if (includeMapperWithEntity(data)) {
-        actions.push(...makeMapperActions(data));
+        actions.push(...makeMapperActions(data, { skipIfExists: extras }));
       }
       appendMakeSqlActions(actions, data);
       return actions;
@@ -1310,7 +259,6 @@ module.exports = function (plop) {
     }
   });
 
-  // ---------- add：像 php artisan / ng add，往「既有專案」裡加一個功能模組 ----------
   plop.setGenerator('add', {
     description: '在既有專案中加入 email / sso / oauth 等功能模組（會改動 application.yml、build.gradle）',
     prompts: [
@@ -1350,7 +298,6 @@ module.exports = function (plop) {
     }
   });
 
-  // ---------- create：像 npm create vite@latest，從零建一個新專案資料夾 ----------
   plop.setGenerator('create', {
     description: '建立一個新的 BIRC Spring Boot 多模組專案（互動選擇要不要 email / sso / oauth）',
     prompts: [
@@ -1388,132 +335,9 @@ module.exports = function (plop) {
         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));
-      actions = actions.concat(seederSkeletonActions(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;
-    }
+    actions: buildCreateActions
   });
 
-  // ---------- docs：給 AI coding agent 讀的目錄與規範 ----------
   plop.setGenerator('docs', {
     description: '產生 AGENTS.md / PROJECT.md / implement.md / test.md',
     prompts: [],
@@ -1530,102 +354,6 @@ module.exports = function (plop) {
     }
   });
 
-  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);
-    const migrationColumns = parsed.kind === 'create'
-      ? resolveCreateTableColumns(data, parsed.tableName, config)
-      : [];
-    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),
-          migrationColumns
-        }
-      }
-    ];
-  }
-
-  function makeSeederActions(data) {
-    data.entityName = entityNameForSeeder(data);
-    const { root, templateData } = makeContext(data);
-    const entityName = data.entityName;
-    const seederClass = `${entityName}Seeder`;
-    const tableName = tableNameFromEntity(entityName);
-    const seedFields = resolveSeedFields(data, tableName, loadProjectConfig());
-    return [
-      ...seederSkeletonActions(root, templateData, { skipIfExists: true }),
-      {
-        type: 'add',
-        path: `${root}/seeder/${seederClass}.java`,
-        templateFile: 'templates/seeder.hbs',
-        data: {
-          ...templateData,
-          extraImports: fieldImports(seedFields),
-          seedFields,
-          seederClass,
-          entityName
-        }
-      }
-    ];
-  }
-
-  function makeModelActions(data) {
-    const actions = makeEntityActions(data, { skipIfExists: true });
-    if (includeMapperWithEntity(data)) {
-      actions.push(...makeMapperActions(data));
-    }
-    appendMakeSqlActions(actions, data);
-    if (includeModelController(data)) {
-      actions.push(...makeControllerActions(data));
-    }
-    return actions;
-  }
-
-  function appendMakeSqlActions(actions, data) {
-    const config = loadProjectConfig();
-    const migrationPath = migrationDir(config);
-    const version = nextMigrationVersion(path.join(projectRoot(), migrationPath));
-    if (includeModelMigration(data)) {
-      const tableName = tableNameFromEntity(data.entityName);
-      actions.push(
-        ...makeMigrationActions({
-          ...data,
-          description: `create_${tableName}_table`,
-          migrationVersion: version
-        })
-      );
-    }
-    if (includeModelSeed(data)) {
-      actions.push(...makeSeederActions(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,