befly 2.3.3 → 3.0.0

package/scripts/{syncDev.js → syncDev.ts}

@@ -1,31 +1,42 @@
 /**
- * 同步开发管理员账号脚本
- * - 账号: dev
+ * 同步开发者用户到数据库
+ * - 用户名: Env.DEV_USERNAME (默认 dev)
  * - 密码: Crypto2.hmacMd5(Crypto2.md5(Env.DEV_PASSWORD), Env.MD5_SALT)
- * - 行为: 若存在则更新密码与 updated_at；不存在则插入新记录
  */
 
+import { DB } from '../plugins/db.js';
 import { Env } from '../config/env.js';
 import { Logger } from '../utils/logger.js';
-import { createSqlClient } from '../utils/index.js';
 import { Crypto2 } from '../utils/crypto.js';
+import { createSqlClient } from '../utils/dbHelper.js';
 
-// 命令行参数（保持与 syncDb.js 一致的 plan 行为）
+// CLI 参数类型
+interface CliArgs {
+    DRY_RUN: boolean;
+}
+
+// 解析命令行参数
 const ARGV = Array.isArray(process.argv) ? process.argv : [];
-const CLI = { DRY_RUN: ARGV.includes('--plan') };
+const CLI: CliArgs = { DRY_RUN: ARGV.includes('--plan') };
 
-// 执行器封装
-const exec = async (client, query, params = []) => {
-    if (params && params.length > 0) return await client.unsafe(query, params);
+/**
+ * 执行 SQL 查询
+ */
+const exec = async (client: any, query: string, params: any[] = []): Promise<any> => {
+    if (params && params.length > 0) {
+        return await client.unsafe(query, params);
+    }
     return await client.unsafe(query);
 };
 
 /**
  * 同步开发管理员账号
- * @param {import('bun').SQL | null} client 可选，复用已有 SQL 客户端；不传则内部创建与关闭
+ * @param client 可选，复用已有 SQL 客户端；不传则内部创建与关闭
+ * @returns 是否成功
  */
-export async function SyncDev(client = null) {
+export async function SyncDev(client: any = null): Promise<boolean> {
     let ownClient = false;
+
     try {
         if (CLI.DRY_RUN) {
             Logger.info('[计划] 同步完成后将初始化/更新 admin.dev 账号（plan 模式不执行）');
@@ -42,54 +53,59 @@ export async function SyncDev(client = null) {
             ownClient = true;
         }
 
-        // 检查 admin 表是否存在
-        const [exist] = await exec(client, 'SELECT COUNT(*) AS cnt FROM information_schema.TABLES WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ? LIMIT 1', [Env.DB_NAME || '', 'admin']);
-        if (!exist || Number(exist.cnt) === 0) {
-            Logger.warn('跳过开发管理员初始化：未检测到 admin 表');
+        // 检查 sys_admin 表是否存在（核心表带 sys_ 前缀）
+        const exist = await exec(client, 'SELECT COUNT(*) AS cnt FROM information_schema.TABLES WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ? LIMIT 1', [Env.DB_NAME || '', 'sys_admin']);
+
+        if (!exist || !exist[0] || Number(exist[0].cnt) === 0) {
+            Logger.warn('跳过开发管理员初始化：未检测到 sys_admin 表');
             return false;
         }
 
         const nowTs = Date.now();
+        // 对密码进行双重加密
         const hashed = Crypto2.hmacMd5(Crypto2.md5(Env.DEV_PASSWORD), Env.MD5_SALT);
 
         // 更新存在的 dev 账号
-        const updateRes = await exec(client, 'UPDATE `admin` SET `password` = ?, `updated_at` = ? WHERE `account` = ? LIMIT 1', [hashed, nowTs, 'dev']);
+        const updateRes = await exec(client, 'UPDATE `sys_admin` SET `password` = ?, `updated_at` = ? WHERE `account` = ? LIMIT 1', [hashed, nowTs, 'dev']);
+
         const affected = updateRes?.affectedRows ?? updateRes?.rowsAffected ?? 0;
 
         if (!affected || affected === 0) {
             // 插入新账号
             const id = nowTs;
-            await exec(client, 'INSERT INTO `admin` (`id`, `created_at`, `updated_at`, `deleted_at`, `state`, `account`, `password`) VALUES (?, ?, ?, 0, 0, ?, ?)', [id, nowTs, nowTs, 'dev', hashed]);
+            await exec(client, 'INSERT INTO `sys_admin` (`id`, `created_at`, `updated_at`, `deleted_at`, `state`, `account`, `password`) VALUES (?, ?, ?, 0, 0, ?, ?)', [id, nowTs, nowTs, 'dev', hashed]);
             Logger.info('开发管理员已初始化：account=dev');
         } else {
             Logger.info('开发管理员已更新密码并刷新更新时间：account=dev');
         }
 
         return true;
-    } catch (e) {
-        Logger.warn(`开发管理员初始化步骤出错：${e.message}`);
+    } catch (error: any) {
+        Logger.warn(`开发管理员初始化步骤出错：${error.message}`);
         return false;
     } finally {
         if (ownClient && client) {
             try {
                 await client.close();
-            } catch (e) {
-                Logger.warn('关闭数据库连接时出错:', e.message);
+            } catch (error: any) {
+                Logger.warn('关闭数据库连接时出错:', error.message);
             }
         }
     }
 }
 
-// 允许直接运行该脚本
-if (import.meta.url === `file://${process.argv[1]}`) {
+/**
+ * 允许直接运行该脚本
+ */
+if (import.meta.main) {
     SyncDev()
-        .then((ok) => {
+        .then((ok: boolean) => {
             if (CLI.DRY_RUN) {
                 process.exit(0);
             }
             process.exit(ok ? 0 : 1);
         })
-        .catch((err) => {
+        .catch((err: Error) => {
             console.error('❌ 开发管理员同步失败:', err);
             process.exit(1);
         });

package/system.ts

@@ -0,0 +1,149 @@
+/**
+ * Befly 框架系统路径定义 - TypeScript 版本
+ * 提供统一的路径变量，供整个框架使用
+ */
+
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve, relative } from 'node:path';
+
+// 当前文件的路径信息
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Befly 框架根目录
+export const __dirroot = __dirname;
+
+// 各个重要目录的路径
+export const __dirscript = join(__dirroot, 'scripts');
+export const __dirbin = join(__dirroot, 'bin');
+export const __dirutils = join(__dirroot, 'utils');
+export const __dirconfig = join(__dirroot, 'config');
+export const __dirtables = join(__dirroot, 'tables');
+export const __dirchecks = join(__dirroot, 'checks');
+export const __dirapis = join(__dirroot, 'apis');
+export const __dirplugins = join(__dirroot, 'plugins');
+export const __dirlibs = join(__dirroot, 'libs');
+export const __dirtests = join(__dirroot, 'tests');
+
+/**
+ * 获取项目根目录（befly 框架的使用方项目）
+ */
+export const getProjectRoot = (): string => {
+    return process.cwd();
+};
+
+/**
+ * 获取项目中的特定目录
+ * @param subdir - 子目录名称
+ */
+export const getProjectDir = (subdir: string = ''): string => {
+    return subdir ? join(getProjectRoot(), subdir) : getProjectRoot();
+};
+
+/**
+ * 创建路径解析器，基于 befly 根目录
+ * @param paths - 路径片段
+ */
+export const resolveBeflyPath = (...paths: string[]): string => {
+    return resolve(__dirroot, ...paths);
+};
+
+/**
+ * 创建路径解析器，基于项目根目录
+ * @param paths - 路径片段
+ */
+export const resolveProjectPath = (...paths: string[]): string => {
+    return resolve(getProjectRoot(), ...paths);
+};
+
+/**
+ * 获取相对于 befly 根目录的相对路径
+ * @param targetPath - 目标路径
+ */
+export const getRelativeBeflyPath = (targetPath: string): string => {
+    return relative(__dirroot, targetPath);
+};
+
+/**
+ * 获取相对于项目根目录的相对路径
+ * @param targetPath - 目标路径
+ */
+export const getRelativeProjectPath = (targetPath: string): string => {
+    return relative(getProjectRoot(), targetPath);
+};
+
+/**
+ * 系统路径配置对象
+ */
+export interface SystemPaths {
+    script: string;
+    bin: string;
+    utils: string;
+    config: string;
+    tables: string;
+    checks: string;
+    apis: string;
+    plugins: string;
+    libs: string;
+    tests: string;
+}
+
+/**
+ * 系统工具函数集合
+ */
+export interface SystemUtils {
+    getProjectRoot: typeof getProjectRoot;
+    getProjectDir: typeof getProjectDir;
+    resolveBeflyPath: typeof resolveBeflyPath;
+    resolveProjectPath: typeof resolveProjectPath;
+    getRelativeBeflyPath: typeof getRelativeBeflyPath;
+    getRelativeProjectPath: typeof getRelativeProjectPath;
+}
+
+/**
+ * 系统配置对象
+ */
+export interface SystemConfig {
+    __filename: string;
+    __dirname: string;
+    __dirroot: string;
+    paths: SystemPaths;
+    utils: SystemUtils;
+}
+
+/**
+ * 默认导出包含所有路径信息的对象
+ */
+const system: SystemConfig = {
+    // 基础路径变量
+    __filename,
+    __dirname,
+    __dirroot,
+
+    // Befly 框架目录
+    paths: {
+        script: __dirscript,
+        bin: __dirbin,
+        utils: __dirutils,
+        config: __dirconfig,
+        tables: __dirtables,
+        checks: __dirchecks,
+        apis: __dirapis,
+        plugins: __dirplugins,
+        libs: __dirlibs,
+        tests: __dirtests
+    },
+
+    // 工具函数
+    utils: {
+        getProjectRoot,
+        getProjectDir,
+        resolveBeflyPath,
+        resolveProjectPath,
+        getRelativeBeflyPath,
+        getRelativeProjectPath
+    }
+};
+
+// 重新导出基础路径变量和 system 对象
+export { __filename, __dirname, system };

package/tables/_common.json

@@ -0,0 +1,21 @@
+{
+    "id": "ID|number|1|null|null|1|null",
+    "email": "邮箱|string|5|100|null|1|^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$",
+    "phone": "手机号|string|11|11|null|1|^1[3-9]\\d{9}$",
+    "page": "页码|number|1|9999|1|0|null",
+    "limit": "每页数量|number|1|100|10|0|null",
+    "title": "标题|string|1|200|null|0|null",
+    "description": "描述|string|0|500|null|0|null",
+    "keyword": "关键词|string|1|50|null|1|null",
+    "keywords": "关键词列表|array|0|50|null|0|null",
+    "enabled": "启用状态|number|0|1|1|0|^(0|1)$",
+    "date": "日期|string|10|10|null|0|^\\d{4}-\\d{2}-\\d{2}$",
+    "datetime": "日期时间|string|19|25|null|0|^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}",
+    "filename": "文件名|string|1|255|null|0|null",
+    "url": "网址|string|5|500|null|0|^https?://",
+    "tag": "标签|array|0|10|null|0|null",
+    "orderBy": "排序字段|array|0|20|null|0|null",
+    "where": "查询条件|object|null|null|null|0|null",
+    "startTime": "开始时间|number|0|9999999999999|null|0|null",
+    "endTime": "结束时间|number|0|9999999999999|null|0|null"
+}

package/tables/admin.json

@@ -0,0 +1,10 @@
+{
+    "account": "账号|string|3|50|null|1|^[a-zA-Z0-9_]+$",
+    "password": "密码|string|32|255|null|0|null",
+    "nickname": "昵称|string|0|50|null|0|null",
+    "avatar": "头像|string|0|500|null|0|null",
+    "email": "邮箱|string|0|100|null|0|^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$",
+    "phone": "手机号|string|0|11|null|0|^1[3-9]\\d{9}$",
+    "role": "角色|string|1|20|admin|1|^(superadmin|admin|user)$",
+    "status": "状态|number|0|1|1|1|^(0|1)$"
+}

package/tsconfig.json

@@ -0,0 +1,58 @@
+{
+    "compilerOptions": {
+        // 基础配置
+        "target": "ESNext",
+        "module": "ESNext",
+        "lib": ["ESNext"],
+        "moduleResolution": "bundler",
+
+        // 类型检查
+        "strict": true,
+        "noImplicitAny": true,
+        "strictNullChecks": true,
+        "strictFunctionTypes": true,
+        "strictBindCallApply": true,
+        "strictPropertyInitialization": true,
+        "noImplicitThis": true,
+        "alwaysStrict": true,
+
+        // 额外检查
+        "noUnusedLocals": true,
+        "noUnusedParameters": true,
+        "noImplicitReturns": true,
+        "noFallthroughCasesInSwitch": true,
+        "noUncheckedIndexedAccess": false,
+        "noImplicitOverride": true,
+        "noPropertyAccessFromIndexSignature": false,
+
+        // 模块
+        "esModuleInterop": true,
+        "allowSyntheticDefaultImports": true,
+        "forceConsistentCasingInFileNames": true,
+        "resolveJsonModule": true,
+        "isolatedModules": true,
+
+        // 输出
+        "declaration": true,
+        "declarationMap": true,
+        "sourceMap": true,
+        "removeComments": false,
+        "importHelpers": false,
+
+        // 高级
+        "skipLibCheck": true,
+        "allowJs": true,
+        "checkJs": false,
+
+        // Bun 特定
+        "types": ["bun-types"],
+
+        // 路径
+        "baseUrl": ".",
+        "paths": {
+            "@/*": ["./*"]
+        }
+    },
+    "include": ["**/*.ts", "**/*.js"],
+    "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.test.js"]
+}

package/types/api.d.ts

@@ -0,0 +1,246 @@
+/**
+ * Befly API 类型定义
+ */
+
+import type { BeflyContext } from './befly.js';
+import type { KeyValue, TableDefinition } from './common.js';
+import type { RequestContext } from './context.js';
+
+/**
+ * HTTP 方法类型
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+
+/**
+ * 请求上下文类型（已废弃，使用 RequestContext 类）
+ * @deprecated 使用 RequestContext 类替代
+ */
+export interface RequestContext<T = any> {
+    /** 请求对象 */
+    request: Request;
+
+    /** 请求体参数 */
+    body: T;
+
+    /** URL 参数 */
+    query: KeyValue<string>;
+
+    /** 路径参数 */
+    pathParams: KeyValue<string>;
+
+    /** 请求头 */
+    headers: Headers;
+
+    /** 用户信息（认证后） */
+    user?: UserInfo;
+
+    /** 客户端 IP */
+    ip?: string;
+
+    /** User-Agent */
+    userAgent?: string;
+
+    /** 请求 ID */
+    requestId?: string;
+
+    /** 开始时间 */
+    startTime: number;
+}
+
+/**
+ * 用户信息类型
+ */
+export interface UserInfo {
+    id: number;
+    username?: string;
+    email?: string;
+    role?: string;
+    [key: string]: any;
+}
+
+/**
+ * 认证类型
+ * - false: 不需要认证
+ * - true: 需要认证（验证 token）
+ * - 'admin': 需要管理员权限
+ * - 'user': 需要普通用户权限
+ * - string[]: 需要特定角色
+ */
+export type AuthType = boolean | 'admin' | 'user' | string[];
+
+/**
+ * API 处理器函数类型
+ */
+export type ApiHandler<T = any, R = any> = (befly: BeflyContext, ctx: RequestContext, req?: Request) => Promise<Response | R> | Response | R;
+
+/**
+ * 字段规则定义
+ * 键为字段名，值为字段规则字符串
+ */
+export type FieldRules = Record<string, string>;
+
+/**
+ * API 配置选项
+ */
+export interface ApiOptions {
+    /** HTTP 方法 */
+    method: HttpMethod;
+    /** 是否需要认证（true/false/角色数组） */
+    auth?: boolean | string[];
+    /** 字段规则 */
+    fields?: FieldRules;
+    /** 必填字段 */
+    required?: string[];
+    /** 处理函数 */
+    handler: ApiHandler;
+}
+
+/**
+ * API 路由配置
+ */
+export interface ApiRoute<T = any, R = any> {
+    /** HTTP 方法 */
+    method: HttpMethod;
+
+    /** 接口名称 */
+    name: string;
+
+    /** 路由路径（运行时生成） */
+    route?: string;
+
+    /** 认证类型 */
+    auth: boolean | string | string[];
+
+    /** 字段定义（验证规则） */
+    fields: TableDefinition;
+
+    /** 必填字段 */
+    required: string[];
+
+    /** 处理器函数 */
+    handler: ApiHandler<T, R>;
+}
+
+/**
+ * API 构建器接口
+ */
+export interface ApiBuilder {
+    /** 设置 HTTP 方法 */
+    method(method: HttpMethod): this;
+
+    /** 设置路径 */
+    path(path: string): this;
+
+    /** 设置描述 */
+    description(desc: string): this;
+
+    /** 设置认证 */
+    auth(auth: AuthType): this;
+
+    /** 设置验证规则 */
+    rules(rules: KeyValue<string>): this;
+
+    /** 设置必填字段 */
+    required(fields: string[]): this;
+
+    /** 设置处理器 */
+    handler(handler: ApiHandler): this;
+
+    /** 构建路由 */
+    build(): ApiRoute;
+}
+
+/**
+ * API 响应辅助函数
+ */
+export interface ApiResponse {
+    /** 成功响应 */
+    success<T = any>(message: string, data?: T): Response;
+
+    /** 失败响应 */
+    error(message: string, error?: any): Response;
+
+    /** JSON 响应 */
+    json<T = any>(data: T, status?: number): Response;
+
+    /** 文本响应 */
+    text(text: string, status?: number): Response;
+
+    /** HTML 响应 */
+    html(html: string, status?: number): Response;
+
+    /** 重定向 */
+    redirect(url: string, status?: number): Response;
+}
+
+/**
+ * 路由匹配结果
+ */
+export interface RouteMatch {
+    /** 路由配置 */
+    route: ApiRoute;
+
+    /** 路径参数 */
+    params: KeyValue<string>;
+}
+
+/**
+ * 路由器接口
+ */
+export interface Router {
+    /** 添加路由 */
+    add(route: ApiRoute): void;
+
+    /** 匹配路由 */
+    match(method: HttpMethod, path: string): RouteMatch | null;
+
+    /** 获取所有路由 */
+    getRoutes(): ApiRoute[];
+
+    /** 删除路由 */
+    remove(method: HttpMethod, path: string): boolean;
+}
+
+// ========== API 响应数据类型 ==========
+
+/**
+ * 令牌检测响应数据
+ */
+export interface TokenCheckData {
+    /** 令牌是否有效 */
+    valid: boolean;
+    /** JWT 载荷（有效时返回） */
+    payload?: any;
+    /** 过期时间（秒） */
+    expiresIn?: number;
+}
+
+/**
+ * 健康检查响应数据
+ */
+export interface HealthInfo {
+    /** 服务状态 */
+    status: string;
+    /** 时间戳 */
+    timestamp: string;
+    /** 运行时长（秒） */
+    uptime: number;
+    /** 内存使用情况 */
+    memory: NodeJS.MemoryUsage;
+    /** 运行时名称 */
+    runtime: string;
+    /** 版本号 */
+    version: string;
+    /** 平台 */
+    platform: string;
+    /** 架构 */
+    arch: string;
+    /** Redis 状态 */
+    redis?: string;
+    /** Redis 错误信息 */
+    redisError?: string;
+    /** 数据库状态 */
+    database?: string;
+    /** 数据库错误信息 */
+    databaseError?: string;
+}