@nest-omni/core 4.1.3-2 → 4.1.3-20

package/file-upload/decorators/column.decorator.js

@@ -0,0 +1,273 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXCEL_COLUMN_METADATA = exports.CSV_COLUMN_METADATA = void 0;
+exports.CSVColumn = CSVColumn;
+exports.ExcelColumn = ExcelColumn;
+exports.getCsvColumnMapping = getCsvColumnMapping;
+exports.getExcelColumnMapping = getExcelColumnMapping;
+exports.excelColumnToNumber = excelColumnToNumber;
+exports.processRowWithMapping = processRowWithMapping;
+exports.numberToExcelColumn = numberToExcelColumn;
+exports.formatValidationErrors = formatValidationErrors;
+exports.createImportResult = createImportResult;
+require("reflect-metadata");
+/**
+ * CSV列名映射元数据键
+ */
+exports.CSV_COLUMN_METADATA = 'csv:column';
+/**
+ * Excel列名映射元数据键
+ */
+exports.EXCEL_COLUMN_METADATA = 'excel:column';
+/**
+ * CSV列装饰器
+ * 用于指定CSV文件中列与DTO属性的映射关系
+ * 支持列名、列序号（从0开始）或Excel列名（A, B, C）
+ *
+ * @example
+ * ```typescript
+ * export class UserImportDto {
+ *   @CSVColumn('姓名')  // 使用列名
+ *   @CSVColumn(0)       // 使用列序号（第一列）
+ *   @CSVColumn('A')     // 使用Excel列名
+ *   @IsString()
+ *   @Length(2, 50)
+ *   name: string;
+ *
+ *   @CSVColumn('年龄')  // 使用列名
+ *   @CSVColumn(1)       // 使用列序号（第二列）
+ *   @CSVColumn('B')     // 使用Excel列名
+ *   @IsNumber()
+ *   @Min(0)
+ *   @Max(150)
+ *   age: number;
+ * }
+ * ```
+ */
+function CSVColumn(columnIdentifier) {
+    return (target, propertyKey) => {
+        // target 是类的原型，我们需要将元数据存储在构造函数上
+        const constructor = target.constructor;
+        const columns = Reflect.getMetadata(exports.CSV_COLUMN_METADATA, constructor) || {};
+        columns[propertyKey] = columnIdentifier;
+        Reflect.defineMetadata(exports.CSV_COLUMN_METADATA, columns, constructor);
+    };
+}
+/**
+ * Excel列装饰器
+ * 用于指定Excel文件中列与DTO属性的映射关系
+ * 支持列名、列序号（从0开始）或Excel列名（A, B, C）
+ *
+ * @example
+ * ```typescript
+ * export class ProductImportDto {
+ *   @ExcelColumn('产品名称')  // 使用列名
+ *   @ExcelColumn(0)           // 使用列序号（第一列）
+ *   @ExcelColumn('A')         // 使用Excel列名
+ *   @IsString()
+ *   @Length(2, 200)
+ *   name: string;
+ *
+ *   @ExcelColumn('价格')     // 使用列名
+ *   @ExcelColumn(1)           // 使用列序号（第二列）
+ *   @ExcelColumn('B')         // 使用Excel列名
+ *   @IsNumber()
+ *   @Min(0)
+ *   price: number;
+ * }
+ * ```
+ */
+function ExcelColumn(columnIdentifier) {
+    return (target, propertyKey) => {
+        // target 是类的原型，我们需要将元数据存储在构造函数上
+        const constructor = target.constructor;
+        const columns = Reflect.getMetadata(exports.EXCEL_COLUMN_METADATA, constructor) || {};
+        columns[propertyKey] = columnIdentifier;
+        Reflect.defineMetadata(exports.EXCEL_COLUMN_METADATA, columns, constructor);
+    };
+}
+/**
+ * 获取CSV列映射信息
+ * 返回列标识到属性名的映射Map
+ *
+ * @param dtoClass DTO类
+ * @returns Map<列标识, 属性名>
+ */
+function getCsvColumnMapping(dtoClass) {
+    const constructor = dtoClass;
+    const mapping = new Map();
+    if (!constructor) {
+        return mapping;
+    }
+    // 从构造函数获取列映射元数据
+    const columns = Reflect.getMetadata(exports.CSV_COLUMN_METADATA, constructor) || {};
+    for (const [propertyKey, columnIdentifier] of Object.entries(columns)) {
+        mapping.set(columnIdentifier, propertyKey);
+    }
+    return mapping;
+}
+/**
+ * 获取Excel列映射信息
+ * 返回列标识到属性名的映射Map
+ *
+ * @param dtoClass DTO类
+ * @returns Map<列标识, 属性名>
+ */
+function getExcelColumnMapping(dtoClass) {
+    const constructor = dtoClass;
+    const mapping = new Map();
+    if (!constructor) {
+        return mapping;
+    }
+    // 从构造函数获取列映射元数据
+    const columns = Reflect.getMetadata(exports.EXCEL_COLUMN_METADATA, constructor) || {};
+    for (const [propertyKey, columnIdentifier] of Object.entries(columns)) {
+        mapping.set(columnIdentifier, propertyKey);
+    }
+    return mapping;
+}
+/**
+ * Excel列名转数字（A=0, B=1, ..., AA=26, AB=27）
+ */
+function excelColumnToNumber(columnLetter) {
+    let result = 0;
+    for (let i = 0; i < columnLetter.length; i++) {
+        const char = columnLetter.toUpperCase().charCodeAt(i) - 64; // A=65, so A-64=1
+        result = result * 26 + char;
+    }
+    return result - 1; // 转换为0基索引
+}
+/**
+ * 处理行数据
+ * 将原始数据行转换为DTO实例，支持多语言错误信息
+ * 支持列名、列序号和Excel列名（A, B, C）
+ *
+ * @param rowData 原始行数据
+ * @param dtoClass DTO类
+ * @param columnMapping 列映射
+ * @param type 数据类型（csv/excel）
+ * @returns 转换结果
+ */
+function processRowWithMapping(rowData, dtoClass, columnMapping, type) {
+    const instance = new dtoClass();
+    const errors = [];
+    // 遍历所有映射的列
+    for (const [columnIdentifier, propertyKey] of columnMapping.entries()) {
+        let value;
+        if (typeof columnIdentifier === 'number') {
+            // 列序号（0基索引）
+            if (Array.isArray(rowData)) {
+                // 如果rowData是数组，直接使用索引
+                value = rowData[columnIdentifier];
+            }
+            else if (type === 'excel') {
+                // Excel数据：尝试将列序号转换为Excel列名
+                const columnLetter = numberToExcelColumn(columnIdentifier);
+                value = rowData[columnLetter];
+            }
+            else {
+                // CSV数据：如果无法通过索引获取，则跳过
+                value = undefined;
+            }
+        }
+        else if (typeof columnIdentifier === 'string') {
+            // 列名或Excel列名
+            // 优先通过列名获取值
+            if (rowData.hasOwnProperty(columnIdentifier)) {
+                value = rowData[columnIdentifier];
+            }
+            else if (type === 'excel' && /^[A-Za-z]+$/.test(columnIdentifier)) {
+                // 如果是Excel列名格式（如A, B, C），但数据中没有，尝试其他方式
+                value = undefined;
+            }
+            // 如果是数组且列标识是特殊的索引格式
+            else if (Array.isArray(rowData) && columnIdentifier.startsWith('__index_')) {
+                const index = parseInt(columnIdentifier.replace('__index_', ''), 10);
+                if (!isNaN(index) && index < rowData.length) {
+                    value = rowData[index];
+                }
+            }
+        }
+        // 设置值到实例
+        instance[propertyKey] = value;
+    }
+    return { instance, errors };
+}
+/**
+ * 数字转Excel列名（0=A, 1=B, ..., 26=AA, 27=AB）
+ */
+function numberToExcelColumn(num) {
+    let result = '';
+    let n = num + 1; // 转换为1基索引
+    while (n > 0) {
+        n--;
+        result = String.fromCharCode(65 + (n % 26)) + result;
+        n = Math.floor(n / 26);
+    }
+    return result;
+}
+/**
+ * 格式化验证错误为多语言
+ * 支持中英文错误信息
+ *
+ * @param errors class-validator错误数组
+ * @returns 格式化后的错误信息
+ */
+function formatValidationErrors(errors) {
+    return errors.map(error => {
+        var _a, _b, _c, _d, _e;
+        const constraint = Object.values(error.constraints)[0];
+        // 英文错误信息直接使用
+        if (/^[a-zA-Z\s]+$/.test(constraint.message)) {
+            return `${error.property}: ${constraint.message}`;
+        }
+        // 中文错误信息特殊处理
+        const chineseMessages = {
+            'isString': '必须是字符串',
+            'isNumber': '必须是数字',
+            'isBoolean': '必须是布尔值',
+            'isDate': '必须是日期格式',
+            'min': `不能小于 ${(_a = constraint.values) === null || _a === void 0 ? void 0 : _a[0]}`,
+            'max': `不能大于 ${(_b = constraint.values) === null || _b === void 0 ? void 0 : _b[0]}`,
+            'minLength': `长度不能少于 ${(_c = constraint.values) === null || _c === void 0 ? void 0 : _c[0]}`,
+            'maxLength': `长度不能超过 ${(_d = constraint.values) === null || _d === void 0 ? void 0 : _d[0]}`,
+            'isEmail': '邮箱格式不正确',
+            'isEnum': `必须是以下值之一: ${(_e = constraint.values) === null || _e === void 0 ? void 0 : _e.join(', ')}`,
+            'matches': '格式不正确',
+        };
+        const ruleName = constraint.message.split(' ')[0];
+        const chineseMessage = chineseMessages[ruleName];
+        if (chineseMessage) {
+            const args = constraint.values || [];
+            let message = chineseMessage;
+            args.forEach(arg => {
+                message = message.replace(/\$\{(\w+)\}/g, (_, key) => {
+                    const index = parseInt(key.replace(/[^\d]/g, '')) - 1;
+                    return args[index] !== undefined ? args[index] : `$${key}`;
+                });
+            });
+            return `${error.property}: ${message}`;
+        }
+        // 默认使用原错误信息
+        return `${error.property}: ${constraint.message}`;
+    });
+}
+/**
+ * 创建CSV数据导入结果
+ * @param data 成功导入的数据
+ * @param errors 错误信息
+ * @param totalRows 总行数
+ * @param headers 表头信息
+ * @returns 导入结果对象
+ */
+function createImportResult(data, errors, totalRows, headers) {
+    return {
+        success: errors.length === 0,
+        data,
+        errors,
+        totalCount: totalRows,
+        successCount: data.length,
+        errorCount: errors.length,
+        headers
+    };
+}

package/file-upload/decorators/csv-data.decorator.d.ts

@@ -0,0 +1,30 @@
+import 'reflect-metadata';
+/**
+ * CSV 列映射装饰器
+ * 用于标记 DTO 类的属性对应的 CSV 列名
+ *
+ * @example
+ * ```typescript
+ * class UserDto {
+ *   @CsvColumn('姓名')
+ *   name: string;
+ *
+ *   @CsvColumn('邮箱')
+ *   email: string;
+ * }
+ * ```
+ */
+export declare function CsvColumn(columnName: string): PropertyDecorator;
+/**
+ * 获取 CSV 列映射
+ */
+export declare function getCsvColumnMapping(dto: any): Record<string, string>;
+/**
+ * 解析并验证 CSV 数据
+ */
+export declare function parseAndValidateCsvData(data: any[], dto: any, options?: {
+    skipValidation?: boolean;
+}): Promise<{
+    data: any[];
+    errors: any[];
+}>;

package/file-upload/decorators/csv-data.decorator.js

@@ -0,0 +1,85 @@
+"use strict";
+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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CsvColumn = CsvColumn;
+exports.getCsvColumnMapping = getCsvColumnMapping;
+exports.parseAndValidateCsvData = parseAndValidateCsvData;
+require("reflect-metadata");
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+const CSV_COLUMN_METADATA_KEY = Symbol('csv:column');
+/**
+ * CSV 列映射装饰器
+ * 用于标记 DTO 类的属性对应的 CSV 列名
+ *
+ * @example
+ * ```typescript
+ * class UserDto {
+ *   @CsvColumn('姓名')
+ *   name: string;
+ *
+ *   @CsvColumn('邮箱')
+ *   email: string;
+ * }
+ * ```
+ */
+function CsvColumn(columnName) {
+    return (target, propertyKey) => {
+        const existingColumns = Reflect.getMetadata(CSV_COLUMN_METADATA_KEY, target.constructor) || {};
+        existingColumns[columnName] = propertyKey;
+        Reflect.defineMetadata(CSV_COLUMN_METADATA_KEY, existingColumns, target.constructor);
+    };
+}
+/**
+ * 获取 CSV 列映射
+ */
+function getCsvColumnMapping(dto) {
+    return Reflect.getMetadata(CSV_COLUMN_METADATA_KEY, dto) || {};
+}
+/**
+ * 解析并验证 CSV 数据
+ */
+function parseAndValidateCsvData(data, dto, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const columnMapping = getCsvColumnMapping(dto);
+        const results = [];
+        const errors = [];
+        for (let i = 0; i < data.length; i++) {
+            const row = data[i];
+            const mappedData = {};
+            // 映射列名
+            for (const [csvColumn, dtoProperty] of Object.entries(columnMapping)) {
+                if (row.hasOwnProperty(csvColumn)) {
+                    mappedData[dtoProperty] = row[csvColumn];
+                }
+            }
+            // 转换为 DTO 实例
+            const instance = (0, class_transformer_1.plainToInstance)(dto, mappedData);
+            // 验证
+            if (!(options === null || options === void 0 ? void 0 : options.skipValidation)) {
+                const validationErrors = yield (0, class_validator_1.validate)(instance);
+                if (validationErrors.length > 0) {
+                    errors.push({
+                        row: i + 1,
+                        data: row,
+                        errors: validationErrors.map((e) => ({
+                            property: e.property,
+                            constraints: e.constraints,
+                        })),
+                    });
+                    continue;
+                }
+            }
+            results.push(instance);
+        }
+        return { data: results, errors };
+    });
+}

package/file-upload/decorators/csv-import.decorator.d.ts

@@ -0,0 +1,34 @@
+import { CsvProcessorOptions } from '../processors/csv.processor';
+import { ValidateDataOptions } from './validate-data.decorator';
+/**
+ * CSV 处理装饰器元数据键
+ */
+export declare const CSV_PROCESS_KEY = "csv:process";
+/**
+ * CSV 数据处理选项
+ */
+export interface CsvDataOptions extends CsvProcessorOptions {
+    /** 验证类（使用 class-validator） */
+    validateClass?: any;
+    /** 验证选项 */
+    validation?: ValidateDataOptions;
+    /** 批处理大小 */
+    batchSize?: number;
+    /** 是否异步处理 */
+    async?: boolean;
+}
+/**
+ * CSV 数据处理装饰器
+ * 用于标记方法处理 CSV 文件数据
+ */
+export declare const CsvData: (options?: CsvDataOptions) => import("@nestjs/common").CustomDecorator<string>;
+/**
+ * CSV 批量导入装饰器
+ * 专门用于批量导入场景
+ */
+export declare const CsvImport: (validateClass: any, options?: Omit<CsvDataOptions, "validateClass"> & {
+    /** 目标服务名 */
+    service?: string;
+    /** 目标方法名 */
+    method?: string;
+}) => import("@nestjs/common").CustomDecorator<string>;

package/file-upload/decorators/csv-import.decorator.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CsvImport = exports.CsvData = exports.CSV_PROCESS_KEY = void 0;
+const common_1 = require("@nestjs/common");
+/**
+ * CSV 处理装饰器元数据键
+ */
+exports.CSV_PROCESS_KEY = 'csv:process';
+/**
+ * CSV 数据处理装饰器
+ * 用于标记方法处理 CSV 文件数据
+ */
+const CsvData = (options = {}) => {
+    return (0, common_1.SetMetadata)(exports.CSV_PROCESS_KEY, options);
+};
+exports.CsvData = CsvData;
+/**
+ * CSV 批量导入装饰器
+ * 专门用于批量导入场景
+ */
+const CsvImport = (validateClass, options = {}) => {
+    return (0, common_1.SetMetadata)(exports.CSV_PROCESS_KEY, Object.assign(Object.assign({}, options), { validateClass, type: 'import' }));
+};
+exports.CsvImport = CsvImport;

package/file-upload/decorators/examples/column-mapping.example.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 用户导入DTO示例
+ * 展示如何使用列序号、列名和Excel列名进行映射
+ */
+export declare class UserImportDto {
+    /**
+     * 使用列名映射（推荐，更易读）
+     * CSV: 通过表头"姓名"找到列
+     * Excel: 通过表头"姓名"或列名"A"找到列
+     */
+    name: string;
+    /**
+     * 使用列序号映射（从0开始）
+     * CSV: 第2列（索引为1）
+     * Excel: 第2列（B列）
+     */
+    age: number;
+    /**
+     * 使用Excel列名映射
+     * CSV: 如果没有表头，需要使用数字索引
+     * Excel: 可以直接使用列名"C"
+     */
+    email: string;
+    /**
+     * 混合使用不同的映射方式
+     */
+    phone?: string;
+    /**
+     * 使用较大的列索引
+     */
+    address?: string;
+    /**
+     * 使用更大的Excel列名（如AA, AB等）
+     */
+    notes?: string;
+}
+/**
+ * 产品导入DTO示例
+ */
+export declare class ProductImportDto {
+    /**
+     * 产品名称 - 第1列
+     */
+    name: string;
+    /**
+     * 价格 - 第2列
+     */
+    price: number;
+    /**
+     * 库存 - 第3列
+     */
+    stock: number;
+    /**
+     * 描述 - 第4列（可选）
+     */
+    description?: string;
+}
+/**
+ * 使用说明：
+ *
+ * 1. CSV文件：
+ *    - 如果CSV有表头，建议使用列名（如 @CSVColumn('姓名')）
+ *    - 如果CSV没有表头，使用数字索引（如 @CSVColumn(0) 表示第1列）
+ *
+ * 2. Excel文件：
+ *    - 可以使用列名（如 @ExcelColumn('姓名')）
+ *    - 可以使用数字索引（如 @ExcelColumn(0) 表示第1列）
+ *    - 可以使用Excel列名（如 @ExcelColumn('A') 表示A列）
+ *    - 数字索引会自动转换为对应的Excel列名（0 -> A, 1 -> B, 26 -> AA）
+ *
+ * 3. 最佳实践：
+ *    - 优先使用列名，代码更易读
+ *    - 对于无表头的CSV文件，使用数字索引
+ *    - 对于Excel文件，推荐使用Excel列名（A, B, C）或数字索引
+ *    - 可以混合使用不同的映射方式
+ */ 

package/file-upload/decorators/examples/column-mapping.example.js

@@ -0,0 +1,122 @@
+"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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProductImportDto = exports.UserImportDto = void 0;
+const column_decorator_1 = require("../column.decorator");
+const class_validator_1 = require("class-validator");
+/**
+ * 用户导入DTO示例
+ * 展示如何使用列序号、列名和Excel列名进行映射
+ */
+class UserImportDto {
+}
+exports.UserImportDto = UserImportDto;
+__decorate([
+    (0, column_decorator_1.CSVColumn)('姓名'),
+    (0, column_decorator_1.ExcelColumn)('姓名'),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], UserImportDto.prototype, "name", void 0);
+__decorate([
+    (0, column_decorator_1.CSVColumn)(1),
+    (0, column_decorator_1.ExcelColumn)(1),
+    (0, class_validator_1.IsNumber)(),
+    (0, class_validator_1.Min)(0),
+    (0, class_validator_1.Max)(150),
+    __metadata("design:type", Number)
+], UserImportDto.prototype, "age", void 0);
+__decorate([
+    (0, column_decorator_1.CSVColumn)(2) // CSV使用数字索引
+    ,
+    (0, column_decorator_1.ExcelColumn)('C') // Excel使用列名
+    ,
+    (0, class_validator_1.IsEmail)(),
+    __metadata("design:type", String)
+], UserImportDto.prototype, "email", void 0);
+__decorate([
+    (0, column_decorator_1.CSVColumn)('电话') // CSV使用列名
+    ,
+    (0, column_decorator_1.ExcelColumn)('D') // Excel使用列名
+    ,
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], UserImportDto.prototype, "phone", void 0);
+__decorate([
+    (0, column_decorator_1.CSVColumn)(4) // 第5列
+    ,
+    (0, column_decorator_1.ExcelColumn)('E') // 或使用Excel列名
+    ,
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], UserImportDto.prototype, "address", void 0);
+__decorate([
+    (0, column_decorator_1.CSVColumn)(26) // 第27列
+    ,
+    (0, column_decorator_1.ExcelColumn)('AA') // Excel列AA
+    ,
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], UserImportDto.prototype, "notes", void 0);
+/**
+ * 产品导入DTO示例
+ */
+class ProductImportDto {
+}
+exports.ProductImportDto = ProductImportDto;
+__decorate([
+    (0, column_decorator_1.CSVColumn)('产品名称'),
+    (0, column_decorator_1.ExcelColumn)(0),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], ProductImportDto.prototype, "name", void 0);
+__decorate([
+    (0, column_decorator_1.CSVColumn)('价格'),
+    (0, column_decorator_1.ExcelColumn)('B'),
+    (0, class_validator_1.IsNumber)(),
+    (0, class_validator_1.Min)(0),
+    __metadata("design:type", Number)
+], ProductImportDto.prototype, "price", void 0);
+__decorate([
+    (0, column_decorator_1.CSVColumn)('库存数量'),
+    (0, column_decorator_1.ExcelColumn)(2),
+    (0, class_validator_1.IsNumber)(),
+    (0, class_validator_1.Min)(0),
+    __metadata("design:type", Number)
+], ProductImportDto.prototype, "stock", void 0);
+__decorate([
+    (0, column_decorator_1.CSVColumn)(3),
+    (0, column_decorator_1.ExcelColumn)('D'),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], ProductImportDto.prototype, "description", void 0);
+/**
+ * 使用说明：
+ *
+ * 1. CSV文件：
+ *    - 如果CSV有表头，建议使用列名（如 @CSVColumn('姓名')）
+ *    - 如果CSV没有表头，使用数字索引（如 @CSVColumn(0) 表示第1列）
+ *
+ * 2. Excel文件：
+ *    - 可以使用列名（如 @ExcelColumn('姓名')）
+ *    - 可以使用数字索引（如 @ExcelColumn(0) 表示第1列）
+ *    - 可以使用Excel列名（如 @ExcelColumn('A') 表示A列）
+ *    - 数字索引会自动转换为对应的Excel列名（0 -> A, 1 -> B, 26 -> AA）
+ *
+ * 3. 最佳实践：
+ *    - 优先使用列名，代码更易读
+ *    - 对于无表头的CSV文件，使用数字索引
+ *    - 对于Excel文件，推荐使用Excel列名（A, B, C）或数字索引
+ *    - 可以混合使用不同的映射方式
+ */ 

package/file-upload/decorators/excel-data.decorator.d.ts

@@ -0,0 +1,30 @@
+import 'reflect-metadata';
+/**
+ * Excel 列映射装饰器
+ * 用于标记 DTO 类的属性对应的 Excel 列名
+ *
+ * @example
+ * ```typescript
+ * class UserDto {
+ *   @ExcelColumn('姓名')
+ *   name: string;
+ *
+ *   @ExcelColumn('邮箱')
+ *   email: string;
+ * }
+ * ```
+ */
+export declare function ExcelColumn(columnName: string): PropertyDecorator;
+/**
+ * 获取 Excel 列映射
+ */
+export declare function getExcelColumnMapping(dto: any): Record<string, string>;
+/**
+ * 解析并验证 Excel 数据
+ */
+export declare function parseAndValidateExcelData(data: any[], dto: any, options?: {
+    skipValidation?: boolean;
+}): Promise<{
+    data: any[];
+    errors: any[];
+}>;