befly 2.3.3 → 3.0.1

package/scripts/syncDb/table.ts

@@ -0,0 +1,214 @@
+/**
+ * syncDb 表操作模块
+ *
+ * 包含：
+ * - 修改表结构
+ * - 对比字段变化
+ * - 应用变更计划
+ */
+
+import { Logger } from '../../utils/logger.js';
+import { toSnakeCase } from '../../utils/helper.js';
+import { parseRule } from '../../utils/helper.js';
+import { IS_MYSQL, IS_PG, IS_SQLITE, SYSTEM_INDEX_FIELDS, CHANGE_TYPE_LABELS, typeMapping } from './constants.js';
+import { quoteIdentifier, logFieldChange, resolveDefaultValue, generateDefaultSql, isStringOrArrayType, getSqlType } from './helpers.js';
+import { buildIndexSQL, generateDDLClause, isPgCompatibleTypeChange } from './ddl.js';
+import { getTableColumns, getTableIndexes, type ColumnInfo } from './schema.js';
+import { compareFieldDefinition, applyTablePlan } from './apply.js';
+import { createTable } from './tableCreate.js';
+import type { TablePlan } from './types.js';
+import type { SQL } from 'bun';
+
+// 是否为计划模式（从环境变量读取）
+const IS_PLAN = process.argv.includes('--plan');
+
+// 导出 createTable 供其他模块使用
+export { createTable };
+
+/**
+ * 同步表结构（对比和应用变更）
+ *
+ * 主要逻辑：
+ * 1. 获取表的现有列和索引信息
+ * 2. 对比每个字段的定义变化
+ * 3. 生成 DDL 变更计划
+ * 4. 处理索引的增删
+ * 5. 应用变更计划
+ *
+ * 安全策略：
+ * - 禁止字段类型变更（除 string<->array）
+ * - 跳过危险的长度收缩
+ * - 使用在线 DDL（MySQL/PG）
+ *
+ * @param sql - SQL 客户端实例
+ * @param tableName - 表名
+ * @param fields - 字段定义对象
+ * @param globalCount - 全局统计对象（用于计数）
+ * @returns 表结构变更计划
+ */
+export async function modifyTable(sql: SQL, tableName: string, fields: Record<string, string>, globalCount: Record<string, number>): Promise<TablePlan> {
+    const existingColumns = await getTableColumns(sql, tableName);
+    const existingIndexes = await getTableIndexes(sql, tableName);
+    let changed = false;
+
+    const addClauses = [];
+    const modifyClauses = [];
+    const defaultClauses = [];
+    const indexActions = [];
+
+    for (const [fieldKey, fieldRule] of Object.entries(fields)) {
+        // 转换字段名为下划线格式（用于与数据库字段对比）
+        const dbFieldName = toSnakeCase(fieldKey);
+
+        if (existingColumns[dbFieldName]) {
+            const comparison = compareFieldDefinition(existingColumns[dbFieldName], fieldRule, dbFieldName);
+            if (comparison.length > 0) {
+                for (const c of comparison) {
+                    // 使用统一的日志格式函数和常量标签
+                    const changeLabel = CHANGE_TYPE_LABELS[c.type] || '未知';
+                    logFieldChange(tableName, dbFieldName, c.type, c.current, c.expected, changeLabel);
+
+                    // 全量计数：全局累加
+                    if (c.type === 'datatype') globalCount.typeChanges++;
+                    else if (c.type === 'length') globalCount.maxChanges++;
+                    else if (c.type === 'default') globalCount.defaultChanges++;
+                    else if (c.type === 'comment') globalCount.nameChanges++;
+                }
+
+                const parsed = parseRule(fieldRule);
+                const { name: fieldName, type: fieldType, max: fieldMax, default: fieldDefault } = parsed;
+
+                if (isStringOrArrayType(fieldType) && existingColumns[dbFieldName].length) {
+                    if (existingColumns[dbFieldName].length! > fieldMax) {
+                        Logger.warn(`[跳过危险变更] ${tableName}.${dbFieldName} 长度收缩 ${existingColumns[dbFieldName].length} -> ${fieldMax} 已被跳过（设置 SYNC_DISALLOW_SHRINK=0 可放开）`);
+                    }
+                }
+
+                const hasTypeChange = comparison.some((c) => c.type === 'datatype');
+                const hasLengthChange = comparison.some((c) => c.type === 'length');
+                const onlyDefaultChanged = comparison.every((c) => c.type === 'default');
+                const defaultChanged = comparison.some((c) => c.type === 'default');
+
+                // 严格限制：除 string/array 互转外，禁止任何字段类型变更；一旦发现，立即终止同步
+                if (hasTypeChange) {
+                    const currentSqlType = String(existingColumns[dbFieldName].type || '').toLowerCase();
+                    const newSqlType = String(typeMapping[fieldType] || '').toLowerCase();
+                    const errorMsg = [`禁止字段类型变更: ${tableName}.${dbFieldName}`, `当前类型: ${currentSqlType}`, `目标类型: ${newSqlType}`, `说明: 仅允许 string<->array 互相切换，其他类型变更需要手动处理`].join('\n');
+                    throw new Error(errorMsg);
+                }
+
+                // 默认值变化处理
+                if (defaultChanged) {
+                    // 使用公共函数处理默认值
+                    const actualDefault = resolveDefaultValue(fieldDefault, fieldType);
+
+                    // 生成 SQL DEFAULT 值（不包含前导空格，因为要用于 ALTER COLUMN）
+                    let v: string | null = null;
+                    if (actualDefault !== 'null') {
+                        const defaultSql = generateDefaultSql(actualDefault, fieldType);
+                        // 移除前导空格 ' DEFAULT ' -> 'DEFAULT '
+                        v = defaultSql.trim().replace(/^DEFAULT\s+/, '');
+                    }
+
+                    if (v !== null && v !== '') {
+                        if (IS_PG) {
+                            defaultClauses.push(`ALTER COLUMN "${dbFieldName}" SET DEFAULT ${v}`);
+                        } else if (IS_MYSQL && onlyDefaultChanged) {
+                            // MySQL 的 TEXT/BLOB 不允许 DEFAULT，跳过 text 类型
+                            if (fieldType !== 'text') {
+                                defaultClauses.push(`ALTER COLUMN \`${dbFieldName}\` SET DEFAULT ${v}`);
+                            }
+                        }
+                    }
+                }
+
+                // 若不仅仅是默认值变化，继续生成修改子句
+                if (!onlyDefaultChanged) {
+                    let skipModify = false;
+                    if (hasLengthChange && isStringOrArrayType(fieldType) && existingColumns[dbFieldName].length) {
+                        const oldLen = existingColumns[dbFieldName].length!;
+                        const isShrink = oldLen > fieldMax;
+                        if (isShrink) skipModify = true;
+                    }
+
+                    if (hasTypeChange) {
+                        if (IS_PG && isPgCompatibleTypeChange(existingColumns[dbFieldName].type, typeMapping[fieldType].toLowerCase())) {
+                            Logger.info(`[PG兼容类型变更] ${tableName}.${dbFieldName} ${existingColumns[dbFieldName].type} -> ${typeMapping[fieldType].toLowerCase()} 允许执行`);
+                        }
+                    }
+
+                    if (!skipModify) modifyClauses.push(generateDDLClause(fieldKey, fieldRule, false));
+                }
+                changed = true;
+            }
+        } else {
+            const parsed = parseRule(fieldRule);
+            const { name: fieldName, type: fieldType, max: fieldMax, default: fieldDefault } = parsed;
+            const lenPart = isStringOrArrayType(fieldType) ? ` 长度:${parseInt(String(fieldMax))}` : '';
+            Logger.info(`[新增字段] ${tableName}.${dbFieldName} 类型:${fieldType}${lenPart} 默认:${fieldDefault ?? 'NULL'}`);
+            addClauses.push(generateDDLClause(fieldKey, fieldRule, true));
+            changed = true;
+            globalCount.addFields++;
+        }
+    }
+
+    // 检查系统字段索引
+    for (const sysField of ['created_at', 'updated_at', 'state']) {
+        const idxName = `idx_${sysField}`;
+        if (!existingIndexes[idxName]) {
+            indexActions.push({ action: 'create', indexName: idxName, fieldName: sysField });
+            changed = true;
+            globalCount.indexCreate++;
+        }
+    }
+
+    // 检查业务字段索引
+    for (const [fieldKey, fieldRule] of Object.entries(fields)) {
+        // 转换字段名为下划线格式
+        const dbFieldName = toSnakeCase(fieldKey);
+
+        const parsed = parseRule(fieldRule);
+        const indexName = `idx_${dbFieldName}`;
+        if (parsed.index === 1 && !existingIndexes[indexName]) {
+            indexActions.push({ action: 'create', indexName, fieldName: dbFieldName });
+            changed = true;
+            globalCount.indexCreate++;
+        } else if (!(parsed.index === 1) && existingIndexes[indexName] && existingIndexes[indexName].length === 1) {
+            indexActions.push({ action: 'drop', indexName, fieldName: dbFieldName });
+            changed = true;
+            globalCount.indexDrop++;
+        }
+    }
+
+    // PG 列注释处理
+    const commentActions = [];
+    if (IS_PG) {
+        for (const [fieldKey, fieldRule] of Object.entries(fields)) {
+            // 转换字段名为下划线格式
+            const dbFieldName = toSnakeCase(fieldKey);
+
+            if (existingColumns[dbFieldName]) {
+                const parsed = parseRule(fieldRule);
+                const { name: fieldName } = parsed;
+                const curr = existingColumns[dbFieldName].comment || '';
+                const want = fieldName && fieldName !== 'null' ? String(fieldName) : '';
+                if (want !== curr) {
+                    commentActions.push(`COMMENT ON COLUMN "${tableName}"."${dbFieldName}" IS ${want ? `'${want}'` : 'NULL'}`);
+                    changed = true;
+                }
+            }
+        }
+    }
+
+    // 仅当存在实际动作时才认为有变更（避免仅日志的收缩跳过被计为修改）
+    changed = addClauses.length > 0 || modifyClauses.length > 0 || defaultClauses.length > 0 || indexActions.length > 0 || commentActions.length > 0;
+
+    const plan = { changed, addClauses, modifyClauses, defaultClauses, indexActions, commentActions };
+
+    // 将计划应用（包含 --plan 情况下仅输出）
+    if (plan.changed) {
+        await applyTablePlan(sql, tableName, fields, plan, globalCount);
+    }
+
+    return plan;
+}

package/scripts/syncDb/tableCreate.ts

@@ -0,0 +1,148 @@
+/**
+ * syncDb 表创建模块
+ *
+ * 包含：
+ * - 创建表（包含系统字段和业务字段）
+ * - 添加 PostgreSQL 注释
+ * - 创建表索引
+ *
+ * 注意：此模块从 table.ts 中提取，用于解除循环依赖
+ */
+
+import { Logger } from '../../utils/logger.js';
+import { IS_MYSQL, IS_PG, MYSQL_TABLE_CONFIG } from './constants.js';
+import { quoteIdentifier } from './helpers.js';
+import { buildSystemColumnDefs, buildBusinessColumnDefs, buildIndexSQL } from './ddl.js';
+import { parseRule, toSnakeCase } from '../../utils/helper.js';
+import type { SQL } from 'bun';
+
+// 是否为计划模式（从环境变量读取）
+const IS_PLAN = process.argv.includes('--plan');
+
+/**
+ * 为 PostgreSQL 表添加列注释
+ *
+ * @param sql - SQL 客户端实例
+ * @param tableName - 表名
+ * @param fields - 字段定义对象
+ */
+async function addPostgresComments(sql: SQL, tableName: string, fields: Record<string, string>): Promise<void> {
+    // 系统字段注释
+    const systemComments = [
+        ['id', '主键ID'],
+        ['created_at', '创建时间'],
+        ['updated_at', '更新时间'],
+        ['deleted_at', '删除时间'],
+        ['state', '状态字段']
+    ];
+
+    for (const [name, comment] of systemComments) {
+        const stmt = `COMMENT ON COLUMN "${tableName}"."${name}" IS '${comment}'`;
+        if (IS_PLAN) {
+            Logger.info(`[计划] ${stmt}`);
+        } else {
+            await sql.unsafe(stmt);
+        }
+    }
+
+    // 业务字段注释
+    for (const [fieldKey, fieldRule] of Object.entries(fields)) {
+        // 转换字段名为下划线格式
+        const dbFieldName = toSnakeCase(fieldKey);
+
+        const parsed = parseRule(fieldRule);
+        const { name: fieldName } = parsed;
+        const stmt = `COMMENT ON COLUMN "${tableName}"."${dbFieldName}" IS '${fieldName}'`;
+        if (IS_PLAN) {
+            Logger.info(`[计划] ${stmt}`);
+        } else {
+            await sql.unsafe(stmt);
+        }
+    }
+}
+
+/**
+ * 创建表的索引（并行执行以提升性能）
+ *
+ * @param sql - SQL 客户端实例
+ * @param tableName - 表名
+ * @param fields - 字段定义对象
+ * @param systemIndexFields - 系统字段索引列表
+ */
+async function createTableIndexes(sql: SQL, tableName: string, fields: Record<string, string>, systemIndexFields: string[]): Promise<void> {
+    const indexTasks: Promise<void>[] = [];
+
+    // 系统字段索引
+    for (const sysField of systemIndexFields) {
+        const stmt = buildIndexSQL(tableName, `idx_${sysField}`, sysField, 'create');
+        if (IS_PLAN) {
+            Logger.info(`[计划] ${stmt}`);
+        } else {
+            indexTasks.push(sql.unsafe(stmt));
+        }
+    }
+
+    // 业务字段索引
+    for (const [fieldKey, fieldRule] of Object.entries(fields)) {
+        // 转换字段名为下划线格式
+        const dbFieldName = toSnakeCase(fieldKey);
+
+        const parsed = parseRule(fieldRule);
+        if (parsed.index === 1) {
+            const stmt = buildIndexSQL(tableName, `idx_${dbFieldName}`, dbFieldName, 'create');
+            if (IS_PLAN) {
+                Logger.info(`[计划] ${stmt}`);
+            } else {
+                indexTasks.push(sql.unsafe(stmt));
+            }
+        }
+    }
+
+    // 并行执行所有索引创建
+    if (indexTasks.length > 0) {
+        await Promise.all(indexTasks);
+    }
+}
+
+/**
+ * 创建表（包含系统字段和业务字段）
+ *
+ * @param sql - SQL 客户端实例
+ * @param tableName - 表名
+ * @param fields - 字段定义对象
+ * @param systemIndexFields - 系统字段索引列表（可选，默认使用 ['created_at', 'updated_at', 'state']）
+ */
+export async function createTable(sql: SQL, tableName: string, fields: Record<string, string>, systemIndexFields: string[] = ['created_at', 'updated_at', 'state']): Promise<void> {
+    // 构建列定义
+    const colDefs = [...buildSystemColumnDefs(), ...buildBusinessColumnDefs(fields)];
+
+    // 生成 CREATE TABLE 语句
+    const cols = colDefs.join(',\n            ');
+    const tableQuoted = quoteIdentifier(tableName);
+    const { ENGINE, CHARSET, COLLATE } = MYSQL_TABLE_CONFIG;
+    const createSQL = IS_MYSQL
+        ? `CREATE TABLE ${tableQuoted} (
+            ${cols}
+        ) ENGINE=${ENGINE} DEFAULT CHARSET=${CHARSET} COLLATE=${COLLATE}`
+        : `CREATE TABLE ${tableQuoted} (
+            ${cols}
+        )`;
+
+    if (IS_PLAN) {
+        Logger.info(`[计划] ${createSQL.replace(/\n+/g, ' ')}`);
+    } else {
+        await sql.unsafe(createSQL);
+        Logger.info(`[新建表] ${tableName}`);
+    }
+
+    // PostgreSQL: 添加列注释
+    if (IS_PG && !IS_PLAN) {
+        await addPostgresComments(sql, tableName, fields);
+    } else if (IS_PG && IS_PLAN) {
+        // 计划模式也要输出注释语句
+        await addPostgresComments(sql, tableName, fields);
+    }
+
+    // 创建索引
+    await createTableIndexes(sql, tableName, fields, systemIndexFields);
+}

package/scripts/syncDb/tests/constants.test.ts

@@ -0,0 +1,105 @@
+/**
+ * syncDb 常量模块测试
+ */
+
+import { describe, test, expect } from 'bun:test';
+import { DB_VERSION_REQUIREMENTS, SYSTEM_FIELDS, SYSTEM_INDEX_FIELDS, CHANGE_TYPE_LABELS, MYSQL_TABLE_CONFIG, IS_MYSQL, IS_PG, IS_SQLITE, typeMapping } from '../constants.js';
+
+describe('syncDb/constants', () => {
+    describe('数据库版本要求', () => {
+        test('应定义 MySQL 最低版本', () => {
+            expect(DB_VERSION_REQUIREMENTS.MYSQL_MIN_MAJOR).toBe(8);
+        });
+
+        test('应定义 PostgreSQL 最低版本', () => {
+            expect(DB_VERSION_REQUIREMENTS.POSTGRES_MIN_MAJOR).toBe(17);
+        });
+
+        test('应定义 SQLite 最低版本', () => {
+            expect(DB_VERSION_REQUIREMENTS.SQLITE_MIN_VERSION).toBe('3.50.0');
+            expect(DB_VERSION_REQUIREMENTS.SQLITE_MIN_VERSION_NUM).toBe(35000);
+        });
+    });
+
+    describe('系统字段定义', () => {
+        test('应包含 5 个系统字段', () => {
+            const fields = Object.keys(SYSTEM_FIELDS);
+            expect(fields).toHaveLength(5);
+            expect(fields).toContain('ID');
+            expect(fields).toContain('CREATED_AT');
+            expect(fields).toContain('UPDATED_AT');
+            expect(fields).toContain('DELETED_AT');
+            expect(fields).toContain('STATE');
+        });
+
+        test('每个系统字段应有名称和注释', () => {
+            expect(SYSTEM_FIELDS.ID.name).toBe('id');
+            expect(SYSTEM_FIELDS.ID.comment).toBe('主键ID');
+        });
+    });
+
+    describe('系统索引字段', () => {
+        test('应包含 3 个索引字段', () => {
+            expect(SYSTEM_INDEX_FIELDS).toHaveLength(3);
+            expect(SYSTEM_INDEX_FIELDS).toContain('created_at');
+            expect(SYSTEM_INDEX_FIELDS).toContain('updated_at');
+            expect(SYSTEM_INDEX_FIELDS).toContain('state');
+        });
+    });
+
+    describe('变更类型标签', () => {
+        test('应包含所有变更类型', () => {
+            expect(CHANGE_TYPE_LABELS.length).toBe('长度');
+            expect(CHANGE_TYPE_LABELS.datatype).toBe('类型');
+            expect(CHANGE_TYPE_LABELS.comment).toBe('注释');
+            expect(CHANGE_TYPE_LABELS.default).toBe('默认值');
+        });
+    });
+
+    describe('MySQL 表配置', () => {
+        test('应有默认配置', () => {
+            expect(MYSQL_TABLE_CONFIG.ENGINE).toBeDefined();
+            expect(MYSQL_TABLE_CONFIG.CHARSET).toBeDefined();
+            expect(MYSQL_TABLE_CONFIG.COLLATE).toBeDefined();
+        });
+
+        test('默认引擎应为 InnoDB', () => {
+            expect(MYSQL_TABLE_CONFIG.ENGINE).toMatch(/InnoDB/i);
+        });
+
+        test('默认字符集应为 utf8mb4', () => {
+            expect(MYSQL_TABLE_CONFIG.CHARSET).toMatch(/utf8mb4/i);
+        });
+    });
+
+    describe('数据库类型检测', () => {
+        test('IS_MYSQL, IS_PG, IS_SQLITE 三者只有一个为 true', () => {
+            const trueCount = [IS_MYSQL, IS_PG, IS_SQLITE].filter(Boolean).length;
+            expect(trueCount).toBe(1);
+        });
+
+        test('类型映射应包含所有字段类型', () => {
+            expect(typeMapping.number).toBeDefined();
+            expect(typeMapping.string).toBeDefined();
+            expect(typeMapping.text).toBeDefined();
+            expect(typeMapping.array_string).toBeDefined();
+            expect(typeMapping.array_text).toBeDefined();
+        });
+
+        test('不同数据库的类型映射应不同', () => {
+            if (IS_MYSQL) {
+                expect(typeMapping.number).toBe('BIGINT');
+                expect(typeMapping.string).toBe('VARCHAR');
+                expect(typeMapping.text).toBe('MEDIUMTEXT');
+            } else if (IS_PG) {
+                expect(typeMapping.number).toBe('BIGINT');
+                expect(typeMapping.string).toBe('character varying');
+                expect(typeMapping.text).toBe('TEXT');
+            } else if (IS_SQLITE) {
+                expect(typeMapping.number).toBe('INTEGER');
+                expect(typeMapping.string).toBe('TEXT');
+                expect(typeMapping.text).toBe('TEXT');
+            }
+        });
+    });
+});

package/scripts/syncDb/tests/ddl.test.ts

@@ -0,0 +1,134 @@
+/**
+ * syncDb DDL 构建测试
+ */
+
+import { describe, test, expect } from 'bun:test';
+import { buildIndexSQL, buildSystemColumnDefs, buildBusinessColumnDefs, generateDDLClause, isPgCompatibleTypeChange } from '../ddl.js';
+import { IS_MYSQL, IS_PG, IS_SQLITE } from '../constants.js';
+
+describe('syncDb/ddl', () => {
+    describe('buildIndexSQL', () => {
+        test('应生成创建索引 SQL', () => {
+            const sql = buildIndexSQL('users', 'idx_email', 'email', 'create');
+            expect(sql).toBeDefined();
+            expect(sql.length).toBeGreaterThan(0);
+
+            if (IS_MYSQL) {
+                expect(sql).toContain('ADD INDEX');
+                expect(sql).toContain('ALGORITHM=INPLACE');
+                expect(sql).toContain('LOCK=NONE');
+            } else if (IS_PG) {
+                expect(sql).toContain('CREATE INDEX CONCURRENTLY');
+            } else if (IS_SQLITE) {
+                expect(sql).toContain('CREATE INDEX');
+            }
+        });
+
+        test('应生成删除索引 SQL', () => {
+            const sql = buildIndexSQL('users', 'idx_email', 'email', 'drop');
+            expect(sql).toBeDefined();
+
+            if (IS_MYSQL) {
+                expect(sql).toContain('DROP INDEX');
+            } else if (IS_PG) {
+                expect(sql).toContain('DROP INDEX CONCURRENTLY');
+            } else if (IS_SQLITE) {
+                expect(sql).toContain('DROP INDEX');
+            }
+        });
+    });
+
+    describe('buildSystemColumnDefs', () => {
+        test('应返回 5 个系统字段定义', () => {
+            const defs = buildSystemColumnDefs();
+            expect(defs).toHaveLength(5);
+        });
+
+        test('系统字段应包含 id, created_at, updated_at, deleted_at, state', () => {
+            const defs = buildSystemColumnDefs();
+            const combined = defs.join(' ');
+
+            expect(combined).toContain('id');
+            expect(combined).toContain('created_at');
+            expect(combined).toContain('updated_at');
+            expect(combined).toContain('deleted_at');
+            expect(combined).toContain('state');
+        });
+
+        test('MySQL 应包含 COMMENT', () => {
+            const defs = buildSystemColumnDefs();
+            const combined = defs.join(' ');
+
+            if (IS_MYSQL) {
+                expect(combined).toContain('COMMENT');
+            }
+        });
+    });
+
+    describe('buildBusinessColumnDefs', () => {
+        test('应处理空字段对象', () => {
+            const defs = buildBusinessColumnDefs({});
+            expect(defs).toHaveLength(0);
+        });
+
+        test('应生成字段定义', () => {
+            const fields = {
+                username: '用户名|string|1|50||1',
+                age: '年龄|number|0|150|0|0'
+            };
+            const defs = buildBusinessColumnDefs(fields);
+
+            expect(defs.length).toBeGreaterThan(0);
+            expect(defs.join(' ')).toContain('username');
+            expect(defs.join(' ')).toContain('age');
+        });
+    });
+
+    describe('generateDDLClause', () => {
+        test('应生成添加字段子句', () => {
+            const clause = generateDDLClause('email', '邮箱|string|0|100||0', true);
+            expect(clause).toBeDefined();
+
+            if (IS_MYSQL) {
+                expect(clause).toContain('ADD COLUMN');
+            } else if (IS_PG) {
+                expect(clause).toContain('ADD COLUMN');
+            } else if (IS_SQLITE) {
+                expect(clause).toContain('ADD COLUMN');
+            }
+        });
+
+        test('应生成修改字段子句', () => {
+            const clause = generateDDLClause('email', '邮箱|string|0|100||0', false);
+            expect(clause).toBeDefined();
+
+            if (IS_MYSQL) {
+                expect(clause).toContain('MODIFY COLUMN');
+            } else if (IS_PG) {
+                expect(clause).toContain('ALTER COLUMN');
+            }
+        });
+    });
+
+    describe('isPgCompatibleTypeChange', () => {
+        test('varchar -> text 应为兼容变更', () => {
+            const result = isPgCompatibleTypeChange('character varying', 'text');
+            expect(result).toBe(true);
+        });
+
+        test('text -> varchar 应为不兼容变更', () => {
+            const result = isPgCompatibleTypeChange('text', 'character varying');
+            expect(result).toBe(false);
+        });
+
+        test('相同类型应为不兼容变更（无需变更）', () => {
+            const result = isPgCompatibleTypeChange('text', 'text');
+            expect(result).toBe(false);
+        });
+
+        test('应处理大小写', () => {
+            const result = isPgCompatibleTypeChange('CHARACTER VARYING', 'TEXT');
+            expect(result).toBe(true);
+        });
+    });
+});

package/scripts/syncDb/tests/helpers.test.ts

@@ -0,0 +1,70 @@
+/**
+ * syncDb 辅助函数测试
+ */
+
+import { describe, test, expect } from 'bun:test';
+import { quoteIdentifier, logFieldChange, formatFieldList } from '../helpers.js';
+
+describe('syncDb/helpers', () => {
+    describe('quoteIdentifier', () => {
+        test('应正确引用标识符', () => {
+            const result = quoteIdentifier('user_table');
+
+            // 根据当前数据库类型验证
+            expect(typeof result).toBe('string');
+            expect(result.length).toBeGreaterThan(0);
+        });
+
+        test('应处理特殊字符', () => {
+            const result = quoteIdentifier('table_name_with_underscore');
+            expect(result).toBeDefined();
+        });
+
+        test('应处理空字符串', () => {
+            const result = quoteIdentifier('');
+            expect(typeof result).toBe('string');
+        });
+    });
+
+    describe('logFieldChange', () => {
+        test('应不抛出错误', () => {
+            expect(() => {
+                logFieldChange('test_table', 'test_field', 'length', 100, 200, '长度');
+            }).not.toThrow();
+        });
+
+        test('应处理各种变更类型', () => {
+            expect(() => {
+                logFieldChange('table1', 'field1', 'length', 100, 200, '长度');
+                logFieldChange('table2', 'field2', 'datatype', 'INT', 'VARCHAR', '类型');
+                logFieldChange('table3', 'field3', 'comment', 'old', 'new', '注释');
+                logFieldChange('table4', 'field4', 'default', 0, 1, '默认值');
+            }).not.toThrow();
+        });
+    });
+
+    describe('formatFieldList', () => {
+        test('应正确格式化单个字段', () => {
+            const result = formatFieldList(['id']);
+            expect(result).toBeDefined();
+            expect(typeof result).toBe('string');
+        });
+
+        test('应正确格式化多个字段', () => {
+            const result = formatFieldList(['id', 'name', 'email']);
+            expect(result).toContain(',');
+            expect(result.split(',').length).toBe(3);
+        });
+
+        test('应处理空数组', () => {
+            const result = formatFieldList([]);
+            expect(result).toBe('');
+        });
+
+        test('应正确引用字段名', () => {
+            const result = formatFieldList(['user_id', 'user_name']);
+            expect(result).toBeDefined();
+            // 结果应包含引用符号（取决于数据库类型）
+        });
+    });
+});