sa2kit 3.0.0 → 3.2.0

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

@@ -0,0 +1,1064 @@
+import { p as UniversalFileServiceConfig, v as StorageConfig, q as IStorageProvider, u as StorageType, y as UploadFileInfo, z as StorageResult, r as ICDNProvider, w as CDNType, x as CDNConfig, G as CDNResult, s as IFileProcessor, H as ProcessorType, J as ProcessingOptions, K as ProcessingResult, I as ImageProcessingOptions, c as AudioProcessingOptions, V as VideoProcessingOptions, D as IFileMetadataRepository } from '../../../types-8TOIsyLn.js';
+export { E as AliyunCDNConfig, t as AliyunOSSConfig, a3 as CDNProviderError, Q as CDNStats, N as CacheConfig, Y as FileEvent, Z as FileEventListener, _ as FileEventType, a1 as FileProcessingError, W as FileQueryOptions, T as FileRecord, $ as FileServiceError, M as FileServicePersistenceConfig, a0 as FileUploadError, L as LocalStorageConfig, X as PaginatedResult, R as ProcessorInfo, O as StorageMetadata, a2 as StorageProviderError } from '../../../types-8TOIsyLn.js';
+export { w as AliyunOSSProvider, A as ApiError, Y as ApiErrorCode, a as ApiErrorFactory, x as ApiResponse, b as ApiResponseHelper, C as CacheManager, n as DEFAULT_ALLOWED_MIME_TYPES, o as DEFAULT_CACHE_CONFIG, r as DEFAULT_FILE_SERVICE_CONFIG, D as DEFAULT_MAX_FILE_SIZE, s as DEFAULT_OSS_CONFIG_KEYS, _ as ErrorHttpStatusMap, Z as ErrorMessages, F as FileDbService, E as FileInfo, G as FileListResponse, M as FileProcessParams, B as FileQueryParams, e as FileServiceConfigManager, u as FileServiceFactoryOptions, X as FileStats, H as FileUpdateParams, z as FileUploadParams, J as FolderCreateParams, K as FolderInfo, L as FolderUpdateParams, I as IConfigService, O as OSSConfigKeyMapping, y as PaginationParams, P as PerformanceMonitor, N as ProcessingStatus, Q as QueryOptimizer, W as ShareAccessParams, R as ShareCreateParams, T as ShareInfo, S as SingletonFactory, U as UploadResponse, V as ValidationHelper, c as cacheManager, d as createDrizzleFileRepository, f as createFileServiceConfigWithConfigManager, t as createFileServiceWithFactory, v as createSingleton, g as createUniversalFileServiceWithConfigManager, j as getDefaultLocalStorage, i as loadCDNConfigFromEnv, l as loadConfigFromEnv, m as loadConfigWithFallback, h as loadOSSConfigFromEnv, k as loadOSSConfigFromService, p as performanceMonitor, q as queryOptimizer } from '../../../config-helpers-Vl6vnfF4.js';
+import { EventEmitter } from 'events';
+export { U as UniversalFileService } from '../../../UniversalFileService-BD23NXUR.js';
+export { FileAccessLog, FileFolder, FileMetadata, FileProcessingRecord, FileShare, FileStorageProvider, FileThumbnail, FileVersion, NewFileAccessLog, NewFileFolder, NewFileMetadata, NewFileProcessingRecord, NewFileShare, NewFileStorageProvider, NewFileThumbnail, NewFileVersion, fileAccessLogs, fileAccessLogsRelations, fileFolders, fileFoldersRelations, fileMetadata, fileMetadataRelations, fileProcessingRecords, fileProcessingRecordsRelations, fileShares, fileSharesRelations, fileStorageProviders, fileStorageProvidersRelations, fileThumbnails, fileThumbnailsRelations, fileVersions, fileVersionsRelations } from '../../file/schema/index.js';
+import 'next/server';
+import 'drizzle-orm/postgres-js';
+import 'drizzle-orm';
+import 'drizzle-orm/pg-core';
+
+/**
+ * UniversalFile Service 工厂函数
+ * 提供简化的服务初始化方式
+ */
+
+/**
+ * 创建文件服务配置（带智能默认值）
+ */
+declare function createFileServiceConfig(options: Partial<UniversalFileServiceConfig> & {
+    storage: StorageConfig | 'local';
+}): UniversalFileServiceConfig;
+/**
+ * 创建文件服务实例（简化版）
+ *
+ * @example
+ * ```typescript
+ * // 最简配置 - 使用本地存储
+ * const service = createUniversalFileService({ storage: 'local' });
+ *
+ * // 标准配置 - 使用阿里云 OSS
+ * const service = createUniversalFileService({
+ *   storage: {
+ *     type: 'aliyun-oss',
+ *     config: {
+ *       accessKeyId: process.env.OSS_KEY!,
+ *       accessKeySecret: process.env.OSS_SECRET!,
+ *       bucket: process.env.OSS_BUCKET!,
+ *       region: process.env.OSS_REGION!,
+ *     },
+ *   },
+ *   db: drizzleDb,
+ * });
+ * ```
+ */
+declare function createUniversalFileService(options: Partial<UniversalFileServiceConfig> & {
+    storage: StorageConfig | 'local';
+}): {
+    config: UniversalFileServiceConfig;
+    upload(): Promise<never>;
+    download(): Promise<never>;
+};
+/**
+ * 从环境变量创建配置（便利函数）
+ *
+ * @example
+ * ```typescript
+ * // .env
+ * // STORAGE_TYPE=aliyun-oss
+ * // OSS_ACCESS_KEY_ID=xxx
+ * // OSS_ACCESS_KEY_SECRET=xxx
+ * // OSS_BUCKET=my-bucket
+ * // OSS_REGION=oss-cn-hangzhou
+ *
+ * const service = createFileServiceFromEnv();
+ * ```
+ */
+declare function createFileServiceFromEnv(db?: any): {
+    config: UniversalFileServiceConfig;
+    upload(): Promise<never>;
+    download(): Promise<never>;
+};
+
+/**
+ * UniversalFile 预设配置
+ * 提供常见场景的开箱即用配置
+ */
+
+/**
+ * 本地开发环境预设
+ */
+declare function createLocalDevPreset(baseUrl?: string): StorageConfig;
+/**
+ * 生产环境 OSS 预设
+ */
+declare function createAliyunOSSPreset(config: {
+    accessKeyId: string;
+    accessKeySecret: string;
+    bucket: string;
+    region?: string;
+}): StorageConfig;
+/**
+ * 智能预设：根据环境自动选择
+ */
+declare function createSmartPreset(): StorageConfig;
+/**
+ * 图片服务预设（针对图片处理优化）
+ */
+declare function createImageServicePreset(storage: StorageConfig): {
+    storage: StorageConfig;
+    maxFileSize: number;
+    allowedMimeTypes: string[];
+};
+/**
+ * 视频服务预设（针对大文件优化）
+ */
+declare function createVideoServicePreset(storage: StorageConfig): {
+    storage: StorageConfig;
+    maxFileSize: number;
+    allowedMimeTypes: string[];
+    enableStreaming: boolean;
+};
+/**
+ * 文档服务预设
+ */
+declare function createDocumentServicePreset(storage: StorageConfig): {
+    storage: StorageConfig;
+    maxFileSize: number;
+    allowedMimeTypes: string[];
+};
+
+/**
+ * UniversalFile 配置验证
+ */
+
+declare class ConfigValidationError extends Error {
+    field: string;
+    constructor(message: string, field: string);
+}
+/**
+ * 验证存储配置
+ */
+declare function validateStorageConfig(storage: StorageConfig): void;
+/**
+ * 验证完整的服务配置
+ */
+declare function validateServiceConfig(config: UniversalFileServiceConfig): void;
+/**
+ * 验证环境变量
+ */
+declare function validateEnvironment(requiredVars: string[]): void;
+/**
+ * 获取环境变量所需的变量列表（根据存储类型）
+ */
+declare function getRequiredEnvVars(storageType: string): string[];
+
+/**
+ * 本地存储提供者实现
+ */
+
+/**
+ * 本地文件系统存储提供者
+ */
+declare class LocalStorageProvider implements IStorageProvider {
+    readonly type: StorageType;
+    private config;
+    private isInitialized;
+    /**
+     * 初始化存储提供者
+     */
+    initialize(config: StorageConfig): Promise<void>;
+    /**
+     * 上传文件
+     */
+    upload(fileInfo: UploadFileInfo, filePath: string): Promise<StorageResult>;
+    /**
+     * 下载文件
+     */
+    download(path: string): Promise<Buffer>;
+    /**
+     * 删除文件
+     */
+    delete(path: string): Promise<StorageResult>;
+    /**
+     * 获取文件信息
+     */
+    getFileInfo(path: string): Promise<StorageResult>;
+    /**
+     * 生成访问URL
+     */
+    getAccessUrl(path: string, _expiresIn?: number): Promise<string>;
+    /**
+     * 生成预签名上传URL
+     */
+    getUploadUrl(path: string, _expiresIn?: number): Promise<string>;
+    /**
+     * 检查文件是否存在
+     */
+    exists(path: string): Promise<boolean>;
+    /**
+     * 列出文件
+     */
+    list(prefix: string, maxKeys?: number): Promise<string[]>;
+    /**
+     * 确保已初始化
+     */
+    private ensureInitialized;
+    /**
+     * 获取完整文件路径
+     */
+    private getFullPath;
+    /**
+     * 生成访问URL
+     */
+    private generateAccessUrl;
+    /**
+     * 确保目录存在
+     */
+    private ensureDirectoryExists;
+    /**
+     * 验证目录访问权限
+     */
+    private validateDirectoryAccess;
+    /**
+     * 流式上传大文件（可选实现）
+     */
+    uploadStream(readableStream: NodeJS.ReadableStream, filePath: string): Promise<StorageResult>;
+    /**
+     * 流式下载大文件（可选实现）
+     */
+    createDownloadStream(path: string): NodeJS.ReadableStream;
+}
+
+/**
+ * 阿里云CDN提供者实现
+ */
+
+/**
+ * 阿里云CDN提供者
+ */
+declare class AliyunCDNProvider implements ICDNProvider {
+    readonly type: CDNType;
+    private config;
+    private client;
+    private isInitialized;
+    /**
+     * 初始化CDN提供者
+     */
+    initialize(config: CDNConfig): Promise<void>;
+    /**
+     * 生成CDN URL
+     */
+    generateUrl(originalUrl: string): Promise<string>;
+    /**
+     * 刷新缓存
+     */
+    refreshCache(urls: string[]): Promise<CDNResult>;
+    /**
+     * 预热缓存
+     */
+    preheatCache(urls: string[]): Promise<CDNResult>;
+    /**
+     * 获取访问统计
+     */
+    getAccessStats(startTime: Date, endTime: Date): Promise<CDNResult>;
+    /**
+     * 生成防盗链签名URL
+     */
+    generateSignedUrl(originalUrl: string, expiresIn?: number, authKey?: string): Promise<string>;
+    /**
+     * 查询刷新任务状态
+     */
+    getRefreshTaskStatus(taskId: string): Promise<CDNResult>;
+    /**
+     * 查询预热任务状态
+     */
+    getPreheatTaskStatus(taskId: string): Promise<CDNResult>;
+    /**
+     * 获取域名配置
+     */
+    getDomainConfig(): Promise<CDNResult>;
+    /**
+     * 优化URL (添加图像处理参数等)
+     */
+    optimizeUrl(originalUrl: string, options?: {
+        imageQuality?: number;
+        imageFormat?: 'webp' | 'jpg' | 'png';
+        imageResize?: {
+            width?: number;
+            height?: number;
+        };
+        enableGzip?: boolean;
+    }): Promise<string>;
+    /**
+     * 确保已初始化
+     */
+    private ensureInitialized;
+    /**
+     * 验证配置
+     */
+    private validateConfig;
+    /**
+     * 验证域名格式
+     */
+    private isValidDomain;
+    /**
+     * 测试连接
+     */
+    private testConnection;
+    /**
+     * 创建模拟客户端（用于开发测试）
+     */
+    private createMockClient;
+    /**
+     * 批量刷新缓存（带进度回调）
+     */
+    batchRefreshCache(urls: string[], batchSize?: number, onProgress?: (completed: number, total: number) => void): Promise<CDNResult>;
+}
+
+/**
+ * CDN缓存策略管理
+ * 优化静态资源缓存策略和预热机制
+ */
+/**
+ * 缓存策略类型
+ */
+declare enum CacheStrategyType$1 {
+    /** 图片资源 */
+    IMAGE = "image",
+    /** 视频资源 */
+    VIDEO = "video",
+    /** 音频资源 */
+    AUDIO = "audio",
+    /** 文档资源 */
+    DOCUMENT = "document",
+    /** 压缩包 */
+    ARCHIVE = "archive",
+    /** 静态资源 */
+    STATIC = "static",
+    /** 其他 */
+    OTHER = "other"
+}
+/**
+ * 缓存策略配置
+ */
+interface CacheStrategyConfig$1 {
+    /** 缓存策略类型 */
+    type: CacheStrategyType$1;
+    /** 缓存时间（秒） */
+    ttl: number;
+    /** 是否启用浏览器缓存 */
+    browserCache: boolean;
+    /** 浏览器缓存时间（秒） */
+    browserCacheTtl: number;
+    /** 是否启用CDN缓存 */
+    cdnCache: boolean;
+    /** CDN缓存时间（秒） */
+    cdnCacheTtl: number;
+    /** 是否启用预热 */
+    enableWarmup: boolean;
+    /** 缓存控制头 */
+    cacheControl: string;
+    /** 允许的文件类型 */
+    allowedMimeTypes: string[];
+    /** 文件大小限制（字节） */
+    maxFileSize?: number;
+}
+/**
+ * 缓存统计信息
+ */
+interface CacheStats$1 {
+    /** 命中次数 */
+    hits: number;
+    /** 未命中次数 */
+    misses: number;
+    /** 命中率 */
+    hitRate: number;
+    /** 总请求数 */
+    totalRequests: number;
+    /** 缓存大小估算 */
+    estimatedSize: number;
+    /** 节省的带宽（字节） */
+    bandwidthSaved: number;
+}
+/**
+ * CDN缓存策略管理器
+ */
+declare class CdnCacheStrategy$1 {
+    private strategies;
+    private stats;
+    constructor();
+    /**
+     * 初始化默认缓存策略
+     */
+    private initializeDefaultStrategies;
+    /**
+     * 根据MIME类型获取缓存策略
+     */
+    getStrategyByMimeType(mimeType: string): CacheStrategyConfig$1;
+    /**
+     * 生成缓存控制头
+     */
+    generateCacheHeaders(mimeType: string, fileSize?: number): Record<string, string>;
+    /**
+     * 检查是否需要缓存预热
+     */
+    shouldWarmupCache(mimeType: string): boolean;
+    /**
+     * 记录缓存命中
+     */
+    recordCacheHit(mimeType: string, fileSize?: number): void;
+    /**
+     * 记录缓存未命中
+     */
+    recordCacheMiss(mimeType: string, fileSize?: number): void;
+    /**
+     * 获取缓存统计信息
+     */
+    getCacheStats(): Map<CacheStrategyType$1, CacheStats$1>;
+    /**
+     * 获取总体缓存统计
+     */
+    getOverallStats(): CacheStats$1;
+    /**
+     * 生成缓存优化建议
+     */
+    generateOptimizationSuggestions(): Array<{
+        type: CacheStrategyType$1;
+        issue: string;
+        suggestion: string;
+        severity: 'low' | 'medium' | 'high';
+    }>;
+    /**
+     * 更新缓存策略
+     */
+    updateStrategy(type: CacheStrategyType$1, config: Partial<CacheStrategyConfig$1>): void;
+    /**
+     * 重置统计信息
+     */
+    resetStats(): void;
+}
+/**
+ * 单例CDN缓存策略管理器
+ */
+declare const cdnCacheStrategy: CdnCacheStrategy$1;
+
+/**
+ * 图片处理器实现
+ * 支持压缩、裁剪、水印、格式转换等功能
+ */
+
+/**
+ * 图片处理器
+ * 使用Sharp库进行高性能图片处理
+ */
+declare class ImageProcessor implements IFileProcessor {
+    readonly type: ProcessorType;
+    private sharp;
+    private isInitialized;
+    /**
+     * 初始化图片处理器
+     */
+    initialize(): Promise<void>;
+    /**
+     * 处理图片文件
+     */
+    process(inputPath: string, outputPath: string, options: ProcessingOptions): Promise<ProcessingResult>;
+    /**
+     * 检查文件是否支持处理
+     */
+    supports(mimeType: string): boolean;
+    /**
+     * 获取图片文件信息
+     */
+    getFileInfo(filePath: string): Promise<Record<string, any>>;
+    /**
+     * 确保处理器已初始化
+     */
+    private ensureInitialized;
+    /**
+     * 获取图片元数据
+     */
+    private getImageMetadata;
+    /**
+     * 应用图片处理操作
+     */
+    private applyImageOperations;
+    /**
+     * 应用水印
+     */
+    private applyWatermark;
+    /**
+     * 创建文字水印SVG
+     */
+    private createTextWatermarkSvg;
+    /**
+     * 获取水印位置对应的gravity值
+     */
+    private getWatermarkGravity;
+    /**
+     * 确定输出格式
+     */
+    private determineOutputFormat;
+    /**
+     * 应用输出设置
+     */
+    private applyOutputSettings;
+    /**
+     * 是否需要生成缩略图
+     */
+    private shouldGenerateThumbnail;
+    /**
+     * 生成缩略图
+     */
+    private generateThumbnail;
+    /**
+     * 获取缩略图路径
+     */
+    private getThumbnailPath;
+    /**
+     * 创建模拟Sharp对象（开发测试用）
+     */
+    private createMockSharp;
+    /**
+     * 批量图片处理
+     */
+    batchProcess(inputPaths: string[], outputDir: string, options: ImageProcessingOptions, onProgress?: (completed: number, total: number) => void): Promise<ProcessingResult[]>;
+}
+
+/**
+ * 音频处理器实现
+ * 支持格式转换、压缩、音质调整等功能
+ */
+
+/**
+ * 音频处理器
+ * 使用FFmpeg进行音频处理
+ */
+declare class AudioProcessor implements IFileProcessor {
+    readonly type: ProcessorType;
+    private ffmpeg;
+    private isInitialized;
+    /**
+     * 初始化音频处理器
+     */
+    initialize(): Promise<void>;
+    /**
+     * 处理音频文件
+     */
+    process(inputPath: string, outputPath: string, options: ProcessingOptions): Promise<ProcessingResult>;
+    /**
+     * 检查文件是否支持处理
+     */
+    supports(mimeType: string): boolean;
+    /**
+     * 获取音频文件信息
+     */
+    getFileInfo(filePath: string): Promise<Record<string, any>>;
+    /**
+     * 确保处理器已初始化
+     */
+    private ensureInitialized;
+    /**
+     * 获取音频元数据
+     */
+    private getAudioMetadata;
+    /**
+     * 执行音频处理
+     */
+    private processAudio;
+    /**
+     * 设置音频编解码器
+     */
+    private setAudioCodec;
+    /**
+     * 确定输出格式
+     */
+    private determineOutputFormat;
+    /**
+     * 格式化时长显示
+     */
+    private formatDuration;
+    /**
+     * 获取声道描述
+     */
+    private getChannelsDescription;
+    /**
+     * 获取音质描述
+     */
+    private getQualityDescription;
+    /**
+     * 创建模拟FFmpeg对象（开发测试用）
+     */
+    private createMockFFmpeg;
+    /**
+     * 批量音频处理
+     */
+    batchProcess(inputPaths: string[], outputDir: string, options: AudioProcessingOptions, onProgress?: (completed: number, total: number) => void): Promise<ProcessingResult[]>;
+    /**
+     * 提取音频封面
+     */
+    extractCover(inputPath: string, outputPath: string): Promise<boolean>;
+    /**
+     * 音频降噪处理
+     */
+    denoise(inputPath: string, outputPath: string): Promise<ProcessingResult>;
+}
+
+/**
+ * 视频处理器实现
+ * 支持缩略图生成、格式转换、压缩等功能
+ */
+
+/**
+ * 视频处理器
+ * 使用FFmpeg进行视频处理
+ */
+declare class VideoProcessor implements IFileProcessor {
+    readonly type: ProcessorType;
+    private ffmpeg;
+    private isInitialized;
+    /**
+     * 初始化视频处理器
+     */
+    initialize(): Promise<void>;
+    /**
+     * 处理视频文件
+     */
+    process(inputPath: string, outputPath: string, options: ProcessingOptions): Promise<ProcessingResult>;
+    /**
+     * 检查文件是否支持处理
+     */
+    supports(mimeType: string): boolean;
+    /**
+     * 获取视频文件信息
+     */
+    getFileInfo(filePath: string): Promise<Record<string, any>>;
+    /**
+     * 确保处理器已初始化
+     */
+    private ensureInitialized;
+    /**
+     * 获取视频元数据
+     */
+    private getVideoMetadata;
+    /**
+     * 解析帧率
+     */
+    private parseFPS;
+    /**
+     * 执行视频处理
+     */
+    private processVideo;
+    /**
+     * 设置视频编解码器
+     */
+    private setVideoCodec;
+    /**
+     * 设置视频质量
+     */
+    private setVideoQuality;
+    /**
+     * 确定输出格式
+     */
+    private determineOutputFormat;
+    /**
+     * 生成缩略图
+     */
+    private generateThumbnail;
+    /**
+     * 获取缩略图路径
+     */
+    private getThumbnailPath;
+    /**
+     * 格式化时长显示
+     */
+    private formatDuration;
+    /**
+     * 获取分辨率描述
+     */
+    private getResolutionDescription;
+    /**
+     * 获取视频质量描述
+     */
+    private getQualityDescription;
+    /**
+     * 创建模拟FFmpeg对象（开发测试用）
+     */
+    private createMockFFmpeg;
+    /**
+     * 批量视频处理
+     */
+    batchProcess(inputPaths: string[], outputDir: string, options: VideoProcessingOptions, onProgress?: (completed: number, total: number) => void): Promise<ProcessingResult[]>;
+    /**
+     * 提取视频帧
+     */
+    extractFrames(inputPath: string, outputDir: string, options?: {
+        count?: number;
+        interval?: number;
+        format?: 'jpg' | 'png';
+    }): Promise<string[]>;
+    /**
+     * 视频压缩
+     */
+    compress(inputPath: string, outputPath: string, compressionLevel?: 'low' | 'medium' | 'high'): Promise<ProcessingResult>;
+    /**
+     * 获取压缩质量
+     */
+    private getCompressionQuality;
+}
+
+/**
+ * 文件处理队列管理系统
+ * 支持异步任务调度、优先级排序、并发控制等功能
+ */
+
+interface QueueTask {
+    id: string;
+    inputPath: string;
+    outputPath: string;
+    options: ProcessingOptions;
+    priority: TaskPriority;
+    status: TaskStatus;
+    processor?: IFileProcessor;
+    startTime?: number;
+    endTime?: number;
+    result?: ProcessingResult;
+    error?: string;
+    retries: number;
+    maxRetries: number;
+    onProgress?: (task: QueueTask, progress: number) => void;
+    onComplete?: (task: QueueTask, result: ProcessingResult) => void;
+    onError?: (task: QueueTask, error: string) => void;
+}
+type TaskPriority = 'low' | 'normal' | 'high' | 'urgent';
+type TaskStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+interface QueueOptions {
+    maxConcurrentTasks?: number;
+    maxRetries?: number;
+    retryDelay?: number;
+    taskTimeout?: number;
+    autoStart?: boolean;
+}
+interface QueueStats {
+    totalTasks: number;
+    pendingTasks: number;
+    runningTasks: number;
+    completedTasks: number;
+    failedTasks: number;
+    cancelledTasks: number;
+    averageProcessingTime: number;
+    successRate: number;
+}
+/**
+ * 文件处理队列管理器
+ */
+declare class ProcessingQueue extends EventEmitter {
+    private tasks;
+    private runningTasks;
+    private processors;
+    private options;
+    private isStarted;
+    private processInterval;
+    constructor(options?: QueueOptions);
+    /**
+     * 注册文件处理器
+     */
+    registerProcessor(processor: IFileProcessor): void;
+    /**
+     * 添加任务到队列
+     */
+    addTask(inputPath: string, outputPath: string, options: ProcessingOptions, taskOptions?: Partial<Pick<QueueTask, 'priority' | 'maxRetries' | 'onProgress' | 'onComplete' | 'onError'>>): string;
+    /**
+     * 启动队列处理
+     */
+    start(): void;
+    /**
+     * 停止队列处理
+     */
+    stop(): void;
+    /**
+     * 暂停任务
+     */
+    pauseTask(taskId: string): boolean;
+    /**
+     * 取消任务
+     */
+    cancelTask(taskId: string): boolean;
+    /**
+     * 获取任务状态
+     */
+    getTask(taskId: string): QueueTask | undefined;
+    /**
+     * 获取所有任务
+     */
+    getAllTasks(): QueueTask[];
+    /**
+     * 获取待处理任务
+     */
+    getPendingTasks(): QueueTask[];
+    /**
+     * 获取正在运行的任务
+     */
+    getRunningTasks(): QueueTask[];
+    /**
+     * 获取队列统计信息
+     */
+    getStats(): QueueStats;
+    /**
+     * 清理已完成的任务
+     */
+    cleanup(): void;
+    /**
+     * 处理下一个任务
+     */
+    private processNext;
+    /**
+     * 获取下一个待处理任务（按优先级排序）
+     */
+    private getNextTask;
+    /**
+     * 处理单个任务
+     */
+    private processTask;
+    /**
+     * 完成任务
+     */
+    private completeTask;
+    /**
+     * 重试或失败任务
+     */
+    private retryOrFailTask;
+    /**
+     * 失败任务
+     */
+    private failTask;
+    /**
+     * 生成唯一任务ID
+     */
+    private generateTaskId;
+    /**
+     * 批量添加任务
+     */
+    addBatchTasks(tasks: Array<{
+        inputPath: string;
+        outputPath: string;
+        options: ProcessingOptions;
+        priority?: TaskPriority;
+    }>, onBatchProgress?: (completed: number, total: number) => void, onBatchComplete?: (results: Map<string, ProcessingResult>) => void): string[];
+    /**
+     * 获取队列健康状态
+     */
+    getHealthStatus(): {
+        isHealthy: boolean;
+        issues: string[];
+        recommendations: string[];
+    };
+}
+
+/**
+ * MIME 类型工具函数
+ */
+/**
+ * 根据文件名获取 MIME 类型
+ *
+ * @param filename 文件名
+ * @returns MIME 类型
+ *
+ * @example
+ * ```typescript
+ * getMimeType('photo.jpg')    // 'image/jpeg'
+ * getMimeType('video.mp4')    // 'video/mp4'
+ * getMimeType('unknown.xyz')  // 'application/octet-stream'
+ * ```
+ */
+declare function getMimeType(filename: string): string;
+
+/**
+ * CDN缓存策略管理
+ * 优化静态资源缓存策略和预热机制
+ */
+/**
+ * 缓存策略类型
+ */
+declare enum CacheStrategyType {
+    /** 图片资源 */
+    IMAGE = "image",
+    /** 视频资源 */
+    VIDEO = "video",
+    /** 音频资源 */
+    AUDIO = "audio",
+    /** 文档资源 */
+    DOCUMENT = "document",
+    /** 压缩包 */
+    ARCHIVE = "archive",
+    /** 静态资源 */
+    STATIC = "static",
+    /** 其他 */
+    OTHER = "other"
+}
+/**
+ * 缓存策略配置
+ */
+interface CacheStrategyConfig {
+    /** 缓存策略类型 */
+    type: CacheStrategyType;
+    /** 缓存时间（秒） */
+    ttl: number;
+    /** 是否启用浏览器缓存 */
+    browserCache: boolean;
+    /** 浏览器缓存时间（秒） */
+    browserCacheTtl: number;
+    /** 是否启用CDN缓存 */
+    cdnCache: boolean;
+    /** CDN缓存时间（秒） */
+    cdnCacheTtl: number;
+    /** 是否启用预热 */
+    enableWarmup: boolean;
+    /** 缓存控制头 */
+    cacheControl: string;
+    /** 允许的文件类型 */
+    allowedMimeTypes: string[];
+    /** 文件大小限制（字节） */
+    maxFileSize?: number;
+}
+/**
+ * 缓存统计信息
+ */
+interface CacheStats {
+    /** 命中次数 */
+    hits: number;
+    /** 未命中次数 */
+    misses: number;
+    /** 命中率 */
+    hitRate: number;
+    /** 总请求数 */
+    totalRequests: number;
+    /** 缓存大小估算 */
+    estimatedSize: number;
+    /** 节省的带宽（字节） */
+    bandwidthSaved: number;
+}
+/**
+ * CDN缓存策略管理器
+ */
+declare class CdnCacheStrategy {
+    private strategies;
+    private stats;
+    constructor();
+    /**
+     * 初始化默认缓存策略
+     */
+    private initializeDefaultStrategies;
+    /**
+     * 根据MIME类型获取缓存策略
+     */
+    getStrategyByMimeType(mimeType: string): CacheStrategyConfig;
+    /**
+     * 生成缓存控制头
+     */
+    generateCacheHeaders(mimeType: string, fileSize?: number): Record<string, string>;
+    /**
+     * 检查是否需要缓存预热
+     */
+    shouldWarmupCache(mimeType: string): boolean;
+    /**
+     * 记录缓存命中
+     */
+    recordCacheHit(mimeType: string, fileSize?: number): void;
+    /**
+     * 记录缓存未命中
+     */
+    recordCacheMiss(mimeType: string, fileSize?: number): void;
+    /**
+     * 获取缓存统计信息
+     */
+    getCacheStats(): Map<CacheStrategyType, CacheStats>;
+    /**
+     * 获取总体缓存统计
+     */
+    getOverallStats(): CacheStats;
+    /**
+     * 生成缓存优化建议
+     */
+    generateOptimizationSuggestions(): Array<{
+        type: CacheStrategyType;
+        issue: string;
+        suggestion: string;
+        severity: 'low' | 'medium' | 'high';
+    }>;
+    /**
+     * 更新缓存策略
+     */
+    updateStrategy(type: CacheStrategyType, config: Partial<CacheStrategyConfig>): void;
+    /**
+     * 重置统计信息
+     */
+    resetStats(): void;
+}
+
+/**
+ * Drizzle ORM 文件元数据持久化适配器
+ *
+ * 提供基于 Drizzle ORM 的数据库持久化实现
+ */
+
+/**
+ * Drizzle 表定义类型（兼容多种 Drizzle 表结构）
+ */
+type DrizzleTable = any;
+/**
+ * Drizzle 数据库连接类型
+ */
+type DrizzleDb = any;
+/**
+ * 字段映射配置
+ *
+ * 将 FileMetadata 的字段映射到数据库表的列名
+ */
+interface FieldMapping {
+    id?: string;
+    filename?: string;
+    originalName?: string;
+    mimeType?: string;
+    size?: string;
+    hash?: string;
+    storageType?: string;
+    storagePath?: string;
+    url?: string;
+    cdnUrl?: string;
+    moduleId?: string;
+    businessId?: string;
+    userId?: string;
+    uploadedAt?: string;
+    expiresAt?: string;
+    metadata?: string;
+    status?: string;
+    processingStatus?: string;
+    versions?: string;
+    tags?: string;
+}
+/**
+ * Drizzle 仓储配置
+ */
+interface DrizzleRepositoryConfig {
+    /** Drizzle 数据库实例 */
+    db: DrizzleDb;
+    /** 文件元数据表 */
+    table: DrizzleTable;
+    /** 字段映射（如果数据库列名与 FileMetadata 字段不同） */
+    fieldMapping?: FieldMapping;
+}
+/**
+ * 创建 Drizzle ORM 文件仓储
+ *
+ * @example
+ * ```typescript
+ * import { createDrizzleRepository } from '@qhr123/sa2kit/universalFile/server';
+ * import { db } from './db';
+ * import { fileMetadata } from './schema';
+ *
+ * const repository = createDrizzleRepository({
+ *   db,
+ *   table: fileMetadata,
+ *   fieldMapping: {
+ *     // 如果列名与 FileMetadata 字段不同，可以在这里映射
+ *     originalName: 'original_filename',
+ *   }
+ * });
+ * ```
+ */
+declare function createDrizzleRepository(config: DrizzleRepositoryConfig): IFileMetadataRepository;
+
+export { AliyunCDNProvider, AudioProcessor, CDNConfig, CDNResult, CDNType, CacheStrategyType$1 as CacheStrategyType, CdnCacheStrategy, ConfigValidationError, type DrizzleDb, type DrizzleRepositoryConfig, type DrizzleTable, type FieldMapping, ICDNProvider, IFileMetadataRepository, IFileProcessor, IStorageProvider, ImageProcessor, LocalStorageProvider, ProcessingOptions, ProcessingQueue, ProcessingResult, ProcessorType, StorageConfig, StorageResult, StorageType, UniversalFileServiceConfig, UploadFileInfo, VideoProcessor, cdnCacheStrategy, createAliyunOSSPreset, createDocumentServicePreset, createDrizzleRepository, createFileServiceConfig, createFileServiceFromEnv, createImageServicePreset, createLocalDevPreset, createSmartPreset, createUniversalFileService, createVideoServicePreset, getMimeType, getRequiredEnvVars, validateEnvironment, validateServiceConfig, validateStorageConfig };