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

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

@@ -1,44 +1,30 @@
-import { CsvDataOptions } from '../interfaces/file-upload-options.interface';
+import 'reflect-metadata';
 /**
- * CSV 列映射元数据键
- */
-export declare const CSV_COLUMN_METADATA = "csv:column";
-/**
- * CSV 列名映射装饰器
+ * CSV 列映射装饰器
+ * 用于标记 DTO 类的属性对应的 CSV 列名
+ *
  * @example
  * ```typescript
- * export class OrderImportDto {
- *   @CsvColumn('订单号')
- *   @IsString()
- *   orderNo: string;
+ * class UserDto {
+ *   @CsvColumn('姓名')
+ *   name: string;
+ *
+ *   @CsvColumn('邮箱')
+ *   email: string;
  * }
  * ```
  */
 export declare function CsvColumn(columnName: string): PropertyDecorator;
 /**
- * CSV 数据参数装饰器
- * @example
- * ```typescript
- * @Post('import/csv')
- * @FileUpload({ types: [FileType.CSV] })
- * async importCsv(@CsvData(OrderImportDto) orders: OrderImportDto[]) {
- *   await this.orderService.batchCreate(orders);
- *   return { count: orders.length };
- * }
- * ```
- */
-export declare const CsvData: (...dataOrPipes: (import("@nestjs/common").PipeTransform<any, any> | import("@nestjs/common").Type<import("@nestjs/common").PipeTransform<any, any>> | {
-    dto: any;
-    options?: CsvDataOptions;
-})[]) => ParameterDecorator;
-/**
- * 辅助函数：获取 DTO 的 CSV 列映射
+ * 获取 CSV 列映射
  */
-export declare function getCsvColumnMapping(dto: any): Map<string, string>;
+export declare function getCsvColumnMapping(dto: any): Record<string, string>;
 /**
- * 辅助函数：解析和验证 CSV 数据
+ * 解析并验证 CSV 数据
  */
-export declare function parseAndValidateCsvData<T extends object>(rawData: any[], dtoClass: new () => T, options?: CsvDataOptions): Promise<{
-    data: T[];
+export declare function parseAndValidateCsvData(data: any[], dto: any, options?: {
+    skipValidation?: boolean;
+}): Promise<{
+    data: any[];
     errors: any[];
 }>;

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

@@ -9,123 +9,77 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CsvData = exports.CSV_COLUMN_METADATA = void 0;
 exports.CsvColumn = CsvColumn;
 exports.getCsvColumnMapping = getCsvColumnMapping;
 exports.parseAndValidateCsvData = parseAndValidateCsvData;
-const common_1 = require("@nestjs/common");
+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 列映射元数据键
- */
-exports.CSV_COLUMN_METADATA = 'csv:column';
-/**
- * CSV 列名映射装饰器
+ * CSV 列映射装饰器
+ * 用于标记 DTO 类的属性对应的 CSV 列名
+ *
  * @example
  * ```typescript
- * export class OrderImportDto {
- *   @CsvColumn('订单号')
- *   @IsString()
- *   orderNo: string;
+ * class UserDto {
+ *   @CsvColumn('姓名')
+ *   name: string;
+ *
+ *   @CsvColumn('邮箱')
+ *   email: string;
  * }
  * ```
  */
 function CsvColumn(columnName) {
     return (target, propertyKey) => {
-        Reflect.defineMetadata(exports.CSV_COLUMN_METADATA, columnName, 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 数据参数装饰器
- * @example
- * ```typescript
- * @Post('import/csv')
- * @FileUpload({ types: [FileType.CSV] })
- * async importCsv(@CsvData(OrderImportDto) orders: OrderImportDto[]) {
- *   await this.orderService.batchCreate(orders);
- *   return { count: orders.length };
- * }
- * ```
- */
-exports.CsvData = (0, common_1.createParamDecorator)((data, ctx) => __awaiter(void 0, void 0, void 0, function* () {
-    const request = ctx.switchToHttp().getRequest();
-    const file = request.file;
-    if (!file) {
-        throw new Error('No file uploaded');
-    }
-    // 这里将在 interceptor 中处理 CSV 解析
-    // 当前只返回文件信息，实际解析逻辑在 FileUploadInterceptor 中
-    return {
-        _csvData: true,
-        dto: data,
-        file,
-        options: data === null || data === void 0 ? void 0 : data['options'],
-    };
-}));
-/**
- * 辅助函数：获取 DTO 的 CSV 列映射
+ * 获取 CSV 列映射
  */
 function getCsvColumnMapping(dto) {
-    const mapping = new Map();
-    const prototype = dto.prototype;
-    if (!prototype) {
-        return mapping;
-    }
-    const propertyKeys = Object.getOwnPropertyNames(prototype);
-    for (const propertyKey of propertyKeys) {
-        const columnName = Reflect.getMetadata(exports.CSV_COLUMN_METADATA, prototype, propertyKey);
-        if (columnName) {
-            mapping.set(columnName, propertyKey);
-        }
-    }
-    return mapping;
+    return Reflect.getMetadata(CSV_COLUMN_METADATA_KEY, dto) || {};
 }
 /**
- * 辅助函数：解析和验证 CSV 数据
+ * 解析并验证 CSV 数据
  */
-function parseAndValidateCsvData(rawData_1, dtoClass_1) {
-    return __awaiter(this, arguments, void 0, function* (rawData, dtoClass, options = {}) {
-        const { skipEmptyLines = true, skipHeader = false } = options;
-        const data = [];
+function parseAndValidateCsvData(data, dto, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const columnMapping = getCsvColumnMapping(dto);
+        const results = [];
         const errors = [];
-        const mapping = getCsvColumnMapping(dtoClass);
-        const startIndex = skipHeader ? 1 : 0;
-        for (let i = startIndex; i < rawData.length; i++) {
-            const row = rawData[i];
-            // 跳过空行
-            if (skipEmptyLines && isEmptyRow(row)) {
-                continue;
-            }
-            const obj = {};
-            // 映射列名到属性名
-            for (const [columnName, propertyKey] of mapping.entries()) {
-                obj[propertyKey] = row[columnName];
+        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)(dtoClass, obj);
+            const instance = (0, class_transformer_1.plainToInstance)(dto, mappedData);
             // 验证
-            const validationErrors = yield (0, class_validator_1.validate)(instance);
-            if (validationErrors.length > 0) {
-                errors.push({
-                    row: i + 1,
-                    data: obj,
-                    errors: validationErrors,
-                });
-            }
-            else {
-                data.push(instance);
+            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, errors };
+        return { data: results, errors };
     });
 }
-/**
- * 检查是否为空行
- */
-function isEmptyRow(row) {
-    if (!row)
-        return true;
-    const values = Object.values(row);
-    return values.every((val) => !val || String(val).trim() === '');
-}

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

@@ -1,44 +1,30 @@
-import { ExcelDataOptions } from '../interfaces/file-upload-options.interface';
+import 'reflect-metadata';
 /**
- * Excel 列映射元数据键
- */
-export declare const EXCEL_COLUMN_METADATA = "excel:column";
-/**
- * Excel 列名映射装饰器
+ * Excel 列映射装饰器
+ * 用于标记 DTO 类的属性对应的 Excel 列名
+ *
  * @example
  * ```typescript
- * export class UserImportDto {
+ * class UserDto {
  *   @ExcelColumn('姓名')
- *   @IsString()
  *   name: string;
+ *
+ *   @ExcelColumn('邮箱')
+ *   email: string;
  * }
  * ```
  */
 export declare function ExcelColumn(columnName: string): PropertyDecorator;
 /**
- * Excel 数据参数装饰器
- * @example
- * ```typescript
- * @Post('import/excel')
- * @FileUpload({ types: [FileType.Excel] })
- * async importExcel(@ExcelData(UserImportDto) users: UserImportDto[]) {
- *   await this.userService.batchCreate(users);
- *   return { count: users.length };
- * }
- * ```
- */
-export declare const ExcelData: (...dataOrPipes: (import("@nestjs/common").PipeTransform<any, any> | import("@nestjs/common").Type<import("@nestjs/common").PipeTransform<any, any>> | {
-    dto: any;
-    options?: ExcelDataOptions;
-})[]) => ParameterDecorator;
-/**
- * 辅助函数：获取 DTO 的 Excel 列映射
+ * 获取 Excel 列映射
  */
-export declare function getExcelColumnMapping(dto: any): Map<string, string>;
+export declare function getExcelColumnMapping(dto: any): Record<string, string>;
 /**
- * 辅助函数：解析和验证 Excel 数据
+ * 解析并验证 Excel 数据
  */
-export declare function parseAndValidateExcelData<T extends object>(rawData: any[], dtoClass: new () => T, options?: ExcelDataOptions): Promise<{
-    data: T[];
+export declare function parseAndValidateExcelData(data: any[], dto: any, options?: {
+    skipValidation?: boolean;
+}): Promise<{
+    data: any[];
     errors: any[];
 }>;