befly 2.3.3 → 3.0.0

package/scripts/syncDb/tableCreate.ts

@@ -0,0 +1,142 @@
+/**
+ * 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 } from '../../utils/tableHelper.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 parsed = parseRule(fieldRule);
+        const { name: fieldName } = parsed;
+        const stmt = `COMMENT ON COLUMN "${tableName}"."${fieldKey}" 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 parsed = parseRule(fieldRule);
+        if (parsed.index === 1) {
+            const stmt = buildIndexSQL(tableName, `idx_${fieldKey}`, fieldKey, '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,104 @@
+/**
+ * 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).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();
+            // 结果应包含引用符号（取决于数据库类型）
+        });
+    });
+});

package/scripts/syncDb/types.ts

@@ -0,0 +1,92 @@
+/**
+ * syncDb 类型定义模块
+ *
+ * 集中管理核心类型定义
+ */
+
+// ==================== 数据库相关类型 ====================
+
+/**
+ * 列信息接口
+ */
+export interface ColumnInfo {
+    type: string;
+    columnType: string;
+    length: number | null;
+    nullable: boolean;
+    defaultValue: any;
+    comment: string | null;
+}
+
+/**
+ * 索引信息接口（键为索引名，值为列名数组）
+ */
+export interface IndexInfo {
+    [indexName: string]: string[];
+}
+
+// ==================== 变更相关类型 ====================
+
+/**
+ * 字段变更接口
+ */
+export interface FieldChange {
+    type: 'length' | 'datatype' | 'comment' | 'default';
+    current: any;
+    expected: any;
+}
+
+/**
+ * 索引操作接口
+ */
+export interface IndexAction {
+    action: 'create' | 'drop';
+    indexName: string;
+    fieldName: string;
+}
+
+/**
+ * 表变更计划接口
+ */
+export interface TablePlan {
+    changed: boolean;
+    addClauses: string[];
+    modifyClauses: string[];
+    defaultClauses: string[];
+    indexActions: IndexAction[];
+    commentActions?: string[];
+}
+
+// ==================== 统计相关类型 ====================
+
+/**
+ * 全局统计对象
+ */
+export interface GlobalStats {
+    processedTables: number;
+    createdTables: number;
+    modifiedTables: number;
+    addFields: number;
+    nameChanges: number;
+    typeChanges: number;
+    minChanges: number;
+    maxChanges: number;
+    defaultChanges: number;
+    indexCreate: number;
+    indexDrop: number;
+}
+
+// ==================== 解析相关类型 ====================
+
+/**
+ * 解析后的字段规则
+ */
+export interface ParsedFieldRule {
+    name: string;
+    type: string;
+    min: any;
+    max: any;
+    default: any;
+    index: number;
+    regex: string;
+}

package/scripts/syncDb/version.ts

@@ -0,0 +1,73 @@
+/**
+ * syncDb 数据库版本检查模块
+ *
+ * 包含：
+ * - 数据库版本验证（MySQL/PostgreSQL/SQLite）
+ */
+
+import { Logger } from '../../utils/logger.js';
+import { Env } from '../../config/env.js';
+import { DB_VERSION_REQUIREMENTS, IS_MYSQL, IS_PG, IS_SQLITE } from './constants.js';
+import type { SQL } from 'bun';
+
+/**
+ * 数据库版本检查（按方言）
+ *
+ * 根据当前数据库类型检查版本是否符合最低要求：
+ * - MySQL: >= 8.0
+ * - PostgreSQL: >= 17
+ * - SQLite: >= 3.50.0
+ *
+ * @param sql - SQL 客户端实例
+ * @throws {Error} 如果数据库版本不符合要求或无法获取版本信息
+ */
+export async function ensureDbVersion(sql: SQL): Promise<void> {
+    if (!sql) throw new Error('SQL 客户端未初始化');
+
+    if (IS_MYSQL) {
+        const r = await sql`SELECT VERSION() AS version`;
+        if (!r || r.length === 0 || !r[0]?.version) {
+            throw new Error('无法获取 MySQL 版本信息');
+        }
+        const version = r[0].version;
+        const majorVersion = parseInt(String(version).split('.')[0], 10);
+        if (!Number.isFinite(majorVersion) || majorVersion < DB_VERSION_REQUIREMENTS.MYSQL_MIN_MAJOR) {
+            throw new Error(`此脚本仅支持 MySQL ${DB_VERSION_REQUIREMENTS.MYSQL_MIN_MAJOR}.0+，当前版本: ${version}`);
+        }
+        Logger.info(`MySQL 版本: ${version}`);
+        return;
+    }
+
+    if (IS_PG) {
+        const r = await sql`SELECT version() AS version`;
+        if (!r || r.length === 0 || !r[0]?.version) {
+            throw new Error('无法获取 PostgreSQL 版本信息');
+        }
+        const versionText = r[0].version;
+        Logger.info(`PostgreSQL 版本: ${versionText}`);
+        const m = /PostgreSQL\s+(\d+)/i.exec(versionText);
+        const major = m ? parseInt(m[1], 10) : NaN;
+        if (!Number.isFinite(major) || major < DB_VERSION_REQUIREMENTS.POSTGRES_MIN_MAJOR) {
+            throw new Error(`此脚本要求 PostgreSQL >= ${DB_VERSION_REQUIREMENTS.POSTGRES_MIN_MAJOR}，当前: ${versionText}`);
+        }
+        return;
+    }
+
+    if (IS_SQLITE) {
+        const r = await sql`SELECT sqlite_version() AS version`;
+        if (!r || r.length === 0 || !r[0]?.version) {
+            throw new Error('无法获取 SQLite 版本信息');
+        }
+        const version = r[0].version;
+        Logger.info(`SQLite 版本: ${version}`);
+        // 强制最低版本：SQLite ≥ 3.50.0
+        const [maj, min, patch] = String(version)
+            .split('.')
+            .map((v) => parseInt(v, 10) || 0);
+        const vnum = maj * 10000 + min * 100 + patch; // 3.50.0 -> 35000
+        if (!Number.isFinite(vnum) || vnum < DB_VERSION_REQUIREMENTS.SQLITE_MIN_VERSION_NUM) {
+            throw new Error(`此脚本要求 SQLite >= ${DB_VERSION_REQUIREMENTS.SQLITE_MIN_VERSION}，当前: ${version}`);
+        }
+        return;
+    }
+}

package/scripts/syncDb.ts

@@ -0,0 +1,9 @@
+import { SyncDb } from './syncDb/index.js';
+
+// 如果直接运行此脚本
+if (import.meta.main) {
+    SyncDb().catch((error) => {
+        console.error('❌ 数据库同步失败:', error);
+        process.exit(1);
+    });
+}