befly 3.8.18 → 3.8.20

package/sync/syncApi.ts

@@ -0,0 +1,264 @@
+/**
+ * SyncApi 命令 - 同步 API 接口数据到数据库
+ * 说明：遍历所有 API 文件，收集接口路由信息并同步到 addon_admin_api 表
+ *
+ * 流程：
+ * 1. 扫描项目 apis 目录下所有项目 API 文件
+ * 2. 扫描 node_modules/@befly-addon/* 目录下所有组件 API 文件
+ * 3. 提取每个 API 的 name、method、auth 等信息
+ * 4. 根据接口路径检查是否存在
+ * 5. 存在则更新，不存在则新增
+ * 6. 删除配置中不存在的接口记录
+ */
+import { readdirSync, statSync } from 'node:fs';
+import { join, dirname, relative, basename } from 'pathe';
+import { Database } from '../lib/database.js';
+import { RedisHelper } from '../lib/redisHelper.js';
+import { scanFiles, scanAddons, addonDirExists, getAddonDir } from 'befly-util';
+
+import { Logger } from '../lib/logger.js';
+import { projectDir } from '../paths.js';
+
+import type { SyncApiOptions, ApiInfo, BeflyOptions } from '../types/index.js';
+
+/**
+ * 从 API 文件中提取接口信息
+ */
+async function extractApiInfo(filePath: string, apiRoot: string, type: 'app' | 'addon', addonName: string = '', addonTitle: string = ''): Promise<ApiInfo | null> {
+    try {
+        const normalizedFilePath = filePath.replace(/\\/g, '/');
+        const apiModule = await import(normalizedFilePath);
+        const apiConfig = apiModule.default;
+
+        if (!apiConfig || !apiConfig.name) {
+            return null;
+        }
+
+        let apiPath = '';
+
+        if (type === 'addon') {
+            // Addon 接口：保留完整目录层级
+            // 例: apis/menu/list.ts → /api/addon/admin/menu/list
+            const relativePath = relative(apiRoot, filePath);
+            const pathWithoutExt = relativePath.replace(/\.(ts|js)$/, '');
+            apiPath = `/api/addon/${addonName}/${pathWithoutExt}`;
+        } else {
+            // 项目接口：保留完整目录层级
+            // 例: apis/user/list.ts → /api/user/list
+            const relativePath = relative(apiRoot, filePath);
+            const pathWithoutExt = relativePath.replace(/\.(ts|js)$/, '');
+            apiPath = `/api/${pathWithoutExt}`;
+        }
+
+        return {
+            name: apiConfig.name || '',
+            path: apiPath,
+            method: apiConfig.method || 'POST',
+            description: apiConfig.description || '',
+            addonName: addonName,
+            addonTitle: addonTitle || addonName
+        };
+    } catch (error: any) {
+        Logger.error('同步 API 失败:', error);
+        throw error;
+    }
+}
+
+/**
+ * 扫描所有 API 文件
+ */
+async function scanAllApis(projectRoot: string): Promise<ApiInfo[]> {
+    const apis: ApiInfo[] = [];
+
+    // 1. 扫描项目 API（只扫描 apis 目录）
+    try {
+        const projectApisDir = join(projectDir, 'apis');
+
+        // 扫描项目 API 文件
+        const projectApiFiles: string[] = [];
+        try {
+            const files = await scanFiles(projectApisDir);
+            for (const { filePath } of files) {
+                projectApiFiles.push(filePath);
+            }
+        } catch (error: any) {
+            Logger.warn(`扫描项目 API 目录失败: ${projectApisDir} - ${error.message}`);
+        }
+
+        for (const filePath of projectApiFiles) {
+            const apiInfo = await extractApiInfo(filePath, projectApisDir, 'app', '', '项目接口');
+            if (apiInfo) {
+                apis.push(apiInfo);
+            }
+        }
+
+        // 2. 扫描组件 API (node_modules/@befly-addon/*)
+        const addonNames = scanAddons();
+
+        for (const addonName of addonNames) {
+            // addonName 格式: admin, demo 等
+
+            // 检查 apis 子目录是否存在
+            if (!addonDirExists(addonName, 'apis')) {
+                continue;
+            }
+
+            const addonApisDir = getAddonDir(addonName, 'apis');
+
+            // 读取 addon 配置
+            const addonConfigPath = getAddonDir(addonName, 'addon.config.json');
+            let addonTitle = addonName;
+            try {
+                const config = await import(addonConfigPath, { with: { type: 'json' } });
+                addonTitle = config.default.title || addonName;
+            } catch (error) {
+                // 忽略配置读取错误
+            }
+
+            // 扫描 addon API 文件
+            const addonApiFiles: string[] = [];
+            try {
+                const files = await scanFiles(addonApisDir);
+                for (const { filePath } of files) {
+                    addonApiFiles.push(filePath);
+                }
+            } catch (error: any) {
+                Logger.warn(`扫描 addon API 目录失败: ${addonApisDir} - ${error.message}`);
+            }
+
+            for (const filePath of addonApiFiles) {
+                const apiInfo = await extractApiInfo(filePath, addonApisDir, 'addon', addonName, addonTitle);
+                if (apiInfo) {
+                    apis.push(apiInfo);
+                }
+            }
+        }
+
+        return apis;
+    } catch (error: any) {
+        Logger.error(`接口扫描失败:`, error);
+        return apis;
+    }
+}
+
+/**
+ * 同步 API 数据到数据库
+ */
+async function syncApis(helper: any, apis: ApiInfo[]): Promise<void> {
+    for (const api of apis) {
+        try {
+            // 根据 path 查询是否存在
+            const existing = await helper.getOne({
+                table: 'addon_admin_api',
+                where: { path: api.path }
+            });
+
+            if (existing) {
+                // 检查是否需要更新
+                const needUpdate = existing.name !== api.name || existing.method !== api.method || existing.description !== api.description || existing.addonName !== api.addonName || existing.addonTitle !== api.addonTitle;
+
+                if (needUpdate) {
+                    await helper.updData({
+                        table: 'addon_admin_api',
+                        where: { id: existing.id },
+                        data: {
+                            name: api.name,
+                            method: api.method,
+                            description: api.description,
+                            addonName: api.addonName,
+                            addonTitle: api.addonTitle
+                        }
+                    });
+                }
+            } else {
+                await helper.insData({
+                    table: 'addon_admin_api',
+                    data: {
+                        name: api.name,
+                        path: api.path,
+                        method: api.method,
+                        description: api.description,
+                        addonName: api.addonName,
+                        addonTitle: api.addonTitle
+                    }
+                });
+            }
+        } catch (error: any) {
+            Logger.error(`同步接口 "${api.name}" 失败:`, error);
+        }
+    }
+}
+
+/**
+ * 删除配置中不存在的记录
+ */
+async function deleteObsoleteRecords(helper: any, apiPaths: Set<string>): Promise<void> {
+    const allRecords = await helper.getAll({
+        table: 'addon_admin_api',
+        fields: ['id', 'path'],
+        where: { state$gte: 0 }
+    });
+
+    for (const record of allRecords) {
+        if (record.path && !apiPaths.has(record.path)) {
+            await helper.delForce({
+                table: 'addon_admin_api',
+                where: { id: record.id }
+            });
+        }
+    }
+}
+
+/**
+ * SyncApi 命令主函数
+ */
+export async function syncApiCommand(config: BeflyOptions, options: SyncApiOptions = {}): Promise<void> {
+    try {
+        if (options.plan) {
+            Logger.debug('[计划] 同步 API 接口到数据库（plan 模式不执行）');
+            return;
+        }
+
+        // 连接数据库（SQL + Redis）
+        await Database.connect();
+
+        const helper = Database.getDbHelper();
+
+        // 1. 检查表是否存在（addon_admin_api 来自 addon-admin 组件）
+        const exists = await helper.tableExists('addon_admin_api');
+
+        if (!exists) {
+            Logger.debug('表 addon_admin_api 不存在，跳过 API 同步（需要安装 addon-admin 组件）');
+            return;
+        }
+
+        // 2. 扫描所有 API 文件
+        const apis = await scanAllApis(projectDir);
+        const apiPaths = new Set(apis.map((api) => api.path));
+
+        // 3. 同步 API 数据
+        await syncApis(helper, apis);
+
+        // 4. 删除文件中不存在的接口
+        await deleteObsoleteRecords(helper, apiPaths);
+
+        // 5. 缓存接口数据到 Redis
+        try {
+            const apiList = await helper.getAll({
+                table: 'addon_admin_api',
+                fields: ['id', 'name', 'path', 'method', 'description', 'addonName', 'addonTitle'],
+                orderBy: ['addonName#ASC', 'path#ASC']
+            });
+
+            const redisHelper = new RedisHelper();
+            await redisHelper.setObject('apis:all', apiList);
+        } catch (error: any) {
+            // 忽略缓存错误
+        }
+    } catch (error: any) {
+        Logger.error('API 同步失败:', error);
+        throw error;
+    } finally {
+        await Database?.disconnect();
+    }
+}

package/sync/syncDb/apply.ts

@@ -0,0 +1,194 @@
+/**
+ * syncDb 变更应用模块
+ *
+ * 包含：
+ * - 比较字段定义变化
+ * - 应用表结构变更计划
+ */
+
+import { Logger } from '../../lib/logger.js';
+import { IS_MYSQL, IS_PG, IS_SQLITE, CHANGE_TYPE_LABELS, typeMapping } from './constants.js';
+import { logFieldChange, resolveDefaultValue, isStringOrArrayType } from './helpers.js';
+import { executeDDLSafely, buildIndexSQL } from './ddl.js';
+import { rebuildSqliteTable } from './sqlite.js';
+import type { FieldChange, IndexAction, TablePlan, ColumnInfo } from '../../types.js';
+import type { SQL } from 'bun';
+import type { FieldDefinition } from 'befly/types/common';
+
+// 是否为计划模式（从环境变量读取）
+const IS_PLAN = process.argv.includes('--plan');
+
+/**
+ * 构建 ALTER TABLE SQL 语句
+ *
+ * 根据数据库类型构建相应的 ALTER TABLE 语句：
+ * - MySQL: 添加 ALGORITHM=INSTANT, LOCK=NONE 优化参数
+ * - PostgreSQL/SQLite: 使用双引号标识符
+ *
+ * @param tableName - 表名
+ * @param clauses - SQL 子句数组
+ * @returns 完整的 ALTER TABLE 语句
+ */
+function buildAlterTableSQL(tableName: string, clauses: string[]): string {
+    if (IS_MYSQL) {
+        return `ALTER TABLE \`${tableName}\` ${clauses.join(', ')}, ALGORITHM=INSTANT, LOCK=NONE`;
+    }
+    return `ALTER TABLE "${tableName}" ${clauses.join(', ')}`;
+}
+
+/**
+ * 比较字段定义变化
+ *
+ * 对比现有列信息和新的字段规则，识别变化类型：
+ * - 长度变化（string/array 类型）
+ * - 注释变化（MySQL/PG）
+ * - 数据类型变化
+ * - 默认值变化
+ *
+ * @param existingColumn - 现有列信息
+ * @param fieldDef - 新的字段定义对象
+ * @param colName - 列名（未使用，保留参数兼容性）
+ * @returns 变化数组
+ */
+export function compareFieldDefinition(existingColumn: ColumnInfo, fieldDef: FieldDefinition): FieldChange[] {
+    const changes: FieldChange[] = [];
+
+    // 检查长度变化（string和array类型） - SQLite 不比较长度
+    if (!IS_SQLITE && isStringOrArrayType(fieldDef.type)) {
+        if (existingColumn.max !== fieldDef.max) {
+            changes.push({
+                type: 'length',
+                current: existingColumn.max,
+                expected: fieldDef.max
+            });
+        }
+    }
+
+    // 检查注释变化（MySQL/PG 支持列注释）
+    if (!IS_SQLITE) {
+        const currentComment = existingColumn.comment || '';
+        if (currentComment !== fieldDef.name) {
+            changes.push({
+                type: 'comment',
+                current: currentComment,
+                expected: fieldDef.name
+            });
+        }
+    }
+
+    // 检查数据类型变化（只对比基础类型）
+    const expectedType = typeMapping[fieldDef.type].toLowerCase();
+    const currentType = existingColumn.type.toLowerCase();
+
+    if (currentType !== expectedType) {
+        changes.push({
+            type: 'datatype',
+            current: currentType,
+            expected: expectedType
+        });
+    }
+
+    // 检查 nullable 变化
+    const expectedNullable = fieldDef.nullable;
+    if (existingColumn.nullable !== expectedNullable) {
+        changes.push({
+            type: 'nullable',
+            current: existingColumn.nullable,
+            expected: expectedNullable
+        });
+    }
+
+    // 使用公共函数处理默认值
+    const expectedDefault = resolveDefaultValue(fieldDef.default, fieldDef.type);
+
+    // 检查默认值变化
+    if (String(existingColumn.defaultValue) !== String(expectedDefault)) {
+        changes.push({
+            type: 'default',
+            current: existingColumn.defaultValue,
+            expected: expectedDefault
+        });
+    }
+
+    return changes;
+}
+
+/**
+ * 将表结构计划应用到数据库（执行 DDL/索引/注释等）
+ *
+ * 根据数据库方言和计划内容，执行相应的 DDL 操作：
+ * - SQLite: 新增字段直接 ALTER，其他操作需要重建表
+ * - MySQL: 尝试在线 DDL（INSTANT/INPLACE）
+ * - PostgreSQL: 直接 ALTER
+ *
+ * @param sql - SQL 客户端实例
+ * @param tableName - 表名
+ * @param fields - 字段定义对象
+ * @param plan - 表结构变更计划
+ */
+export async function applyTablePlan(sql: SQL, tableName: string, fields: Record<string, FieldDefinition>, plan: TablePlan): Promise<void> {
+    if (!plan || !plan.changed) return;
+
+    // SQLite: 仅支持部分 ALTER；需要时走重建
+    if (IS_SQLITE) {
+        if (plan.modifyClauses.length > 0 || plan.defaultClauses.length > 0) {
+            if (IS_PLAN) Logger.debug(`[计划] 重建表 ${tableName} 以应用列修改/默认值变化`);
+            else await rebuildSqliteTable(sql, tableName, fields);
+        } else {
+            for (const c of plan.addClauses) {
+                const stmt = `ALTER TABLE "${tableName}" ${c}`;
+                if (IS_PLAN) Logger.debug(`[计划] ${stmt}`);
+                else await sql.unsafe(stmt);
+            }
+        }
+    } else {
+        const clauses = [...plan.addClauses, ...plan.modifyClauses];
+        if (clauses.length > 0) {
+            const stmt = buildAlterTableSQL(tableName, clauses);
+            if (IS_PLAN) Logger.debug(`[计划] ${stmt}`);
+            else if (IS_MYSQL) await executeDDLSafely(sql, stmt);
+            else await sql.unsafe(stmt);
+        }
+    }
+
+    // 默认值专用 ALTER（SQLite 不支持）
+    if (plan.defaultClauses.length > 0) {
+        if (IS_SQLITE) {
+            Logger.warn(`SQLite 不支持修改默认值，表 ${tableName} 的默认值变更已跳过`);
+        } else {
+            const stmt = buildAlterTableSQL(tableName, plan.defaultClauses);
+            if (IS_PLAN) Logger.debug(`[计划] ${stmt}`);
+            else if (IS_MYSQL) await executeDDLSafely(sql, stmt);
+            else await sql.unsafe(stmt);
+        }
+    }
+
+    // 索引操作
+    for (const act of plan.indexActions) {
+        const stmt = buildIndexSQL(tableName, act.indexName, act.fieldName, act.action);
+        if (IS_PLAN) {
+            Logger.debug(`[计划] ${stmt}`);
+        } else {
+            try {
+                await sql.unsafe(stmt);
+                if (act.action === 'create') {
+                    Logger.debug(`[索引变化] 新建索引 ${tableName}.${act.indexName} (${act.fieldName})`);
+                } else {
+                    Logger.debug(`[索引变化] 删除索引 ${tableName}.${act.indexName} (${act.fieldName})`);
+                }
+            } catch (error: any) {
+                Logger.error(`${act.action === 'create' ? '创建' : '删除'}索引失败`, error);
+                Logger.warn(`表名: ${tableName}, 索引名: ${act.indexName}, 字段: ${act.fieldName}`);
+                throw error;
+            }
+        }
+    }
+
+    // PG 列注释
+    if (IS_PG && plan.commentActions && plan.commentActions.length > 0) {
+        for (const stmt of plan.commentActions) {
+            if (IS_PLAN) Logger.info(`[计划] ${stmt}`);
+            else await sql.unsafe(stmt);
+        }
+    }
+}

package/sync/syncDb/constants.ts

@@ -0,0 +1,76 @@
+/**
+ * syncDb 常量定义模块
+ *
+ * 包含：
+ * - 数据库类型判断
+ * - 版本要求
+ * - 数据类型映射
+ * - 系统字段定义
+ */
+
+/**
+ * 数据库版本要求
+ */
+export const DB_VERSION_REQUIREMENTS = {
+    MYSQL_MIN_MAJOR: 8,
+    POSTGRES_MIN_MAJOR: 17,
+    SQLITE_MIN_VERSION: '3.50.0',
+    SQLITE_MIN_VERSION_NUM: 35000 // 3 * 10000 + 50 * 100
+} as const;
+
+/**
+ * 系统字段定义（所有表都包含的固定字段）
+ */
+export const SYSTEM_FIELDS = {
+    ID: { name: 'id', comment: '主键ID' },
+    CREATED_AT: { name: 'created_at', comment: '创建时间' },
+    UPDATED_AT: { name: 'updated_at', comment: '更新时间' },
+    DELETED_AT: { name: 'deleted_at', comment: '删除时间' },
+    STATE: { name: 'state', comment: '状态字段' }
+} as const;
+
+/**
+ * 需要创建索引的系统字段
+ */
+export const SYSTEM_INDEX_FIELDS = ['created_at', 'updated_at', 'state'] as const;
+
+/**
+ * 字段变更类型的中文标签映射
+ */
+export const CHANGE_TYPE_LABELS = {
+    length: '长度',
+    datatype: '类型',
+    comment: '注释',
+    default: '默认值',
+    nullable: '可空约束',
+    unique: '唯一约束'
+} as const;
+
+/**
+ * MySQL 表配置
+ *
+ * 固定配置说明：
+ * - ENGINE: InnoDB（支持事务、外键）
+ * - CHARSET: utf8mb4（完整 Unicode 支持，包括 Emoji）
+ * - COLLATE: utf8mb4_0900_ai_ci（MySQL 8.0 推荐，不区分重音和大小写）
+ */
+export const MYSQL_TABLE_CONFIG = {
+    ENGINE: 'InnoDB',
+    CHARSET: 'utf8mb4',
+    COLLATE: 'utf8mb4_0900_ai_ci'
+} as const;
+
+// 数据库类型判断
+export const DB = (process.env.DB_TYPE || 'mysql').toLowerCase();
+export const IS_MYSQL = DB === 'mysql';
+export const IS_PG = DB === 'postgresql' || DB === 'postgres';
+export const IS_SQLITE = DB === 'sqlite';
+
+// 字段类型映射（按方言）
+export const typeMapping = {
+    number: IS_SQLITE ? 'INTEGER' : IS_PG ? 'BIGINT' : 'BIGINT',
+    string: IS_SQLITE ? 'TEXT' : IS_PG ? 'character varying' : 'VARCHAR',
+    text: IS_MYSQL ? 'MEDIUMTEXT' : 'TEXT',
+    array_string: IS_SQLITE ? 'TEXT' : IS_PG ? 'character varying' : 'VARCHAR',
+    array_text: IS_MYSQL ? 'MEDIUMTEXT' : 'TEXT'
+};