sa2kit 1.6.44 → 1.6.45

package/dist/universalFile/server/index.d.ts

@@ -1,8 +1,9 @@
-import { a as UniversalFileServiceConfig, S as StorageConfig, I as IStorageProvider, b as StorageType, c as UploadFileInfo, d as StorageResult, e as ICDNProvider, C as CDNType, f as CDNConfig, g as CDNResult, h as IFileProcessor, P as ProcessorType, i as ProcessingOptions, j as ProcessingResult, k as IFileMetadataRepository, A as AliyunOSSConfig, l as AliyunCDNConfig, L as LocalStorageConfig, U as UniversalFileService } from '../../UniversalFileService-Ct4baUMz.js';
+import { a as UniversalFileServiceConfig, S as StorageConfig, I as IStorageProvider, b as StorageType, c as UploadFileInfo, d as StorageResult, e as ICDNProvider, C as CDNType, f as CDNConfig, g as CDNResult, h as IFileProcessor, P as ProcessorType, i as ProcessingOptions, j as ProcessingResult, k as IFileMetadataRepository, U as UniversalFileService, A as AliyunOSSConfig, l as AliyunCDNConfig, L as LocalStorageConfig } from '../../UniversalFileService-Ct4baUMz.js';
 export { B as CDNProviderError, o as CDNStats, m as CacheConfig, t as FileEvent, u as FileEventListener, v as FileEventType, y as FileProcessingError, r as FileQueryOptions, q as FileRecord, w as FileServiceError, F as FileServicePersistenceConfig, x as FileUploadError, s as PaginatedResult, p as ProcessorInfo, n as StorageMetadata, z as StorageProviderError } from '../../UniversalFileService-Ct4baUMz.js';
 import { I as ImageProcessingOptions, l as AudioProcessingOptions, V as VideoProcessingOptions } from '../../types-CK4We_aI.js';
 import { EventEmitter } from 'events';
 import { NextResponse } from 'next/server';
+import { drizzle } from 'drizzle-orm/postgres-js';
 import * as drizzle_orm from 'drizzle-orm';
 import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
 
@@ -1105,6 +1106,10 @@ declare class CacheManager {
      */
     close(): Promise<void>;
 }
+/**
+ * 单例缓存管理器实例
+ */
+declare const cacheManager: CacheManager;
 
 /**
  * 通用文件服务性能监控器
@@ -1301,6 +1306,10 @@ declare class PerformanceMonitor {
      */
     reset(): void;
 }
+/**
+ * 单例性能监控器实例
+ */
+declare const performanceMonitor: PerformanceMonitor;
 
 /**
  * CDN缓存策略管理
@@ -1903,6 +1912,152 @@ declare class ApiError extends Error {
      */
     toNextResponse(): NextResponse;
 }
+/**
+ * API错误工厂类
+ * 提供便捷的错误创建方法
+ */
+declare class ApiErrorFactory {
+    /**
+     * 创建文件不存在错误
+     */
+    static fileNotFound(fileId?: string): ApiError;
+    /**
+     * 创建文件过大错误
+     */
+    static fileTooLarge(maxSize: number, actualSize: number): ApiError;
+    /**
+     * 创建不支持的文件类型错误
+     */
+    static fileTypeNotSupported(mimeType: string, supportedTypes?: string[]): ApiError;
+    /**
+     * 创建文件上传失败错误
+     */
+    static fileUploadFailed(reason?: string): ApiError;
+    /**
+     * 创建文件夹不存在错误
+     */
+    static folderNotFound(folderId?: string): ApiError;
+    /**
+     * 创建文件夹不为空错误
+     */
+    static folderNotEmpty(folderId: string, fileCount: number, subfolderCount: number): ApiError;
+    /**
+     * 创建参数验证错误
+     */
+    static validationError(field: string, value: any, rule: string): ApiError;
+    /**
+     * 创建身份验证错误
+     */
+    static authenticationError(reason?: string): ApiError;
+    /**
+     * 创建权限不足错误
+     */
+    static authorizationError(resource?: string, action?: string): ApiError;
+    /**
+     * 创建资源冲突错误
+     */
+    static conflict(resource: string, reason?: string): ApiError;
+    /**
+     * 创建请求频率超限错误
+     */
+    static rateLimitExceeded(limit: number, windowMs: number): ApiError;
+    /**
+     * 创建存储服务错误
+     */
+    static storageProviderError(provider: string, reason?: string): ApiError;
+    /**
+     * 创建存储配额已满错误
+     */
+    static storageQuotaExceeded(used: number, limit: number): ApiError;
+    /**
+     * 创建分享不存在错误
+     */
+    static shareNotFound(shareCode?: string): ApiError;
+    /**
+     * 创建分享已过期错误
+     */
+    static shareExpired(shareCode: string, expiredAt: string): ApiError;
+    /**
+     * 创建分享密码错误
+     */
+    static sharePasswordIncorrect(shareCode: string): ApiError;
+    /**
+     * 创建分享下载次数超限错误
+     */
+    static shareDownloadLimitExceeded(shareCode: string, maxDownloads: number): ApiError;
+}
+/**
+ * API响应工具类
+ * 提供标准化的成功响应格式
+ */
+declare class ApiResponseHelper {
+    /**
+     * 创建成功响应
+     */
+    static success<T>(data?: T, meta?: {
+        total?: number;
+        page?: number;
+        pageSize?: number;
+        totalPages?: number;
+        requestId?: string;
+    }): ApiResponse<T>;
+    /**
+     * 创建分页响应
+     */
+    static paginated<T>(data: T[], total: number, page: number, pageSize: number, requestId?: string): ApiResponse<{
+        items: T[];
+        pagination: any;
+    }>;
+    /**
+     * 创建空响应
+     */
+    static empty(requestId?: string): ApiResponse<null>;
+    /**
+     * 转换为NextResponse
+     */
+    static toNextResponse<T>(response: ApiResponse<T>, status?: number): NextResponse;
+}
+/**
+ * 参数验证工具
+ */
+declare class ValidationHelper {
+    /**
+     * 验证必填参数
+     */
+    static required(value: any, fieldName: string): void;
+    /**
+     * 验证字符串长度
+     */
+    static stringLength(value: string, fieldName: string, min?: number, max?: number): void;
+    /**
+     * 验证数字范围
+     */
+    static numberRange(value: number, fieldName: string, min?: number, max?: number): void;
+    /**
+     * 验证数组长度
+     */
+    static arrayLength(value: any[], fieldName: string, min?: number, max?: number): void;
+    /**
+     * 验证文件类型
+     */
+    static fileType(mimeType: string, allowedTypes: string[]): void;
+    /**
+     * 验证文件大小
+     */
+    static fileSize(size: number, maxSize: number): void;
+    /**
+     * 验证UUID格式
+     */
+    static uuid(value: string, fieldName: string): void;
+    /**
+     * 验证邮箱格式
+     */
+    static email(value: string, fieldName: string): void;
+    /**
+     * 验证URL格式
+     */
+    static url(value: string, fieldName: string): void;
+}
 
 /**
  * Drizzle ORM 文件元数据持久化适配器
@@ -1978,281 +2133,50 @@ interface DrizzleRepositoryConfig {
 declare function createDrizzleRepository(config: DrizzleRepositoryConfig): IFileMetadataRepository;
 
 /**
- * 文件服务配置加载辅助工具
+ * Drizzle ORM 适配器
  *
- * 提供从环境变量加载配置、默认配置常量等通用功能
+ * 实现 IFileMetadataRepository 接口
  */
 
-/**
- * 默认文件大小限制（字节）
- */
-declare const DEFAULT_MAX_FILE_SIZE = 104857600;
-/**
- * 默认允许的 MIME 类型
- */
-declare const DEFAULT_ALLOWED_MIME_TYPES: string[];
-/**
- * 默认缓存配置
- */
-declare const DEFAULT_CACHE_CONFIG: {
-    enabled: boolean;
-    metadataTTL: number;
-    urlTTL: number;
-};
-/**
- * 默认文件服务配置
- */
-declare const DEFAULT_FILE_SERVICE_CONFIG: {
-    readonly maxFileSize: 104857600;
-    readonly allowedMimeTypes: string[];
-    readonly cache: {
-        enabled: boolean;
-        metadataTTL: number;
-        urlTTL: number;
-    };
-    readonly enableMonitoring: false;
-};
-/**
- * 从环境变量加载阿里云 OSS 配置
- *
- * 支持的环境变量：
- * - ALIYUN_OSS_REGION
- * - ALIYUN_OSS_BUCKET
- * - ALIYUN_OSS_ACCESS_KEY_ID
- * - ALIYUN_OSS_ACCESS_KEY_SECRET
- * - ALIYUN_OSS_CUSTOM_DOMAIN (可选)
- * - ALIYUN_OSS_SECURE (可选，默认 false)
- * - ALIYUN_OSS_INTERNAL (可选，默认 false)
- */
-declare function loadOSSConfigFromEnv(): AliyunOSSConfig | null;
-/**
- * 从环境变量加载阿里云 CDN 配置
- *
- * 支持的环境变量：
- * - ALIYUN_CDN_DOMAIN
- * - ALIYUN_CDN_ACCESS_KEY_ID
- * - ALIYUN_CDN_ACCESS_KEY_SECRET
- * - ALIYUN_CDN_REGION (可选)
- */
-declare function loadCDNConfigFromEnv(): AliyunCDNConfig | null;
-/**
- * 获取默认本地存储配置
- *
- * 支持的环境变量：
- * - FILE_STORAGE_PATH (可选，默认 'uploads')
- * - FILE_BASE_URL (可选，默认 '/uploads')
- */
-declare function getDefaultLocalStorage(): LocalStorageConfig;
-/**
- * 从环境变量加载完整的文件服务配置
- *
- * 配置优先级：
- * 1. 阿里云 OSS（如果配置完整）
- * 2. 本地存储（备用方案）
- *
- * 支持的环境变量：
- * - MAX_FILE_SIZE (可选，默认 100MB)
- * - ENABLE_CACHE (可选，默认 false)
- * - METADATA_CACHE_TTL (可选，默认 3600秒)
- * - URL_CACHE_TTL (可选，默认 1800秒)
- * - ENABLE_FILE_MONITORING (可选，默认 false)
- */
-declare function loadConfigFromEnv(): Partial<UniversalFileServiceConfig>;
-/**
- * 配置服务接口
- *
- * 用于从配置管理系统加载配置
- */
-interface IConfigService {
-    /**
-     * 获取配置值
-     */
-    getConfig(key: string, defaultValue?: any): Promise<any>;
-}
-/**
- * 配置键映射
- */
-interface OSSConfigKeyMapping {
-    region: string;
-    bucket: string;
-    accessKeyId: string;
-    accessKeySecret: string;
-    customDomain?: string;
-    secure?: string;
-    internal?: string;
+interface DrizzleAdapterOptions {
+    db: any;
+    fileMetadata: any;
+    fileStorageProviders: any;
 }
+declare function createDrizzleFileRepository(options: DrizzleAdapterOptions): IFileMetadataRepository;
+
 /**
- * 默认的 OSS 配置键映射（阿里云标准）
- */
-declare const DEFAULT_OSS_CONFIG_KEYS: OSSConfigKeyMapping;
-/**
- * 从配置服务加载 OSS 配置
+ * 通用文件服务 - PostgreSQL 数据库表结构定义
  *
- * 通用函数，可用于任何实现了 IConfigService 接口的配置系统
+ * 这个文件定义了通用文件服务的完整数据库表结构，使用Drizzle ORM框架。
+ * 支持多模块文件管理、版本控制、分享功能、处理记录等。
  *
- * @param configService - 配置服务实例
- * @param keyMapping - 配置键映射（可选，默认使用标准键名）
+ * 表结构概览：
+ * - file_storage_providers: 存储提供者配置表
+ * - file_folders: 文件夹表（支持层级结构）
+ * - file_metadata: 文件元数据主表
+ * - file_versions: 文件版本表
+ * - file_processing_records: 文件处理记录表
+ * - file_shares: 文件分享表
+ * - file_access_logs: 文件访问日志表
+ * - file_thumbnails: 文件缩略图表
  *
- * @example
- * ```typescript
- * import { loadOSSConfigFromService } from 'sa2kit/universalFile/server';
+ * 设计特点：
+ * - 支持多存储提供者（本地、OSS、CDN等）
+ * - 完整的文件版本管理
+ * - 灵活的文件夹层级结构
+ * - 详细的访问日志和统计
+ * - 文件处理流水线记录
+ * - 安全的分享机制
  *
- * const config = await loadOSSConfigFromService(myConfigService, {
- *   region: 'oss_region',
- *   bucket: 'oss_bucket',
- *   // ...
- * });
- * ```
+ * @fileoverview 数据库表结构 - 通用文件服务 (PostgreSQL)
+ * @package sa2kit/universalFile/server
  */
-declare function loadOSSConfigFromService(configService: IConfigService, keyMapping?: Partial<OSSConfigKeyMapping>): Promise<AliyunOSSConfig | null>;
 /**
- * 组合多个配置源
- *
- * 按优先级顺序尝试加载配置，返回第一个成功的配置
- *
- * @param loaders - 配置加载器数组（按优先级排序）
+ * 存储提供者配置表 (file_storage_providers)
  *
- * @example
- * ```typescript
- * const config = await loadConfigWithFallback([
- *   async () => loadOSSConfigFromService(configService),
- *   () => loadOSSConfigFromEnv(),
- * ]);
- * ```
- */
-declare function loadConfigWithFallback<T>(loaders: Array<() => Promise<T | null>>): Promise<T | null>;
-/**
- * 文件服务工厂选项
- */
-interface FileServiceFactoryOptions {
-    /**
-     * 配置加载器（按优先级排序）
-     */
-    configLoaders?: Array<() => Promise<Partial<UniversalFileServiceConfig> | null>>;
-    /**
-     * 持久化仓储（可选）
-     */
-    repository?: any;
-    /**
-     * 自定义配置（会覆盖加载的配置）
-     */
-    customConfig?: Partial<UniversalFileServiceConfig>;
-    /**
-     * 是否自动初始化服务
-     */
-    autoInitialize?: boolean;
-}
-/**
- * 创建文件服务（工厂函数）
- *
- * 通用的服务创建函数，支持多种配置源和可选的持久化
- *
- * @param options - 工厂选项
- *
- * @example
- * ```typescript
- * import {
- *   createFileServiceWithFactory,
- *   loadOSSConfigFromService,
- *   loadConfigFromEnv
- * } from 'sa2kit/universalFile/server';
- *
- * const service = await createFileServiceWithFactory({
- *   configLoaders: [
- *     async () => {
- *       const ossConfig = await loadOSSConfigFromService(configService);
- *       return ossConfig ? { storage: ossConfig, defaultStorage: 'aliyun-oss' } : null;
- *     },
- *     () => Promise.resolve(loadConfigFromEnv()),
- *   ],
- *   repository: myRepository,
- *   autoInitialize: true,
- * });
- * ```
- */
-declare function createFileServiceWithFactory(options?: FileServiceFactoryOptions): Promise<UniversalFileService>;
-/**
- * 单例工厂返回值
- */
-interface SingletonFactory<T> {
-    /**
-     * 获取单例实例
-     */
-    get(): Promise<T>;
-    /**
-     * 重置单例（主要用于测试）
-     */
-    reset(): void;
-    /**
-     * 检查单例是否已创建
-     */
-    isCreated(): boolean;
-}
-/**
- * 创建单例工厂
- *
- * 提供单例模式的通用实现，适用于需要单例的服务
- *
- * @param factory - 创建实例的工厂函数
- * @param options - 单例选项
- *
- * @example
- * ```typescript
- * const fileServiceSingleton = createSingleton(
- *   async () => {
- *     const service = new UniversalFileService(config);
- *     await service.initialize();
- *     return service;
- *   },
- *   { autoInitialize: true }
- * );
- *
- * // 获取单例
- * const service = await fileServiceSingleton.get();
- *
- * // 重置（测试用）
- * fileServiceSingleton.reset();
- * ```
- */
-declare function createSingleton<T>(factory: () => Promise<T>, options?: {
-    /** 是否在第一次获取时自动初始化（默认 true） */
-    autoInitialize?: boolean;
-    /** 单例名称（用于日志） */
-    name?: string;
-}): SingletonFactory<T>;
-
-/**
- * 通用文件服务 - PostgreSQL 数据库表结构定义
- *
- * 这个文件定义了通用文件服务的完整数据库表结构，使用Drizzle ORM框架。
- * 支持多模块文件管理、版本控制、分享功能、处理记录等。
- *
- * 表结构概览：
- * - file_storage_providers: 存储提供者配置表
- * - file_folders: 文件夹表（支持层级结构）
- * - file_metadata: 文件元数据主表
- * - file_versions: 文件版本表
- * - file_processing_records: 文件处理记录表
- * - file_shares: 文件分享表
- * - file_access_logs: 文件访问日志表
- * - file_thumbnails: 文件缩略图表
- *
- * 设计特点：
- * - 支持多存储提供者（本地、OSS、CDN等）
- * - 完整的文件版本管理
- * - 灵活的文件夹层级结构
- * - 详细的访问日志和统计
- * - 文件处理流水线记录
- * - 安全的分享机制
- *
- * @fileoverview 数据库表结构 - 通用文件服务 (PostgreSQL)
- * @package sa2kit/universalFile/server
- */
-/**
- * 存储提供者配置表 (file_storage_providers)
- *
- * 管理不同的文件存储提供者配置，支持本地存储、云存储等多种方式。
- * 每个提供者有独立的配置和优先级设置。
+ * 管理不同的文件存储提供者配置，支持本地存储、云存储等多种方式。
+ * 每个提供者有独立的配置和优先级设置。
  */
 declare const fileStorageProviders: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "file_storage_providers";
@@ -4513,4 +4437,407 @@ type NewFileAccessLog = typeof fileAccessLogs.$inferInsert;
 type FileThumbnail = typeof fileThumbnails.$inferSelect;
 type NewFileThumbnail = typeof fileThumbnails.$inferInsert;
 
-export { AliyunCDNConfig, AliyunCDNProvider, AliyunOSSConfig, AliyunOSSProvider, ApiError, ApiErrorCode, type ApiResponse, AudioProcessor, CDNConfig, CDNResult, CDNType, CacheManager, CacheStrategyType$1 as CacheStrategyType, CdnCacheStrategy, ConfigValidationError, DEFAULT_ALLOWED_MIME_TYPES, DEFAULT_CACHE_CONFIG, DEFAULT_FILE_SERVICE_CONFIG, DEFAULT_MAX_FILE_SIZE, DEFAULT_OSS_CONFIG_KEYS, type DrizzleDb, type DrizzleRepositoryConfig, type DrizzleTable, ErrorHttpStatusMap, ErrorMessages, type FieldMapping, type FileAccessLog, type FileFolder, type FileInfo, type FileListResponse, type FileMetadata, type FileProcessParams, type FileProcessingRecord, type FileQueryParams, type FileServiceFactoryOptions, type FileShare, type FileStats, type FileStorageProvider, type FileThumbnail, type FileUpdateParams, type FileUploadParams, type FileVersion, type FolderCreateParams, type FolderInfo, type FolderUpdateParams, ICDNProvider, type IConfigService, IFileMetadataRepository, IFileProcessor, IStorageProvider, ImageProcessor, LocalStorageConfig, LocalStorageProvider, type NewFileAccessLog, type NewFileFolder, type NewFileMetadata, type NewFileProcessingRecord, type NewFileShare, type NewFileStorageProvider, type NewFileThumbnail, type NewFileVersion, type OSSConfigKeyMapping, type PaginationParams, PerformanceMonitor, ProcessingOptions, ProcessingQueue, ProcessingResult, type ProcessingStatus, ProcessorType, type ShareAccessParams, type ShareCreateParams, type ShareInfo, type SingletonFactory, StorageConfig, StorageResult, StorageType, UniversalFileService, UniversalFileServiceConfig, UploadFileInfo, type UploadResponse, VideoProcessor, cdnCacheStrategy, createAliyunOSSPreset, createDocumentServicePreset, createDrizzleRepository, createFileServiceConfig, createFileServiceFromEnv, createFileServiceWithFactory, createImageServicePreset, createLocalDevPreset, createSingleton, createSmartPreset, createUniversalFileService, createVideoServicePreset, fileAccessLogs, fileAccessLogsRelations, fileFolders, fileFoldersRelations, fileMetadata, fileMetadataRelations, fileProcessingRecords, fileProcessingRecordsRelations, fileShares, fileSharesRelations, fileStorageProviders, fileStorageProvidersRelations, fileThumbnails, fileThumbnailsRelations, fileVersions, fileVersionsRelations, getDefaultLocalStorage, getMimeType, getRequiredEnvVars, loadCDNConfigFromEnv, loadConfigFromEnv, loadConfigWithFallback, loadOSSConfigFromEnv, loadOSSConfigFromService, validateEnvironment, validateServiceConfig, validateStorageConfig };
+/**
+ * 通用文件服务数据库操作类
+ * 提供基础的文件数据库CRUD操作
+ */
+
+interface FileQueryOptions {
+    moduleId?: string;
+    businessId?: string;
+    folderId?: string;
+    offset?: number;
+    limit?: number;
+    isDeleted?: boolean;
+    uploaderId?: string;
+}
+declare class FileDbService {
+    private db;
+    constructor(db: ReturnType<typeof drizzle>);
+    getDefaultStorageProvider(): Promise<FileStorageProvider | null>;
+    createStorageProvider(provider: NewFileStorageProvider): Promise<FileStorageProvider>;
+    getFolderByPath(path: string, moduleId?: string): Promise<FileFolder | null>;
+    createFolder(folder: NewFileFolder): Promise<FileFolder>;
+    getFiles(options?: FileQueryOptions): Promise<{
+        files: FileMetadata[];
+        total: number;
+    }>;
+    getFileById(id: string): Promise<FileMetadata | null>;
+    createFile(file: NewFileMetadata): Promise<FileMetadata>;
+    updateFile(id: string, updates: Partial<FileMetadata>): Promise<FileMetadata>;
+    deleteFile(id: string): Promise<void>;
+    getFolderById(folderId: string): Promise<FileFolder | null>;
+    getFolders(moduleId?: string, businessId?: string): Promise<FileFolder[]>;
+    updateFolder(folderId: string, updates: Partial<FileFolder>): Promise<FileFolder>;
+    deleteFolder(folderId: string): Promise<void>;
+    countFolderContents(folderId: string): Promise<{
+        files: number;
+        folders: number;
+    }>;
+    createFileVersion(version: NewFileVersion): Promise<void>;
+    createProcessingRecord(record: NewFileProcessingRecord): Promise<void>;
+    createShare(share: NewFileShare): Promise<void>;
+    createAccessLog(log: NewFileAccessLog): Promise<void>;
+    createThumbnail(thumbnail: NewFileThumbnail): Promise<void>;
+    listDeletedFiles(): Promise<FileMetadata[]>;
+    clearDeletedFiles(days?: number): Promise<number>;
+    getStorageStats(): Promise<{
+        totalFiles: number;
+        totalSize: number;
+        byStorage: {
+            storageProviderId: number;
+            count: number;
+            totalSize: number;
+        }[];
+    }>;
+}
+
+/**
+ * 数据库查询优化中间件
+ */
+declare class QueryOptimizer {
+    private queryHistory;
+    private readonly maxHistorySize;
+    private readonly slowQueryThreshold;
+    monitorQuery<T>(queryFn: () => Promise<T>, sql: string, params?: any[]): Promise<T>;
+    private getQueryType;
+    private addQueryToHistory;
+    getQueryStats(): {
+        total: number;
+        byType: Record<string, number>;
+        slowQueries: number;
+        averageDuration: number;
+        maxDuration: number;
+        minDuration: number;
+    };
+}
+declare const queryOptimizer: QueryOptimizer;
+
+/**
+ * 通用文件服务配置管理
+ */
+
+interface FileServiceConfig {
+    defaultStorage: StorageType;
+    storageProviders: Record<string, StorageConfig>;
+    defaultCDN: CDNType;
+    cdnProviders: Record<string, CDNConfig>;
+    maxFileSize: number;
+    allowedMimeTypes: string[];
+    enableProcessing: boolean;
+    processingQueueSize: number;
+    cache: {
+        metadataTTL: number;
+        urlTTL: number;
+    };
+}
+/**
+ * 配置管理器
+ */
+declare class FileServiceConfigManager {
+    private config;
+    constructor(customConfig?: Partial<FileServiceConfig>);
+    /**
+     * 获取完整配置
+     */
+    getConfig(): FileServiceConfig;
+    /**
+     * 获取存储提供者配置
+     */
+    getStorageConfig(type: StorageType): StorageConfig | undefined;
+    /**
+     * 获取CDN提供者配置
+     */
+    getCDNConfig(type: CDNType): CDNConfig | undefined;
+    /**
+     * 更新配置
+     */
+    updateConfig(updates: Partial<FileServiceConfig>): void;
+    /**
+     * 启用存储提供者
+     */
+    enableStorageProvider(type: StorageType, config?: Partial<StorageConfig>): void;
+    /**
+     * 禁用存储提供者
+     */
+    disableStorageProvider(type: StorageType): void;
+    /**
+     * 启用CDN提供者
+     */
+    enableCDNProvider(type: CDNType, config?: Partial<CDNConfig>): void;
+    /**
+     * 禁用CDN提供者
+     */
+    disableCDNProvider(type: CDNType): void;
+    /**
+     * 从环境变量加载阿里云OSS配置
+     */
+    loadAliyunOSSFromEnv(): void;
+    /**
+     * 从环境变量加载阿里云CDN配置
+     */
+    loadAliyunCDNFromEnv(): void;
+    /**
+     * 验证配置
+     */
+    private validateConfig;
+    /**
+     * 深度合并配置
+     */
+    private mergeConfig;
+}
+/**
+ * 创建配置管理器
+ */
+declare function createFileServiceConfigWithConfigManager(customConfig?: Partial<FileServiceConfig>): Promise<FileServiceConfigManager>;
+
+/**
+ * 创建支持动态配置加载的通用文件服务
+ */
+declare function createUniversalFileServiceWithConfigManager(): Promise<UniversalFileService>;
+
+/**
+ * 文件服务配置加载辅助工具
+ *
+ * 提供从环境变量加载配置、默认配置常量等通用功能
+ */
+
+/**
+ * 默认文件大小限制（字节）
+ */
+declare const DEFAULT_MAX_FILE_SIZE = 104857600;
+/**
+ * 默认允许的 MIME 类型
+ */
+declare const DEFAULT_ALLOWED_MIME_TYPES: string[];
+/**
+ * 默认缓存配置
+ */
+declare const DEFAULT_CACHE_CONFIG: {
+    enabled: boolean;
+    metadataTTL: number;
+    urlTTL: number;
+};
+/**
+ * 默认文件服务配置
+ */
+declare const DEFAULT_FILE_SERVICE_CONFIG: {
+    readonly maxFileSize: 104857600;
+    readonly allowedMimeTypes: string[];
+    readonly cache: {
+        enabled: boolean;
+        metadataTTL: number;
+        urlTTL: number;
+    };
+    readonly enableMonitoring: false;
+};
+/**
+ * 从环境变量加载阿里云 OSS 配置
+ *
+ * 支持的环境变量：
+ * - ALIYUN_OSS_REGION
+ * - ALIYUN_OSS_BUCKET
+ * - ALIYUN_OSS_ACCESS_KEY_ID
+ * - ALIYUN_OSS_ACCESS_KEY_SECRET
+ * - ALIYUN_OSS_CUSTOM_DOMAIN (可选)
+ * - ALIYUN_OSS_SECURE (可选，默认 false)
+ * - ALIYUN_OSS_INTERNAL (可选，默认 false)
+ */
+declare function loadOSSConfigFromEnv(): AliyunOSSConfig | null;
+/**
+ * 从环境变量加载阿里云 CDN 配置
+ *
+ * 支持的环境变量：
+ * - ALIYUN_CDN_DOMAIN
+ * - ALIYUN_CDN_ACCESS_KEY_ID
+ * - ALIYUN_CDN_ACCESS_KEY_SECRET
+ * - ALIYUN_CDN_REGION (可选)
+ */
+declare function loadCDNConfigFromEnv(): AliyunCDNConfig | null;
+/**
+ * 获取默认本地存储配置
+ *
+ * 支持的环境变量：
+ * - FILE_STORAGE_PATH (可选，默认 'uploads')
+ * - FILE_BASE_URL (可选，默认 '/uploads')
+ */
+declare function getDefaultLocalStorage(): LocalStorageConfig;
+/**
+ * 从环境变量加载完整的文件服务配置
+ *
+ * 配置优先级：
+ * 1. 阿里云 OSS（如果配置完整）
+ * 2. 本地存储（备用方案）
+ *
+ * 支持的环境变量：
+ * - MAX_FILE_SIZE (可选，默认 100MB)
+ * - ENABLE_CACHE (可选，默认 false)
+ * - METADATA_CACHE_TTL (可选，默认 3600秒)
+ * - URL_CACHE_TTL (可选，默认 1800秒)
+ * - ENABLE_FILE_MONITORING (可选，默认 false)
+ */
+declare function loadConfigFromEnv(): Partial<UniversalFileServiceConfig>;
+/**
+ * 配置服务接口
+ *
+ * 用于从配置管理系统加载配置
+ */
+interface IConfigService {
+    /**
+     * 获取配置值
+     */
+    getConfig(key: string, defaultValue?: any): Promise<any>;
+}
+/**
+ * 配置键映射
+ */
+interface OSSConfigKeyMapping {
+    region: string;
+    bucket: string;
+    accessKeyId: string;
+    accessKeySecret: string;
+    customDomain?: string;
+    secure?: string;
+    internal?: string;
+}
+/**
+ * 默认的 OSS 配置键映射（阿里云标准）
+ */
+declare const DEFAULT_OSS_CONFIG_KEYS: OSSConfigKeyMapping;
+/**
+ * 从配置服务加载 OSS 配置
+ *
+ * 通用函数，可用于任何实现了 IConfigService 接口的配置系统
+ *
+ * @param configService - 配置服务实例
+ * @param keyMapping - 配置键映射（可选，默认使用标准键名）
+ *
+ * @example
+ * ```typescript
+ * import { loadOSSConfigFromService } from 'sa2kit/universalFile/server';
+ *
+ * const config = await loadOSSConfigFromService(myConfigService, {
+ *   region: 'oss_region',
+ *   bucket: 'oss_bucket',
+ *   // ...
+ * });
+ * ```
+ */
+declare function loadOSSConfigFromService(configService: IConfigService, keyMapping?: Partial<OSSConfigKeyMapping>): Promise<AliyunOSSConfig | null>;
+/**
+ * 组合多个配置源
+ *
+ * 按优先级顺序尝试加载配置，返回第一个成功的配置
+ *
+ * @param loaders - 配置加载器数组（按优先级排序）
+ *
+ * @example
+ * ```typescript
+ * const config = await loadConfigWithFallback([
+ *   async () => loadOSSConfigFromService(configService),
+ *   () => loadOSSConfigFromEnv(),
+ * ]);
+ * ```
+ */
+declare function loadConfigWithFallback<T>(loaders: Array<() => Promise<T | null>>): Promise<T | null>;
+/**
+ * 文件服务工厂选项
+ */
+interface FileServiceFactoryOptions {
+    /**
+     * 配置加载器（按优先级排序）
+     */
+    configLoaders?: Array<() => Promise<Partial<UniversalFileServiceConfig> | null>>;
+    /**
+     * 持久化仓储（可选）
+     */
+    repository?: any;
+    /**
+     * 自定义配置（会覆盖加载的配置）
+     */
+    customConfig?: Partial<UniversalFileServiceConfig>;
+    /**
+     * 是否自动初始化服务
+     */
+    autoInitialize?: boolean;
+}
+/**
+ * 创建文件服务（工厂函数）
+ *
+ * 通用的服务创建函数，支持多种配置源和可选的持久化
+ *
+ * @param options - 工厂选项
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createFileServiceWithFactory,
+ *   loadOSSConfigFromService,
+ *   loadConfigFromEnv
+ * } from 'sa2kit/universalFile/server';
+ *
+ * const service = await createFileServiceWithFactory({
+ *   configLoaders: [
+ *     async () => {
+ *       const ossConfig = await loadOSSConfigFromService(configService);
+ *       return ossConfig ? { storage: ossConfig, defaultStorage: 'aliyun-oss' } : null;
+ *     },
+ *     () => Promise.resolve(loadConfigFromEnv()),
+ *   ],
+ *   repository: myRepository,
+ *   autoInitialize: true,
+ * });
+ * ```
+ */
+declare function createFileServiceWithFactory(options?: FileServiceFactoryOptions): Promise<UniversalFileService>;
+/**
+ * 单例工厂返回值
+ */
+interface SingletonFactory<T> {
+    /**
+     * 获取单例实例
+     */
+    get(): Promise<T>;
+    /**
+     * 重置单例（主要用于测试）
+     */
+    reset(): void;
+    /**
+     * 检查单例是否已创建
+     */
+    isCreated(): boolean;
+}
+/**
+ * 创建单例工厂
+ *
+ * 提供单例模式的通用实现，适用于需要单例的服务
+ *
+ * @param factory - 创建实例的工厂函数
+ * @param options - 单例选项
+ *
+ * @example
+ * ```typescript
+ * const fileServiceSingleton = createSingleton(
+ *   async () => {
+ *     const service = new UniversalFileService(config);
+ *     await service.initialize();
+ *     return service;
+ *   },
+ *   { autoInitialize: true }
+ * );
+ *
+ * // 获取单例
+ * const service = await fileServiceSingleton.get();
+ *
+ * // 重置（测试用）
+ * fileServiceSingleton.reset();
+ * ```
+ */
+declare function createSingleton<T>(factory: () => Promise<T>, options?: {
+    /** 是否在第一次获取时自动初始化（默认 true） */
+    autoInitialize?: boolean;
+    /** 单例名称（用于日志） */
+    name?: string;
+}): SingletonFactory<T>;
+
+export { AliyunCDNConfig, AliyunCDNProvider, AliyunOSSConfig, AliyunOSSProvider, ApiError, ApiErrorCode, ApiErrorFactory, type ApiResponse, ApiResponseHelper, AudioProcessor, CDNConfig, CDNResult, CDNType, CacheManager, CacheStrategyType$1 as CacheStrategyType, CdnCacheStrategy, ConfigValidationError, DEFAULT_ALLOWED_MIME_TYPES, DEFAULT_CACHE_CONFIG, DEFAULT_FILE_SERVICE_CONFIG, DEFAULT_MAX_FILE_SIZE, DEFAULT_OSS_CONFIG_KEYS, type DrizzleDb, type DrizzleRepositoryConfig, type DrizzleTable, ErrorHttpStatusMap, ErrorMessages, type FieldMapping, type FileAccessLog, FileDbService, type FileFolder, type FileInfo, type FileListResponse, type FileMetadata, type FileProcessParams, type FileProcessingRecord, type FileQueryParams, FileServiceConfigManager, type FileServiceFactoryOptions, type FileShare, type FileStats, type FileStorageProvider, type FileThumbnail, type FileUpdateParams, type FileUploadParams, type FileVersion, type FolderCreateParams, type FolderInfo, type FolderUpdateParams, ICDNProvider, type IConfigService, IFileMetadataRepository, IFileProcessor, IStorageProvider, ImageProcessor, LocalStorageConfig, LocalStorageProvider, type NewFileAccessLog, type NewFileFolder, type NewFileMetadata, type NewFileProcessingRecord, type NewFileShare, type NewFileStorageProvider, type NewFileThumbnail, type NewFileVersion, type OSSConfigKeyMapping, type PaginationParams, PerformanceMonitor, ProcessingOptions, ProcessingQueue, ProcessingResult, type ProcessingStatus, ProcessorType, QueryOptimizer, type ShareAccessParams, type ShareCreateParams, type ShareInfo, type SingletonFactory, StorageConfig, StorageResult, StorageType, UniversalFileService, UniversalFileServiceConfig, UploadFileInfo, type UploadResponse, ValidationHelper, VideoProcessor, cacheManager, cdnCacheStrategy, createAliyunOSSPreset, createDocumentServicePreset, createDrizzleFileRepository, createDrizzleRepository, createFileServiceConfig, createFileServiceConfigWithConfigManager, createFileServiceFromEnv, createFileServiceWithFactory, createImageServicePreset, createLocalDevPreset, createSingleton, createSmartPreset, createUniversalFileService, createUniversalFileServiceWithConfigManager, createVideoServicePreset, fileAccessLogs, fileAccessLogsRelations, fileFolders, fileFoldersRelations, fileMetadata, fileMetadataRelations, fileProcessingRecords, fileProcessingRecordsRelations, fileShares, fileSharesRelations, fileStorageProviders, fileStorageProvidersRelations, fileThumbnails, fileThumbnailsRelations, fileVersions, fileVersionsRelations, getDefaultLocalStorage, getMimeType, getRequiredEnvVars, loadCDNConfigFromEnv, loadConfigFromEnv, loadConfigWithFallback, loadOSSConfigFromEnv, loadOSSConfigFromService, performanceMonitor, queryOptimizer, validateEnvironment, validateServiceConfig, validateStorageConfig };