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

package/dist/file-upload/interceptors/file-upload.interceptor.js

@@ -0,0 +1,594 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var FileUploadInterceptor_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileUploadInterceptor = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const rxjs_1 = require("rxjs");
+const operators_1 = require("rxjs/operators");
+const file_upload_decorator_1 = require("../decorators/file-upload.decorator");
+const file_entity_interface_1 = require("../interfaces/file-entity.interface");
+const file_service_1 = require("../services/file.service");
+const file_signature_validator_service_1 = require("../services/file-signature-validator.service");
+const malicious_file_detector_service_1 = require("../services/malicious-file-detector.service");
+const mime_registry_service_1 = require("../services/mime-registry.service");
+const utils_1 = require("../utils");
+const file_upload_exception_1 = require("../exceptions/file-upload.exception");
+const fs = require("fs-extra");
+const crypto = require("crypto");
+/**
+ * 文件上传拦截器（优化版）
+ * 负责创建文件记录、执行钩子、处理器等后置逻辑
+ */
+let FileUploadInterceptor = FileUploadInterceptor_1 = class FileUploadInterceptor {
+    constructor(reflector, mimeRegistry, processors, fileService, signatureValidator, maliciousDetector, moduleOptions) {
+        this.reflector = reflector;
+        this.mimeRegistry = mimeRegistry;
+        this.processors = processors;
+        this.fileService = fileService;
+        this.signatureValidator = signatureValidator;
+        this.maliciousDetector = maliciousDetector;
+        this.moduleOptions = moduleOptions;
+        this.logger = new common_1.Logger(FileUploadInterceptor_1.name);
+    }
+    intercept(context, next) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const options = this.reflector.get(file_upload_decorator_1.FILE_UPLOAD_OPTIONS, context.getHandler());
+            if (!options) {
+                return next.handle();
+            }
+            const request = context.switchToHttp().getRequest();
+            const file = request.file;
+            if (!file) {
+                return next.handle();
+            }
+            // 快速路径：如果没有配置验证选项，直接跳过验证
+            if (this.shouldSkipValidation(options, request)) {
+                return this.processFile(file, request, options, next);
+            }
+            // 执行验证
+            yield this.validateFile(file, options, request);
+            // 处理文件
+            return this.processFile(file, request, options, next);
+        });
+    }
+    /**
+     * 判断是否应该跳过验证
+     */
+    shouldSkipValidation(options, request) {
+        var _a, _b;
+        return (!options.maxSize &&
+            !((_a = options.types) === null || _a === void 0 ? void 0 : _a.length) &&
+            !((_b = options.exts) === null || _b === void 0 ? void 0 : _b.length) &&
+            !options.auth &&
+            options.validateSignature === false &&
+            options.maliciousCheck === false);
+    }
+    /**
+     * 验证文件
+     */
+    validateFile(file, options, request) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // 1. 验证文件大小
+            if (options.maxSize && file.size > options.maxSize) {
+                throw new file_upload_exception_1.FileSizeExceededException(file.size, options.maxSize);
+            }
+            // 2. 验证权限
+            if (options.auth && !request.user) {
+                throw new common_1.UnauthorizedException('Authentication required for file upload');
+            }
+            // 3. 验证文件名
+            if (options.sanitize !== false) {
+                const sanitized = utils_1.FileNameUtil.sanitize(file.originalname);
+                if (!sanitized || sanitized.length === 0) {
+                    throw new file_upload_exception_1.InvalidFilenameException(file.originalname);
+                }
+            }
+            // 4. 批量验证文件类型和扩展名
+            yield this.validateFileTypeAndExtension(file, options);
+            // 5. 文件签名验证（可选）
+            if (this.shouldPerformSignatureValidation(options) && file.path) {
+                yield this.validateFileSignature(file, options);
+            }
+            // 6. 恶意文件检测（可选）
+            if (this.shouldPerformMaliciousCheck(options)) {
+                yield this.checkMaliciousFile(file, options);
+            }
+        });
+    }
+    /**
+     * 批量验证文件类型和扩展名
+     */
+    validateFileTypeAndExtension(file, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c;
+            if (!((_a = options.types) === null || _a === void 0 ? void 0 : _a.length) && !((_b = options.exts) === null || _b === void 0 ? void 0 : _b.length)) {
+                return;
+            }
+            const allowedTypes = ((_c = options.types) === null || _c === void 0 ? void 0 : _c.length)
+                ? this.mimeRegistry.resolveFileTypes(options.types)
+                : { mimes: [], exts: options.exts || [] };
+            // 获取文件扩展名
+            const ext = utils_1.FileNameUtil.extractExtension(file.originalname);
+            // 同时验证 MIME 类型和扩展名
+            const mimeValid = !allowedTypes.mimes.length ||
+                allowedTypes.mimes.some((mime) => mime.endsWith('/*')
+                    ? file.mimetype.startsWith(mime.slice(0, -2))
+                    : mime === file.mimetype);
+            const extValid = !allowedTypes.exts.length ||
+                allowedTypes.exts.some((allowedExt) => allowedExt.toLowerCase() === ext.toLowerCase());
+            if (!mimeValid || !extValid) {
+                if (!mimeValid) {
+                    throw new file_upload_exception_1.FileTypeNotAllowedException(file.mimetype, allowedTypes.mimes);
+                }
+                if (!extValid) {
+                    throw new file_upload_exception_1.FileExtensionNotAllowedException(ext, allowedTypes.exts);
+                }
+            }
+        });
+    }
+    /**
+     * 判断是否需要执行文件签名验证
+     */
+    shouldPerformSignatureValidation(options) {
+        var _a, _b;
+        return (options.validateSignature !== false &&
+            ((_a = this.moduleOptions) === null || _a === void 0 ? void 0 : _a.validateSignature) !== false &&
+            this.signatureValidator &&
+            ((_b = options.types) === null || _b === void 0 ? void 0 : _b.length) > 0);
+    }
+    /**
+     * 验证文件签名
+     */
+    validateFileSignature(file, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d;
+            try {
+                const allowedTypes = this.mimeRegistry.resolveFileTypes(options.types);
+                if (allowedTypes.signatureTypes.length === 0) {
+                    return;
+                }
+                const signatureResult = yield this.signatureValidator.validateFileSignature(file.path, allowedTypes.signatureTypes, (_a = this.moduleOptions) === null || _a === void 0 ? void 0 : _a.signatureValidation);
+                if (!signatureResult.valid) {
+                    const detectedType = (_b = signatureResult.detectedTypes[0]) === null || _b === void 0 ? void 0 : _b.type;
+                    throw new file_upload_exception_1.FileSignatureMismatchException(signatureResult.errors.join(', '), file.mimetype, detectedType);
+                }
+                // 附加验证数据到请求
+                if (signatureResult) {
+                    file._validationData = signatureResult;
+                }
+            }
+            catch (error) {
+                if (error instanceof file_upload_exception_1.FileSignatureMismatchException) {
+                    throw error;
+                }
+                if ((_d = (_c = this.moduleOptions) === null || _c === void 0 ? void 0 : _c.signatureValidation) === null || _d === void 0 ? void 0 : _d.strict) {
+                    throw error;
+                }
+                // 非严格模式下只记录警告
+                this.logger.warn(`Signature validation failed: ${error.message}`);
+            }
+        });
+    }
+    /**
+     * 判断是否需要执行恶意文件检测
+     */
+    shouldPerformMaliciousCheck(options) {
+        var _a, _b;
+        return (options.maliciousCheck !== false &&
+            ((_b = (_a = this.moduleOptions) === null || _a === void 0 ? void 0 : _a.maliciousDetection) === null || _b === void 0 ? void 0 : _b.enabled) !== false &&
+            !!this.maliciousDetector);
+    }
+    /**
+     * 检测恶意文件
+     */
+    checkMaliciousFile(file, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                // For in-memory files, use buffer; for disk files, use path
+                const maliciousCheck = file.path
+                    ? yield this.maliciousDetector.scanFile(file.path)
+                    : yield this.maliciousDetector.scanFile(undefined, file.buffer);
+                if (!maliciousCheck.safe) {
+                    throw new file_upload_exception_1.MaliciousFileException(maliciousCheck.threats);
+                }
+                // 附加检测数据到请求
+                if (maliciousCheck) {
+                    file._maliciousCheck = maliciousCheck;
+                }
+            }
+            catch (error) {
+                if (error instanceof file_upload_exception_1.MaliciousFileException) {
+                    throw error;
+                }
+                // 检测出错，记录日志但继续
+                this.logger.error(`Malicious detection error: ${error.message}`);
+            }
+        });
+    }
+    /**
+     * 处理文件
+     */
+    processFile(file, request, options, next) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // 创建文件实体记录（如果可用）
+            const { fileEntity, uploadId } = yield this.createFileEntity(file, request);
+            // 创建上传上下文
+            const uploadContext = this.createUploadContext(request, fileEntity);
+            try {
+                // 执行 before 钩子
+                if (options.before) {
+                    yield options.before(file, uploadContext);
+                }
+                // 执行处理器
+                const processResult = yield this.executeProcessors(file, request, options);
+                if (processResult) {
+                    request._processResult = processResult;
+                }
+                // 如果需要，在处理后删除原文件
+                const shouldDeleteFile = this.shouldDeleteAfterProcess(options, processResult);
+                return next.handle().pipe((0, operators_1.tap)((response) => __awaiter(this, void 0, void 0, function* () {
+                    // 执行 after 钩子
+                    if (options.after) {
+                        yield options.after(file, uploadContext);
+                    }
+                    // 更新文件实体状态
+                    if (fileEntity && this.fileService) {
+                        yield this.updateFileEntityOnSuccess(fileEntity, uploadId, file, response);
+                    }
+                    // 处理完成后删除原文件
+                    if (shouldDeleteFile && file.path) {
+                        yield this.deleteOriginalFile(file, fileEntity);
+                    }
+                })), (0, operators_1.catchError)((error) => __awaiter(this, void 0, void 0, function* () {
+                    // 清理资源
+                    if (fileEntity && this.fileService) {
+                        yield this.cleanupOnFailure(fileEntity, file, error);
+                    }
+                    return (0, rxjs_1.throwError)(() => error);
+                })));
+            }
+            catch (error) {
+                // 处理失败，更新状态
+                if (fileEntity && this.fileService) {
+                    yield this.fileService.update(fileEntity.id, {
+                        status: 'failed',
+                        errorMessage: error.message,
+                    });
+                }
+                throw error;
+            }
+        });
+    }
+    /**
+     * 创建文件实体
+     */
+    createFileEntity(file, request) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            if (!this.fileService) {
+                return { fileEntity: null, uploadId: null };
+            }
+            try {
+                const uploadId = request.body.uploadId || this.generateUploadId();
+                const checksum = file.path
+                    ? yield utils_1.ChecksumUtil.calculate(file.path, 'md5')
+                    : undefined;
+                const originalName = utils_1.FileNameUtil.decodeAndNormalize(file.originalname);
+                const fileEntity = yield this.fileService.create({
+                    originalName,
+                    filename: file.filename,
+                    mimeType: file.mimetype,
+                    size: file.size,
+                    tempPath: file.path,
+                    storageProvider: 'local',
+                    userId: (_a = request.user) === null || _a === void 0 ? void 0 : _a.id,
+                    uploadId,
+                    status: 'processing',
+                    checksum,
+                });
+                // 自动检测并设置文件类型
+                fileEntity.detectAndSetFileType();
+                yield this.fileService.update(fileEntity.id, {
+                    fileType: fileEntity.fileType,
+                    extension: fileEntity.extension,
+                });
+                // 添加验证数据（如果有）
+                const validationData = file._validationData;
+                if (validationData) {
+                    fileEntity.addValidationData({
+                        detectedTypes: validationData.detectedTypes || [],
+                        signatures: ((_b = validationData.metadata) === null || _b === void 0 ? void 0 : _b.signatures) || [],
+                        integrityChecks: [],
+                    });
+                    yield this.fileService.update(fileEntity.id, {
+                        validationData: fileEntity.validationData,
+                    });
+                }
+                // 附加到请求对象
+                request.fileEntity = fileEntity;
+                request.uploadId = uploadId;
+                return { fileEntity, uploadId };
+            }
+            catch (error) {
+                this.logger.error(`Failed to create file entity: ${error.message}`);
+                return { fileEntity: null, uploadId: null };
+            }
+        });
+    }
+    /**
+     * 执行处理器
+     */
+    executeProcessors(file, request, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // 装饰器配置的处理器
+            if (options.processor) {
+                const processorConfig = typeof options.processor === 'string'
+                    ? { name: options.processor, options: undefined }
+                    : options.processor;
+                const processor = this.getProcessor(processorConfig.name);
+                if (processor) {
+                    const fileEntity = this.convertToFileEntity(file);
+                    // 使用请求上的 fileEntity（如果有）
+                    const actualFileEntity = request.fileEntity || fileEntity;
+                    if (request.fileEntity) {
+                        fileEntity.id = request.fileEntity.id;
+                    }
+                    // 记录处理开始
+                    if (actualFileEntity.id && this.fileService) {
+                        yield this.fileService.updateProcessingStatus(actualFileEntity.id, processorConfig.name, 'pending');
+                    }
+                    // 合并处理器选项
+                    const mergedOptions = Object.assign(Object.assign({}, processorConfig.options), options.processorOptions);
+                    const result = yield processor.process(fileEntity, mergedOptions);
+                    // 将处理结果保存到 file_metadata 表
+                    if (result && actualFileEntity.id && this.fileService) {
+                        yield this.saveProcessorResultToMetadata(actualFileEntity.id, processorConfig.name, result, mergedOptions);
+                    }
+                    // 记录处理成功
+                    if (actualFileEntity.id && this.fileService) {
+                        yield this.fileService.updateProcessingStatus(actualFileEntity.id, processorConfig.name, 'completed', result);
+                    }
+                    return result;
+                }
+            }
+            // 参数装饰器指定的处理器
+            if (request._processParams) {
+                const { name, options: procOptions } = request._processParams;
+                const processor = this.getProcessor(name);
+                if (processor) {
+                    const fileEntity = this.convertToFileEntity(file);
+                    return yield processor.process(fileEntity, procOptions);
+                }
+            }
+            return null;
+        });
+    }
+    /**
+     * 转换为 FileEntity
+     */
+    convertToFileEntity(file) {
+        return {
+            id: file.filename || '',
+            originalName: file.originalname,
+            fileName: file.filename,
+            mimeType: file.mimetype,
+            size: file.size,
+            hash: '',
+            storage: 'local',
+            path: file.path,
+            uploadedAt: new Date(),
+            status: file_entity_interface_1.FileStatus.PROCESSING,
+        };
+    }
+    /**
+     * 更新成功状态
+     */
+    updateFileEntityOnSuccess(fileEntity, uploadId, file, response) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const relativePath = utils_1.FilePathUtil.toRelativePath(file.path);
+                yield this.fileService.update(fileEntity.id, {
+                    path: relativePath || (response === null || response === void 0 ? void 0 : response.path),
+                    status: 'completed',
+                });
+                // 添加文件信息到响应
+                if (typeof response === 'object' && response !== null) {
+                    response.fileId = fileEntity.id;
+                    response.uploadId = uploadId;
+                }
+                // 同时将 fileId 添加到 file 对象，方便 controller 访问
+                file.fileId = fileEntity.id;
+            }
+            catch (error) {
+                this.logger.error(`Error updating file record: ${error.message}`);
+            }
+        });
+    }
+    /**
+     * 清理失败的文件
+     */
+    cleanupOnFailure(fileEntity, file, error) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                yield this.fileService.update(fileEntity.id, {
+                    status: 'failed',
+                    errorMessage: error.message || 'Unknown error',
+                });
+                // 清理临时文件
+                if (file.path) {
+                    yield fs.unlink(file.path).catch((unlinkError) => {
+                        if (unlinkError.code !== 'ENOENT') {
+                            this.logger.error(`Failed to cleanup file: ${unlinkError.message}`);
+                        }
+                    });
+                }
+            }
+            catch (cleanupError) {
+                this.logger.error(`Error during cleanup: ${cleanupError.message}`);
+            }
+        });
+    }
+    /**
+     * 创建上传上下文
+     */
+    createUploadContext(request, fileEntity) {
+        return {
+            getProcessor: (name) => this.getProcessor(name),
+            saveMetadata: (fileId, metadata) => __awaiter(this, void 0, void 0, function* () {
+                if (this.fileService && fileEntity) {
+                    try {
+                        for (const [key, value] of Object.entries(metadata)) {
+                            yield this.fileService.addMetadata(fileEntity.id, key, value);
+                        }
+                    }
+                    catch (error) {
+                        this.logger.error(`Failed to save metadata: ${error.message}`);
+                    }
+                }
+                request['_fileMetadata'] = request['_fileMetadata'] || {};
+                request['_fileMetadata'][fileId] = metadata;
+            }),
+            getUser: () => request['user'],
+            getRequest: () => request,
+            shared: request['_shared'] || (request['_shared'] = {}),
+        };
+    }
+    /**
+     * 获取处理器
+     */
+    getProcessor(name) {
+        var _a;
+        return ((_a = this.processors) === null || _a === void 0 ? void 0 : _a.get(name)) || null;
+    }
+    /**
+     * 生成uploadId
+     */
+    generateUploadId() {
+        return `upload_${Date.now()}_${crypto.randomBytes(4).toString('hex')}`;
+    }
+    /**
+     * 判断是否应该在处理后删除原文件
+     */
+    shouldDeleteAfterProcess(options, processResult) {
+        var _a, _b;
+        // 检查 processorOptions 中的 deleteAfterProcess 选项
+        if (((_a = options.processorOptions) === null || _a === void 0 ? void 0 : _a.deleteAfterProcess) === true) {
+            return true;
+        }
+        // 检查 processor 配置中的 deleteAfterProcess
+        if (typeof options.processor === 'object') {
+            if (((_b = options.processor.options) === null || _b === void 0 ? void 0 : _b.deleteAfterProcess) === true) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * 将处理器结果保存到 file_metadata 表
+     * 处理器可以通过返回结果中的 metadata 字段来指定要保存的内容
+     */
+    saveProcessorResultToMetadata(fileId, processorName, result, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                // 检查是否启用 saveToMetadata
+                if ((options === null || options === void 0 ? void 0 : options.saveToMetadata) === false) {
+                    return;
+                }
+                // 如果结果为空或不是对象，直接返回
+                if (!result || typeof result !== 'object') {
+                    return;
+                }
+                const metadataKey = (options === null || options === void 0 ? void 0 : options.metadataKey) || `${processorName}_parsed_data`;
+                // 准备要保存的数据
+                let metadataValue;
+                // 优先使用处理器返回的 metadata 字段
+                if (result.metadata && typeof result.metadata === 'object') {
+                    // 处理器自己决定要保存的内容
+                    metadataValue = Object.assign(Object.assign({}, result.metadata), { timestamp: result.metadata.timestamp || new Date().toISOString(), processorName: result.metadata.processorName || processorName });
+                }
+                else {
+                    // 备选方案：保存整个结果（向后兼容）
+                    metadataValue = {
+                        timestamp: new Date().toISOString(),
+                        processorName,
+                        result,
+                    };
+                }
+                // 保存到 file_metadata 表
+                yield this.fileService.addMetadata(fileId, metadataKey, metadataValue);
+                this.logger.log(`Processor result saved to metadata: ${metadataKey} for file ${fileId}`);
+            }
+            catch (error) {
+                this.logger.error(`Failed to save processor result to metadata: ${error.message}`);
+                // 不抛出错误，避免影响主流程
+            }
+        });
+    }
+    /**
+     * 删除原文件
+     */
+    deleteOriginalFile(file, fileEntity) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                // 删除物理文件
+                yield fs.unlink(file.path).catch((error) => {
+                    if (error.code !== 'ENOENT') {
+                        throw error;
+                    }
+                });
+                this.logger.log(`Original file deleted after processing: ${file.originalname} (${file.path})`);
+                // 如果有文件实体，更新状态或标记
+                if (fileEntity && this.fileService) {
+                    yield this.fileService.addMetadata(fileEntity.id, 'original_file_deleted', {
+                        deletedAt: new Date().toISOString(),
+                        reason: 'deleted_after_processing',
+                        originalPath: file.path,
+                    });
+                }
+            }
+            catch (error) {
+                this.logger.error(`Failed to delete original file after processing: ${error.message}`);
+                // 不抛出错误，避免影响主流程
+            }
+        });
+    }
+};
+exports.FileUploadInterceptor = FileUploadInterceptor;
+exports.FileUploadInterceptor = FileUploadInterceptor = FileUploadInterceptor_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(2, (0, common_1.Optional)()),
+    __param(2, (0, common_1.Inject)('FILE_PROCESSORS')),
+    __param(3, (0, common_1.Optional)()),
+    __param(4, (0, common_1.Optional)()),
+    __param(5, (0, common_1.Optional)()),
+    __param(6, (0, common_1.Optional)()),
+    __param(6, (0, common_1.Inject)('FILE_UPLOAD_OPTIONS')),
+    __metadata("design:paramtypes", [core_1.Reflector,
+        mime_registry_service_1.MimeRegistryService,
+        Map,
+        file_service_1.FileService,
+        file_signature_validator_service_1.FileSignatureValidator,
+        malicious_file_detector_service_1.MaliciousFileDetector, Object])
+], FileUploadInterceptor);

package/dist/file-upload/interfaces/file-processor.interface.d.ts

@@ -0,0 +1,93 @@
+import { FileEntity } from './file-entity.interface';
+import { ProcessOptions, ProcessResult } from './processor-options.interface';
+/**
+ * 文件处理器基础接口
+ */
+export interface IFileProcessor {
+    /** 处理器名称 */
+    readonly name: string;
+    /** 支持的MIME类型 */
+    readonly supportedTypes: string[];
+    /**
+     * 验证文件是否可以被此处理器处理
+     * @param buffer 文件缓冲区
+     * @returns 是否支持
+     */
+    validate(buffer: Buffer): Promise<boolean>;
+    /**
+     * 处理文件
+     * @param file 文件实体
+     * @param options 处理选项
+     * @returns 处理结果
+     */
+    process(file: FileEntity, options: ProcessOptions): Promise<ProcessResult>;
+    /**
+     * 获取处理器信息（可选）
+     */
+    getInfo?(): ProcessorInfo;
+    /**
+     * 清理资源（可选）
+     */
+    cleanup?(): Promise<void>;
+    /**
+     * 健康检查（可选）
+     */
+    healthCheck?(): Promise<boolean>;
+}
+/**
+ * 处理器信息
+ */
+export interface ProcessorInfo {
+    /** 处理器名称 */
+    name: string;
+    /** 处理器版本 */
+    version: string;
+    /** 处理器描述 */
+    description: string;
+    /** 支持的文件类型 */
+    supportedTypes: string[];
+    /** 支持的文件扩展名 */
+    supportedExtensions: string[];
+    /** 处理器能力 */
+    capabilities: ProcessorCapabilities;
+    /** 性能指标 */
+    performance?: {
+        /** 最大文件大小（字节） */
+        maxFileSize?: number;
+        /** 平均处理时间（毫秒/MB） */
+        avgProcessTime?: number;
+        /** 内存使用量（MB） */
+        memoryUsage?: number;
+    };
+    /** 配置选项 */
+    configOptions?: Record<string, {
+        type: string;
+        description: string;
+        required?: boolean;
+        default?: any;
+        enum?: any[];
+    }>;
+}
+/**
+ * 处理器能力
+ */
+export interface ProcessorCapabilities {
+    /** 是否支持读取 */
+    read: boolean;
+    /** 是否支持写入 */
+    write: boolean;
+    /** 是否支持转换 */
+    transform: boolean;
+    /** 是否支持批量处理 */
+    batch: boolean;
+    /** 是否支持流式处理 */
+    stream: boolean;
+    /** 是否支持实时处理 */
+    realtime: boolean;
+    /** 是否支持并行处理 */
+    parallel: boolean;
+    /** 是否支持压缩 */
+    compress: boolean;
+    /** 是否支持加密 */
+    encrypt: boolean;
+}