@nest-omni/core 4.1.3-10 → 4.1.3-12

package/file-upload/interfaces/file-entity.interface.d.ts

@@ -0,0 +1,142 @@
+/** 文件状态枚举 */
+export declare enum FileStatus {
+    UPLOADING = "uploading",
+    PROCESSING = "processing",
+    READY = "ready",
+    FAILED = "failed",
+    DELETED = "deleted",
+    QUARANTINED = "quarantined"
+}
+export interface FileEntity {
+    /** 唯一标识符 */
+    id: string;
+    /** 原始文件名 */
+    originalName: string;
+    /** 存储的文件名（经过安全处理） */
+    fileName: string;
+    /** MIME类型 */
+    mimeType: string;
+    /** 文件大小（字节） */
+    size: number;
+    /** 文件哈希值（SHA-256） */
+    hash: string;
+    /** 使用的存储提供者 */
+    storage: string;
+    /** 存储路径/键 */
+    path: string;
+    /** 公开访问URL（如果可公开访问） */
+    url?: string;
+    /** 文件元数据 */
+    metadata?: FileEntityMetadata;
+    /** 上传者ID */
+    uploadedBy?: string;
+    /** 上传时间 */
+    uploadedAt: Date;
+    /** 文件状态 */
+    status: FileStatus;
+    /** 是否已删除（软删除） */
+    isDeleted?: boolean;
+    /** 删除时间 */
+    deletedAt?: Date;
+    /** 文件版本号 */
+    version?: number;
+    /** 标签 */
+    tags?: string[];
+    /** 父级文件ID（用于版本管理） */
+    parentFileId?: string;
+    /** 所属文件集合ID */
+    collectionId?: string;
+    /** 访问次数 */
+    accessCount?: number;
+    /** 最后访问时间 */
+    lastAccessedAt?: Date;
+    /** 过期时间 */
+    expiresAt?: Date;
+    /** 存储提供商返回的额外信息 */
+    providerMetadata?: Record<string, any>;
+}
+/** 文件实体元数据 */
+export interface FileEntityMetadata {
+    /** 文件类型分类 */
+    category?: FileCategory;
+    /** 文件扩展名 */
+    extension?: string;
+    /** 文件编码 */
+    encoding?: string;
+    /** 宽度（适用于图片/视频） */
+    width?: number;
+    /** 高度（适用于图片/视频） */
+    height?: number;
+    /** 持续时间（适用于音频/视频） */
+    duration?: number;
+    /** 页数（适用于文档） */
+    pages?: number;
+    /** DPI（适用于图片） */
+    dpi?: number;
+    /** 色彩模式（适用于图片） */
+    colorMode?: string;
+    /** 压缩率 */
+    compressionRatio?: number;
+    /** EXIF信息（适用于图片） */
+    exif?: Record<string, any>;
+    /** 自定义元数据 */
+    custom?: Record<string, any>;
+}
+/** 文件分类 */
+export declare enum FileCategory {
+    IMAGE = "image",
+    VIDEO = "video",
+    AUDIO = "audio",
+    DOCUMENT = "document",
+    SPREADSHEET = "spreadsheet",
+    PRESENTATION = "presentation",
+    ARCHIVE = "archive",
+    CODE = "code",
+    TEXT = "text",
+    BINARY = "binary",
+    OTHER = "other"
+}
+/** 文件集合 */
+export interface FileCollection {
+    /** 集合ID */
+    id: string;
+    /** 集合名称 */
+    name: string;
+    /** 集合描述 */
+    description?: string;
+    /** 包含的文件列表 */
+    files?: FileEntity[];
+    /** 集合所有者 */
+    ownerId?: string;
+    /** 创建时间 */
+    createdAt?: Date;
+    /** 更新时间 */
+    updatedAt?: Date;
+    /** 是否公开 */
+    isPublic?: boolean;
+    /** 访问密码 */
+    password?: string;
+    /** 下载限制 */
+    downloadLimit?: number;
+    /** 过期时间 */
+    expiresAt?: Date;
+    /** 集合配置 */
+    settings?: CollectionSettings;
+}
+/** 集合设置 */
+export interface CollectionSettings {
+    /** 是否允许添加文件 */
+    allowAddFiles?: boolean;
+    /** 是否允许删除文件 */
+    allowDeleteFiles?: boolean;
+    /** 是否允许下载 */
+    allowDownload?: boolean;
+    /** 是否需要密码访问 */
+    requirePassword?: boolean;
+    /** 生成ZIP包 */
+    generateZip?: boolean;
+    /** 最大文件数 */
+    maxFiles?: number;
+    /** 最大总大小 */
+    maxTotalSize?: number;
+}

package/file-upload/interfaces/file-entity.interface.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileCategory = exports.FileStatus = void 0;
+/** 文件状态枚举 */
+var FileStatus;
+(function (FileStatus) {
+    FileStatus["UPLOADING"] = "uploading";
+    FileStatus["PROCESSING"] = "processing";
+    FileStatus["READY"] = "ready";
+    FileStatus["FAILED"] = "failed";
+    FileStatus["DELETED"] = "deleted";
+    FileStatus["QUARANTINED"] = "quarantined";
+})(FileStatus || (exports.FileStatus = FileStatus = {}));
+/** 文件分类 */
+var FileCategory;
+(function (FileCategory) {
+    FileCategory["IMAGE"] = "image";
+    FileCategory["VIDEO"] = "video";
+    FileCategory["AUDIO"] = "audio";
+    FileCategory["DOCUMENT"] = "document";
+    FileCategory["SPREADSHEET"] = "spreadsheet";
+    FileCategory["PRESENTATION"] = "presentation";
+    FileCategory["ARCHIVE"] = "archive";
+    FileCategory["CODE"] = "code";
+    FileCategory["TEXT"] = "text";
+    FileCategory["BINARY"] = "binary";
+    FileCategory["OTHER"] = "other";
+})(FileCategory || (exports.FileCategory = FileCategory = {}));

package/file-upload/interfaces/file-metadata.interface.d.ts

@@ -0,0 +1,21 @@
+/** 文件元数据接口 */
+export interface FileMetadata {
+    /** 文件大小 */
+    size: number;
+    /** MIME类型 */
+    mimeType: string;
+    /** 最后修改时间 */
+    lastModified: Date;
+    /** ETag */
+    etag?: string;
+    /** 文件扩展名 */
+    extension?: string;
+    /** 文件编码 */
+    encoding?: string;
+    /** 宽度（像素）- 适用于图片、视频 */
+    width?: number;
+    /** 高度（像素）- 适用于图片、视频 */
+    height?: number;
+    /** 自定义元数据 */
+    metadata?: Record<string, any>;
+}

package/file-upload/interfaces/file-metadata.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/file-upload/interfaces/file-upload-options.interface.d.ts

@@ -0,0 +1,117 @@
+import { FileType } from '../enums/file-type.enum';
+import { Request } from 'express';
+/**
+ * 文件上传选项
+ */
+export interface FileUploadOptions {
+    /** 文件大小限制（字节），默认 10MB */
+    maxSize?: number;
+    /** 允许的文件类型（FileType 枚举或 MIME 类型） */
+    types?: Array<FileType | string>;
+    /** 允许的扩展名 */
+    exts?: string[];
+    /** 需要认证 */
+    auth?: boolean;
+    /** 需要文件所有权 */
+    ownership?: boolean;
+    /** 公开访问 */
+    public?: boolean;
+    /** 病毒扫描: true=强制, false=禁用, 'auto'=智能（默认） */
+    scan?: boolean | 'auto';
+    /** 文件名清理，默认 true */
+    sanitize?: boolean;
+    /** 保留原始文件名（默认 false，使用 UUID）*/
+    preserveOriginalName?: boolean;
+    /** 是否启用文件签名验证（默认 true） */
+    validateSignature?: boolean;
+    /** 是否启用恶意文件检测 */
+    maliciousCheck?: boolean;
+    image?: {
+        /** 调整大小 */
+        resize?: {
+            width: number;
+            height: number;
+            fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside';
+        };
+        /** 压缩质量 0-100 */
+        quality?: number;
+        /** 输出格式 */
+        format?: 'jpeg' | 'png' | 'webp';
+        /** 水印文字 */
+        watermark?: string;
+        /** 生成缩略图 */
+        thumbnail?: boolean;
+    };
+    processor?: string | {
+        name: string;
+        options?: any;
+    };
+    /** 存储提供者: 'local' | 's3' | 'oss' | 'minio' */
+    storage?: string;
+    /** 自定义存储路径 */
+    path?: string;
+    /** 上传前钩子 */
+    before?: (file: Express.Multer.File, context: UploadContext) => Promise<void>;
+    /** 上传后钩子 */
+    after?: (file: Express.Multer.File, context: UploadContext) => Promise<void>;
+}
+/**
+ * 上传上下文
+ */
+export interface UploadContext {
+    /** 共享数据 */
+    shared: Record<string, any>;
+    /** 获取处理器 */
+    getProcessor(name: string): IFileProcessor | null;
+    /** 保存文件元数据 */
+    saveMetadata(fileId: string, metadata: any): Promise<void>;
+    /** 获取当前用户 */
+    getUser(): any;
+    /** 获取请求对象 */
+    getRequest(): Request;
+}
+/**
+ * 文件处理器接口
+ */
+export interface IFileProcessor {
+    /** 处理器名称 */
+    name: string;
+    /** 支持的文件类型 */
+    supports: Array<FileType | string>;
+    /** 处理文件 */
+    process(file: Express.Multer.File, options?: any): Promise<any>;
+    /** 验证文件（可选） */
+    validate?(file: Express.Multer.File): Promise<boolean>;
+}
+/**
+ * Excel 数据配置
+ */
+export interface ExcelDataOptions {
+    /** 工作表索引，默认 0 */
+    sheetIndex?: number;
+    /** 开始行，默认 1（跳过表头） */
+    startRow?: number;
+    /** 最大行数 */
+    maxRows?: number;
+    /** 解析前验证 */
+    validateBeforeParse?: boolean;
+    /** 遇到错误停止 */
+    stopOnError?: boolean;
+}
+/**
+ * CSV 数据配置
+ */
+export interface CsvDataOptions {
+    /** 分隔符，默认 ',' */
+    delimiter?: ',' | ';' | '\t' | string;
+    /** 引号字符，默认 '"' */
+    quote?: string;
+    /** 转义字符，默认 '"' */
+    escape?: string;
+    /** 跳过空行 */
+    skipEmptyLines?: boolean;
+    /** 跳过表头 */
+    skipHeader?: boolean;
+    /** 编码，默认 'utf8' */
+    encoding?: 'utf8' | 'gbk' | 'gb2312' | string;
+}

package/file-upload/interfaces/file-upload-options.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/file-upload/interfaces/index.d.ts

@@ -0,0 +1,7 @@
+export * from './file-entity.interface';
+export * from './storage-provider.interface';
+export * from './file-buffer.interface';
+export * from './file-metadata.interface';
+export * from './upload-options.interface';
+export * from './file-upload-options.interface';
+export * from './custom-file-type.interface';

package/file-upload/interfaces/index.js

@@ -0,0 +1,24 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Core interfaces
+__exportStar(require("./file-entity.interface"), exports);
+__exportStar(require("./storage-provider.interface"), exports);
+__exportStar(require("./file-buffer.interface"), exports);
+__exportStar(require("./file-metadata.interface"), exports);
+__exportStar(require("./upload-options.interface"), exports);
+__exportStar(require("./file-upload-options.interface"), exports);
+__exportStar(require("./custom-file-type.interface"), exports);

package/file-upload/interfaces/storage-provider.interface.d.ts

@@ -0,0 +1,239 @@
+import { FileBuffer } from './file-buffer.interface';
+import { UploadOptions } from './upload-options.interface';
+import { FileMetadata } from './file-metadata.interface';
+/** 存储提供者接口 */
+export interface IStorageProvider {
+    /** 提供者名称 */
+    name: string;
+    /** 上传文件 */
+    upload(file: FileBuffer, options: UploadOptions): Promise<UploadResult>;
+    /** 下载文件 */
+    download(path: string): Promise<FileBuffer>;
+    /** 删除文件 */
+    delete(path: string): Promise<void>;
+    /** 批量删除 */
+    deleteBatch(paths: string[]): Promise<BatchDeleteResult>;
+    /** 检查文件是否存在 */
+    exists(path: string): Promise<boolean>;
+    /** 获取文件元数据 */
+    getMetadata(path: string): Promise<FileMetadata>;
+    /** 获取预签名URL */
+    getSignedUrl(path: string, expiresIn?: number): Promise<string>;
+    /** 获取预签名上传URL（用于客户端直传） */
+    getSignedUploadUrl(path: string, expiresIn?: number, contentType?: string): Promise<PreSignedUploadInfo>;
+    /** 复制文件 */
+    copy(sourcePath: string, destinationPath: string): Promise<CopyResult>;
+    /** 移动文件 */
+    move(sourcePath: string, destinationPath: string): Promise<MoveResult>;
+    /** 列出文件 */
+    list(prefix?: string, limit?: number): Promise<ListResult>;
+    /** 初始化存储配置 */
+    initialize(): Promise<void>;
+    /** 健康检查 */
+    healthCheck(): Promise<HealthStatus>;
+}
+/** 上传结果 */
+export interface UploadResult {
+    /** 文件路径/键 */
+    key: string;
+    /** 访问URL */
+    url?: string;
+    /** ETag */
+    etag?: string;
+    /** 版本ID（如果支持） */
+    versionId?: string;
+    /** 文件大小 */
+    size: number;
+    /** 上传时间 */
+    uploadedAt: Date;
+    /** 额外元数据 */
+    metadata?: Record<string, any>;
+}
+/** 批量删除结果 */
+export interface BatchDeleteResult {
+    /** 成功删除的文件列表 */
+    deleted: string[];
+    /** 删除失败的文件列表 */
+    failed: Array<{
+        path: string;
+        error: string;
+    }>;
+    /** 总数 */
+    total: number;
+}
+/** 复制结果 */
+export interface CopyResult {
+    /** 目标路径 */
+    destinationPath: string;
+    /** 文件大小 */
+    size: number;
+    /** 复制时间 */
+    copiedAt: Date;
+    /** ETag */
+    etag?: string;
+}
+/** 移动结果 */
+export interface MoveResult {
+    /** 目标路径 */
+    destinationPath: string;
+    /** 文件大小 */
+    size: number;
+    /** 移动时间 */
+    movedAt: Date;
+    /** ETag */
+    etag?: string;
+}
+/** 列表结果 */
+export interface ListResult {
+    /** 文件列表 */
+    files: Array<{
+        key: string;
+        size: number;
+        lastModified: Date;
+        etag?: string;
+    }>;
+    /** 是否还有更多文件 */
+    hasMore: boolean;
+    /** 下一个标记 */
+    nextMarker?: string;
+    /** 总数（如果支持） */
+    totalCount?: number;
+}
+/** 预签名上传信息 */
+export interface PreSignedUploadInfo {
+    /** 上传URL */
+    url: string;
+    /** HTTP方法 */
+    method: 'PUT' | 'POST';
+    /** 需要的头部 */
+    headers: Record<string, string>;
+    /** 表单字段（如果使用POST） */
+    fields?: Record<string, string>;
+    /** 过期时间 */
+    expiresAt: Date;
+}
+/** 健康状态 */
+export interface HealthStatus {
+    /** 是否健康 */
+    healthy: boolean;
+    /** 响应时间（毫秒） */
+    responseTime: number;
+    /** 错误信息 */
+    error?: string;
+    /** 额外信息 */
+    details?: Record<string, any>;
+}
+/** 本地存储选项 */
+export interface LocalStorageOptions {
+    /** 上传根目录 */
+    uploadPath: string;
+    /** 基础URL */
+    baseUrl?: string;
+    /** 是否创建子目录 */
+    createSubdirectories?: boolean;
+    /** 子目录格式（date: YYYY/MM/DD, hash: AB/CD/EF） */
+    subdirectoryFormat?: 'none' | 'date' | 'hash';
+    /** 最大文件大小 */
+    maxSize?: number;
+    /** 文件权限 */
+    fileMode?: string;
+    /** 目录权限 */
+    dirMode?: string;
+}
+/** S3存储选项 */
+export interface S3StorageOptions {
+    /** AWS访问密钥ID */
+    accessKeyId: string;
+    /** AWS秘密访问密钥 */
+    secretAccessKey: string;
+    /** AWS区域 */
+    region: string;
+    /** S3存储桶名称 */
+    bucket: string;
+    /** 自定义端点 */
+    endpoint?: string;
+    /** ACL（访问控制列表） */
+    acl?: string;
+    /** 服务器端加密 */
+    serverSideEncryption?: string;
+    /** 存储类别 */
+    storageClass?: string;
+    /** 是否启用CDN */
+    cdnEnabled?: boolean;
+    /** CDN域名 */
+    cdnDomain?: string;
+    /** 是否使用路径样式访问 */
+    forcePathStyle?: boolean;
+    /** 签名版本 */
+    signatureVersion?: string;
+}
+/** OSS存储选项 */
+export interface OSSStorageOptions {
+    /** Access Key ID */
+    accessKeyId: string;
+    /** Access Key Secret */
+    accessKeySecret: string;
+    /** OSS区域 */
+    region: string;
+    /** OSS Bucket名称 */
+    bucket: string;
+    /** 内网域名 */
+    internalEndpoint?: string;
+    /** 外网域名 */
+    externalEndpoint?: string;
+    /** 安全令牌（STS） */
+    securityToken?: string;
+    /** 访问权限 */
+    acl?: string;
+    /** 服务器端加密 */
+    serverSideEncryption?: string;
+    /** 是否启用CDN */
+    cdnEnabled?: boolean;
+    /** CDN加速域名 */
+    cdnDomain?: string;
+}
+/** MinIO存储选项 */
+export interface MinIOStorageOptions {
+    /** 端点URL */
+    endPoint: string;
+    /** 端口 */
+    port: number;
+    /** 是否使用SSL */
+    useSSL: boolean;
+    /** Access Key */
+    accessKey: string;
+    /** Secret Key */
+    secretKey: string;
+    /** Bucket名称 */
+    bucket: string;
+    /** Region */
+    region?: string;
+    /** 是否启用CDN */
+    cdnEnabled?: boolean;
+    /** CDN域名 */
+    cdnDomain?: string;
+}
+/** 存储配置 */
+export interface StorageConfig {
+    /** 存储提供者类型 */
+    provider: 'local' | 's3' | 'oss' | 'minio';
+    /** 提供者特定配置 */
+    options: LocalStorageOptions | S3StorageOptions | OSSStorageOptions | MinIOStorageOptions;
+    /** 是否启用备份 */
+    backup?: {
+        enabled: boolean;
+        provider: StorageConfig['provider'];
+        options: StorageConfig['options'];
+    };
+    /** 是否启用镜像 */
+    mirror?: {
+        enabled: boolean;
+        providers: Array<StorageConfig>;
+    };
+    /** 缓存配置 */
+    cache?: {
+        enabled: boolean;
+        ttl: number;
+        maxSize: number;
+    };
+}

package/file-upload/interfaces/storage-provider.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/file-upload/interfaces/upload-options.interface.d.ts

@@ -0,0 +1,19 @@
+/** 上传选项 */
+export interface UploadOptions {
+    /** 文件存储路径前缀 */
+    path?: string;
+    /** 自定义文件名 */
+    filename?: string;
+    /** 文件访问权限 */
+    acl?: 'public-read' | 'private' | 'public-read-write' | 'authenticated-read';
+    /** 文件标签 */
+    tags?: string[];
+    /** 元数据 */
+    metadata?: Record<string, string>;
+    /** 是否覆盖已存在的文件 */
+    overwrite?: boolean;
+    /** 用户ID */
+    userId?: string;
+    /** 自定义选项 */
+    custom?: Record<string, any>;
+}

package/file-upload/interfaces/upload-options.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/file-upload/providers/index.d.ts

@@ -0,0 +1,2 @@
+export * from './local-storage.provider';
+export * from './s3-storage.provider';

package/file-upload/providers/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./local-storage.provider"), exports);
+__exportStar(require("./s3-storage.provider"), exports);