sa2kit 1.6.9 → 1.6.11

package/dist/UniversalFileService-BuHN-jrR.d.ts

@@ -0,0 +1,515 @@
+import { EventEmitter } from 'events';
+import { S as StorageType$1, C as CDNType$1, F as FileMetadata, A as AccessPermission, U as UploadStatus, P as ProcessorType$1, a as UploadFileInfo$1, b as ProcessingOptions$1, c as UploadProgress, d as FileQueryOptions$1, e as PaginatedResult$1, B as BatchOperationResult, f as FileEventListener$1 } from './types-CK4We_aI.js';
+
+/**
+ * UniversalFile Server 端类型定义
+ */
+
+type StorageType = StorageType$1;
+type CDNType = CDNType$1;
+type ProcessorType = ProcessorType$1;
+type UploadFileInfo = UploadFileInfo$1;
+type ProcessingOptions = ProcessingOptions$1;
+/** 存储提供者接口 */
+interface IStorageProvider {
+    /** 提供者类型 */
+    readonly type: StorageType;
+    /** 初始化 */
+    initialize(config: StorageConfig): Promise<void>;
+    /** 上传文件 */
+    upload(fileInfo: UploadFileInfo, path: 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[]>;
+}
+/** CDN 提供者接口 */
+interface ICDNProvider {
+    /** 提供者类型 */
+    readonly type: CDNType;
+    /** 初始化 */
+    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>;
+}
+/** 文件处理器接口 */
+interface IFileProcessor {
+    /** 处理器类型 */
+    readonly type: ProcessorType;
+    /** 初始化 */
+    initialize(): Promise<void>;
+    /** 处理文件 */
+    process(inputPath: string, outputPath: string, options: ProcessingOptions): Promise<ProcessingResult>;
+    /** 检查文件是否支持处理 */
+    supports(mimeType: string): boolean;
+    /** 获取文件信息 */
+    getFileInfo(filePath: string): Promise<Record<string, any>>;
+}
+/** 存储配置基础接口 */
+interface StorageConfig {
+    /** 存储类型 */
+    type: StorageType;
+    /** 是否启用 */
+    enabled: boolean;
+}
+/** 本地存储配置 */
+interface LocalStorageConfig extends StorageConfig {
+    type: 'local';
+    /** 存储根目录 */
+    rootPath: string;
+    /** 基础URL */
+    baseUrl: string;
+}
+/** 阿里云 OSS 配置 */
+interface AliyunOSSConfig extends StorageConfig {
+    type: 'aliyun-oss';
+    /** 地域 */
+    region: string;
+    /** 存储桶名称 */
+    bucket: string;
+    /** 访问密钥ID */
+    accessKeyId: string;
+    /** 访问密钥密码 */
+    accessKeySecret: string;
+    /** 自定义域名 */
+    customDomain?: string;
+    /** 是否使用HTTPS */
+    secure?: boolean;
+    /** 是否使用内网访问 */
+    internal?: boolean;
+}
+/** CDN配置基础接口 */
+interface CDNConfig {
+    /** CDN类型 */
+    type: CDNType;
+    /** 是否启用 */
+    enabled: boolean;
+}
+/** 阿里云 CDN 配置 */
+interface AliyunCDNConfig extends CDNConfig {
+    type: 'aliyun-cdn';
+    /** CDN域名 */
+    domain: string;
+    /** 访问密钥ID */
+    accessKeyId: string;
+    /** 访问密钥密码 */
+    accessKeySecret: string;
+    /** 地域 */
+    region?: string;
+}
+/** 缓存配置 */
+interface CacheConfig {
+    /** 是否启用缓存 */
+    enabled: boolean;
+    /** 最大缓存大小 */
+    maxSize?: number;
+    /** 缓存 TTL（秒） */
+    ttl?: number;
+    /** 是否使用 Redis */
+    useRedis?: boolean;
+    /** Redis 配置 */
+    redisConfig?: {
+        host: string;
+        port: number;
+        password?: string;
+        db?: number;
+    };
+}
+/** 文件服务配置 */
+/** 缓存配置扩展 */
+interface CacheConfig {
+    /** 是否启用缓存 */
+    enabled: boolean;
+    /** 元数据缓存TTL（秒） */
+    metadataTTL?: number;
+    /** URL缓存TTL（秒） */
+    urlTTL?: number;
+    /** 最大缓存条目数 */
+    maxSize?: number;
+}
+interface UniversalFileServiceConfig {
+    /** 存储配置 */
+    storage: StorageConfig;
+    /** CDN 配置（可选） */
+    cdn?: CDNConfig;
+    /** 缓存配置（可选） */
+    cache?: CacheConfig;
+    /** 数据库持久化配置（可选） */
+    persistence?: FileServicePersistenceConfig;
+    /** 启用的处理器 */
+    processors?: ProcessorType[];
+    /** 数据库连接（可选） @deprecated 使用 persistence.repository 代替 */
+    db?: any;
+    /** 最大文件大小（字节） */
+    maxFileSize?: number;
+    /** 允许的文件类型 */
+    allowedMimeTypes?: string[];
+    /** 是否启用监控 */
+    enableMonitoring?: boolean;
+    /** 存储提供者映射（内部使用） */
+    storageProviders?: Map<StorageType, IStorageProvider>;
+    /** 默认存储类型 */
+    defaultStorage?: StorageType;
+    /** 默认CDN类型 */
+    defaultCDN?: CDNType;
+}
+/** 存储结果 */
+/** 存储操作结果 */
+interface StorageResult {
+    /** 是否成功 */
+    success: boolean;
+    /** 存储路径 */
+    path?: string;
+    /** 访问URL */
+    url?: string;
+    /** 文件大小 */
+    size?: number;
+    /** 错误信息 */
+    error?: string;
+    /** 额外数据 */
+    data?: Record<string, any>;
+}
+/** 存储元数据 */
+interface StorageMetadata {
+    /** 文件大小 */
+    size: number;
+    /** MIME 类型 */
+    mimeType: string;
+    /** 最后修改时间 */
+    lastModified: Date;
+    /** 自定义元数据 */
+    metadata?: Record<string, any>;
+}
+/** CDN 结果 */
+/** CDN操作结果 */
+interface CDNResult {
+    /** 是否成功 */
+    success: boolean;
+    /** CDN URL */
+    url?: string;
+    /** 错误信息 */
+    error?: string;
+    /** 额外数据 */
+    data?: Record<string, any>;
+}
+/** CDN 统计信息 */
+interface CDNStats {
+    /** 带宽（字节/秒） */
+    bandwidth: number;
+    /** 请求数 */
+    requests: number;
+    /** 流量（字节） */
+    traffic: number;
+    /** 统计时间范围 */
+    timeRange: {
+        start: Date;
+        end: Date;
+    };
+}
+/** 处理结果 */
+interface ProcessingResult {
+    /** 是否成功 */
+    success: boolean;
+    /** 处理后的文件路径 */
+    processedPath?: string;
+    /** 处理后的文件大小 */
+    processedSize?: number;
+    /** 缩略图路径 */
+    thumbnailPath?: string;
+    /** 错误信息 */
+    error?: string;
+    /** 处理耗时(毫秒) */
+    processingTime?: number;
+    /** 额外数据 */
+    data?: Record<string, any>;
+}
+/** 处理器信息 */
+interface ProcessorInfo {
+    /** 处理器名称 */
+    name: string;
+    /** 处理器版本 */
+    version: string;
+    /** 支持的格式 */
+    supportedFormats: string[];
+    /** 支持的操作 */
+    supportedOperations: string[];
+}
+/** 文件数据库记录 */
+interface FileRecord extends FileMetadata {
+    /** 创建时间 */
+    createdAt: Date | string;
+    /** 更新时间 */
+    updatedAt: Date | string;
+}
+/** 文件查询选项 */
+interface FileQueryOptions {
+    /** 模块 ID */
+    moduleId?: string;
+    /** 业务 ID */
+    businessId?: string;
+    /** 上传者 ID */
+    uploaderId?: string;
+    /** 文件类型 */
+    mimeType?: string;
+    /** 访问权限 */
+    permission?: AccessPermission;
+    /** 状态 */
+    status?: UploadStatus;
+    /** 分页 */
+    page?: number;
+    pageSize?: number;
+    /** 排序 */
+    orderBy?: string;
+    orderDirection?: 'asc' | 'desc';
+}
+/** 分页结果 */
+interface PaginatedResult<T> {
+    /** 数据列表 */
+    items: T[];
+    /** 总数 */
+    total: number;
+    /** 当前页 */
+    page: number;
+    /** 每页大小 */
+    pageSize: number;
+    /** 总页数 */
+    totalPages: number;
+}
+/** 文件事件类型 */
+type FileEventType = 'upload:start' | 'upload:progress' | 'upload:complete' | 'upload:error' | 'download:start' | 'download:complete' | 'download:error' | 'delete:complete' | 'delete:error' | 'process:start' | 'process:complete' | 'process:error';
+/** 文件事件 */
+interface FileEvent {
+    /** 事件类型 */
+    type: FileEventType;
+    /** 文件 ID */
+    fileId: string;
+    /** 事件数据 */
+    data?: any;
+    /** 时间戳 */
+    timestamp: Date;
+}
+/** 事件监听器 */
+type FileEventListener = (event: FileEvent) => void | Promise<void>;
+/**
+ * 文件元数据数据库持久化接口
+ *
+ * 实现此接口以提供自定义的数据库持久化支持
+ *
+ * @example
+ * ```typescript
+ * // Drizzle ORM 实现
+ * class DrizzleFileRepository implements IFileMetadataRepository {
+ *   async save(metadata: FileMetadata): Promise<void> {
+ *     await db.insert(fileMetadata).values(metadata);
+ *   }
+ *   // ... 其他方法
+ * }
+ * ```
+ */
+interface IFileMetadataRepository {
+    /**
+     * 保存文件元数据到数据库
+     */
+    save(metadata: FileMetadata): Promise<void>;
+    /**
+     * 从数据库获取文件元数据
+     */
+    get(fileId: string): Promise<FileMetadata | null>;
+    /**
+     * 查询文件列表
+     */
+    query(options: FileQueryOptions): Promise<PaginatedResult<FileMetadata>>;
+    /**
+     * 从数据库删除文件元数据
+     */
+    delete(fileId: string): Promise<void>;
+    /**
+     * 批量删除文件元数据
+     */
+    batchDelete(fileIds: string[]): Promise<void>;
+}
+/**
+ * 数据库持久化配置
+ */
+interface FileServicePersistenceConfig {
+    /**
+     * 是否启用持久化
+     */
+    enabled: boolean;
+    /**
+     * 持久化仓储实现
+     */
+    repository: IFileMetadataRepository;
+    /**
+     * 是否自动持久化（默认 true）
+     * 如果为 true，文件上传完成后自动保存到数据库
+     */
+    autoPersist?: boolean;
+    /**
+     * 是否优先使用缓存（默认 false）
+     * 如果为 true，查询时优先从缓存获取
+     */
+    cacheFirst?: boolean;
+}
+/** 文件服务异常基类 */
+declare class FileServiceError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, any> | undefined;
+    constructor(message: string, code: string, details?: Record<string, any> | undefined);
+}
+/** 文件上传异常 */
+declare class FileUploadError extends FileServiceError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/** 文件处理异常 */
+declare class FileProcessingError extends FileServiceError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/** 存储提供者异常 */
+declare class StorageProviderError extends FileServiceError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/** CDN提供者异常 */
+declare class CDNProviderError extends FileServiceError {
+    constructor(message: string, details?: Record<string, any>);
+}
+
+/**
+ * 通用文件服务核心实现
+ *
+ * 提供统一的文件上传、下载、管理接口
+ */
+
+/**
+ * 通用文件服务类
+ */
+declare class UniversalFileService extends EventEmitter {
+    private config;
+    private storageProviders;
+    private cdnProviders;
+    private fileProcessors;
+    private uploadProgressMap;
+    private metadataCache;
+    private urlCache;
+    private processingQueue;
+    private isProcessingQueueRunning;
+    constructor(config: UniversalFileServiceConfig);
+    /**
+     * 设置数据库持久化监听器
+     *
+     * 当文件上传完成或删除时，自动触发数据库操作
+     */
+    private setupPersistenceListeners;
+    /**
+     * 初始化文件服务
+     */
+    initialize(): Promise<void>;
+    /**
+     * 重新初始化存储提供者（支持配置热更新）
+     */
+    reinitializeStorageProviders(): Promise<void>;
+    /**
+     * 注册存储提供者
+     */
+    registerStorageProvider(provider: IStorageProvider): void;
+    /**
+     * 注册CDN提供者
+     */
+    registerCDNProvider(provider: ICDNProvider): void;
+    /**
+     * 注册文件处理器
+     */
+    registerFileProcessor(processor: IFileProcessor): void;
+    /**
+     * 上传文件
+     */
+    uploadFile(fileInfo: UploadFileInfo$1, storageType?: StorageType$1, onProgress?: (progress: UploadProgress) => void): Promise<FileMetadata>;
+    /**
+     * 下载文件
+     */
+    downloadFile(fileId: string, userId?: string): Promise<Buffer>;
+    /**
+     * 删除文件
+     */
+    deleteFile(fileId: string, userId?: string): Promise<void>;
+    /**
+     * 获取文件访问URL
+     */
+    getFileUrl(fileId: string, userId?: string, expiresIn?: number): Promise<string>;
+    /**
+     * 获取文件元数据
+     */
+    getFileMetadata(fileId: string): Promise<FileMetadata | null>;
+    /**
+     * 查询文件列表
+     */
+    queryFiles(options: FileQueryOptions$1): Promise<PaginatedResult$1<FileMetadata>>;
+    /**
+     * 批量删除文件
+     */
+    batchDeleteFiles(fileIds: string[], userId?: string): Promise<BatchOperationResult>;
+    /**
+     * 获取上传进度
+     */
+    getUploadProgress(fileId: string): UploadProgress | undefined;
+    /**
+     * 监听文件事件
+     */
+    onFileEvent(eventType: string, listener: FileEventListener$1): void;
+    /**
+     * 移除文件事件监听器
+     */
+    offFileEvent(eventType: string, listener: FileEventListener$1): void;
+    private initializeStorageProviders;
+    private registerDefaultStorageProviders;
+    private initializeCDNProviders;
+    private initializeFileProcessors;
+    private validateFile;
+    private generateFileMetadata;
+    private generateStoragePath;
+    private generateFileHash;
+    private queueFileProcessing;
+    private generateProcessedPath;
+    private processFileQueue;
+    private cacheMetadata;
+    private clearMetadataCache;
+    private emitFileEvent;
+    /**
+     * 保存文件元数据到数据库 (通过持久化仓储)
+     */
+    private saveFileMetadata;
+    /**
+     * 从数据库删除文件元数据 (通过持久化仓储)
+     */
+    private deleteFileMetadata;
+    /**
+     * 更新访问统计
+     */
+    private updateAccessStats;
+    /**
+     * 检查文件访问权限
+     */
+    private checkFileAccess;
+    /**
+     * 检查文件删除权限
+     */
+    private checkFileDeleteAccess;
+}
+
+export { type AliyunOSSConfig as A, CDNProviderError as B, type CDNType as C, type FileServicePersistenceConfig as F, type IStorageProvider as I, type LocalStorageConfig as L, type ProcessorType as P, type StorageConfig as S, UniversalFileService as U, type UniversalFileServiceConfig as a, type StorageType as b, type UploadFileInfo as c, type StorageResult as d, type ICDNProvider as e, type CDNConfig as f, type CDNResult as g, type IFileProcessor as h, type ProcessingOptions as i, type ProcessingResult as j, type IFileMetadataRepository as k, type AliyunCDNConfig as l, type CacheConfig as m, type StorageMetadata as n, type CDNStats as o, type ProcessorInfo as p, type FileRecord as q, type FileQueryOptions as r, type PaginatedResult as s, type FileEvent as t, type FileEventListener as u, type FileEventType as v, FileServiceError as w, FileUploadError as x, FileProcessingError as y, StorageProviderError as z };