befly 2.3.3 → 3.0.0

package/scripts/syncDb/ddl.ts

@@ -0,0 +1,182 @@
+/**
+ * syncDb DDL 构建模块
+ *
+ * 包含：
+ * - 构建索引 SQL
+ * - 生成 DDL 子句（添加/修改列）
+ * - 安全执行 DDL（MySQL 降级策略）
+ * - 构建系统列和业务列定义
+ */
+
+import { Logger } from '../../utils/logger.js';
+import { parseRule } from '../../utils/tableHelper.js';
+import { IS_MYSQL, IS_PG, IS_SQLITE, SYSTEM_INDEX_FIELDS, typeMapping } from './constants.js';
+import { quoteIdentifier, resolveDefaultValue, generateDefaultSql, getSqlType, escapeComment } from './helpers.js';
+import type { SQL } from 'bun';
+
+/**
+ * 构建索引操作 SQL（统一使用在线策略）
+ *
+ * @param tableName - 表名
+ * @param indexName - 索引名
+ * @param fieldName - 字段名
+ * @param action - 操作类型（create/drop）
+ * @returns SQL 语句
+ */
+export function buildIndexSQL(tableName: string, indexName: string, fieldName: string, action: 'create' | 'drop'): string {
+    const tableQuoted = quoteIdentifier(tableName);
+    const indexQuoted = quoteIdentifier(indexName);
+    const fieldQuoted = quoteIdentifier(fieldName);
+
+    if (IS_MYSQL) {
+        const parts = [];
+        if (action === 'create') {
+            parts.push(`ADD INDEX ${indexQuoted} (${fieldQuoted})`);
+        } else {
+            parts.push(`DROP INDEX ${indexQuoted}`);
+        }
+        // 始终使用在线算法
+        parts.push('ALGORITHM=INPLACE');
+        parts.push('LOCK=NONE');
+        return `ALTER TABLE ${tableQuoted} ${parts.join(', ')}`;
+    }
+
+    if (IS_PG) {
+        if (action === 'create') {
+            // 始终使用 CONCURRENTLY
+            return `CREATE INDEX CONCURRENTLY IF NOT EXISTS ${indexQuoted} ON ${tableQuoted}(${fieldQuoted})`;
+        }
+        return `DROP INDEX CONCURRENTLY IF EXISTS ${indexQuoted}`;
+    }
+
+    // SQLite
+    if (action === 'create') {
+        return `CREATE INDEX IF NOT EXISTS ${indexQuoted} ON ${tableQuoted}(${fieldQuoted})`;
+    }
+    return `DROP INDEX IF EXISTS ${indexQuoted}`;
+}
+
+/**
+ * 构建系统字段列定义
+ *
+ * @returns 系统字段的列定义数组
+ */
+export function buildSystemColumnDefs(): string[] {
+    if (IS_MYSQL) {
+        return ['`id` BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT "主键ID"', '`created_at` BIGINT NOT NULL DEFAULT 0 COMMENT "创建时间"', '`updated_at` BIGINT NOT NULL DEFAULT 0 COMMENT "更新时间"', '`deleted_at` BIGINT NOT NULL DEFAULT 0 COMMENT "删除时间"', '`state` BIGINT NOT NULL DEFAULT 0 COMMENT "状态字段"'];
+    }
+    return ['"id" INTEGER PRIMARY KEY', '"created_at" INTEGER NOT NULL DEFAULT 0', '"updated_at" INTEGER NOT NULL DEFAULT 0', '"deleted_at" INTEGER NOT NULL DEFAULT 0', '"state" INTEGER NOT NULL DEFAULT 0'];
+}
+
+/**
+ * 构建业务字段列定义
+ *
+ * @param fields - 字段定义对象
+ * @returns 业务字段的列定义数组
+ */
+export function buildBusinessColumnDefs(fields: Record<string, string>): string[] {
+    const colDefs: string[] = [];
+
+    for (const [fieldKey, fieldRule] of Object.entries(fields)) {
+        const parsed = parseRule(fieldRule);
+        const { name: fieldName, type: fieldType, max: fieldMax, default: fieldDefault } = parsed;
+        const sqlType = getSqlType(fieldType, fieldMax);
+
+        // 使用公共函数处理默认值
+        const actualDefault = resolveDefaultValue(fieldDefault, fieldType);
+        const defaultSql = generateDefaultSql(actualDefault, fieldType);
+
+        if (IS_MYSQL) {
+            colDefs.push(`\`${fieldKey}\` ${sqlType} NOT NULL${defaultSql} COMMENT "${escapeComment(fieldName)}"`);
+        } else {
+            colDefs.push(`"${fieldKey}" ${sqlType} NOT NULL${defaultSql}`);
+        }
+    }
+
+    return colDefs;
+}
+
+/**
+ * 生成字段 DDL 子句（不含 ALTER TABLE 前缀）
+ *
+ * @param fieldKey - 字段键名
+ * @param fieldRule - 字段规则字符串
+ * @param isAdd - 是否为添加字段（true）还是修改字段（false）
+ * @returns DDL 子句
+ */
+export function generateDDLClause(fieldKey: string, fieldRule: string, isAdd: boolean = false): string {
+    const parsed = parseRule(fieldRule);
+    const { name: fieldName, type: fieldType, max: fieldMax, default: fieldDefault } = parsed;
+    const sqlType = getSqlType(fieldType, fieldMax);
+
+    // 使用公共函数处理默认值
+    const actualDefault = resolveDefaultValue(fieldDefault, fieldType);
+    const defaultSql = generateDefaultSql(actualDefault, fieldType);
+
+    if (IS_MYSQL) {
+        return `${isAdd ? 'ADD COLUMN' : 'MODIFY COLUMN'} \`${fieldKey}\` ${sqlType} NOT NULL${defaultSql} COMMENT "${escapeComment(fieldName)}"`;
+    }
+    if (IS_PG) {
+        if (isAdd) return `ADD COLUMN IF NOT EXISTS "${fieldKey}" ${sqlType} NOT NULL${defaultSql}`;
+        // PG 修改：类型与非空可分条执行，生成 TYPE 改变；非空另由上层统一控制
+        return `ALTER COLUMN "${fieldKey}" TYPE ${sqlType}`;
+    }
+    // SQLite 仅支持 ADD COLUMN（>=3.50.0：支持 IF NOT EXISTS）
+    if (isAdd) return `ADD COLUMN IF NOT EXISTS "${fieldKey}" ${sqlType} NOT NULL${defaultSql}`;
+    return '';
+}
+
+/**
+ * 安全执行 DDL 语句（MySQL 降级策略）
+ *
+ * 执行 DDL 时按以下顺序尝试：
+ * 1. ALGORITHM=INSTANT (最快，无表锁)
+ * 2. ALGORITHM=INPLACE (在线 DDL)
+ * 3. 传统 DDL (可能需要表锁)
+ *
+ * @param sql - SQL 客户端实例
+ * @param stmt - DDL 语句
+ * @returns 是否执行成功
+ * @throws {Error} 如果所有尝试都失败
+ */
+export async function executeDDLSafely(sql: SQL, stmt: string): Promise<boolean> {
+    try {
+        await sql.unsafe(stmt);
+        return true;
+    } catch (error: any) {
+        // MySQL 专用降级路径
+        if (stmt.includes('ALGORITHM=INSTANT')) {
+            const inplaceSql = stmt.replace(/ALGORITHM=INSTANT/g, 'ALGORITHM=INPLACE');
+            try {
+                await sql.unsafe(inplaceSql);
+                return true;
+            } catch (inplaceError) {
+                // 最后尝试传统DDL：移除 ALGORITHM/LOCK 附加子句后执行
+                const traditionSql = stmt
+                    .replace(/,\s*ALGORITHM=INPLACE/g, '')
+                    .replace(/,\s*ALGORITHM=INSTANT/g, '')
+                    .replace(/,\s*LOCK=(NONE|SHARED|EXCLUSIVE)/g, '');
+                await sql.unsafe(traditionSql);
+                return true;
+            }
+        } else {
+            throw error;
+        }
+    }
+}
+
+/**
+ * PG 兼容类型变更识别：无需数据重写的宽化型变更
+ *
+ * @param currentType - 当前类型
+ * @param newType - 新类型
+ * @returns 是否为兼容变更
+ */
+export function isPgCompatibleTypeChange(currentType: string, newType: string): boolean {
+    const c = String(currentType || '').toLowerCase();
+    const n = String(newType || '').toLowerCase();
+    // varchar -> text 视为宽化
+    if (c === 'character varying' && n === 'text') return true;
+    // text -> character varying 非宽化（可能截断），不兼容
+    return false;
+}

package/scripts/syncDb/helpers.ts

@@ -0,0 +1,172 @@
+/**
+ * syncDb 辅助函数模块
+ *
+ * 包含：
+ * - SQL 标识符引用
+ * - 日志格式化
+ * - 类型判断工具
+ * - 默认值处理
+ */
+
+import { IS_MYSQL, IS_PG, typeMapping } from './constants.js';
+import { isType } from '../../utils/typeHelper.js';
+
+/**
+ * 根据数据库类型引用标识符
+ *
+ * @param identifier - 标识符（表名、列名等）
+ * @returns 引用后的标识符
+ *
+ * @example
+ * quoteIdentifier('user_table')
+ * // MySQL: `user_table`
+ * // PostgreSQL: "user_table"
+ * // SQLite: user_table
+ */
+export function quoteIdentifier(identifier: string): string {
+    if (IS_MYSQL) return `\`${identifier}\``;
+    if (IS_PG) return `"${identifier}"`;
+    return identifier; // SQLite 无需引用
+}
+
+/**
+ * 处理默认值：将 'null' 字符串转换为对应类型的默认值
+ *
+ * @param fieldDefault - 字段默认值（可能是 'null' 字符串）
+ * @param fieldType - 字段类型（number/string/text/array）
+ * @returns 实际默认值
+ *
+ * @example
+ * resolveDefaultValue('null', 'string') // => ''
+ * resolveDefaultValue('null', 'number') // => 0
+ * resolveDefaultValue('null', 'array') // => '[]'
+ * resolveDefaultValue('null', 'text') // => 'null'
+ * resolveDefaultValue('admin', 'string') // => 'admin'
+ */
+export function resolveDefaultValue(fieldDefault: any, fieldType: 'number' | 'string' | 'text' | 'array'): any {
+    if (fieldDefault !== 'null') {
+        return fieldDefault;
+    }
+
+    // null 表示使用类型默认值
+    switch (fieldType) {
+        case 'number':
+            return 0;
+        case 'string':
+            return '';
+        case 'array':
+            return '[]';
+        case 'text':
+            // text 类型不设置默认值，保持 'null'
+            return 'null';
+        default:
+            return fieldDefault;
+    }
+}
+
+/**
+ * 生成 SQL DEFAULT 子句
+ *
+ * @param actualDefault - 实际默认值（已经过 resolveDefaultValue 处理）
+ * @param fieldType - 字段类型
+ * @returns SQL DEFAULT 子句字符串（包含前导空格），如果不需要则返回空字符串
+ *
+ * @example
+ * generateDefaultSql(0, 'number') // => ' DEFAULT 0'
+ * generateDefaultSql('admin', 'string') // => " DEFAULT 'admin'"
+ * generateDefaultSql('', 'string') // => " DEFAULT ''"
+ * generateDefaultSql('null', 'text') // => ''
+ */
+export function generateDefaultSql(actualDefault: any, fieldType: 'number' | 'string' | 'text' | 'array'): string {
+    // text 类型不设置默认值
+    if (fieldType === 'text' || actualDefault === 'null') {
+        return '';
+    }
+
+    // 仅 number/string/array 类型设置默认值
+    if (fieldType === 'number' || fieldType === 'string' || fieldType === 'array') {
+        if (isType(actualDefault, 'number')) {
+            return ` DEFAULT ${actualDefault}`;
+        } else {
+            // 字符串需要转义单引号：' -> ''
+            const escaped = String(actualDefault).replace(/'/g, "''");
+            return ` DEFAULT '${escaped}'`;
+        }
+    }
+
+    return '';
+}
+
+/**
+ * 判断是否为字符串或数组类型（需要长度限制的类型）
+ *
+ * @param fieldType - 字段类型
+ * @returns 是否为 string 或 array
+ *
+ * @example
+ * isStringOrArrayType('string') // => true
+ * isStringOrArrayType('array') // => true
+ * isStringOrArrayType('number') // => false
+ * isStringOrArrayType('text') // => false
+ */
+export function isStringOrArrayType(fieldType: string): boolean {
+    return fieldType === 'string' || fieldType === 'array';
+}
+
+/**
+ * 获取 SQL 数据类型
+ *
+ * @param fieldType - 字段类型（number/string/text/array）
+ * @param fieldMax - 最大长度（string/array 类型需要）
+ * @returns SQL 类型字符串
+ *
+ * @example
+ * getSqlType('string', 100) // => 'VARCHAR(100)'
+ * getSqlType('number', null) // => 'BIGINT'
+ * getSqlType('text', null) // => 'TEXT'
+ * getSqlType('array', 500) // => 'VARCHAR(500)'
+ */
+export function getSqlType(fieldType: string, fieldMax: number | null): string {
+    if (isStringOrArrayType(fieldType)) {
+        return `${typeMapping[fieldType]}(${fieldMax})`;
+    }
+    return typeMapping[fieldType];
+}
+
+/**
+ * 转义 SQL 注释中的双引号
+ *
+ * @param str - 注释字符串
+ * @returns 转义后的字符串
+ *
+ * @example
+ * escapeComment('用户名称') // => '用户名称'
+ * escapeComment('用户"昵称"') // => '用户\\"昵称\\"'
+ */
+export function escapeComment(str: string): string {
+    return String(str).replace(/"/g, '\\"');
+}
+
+/**
+ * 记录字段变更信息（带缩进和格式化）
+ *
+ * @param tableName - 表名
+ * @param fieldName - 字段名
+ * @param changeType - 变更类型（length/datatype/comment/default）
+ * @param oldValue - 旧值
+ * @param newValue - 新值
+ * @param changeLabel - 变更类型的中文标签
+ */
+export function logFieldChange(tableName: string, fieldName: string, changeType: string, oldValue: any, newValue: any, changeLabel: string): void {
+    console.log(`   修改表 ${tableName} 的字段 ${fieldName} 的${changeLabel}: ${oldValue} -> ${newValue}`);
+}
+
+/**
+ * 格式化字段列表为可读字符串
+ *
+ * @param fields - 字段名数组
+ * @returns 格式化的字符串（逗号分隔）
+ */
+export function formatFieldList(fields: string[]): string {
+    return fields.map((f) => quoteIdentifier(f)).join(', ');
+}

package/scripts/syncDb/index.ts

@@ -0,0 +1,215 @@
+/**
+ * syncDb 主入口文件
+ *
+ * 功能：
+ * - 协调所有模块，执行数据库表结构同步
+ * - 处理核心表、项目表、addon 表
+ * - 提供统计信息和错误处理
+ */
+
+import path from 'node:path';
+import { Logger } from '../../utils/logger.js';
+import { Env } from '../../config/env.js';
+import { createSqlClient, toSnakeTableName } from '../../utils/dbHelper.js';
+import checkTable from '../../checks/table.js';
+import { __dirtables, getProjectDir } from '../../system.js';
+import { scanAddons, hasAddonDir, getAddonDir } from '../../utils/addonHelper.js';
+
+// 导入模块化的功能
+import { ensureDbVersion } from './version.js';
+import { tableExists } from './schema.js';
+import { createTable, modifyTable } from './table.js';
+import { PerformanceTracker, ProgressLogger } from './state.js';
+import type { SQL } from 'bun';
+
+// 全局 SQL 客户端实例
+let sql: SQL | null = null;
+
+// 全局统计对象
+const globalCount: Record<string, number> = {
+    processedTables: 0,
+    createdTables: 0,
+    modifiedTables: 0,
+    addFields: 0,
+    nameChanges: 0,
+    typeChanges: 0,
+    minChanges: 0,
+    maxChanges: 0,
+    defaultChanges: 0,
+    indexCreate: 0,
+    indexDrop: 0
+};
+
+/**
+ * 主同步函数
+ *
+ * 流程：
+ * 1. 验证表定义文件
+ * 2. 建立数据库连接并检查版本
+ * 3. 扫描表定义文件（核心表、项目表、addon表）
+ * 4. 对比并应用表结构变更
+ * 5. 输出统计信息
+ */
+export const SyncDb = async (): Promise<void> => {
+    const perfTracker = new PerformanceTracker();
+    const progressLogger = new ProgressLogger();
+
+    try {
+        Logger.info('开始数据库表结构同步...');
+
+        // 重置全局统计，避免多次调用累加
+        for (const k of Object.keys(globalCount)) {
+            if (typeof globalCount[k] === 'number') globalCount[k] = 0;
+        }
+
+        // 阶段1：验证表定义文件
+        perfTracker.markPhase('validation');
+        if (!(await checkTable())) {
+            throw new Error('表定义验证失败');
+        }
+        Logger.info(`✓ 表定义验证完成，耗时: ${perfTracker.getPhaseTime('validation')}`);
+
+        // 阶段2：建立数据库连接并检查版本
+        perfTracker.markPhase('connection');
+        sql = await createSqlClient({ max: 1 });
+        await ensureDbVersion(sql);
+        Logger.info(`✓ 数据库连接建立，耗时: ${perfTracker.getPhaseTime('connection')}`);
+
+        // 阶段3：扫描表定义文件
+        perfTracker.markPhase('scan');
+        const tablesGlob = new Bun.Glob('*.json');
+        const directories: Array<{ path: string; isCore: boolean; addonName?: string }> = [
+            { path: __dirtables, isCore: true },
+            { path: getProjectDir('tables'), isCore: false }
+        ];
+
+        // 添加所有 addon 的 tables 目录
+        const addons = scanAddons();
+        for (const addon of addons) {
+            if (hasAddonDir(addon, 'tables')) {
+                directories.push({
+                    path: getAddonDir(addon, 'tables'),
+                    isCore: false,
+                    addonName: addon
+                });
+            }
+        }
+
+        // 统计表文件总数
+        let totalTables = 0;
+        for (const dirConfig of directories) {
+            for await (const file of tablesGlob.scan({
+                cwd: dirConfig.path,
+                absolute: true,
+                onlyFiles: true
+            })) {
+                const fileName = path.basename(file, '.json');
+                if (!fileName.startsWith('_')) {
+                    totalTables++;
+                }
+            }
+        }
+        perfTracker.finishPhase('scan');
+        Logger.info(`✓ 扫描完成，发现 ${totalTables} 个表定义文件，耗时: ${perfTracker.getPhaseTime('scan')}`);
+
+        // 阶段4：处理表文件
+        perfTracker.markPhase('process');
+        let processedCount = 0;
+
+        for (const dirConfig of directories) {
+            const { path: dir, isCore, addonName } = dirConfig;
+            const dirType = isCore ? '内核' : addonName ? `组件[${addonName}]` : '项目';
+
+            for await (const file of tablesGlob.scan({
+                cwd: dir,
+                absolute: true,
+                onlyFiles: true
+            })) {
+                const fileName = path.basename(file, '.json');
+
+                // 跳过以下划线开头的文件（这些是公共字段规则，不是表定义）
+                if (fileName.startsWith('_')) {
+                    Logger.info(`跳过非表定义文件: ${fileName}.json`);
+                    continue;
+                }
+
+                // 确定表名前缀：
+                // - 核心表：sys_ 前缀
+                // - addon 表：{addonName}_ 前缀
+                // - 项目表：无前缀
+                let tableName = toSnakeTableName(fileName);
+                if (isCore) {
+                    tableName = `sys_${tableName}`;
+                } else if (addonName) {
+                    tableName = `${addonName}_${tableName}`;
+                }
+
+                processedCount++;
+                progressLogger.logTableProgress(processedCount, totalTables, tableName);
+                Logger.info(`  类型: ${dirType}`);
+
+                const tableDefinition = await Bun.file(file).json();
+                const existsTable = await tableExists(sql!, tableName);
+
+                if (existsTable) {
+                    await modifyTable(sql!, tableName, tableDefinition, globalCount);
+                } else {
+                    await createTable(sql!, tableName, tableDefinition);
+                    globalCount.createdTables++;
+                }
+                globalCount.processedTables++;
+            }
+        }
+
+        perfTracker.finishPhase('process');
+        Logger.info(`✓ 表处理完成，耗时: ${perfTracker.getPhaseTime('process')}`);
+
+        // 阶段5：显示统计信息
+        Logger.info('\n=== 同步统计信息 ===');
+        Logger.info(`总耗时: ${perfTracker.getTotalTime()}`);
+        Logger.info(`处理表总数: ${globalCount.processedTables}`);
+        Logger.info(`创建表: ${globalCount.createdTables}`);
+        Logger.info(`修改表: ${globalCount.modifiedTables}`);
+        Logger.info(`字段新增: ${globalCount.addFields}`);
+        Logger.info(`字段名称变更: ${globalCount.nameChanges}`);
+        Logger.info(`字段类型变更: ${globalCount.typeChanges}`);
+        Logger.info(`字段最小值变更: ${globalCount.minChanges}`);
+        Logger.info(`字段最大值变更: ${globalCount.maxChanges}`);
+        Logger.info(`字段默认值变更: ${globalCount.defaultChanges}`);
+        Logger.info(`索引新增: ${globalCount.indexCreate}`);
+        Logger.info(`索引删除: ${globalCount.indexDrop}`);
+
+        if (globalCount.processedTables === 0) {
+            Logger.warn('没有找到任何表定义文件');
+        }
+
+        // 输出性能统计
+        perfTracker.logStats();
+    } catch (error: any) {
+        Logger.error(`数据库同步失败: ${error.message}`);
+        Logger.error(`错误详情: ${error.stack}`);
+        if (error.code) {
+            Logger.error(`错误代码: ${error.code}`);
+        }
+        if (error.errno) {
+            Logger.error(`错误编号: ${error.errno}`);
+        }
+        process.exit(1);
+    } finally {
+        if (sql) {
+            try {
+                await sql.close();
+            } catch (error: any) {
+                Logger.warn('关闭数据库连接时出错:', error.message);
+            }
+        }
+    }
+};
+
+// 如果直接运行此脚本（Bun 支持 import.meta.main）
+if (import.meta.main) {
+    SyncDb().catch((error) => {
+        console.error('❌ 数据库同步失败:', error);
+        process.exit(1);
+    });
+}