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

package/common/dto/dto-extensions.js

@@ -12,6 +12,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.transformEntityToDto = transformEntityToDto;
 const typeorm_1 = require("typeorm");
 const dto_transformer_1 = require("./dto-transformer");
+// 实现Array.toDto方法
 Array.prototype.toDto = function (dtoClass, context) {
     return __awaiter(this, void 0, void 0, function* () {
         if (!this || this.length === 0) {
@@ -20,6 +21,7 @@ Array.prototype.toDto = function (dtoClass, context) {
         return yield dto_transformer_1.DtoTransformer.transformArray(this, dtoClass, context);
     });
 };
+// 避免直接修改Object原型，改为使用独立的函数
 function transformEntityToDto(entity, dtoClass, context) {
     return __awaiter(this, void 0, void 0, function* () {
         if (!entity) {
@@ -28,21 +30,28 @@ function transformEntityToDto(entity, dtoClass, context) {
         return yield dto_transformer_1.DtoTransformer.transform(entity, dtoClass, context);
     });
 }
+// 实现QueryBuilder.toDtoPage方法
 typeorm_1.SelectQueryBuilder.prototype.toDtoPage = function (pageOptionsDto, dtoClass, context) {
     return __awaiter(this, void 0, void 0, function* () {
         const page = pageOptionsDto.page || 1;
         const pageSize = pageOptionsDto.pageSize || 10;
         const skip = (page - 1) * pageSize;
+        // 获取总数
         const total = yield this.getCount();
+        // 应用分页
         const entities = yield this.skip(skip).take(pageSize).getMany();
         const count = entities.length;
+        // 调试：输出原始实体数据
         if (count) {
             console.log('Raw entity sample:', JSON.stringify(entities[0], null, 2));
         }
+        // 转换为DTO
         const data = yield entities.toDto(dtoClass, context);
+        // 调试：输出转换后的DTO数据
         if (data.length > 0) {
             console.log('Converted DTO sample:', JSON.stringify(data[0], null, 2));
         }
+        // 计算分页信息
         const pageCount = Math.ceil(total / pageSize);
         const hasPreviousPage = page > 1;
         const hasNextPage = page < pageCount;

package/common/dto/dto-service-accessor.d.ts

@@ -1,7 +1,24 @@
 import { Constructor } from '../types';
+/**
+ * DTO服务访问器 - 使用全局容器获取服务
+ * 类似class-validator的useContainer机制
+ */
 export declare class DtoServiceAccessor {
+    /**
+     * 获取服务实例
+     */
     static getService<T = any>(serviceToken: string | symbol | Constructor<any>): Promise<T | null>;
+    /**
+     * 批量获取服务
+     */
     static getServices<T = any>(serviceTokens: Array<string | symbol | Constructor<any>>): Promise<Record<string, T>>;
+    /**
+     * 为特定DTO类获取所需服务
+     * 基于预定义的服务依赖列表
+     */
     static getServicesForDto(dtoClass: Constructor<any>): Promise<Record<string, any>>;
+    /**
+     * 检查是否已初始化
+     */
     static isInitialized(): boolean;
 }

package/common/dto/dto-service-accessor.js

@@ -11,12 +11,22 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DtoServiceAccessor = void 0;
 const dto_container_1 = require("./dto-container");
+/**
+ * DTO服务访问器 - 使用全局容器获取服务
+ * 类似class-validator的useContainer机制
+ */
 class DtoServiceAccessor {
+    /**
+     * 获取服务实例
+     */
     static getService(serviceToken) {
         return __awaiter(this, void 0, void 0, function* () {
             return yield dto_container_1.DtoContainer.get(serviceToken);
         });
     }
+    /**
+     * 批量获取服务
+     */
     static getServices(serviceTokens) {
         return __awaiter(this, void 0, void 0, function* () {
             const services = {};
@@ -33,8 +43,13 @@ class DtoServiceAccessor {
             return services;
         });
     }
+    /**
+     * 为特定DTO类获取所需服务
+     * 基于预定义的服务依赖列表
+     */
     static getServicesForDto(dtoClass) {
         return __awaiter(this, void 0, void 0, function* () {
+            // 从元数据获取服务依赖
             const serviceTokens = Reflect.getMetadata('dto:required-services', dtoClass) || [];
             if (serviceTokens.length === 0) {
                 return {};
@@ -42,6 +57,9 @@ class DtoServiceAccessor {
             return yield DtoServiceAccessor.getServices(serviceTokens);
         });
     }
+    /**
+     * 检查是否已初始化
+     */
     static isInitialized() {
         return dto_container_1.DtoContainer.isInitialized();
     }

package/common/dto/dto-transformer.d.ts

@@ -1,11 +1,23 @@
 import { Constructor } from '../types';
+/**
+ * DTO转换上下文
+ */
 export interface DtoTransformContext {
     user?: any;
     request?: any;
     services?: Record<string, any>;
     [key: string]: any;
 }
+/**
+ * 简化的DTO转换器 - 利用class-transformer和自动服务注入
+ */
 export declare class DtoTransformer {
+    /**
+     * 转换单个实体到DTO
+     */
     static transform<EntityType, DtoType>(entity: EntityType, dtoClass: Constructor<DtoType>, context?: DtoTransformContext): Promise<DtoType>;
+    /**
+     * 批量转换实体数组到DTO数组
+     */
     static transformArray<EntityType, DtoType>(entities: EntityType[], dtoClass: Constructor<DtoType>, context?: DtoTransformContext): Promise<DtoType[]>;
 }

package/common/dto/dto-transformer.js

@@ -12,7 +12,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DtoTransformer = void 0;
 const class_transformer_1 = require("class-transformer");
 const dto_service_accessor_1 = require("./dto-service-accessor");
+/**
+ * 简化的DTO转换器 - 利用class-transformer和自动服务注入
+ */
 class DtoTransformer {
+    /**
+     * 转换单个实体到DTO
+     */
     static transform(entity, dtoClass, context) {
         return __awaiter(this, void 0, void 0, function* () {
             const services = yield dto_service_accessor_1.DtoServiceAccessor.getServicesForDto(dtoClass);
@@ -27,6 +33,9 @@ class DtoTransformer {
             return (0, class_transformer_1.plainToInstance)(dtoClass, entity, options);
         });
     }
+    /**
+     * 批量转换实体数组到DTO数组
+     */
     static transformArray(entities, dtoClass, context) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!entities || entities.length === 0) {

package/common/dto/index.js

@@ -20,9 +20,11 @@ __exportStar(require("./create-translation.dto"), exports);
 __exportStar(require("./page.dto"), exports);
 __exportStar(require("./page-meta.dto"), exports);
 __exportStar(require("./page-options.dto"), exports);
+// 导出新的DTO转换功能
 __exportStar(require("./dto-service-accessor"), exports);
 __exportStar(require("./dto-decorators"), exports);
 __exportStar(require("./dto-transformer"), exports);
 __exportStar(require("./dto-extensions"), exports);
 __exportStar(require("./dto-container"), exports);
+// 需要导入扩展文件以激活原型方法扩展
 require("./dto-extensions");

package/common/examples/paginate-and-map.example.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Example usage of the paginateAndMap method with async transform
+ *
+ * This file demonstrates various ways to use the enhanced paginateAndMap method
+ * with support for both synchronous and asynchronous transform functions.
+ */
 import { Repository } from 'typeorm';
 import { PageOptionsDto } from '../dto/page-options.dto';
 export declare function basicPaginationExample(repository: Repository<any>, pageOptions: PageOptionsDto): Promise<import("..").PageDto<import("..").AbstractDto>>;

package/common/examples/paginate-and-map.example.js

@@ -1,4 +1,10 @@
 "use strict";
+/**
+ * Example usage of the paginateAndMap method with async transform
+ *
+ * This file demonstrates various ways to use the enhanced paginateAndMap method
+ * with support for both synchronous and asynchronous transform functions.
+ */
 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) {
@@ -24,6 +30,7 @@ exports.complexAsyncTransformExample = complexAsyncTransformExample;
 exports.iterateExample = iterateExample;
 exports.eachBatchSingleExample = eachBatchSingleExample;
 exports.eachBatchGroupExample = eachBatchGroupExample;
+// Example 1: Basic usage without transform
 function basicPaginationExample(repository, pageOptions) {
     return __awaiter(this, void 0, void 0, function* () {
         const result = yield repository
@@ -32,6 +39,7 @@ function basicPaginationExample(repository, pageOptions) {
         return result;
     });
 }
+// Example 2: Synchronous transform
 function syncTransformExample(repository, pageOptions) {
     return __awaiter(this, void 0, void 0, function* () {
         const result = yield repository
@@ -39,12 +47,14 @@ function syncTransformExample(repository, pageOptions) {
             .where('entity.isActive = :isActive', { isActive: true })
             .paginateAndMap(pageOptions, {
             transform: (items) => {
+                // Filter items synchronously
                 return items.filter(item => item.status === 'approved');
             },
         });
         return result;
     });
 }
+// Example 3: Async transform with external service call
 function asyncTransformExample(repository, pageOptions, externalService) {
     return __awaiter(this, void 0, void 0, function* () {
         const result = yield repository
@@ -52,16 +62,19 @@ function asyncTransformExample(repository, pageOptions, externalService) {
             .where('entity.isActive = :isActive', { isActive: true })
             .paginateAndMap(pageOptions, {
             transform: (items) => __awaiter(this, void 0, void 0, function* () {
+                // Enrich each item with data from external service
                 const enrichedItems = yield Promise.all(items.map((item) => __awaiter(this, void 0, void 0, function* () {
                     const additionalData = yield externalService.fetchData(item.id);
                     return Object.assign(Object.assign({}, item), { additionalData });
                 })));
+                // Filter after enrichment
                 return enrichedItems.filter(item => { var _a; return (_a = item.additionalData) === null || _a === void 0 ? void 0 : _a.isValid; });
             }),
         });
         return result;
     });
 }
+// Example 4: Async transform with batch processing
 function asyncBatchTransformExample(repository, pageOptions, batchProcessor) {
     return __awaiter(this, void 0, void 0, function* () {
         const result = yield repository
@@ -70,13 +83,16 @@ function asyncBatchTransformExample(repository, pageOptions, batchProcessor) {
             .paginateAndMap(pageOptions, {
             dtoOptions: { includeRelations: true },
             transform: (items) => __awaiter(this, void 0, void 0, function* () {
+                // Process items in batches for better performance
                 const processedItems = yield batchProcessor.processBatch(items);
+                // Additional filtering or transformation
                 return processedItems.map(item => (Object.assign(Object.assign({}, item), { processed: true, processedAt: new Date() })));
             }),
         });
         return result;
     });
 }
+// Example 5: Complex async transform with error handling
 function complexAsyncTransformExample(repository, pageOptions, services) {
     return __awaiter(this, void 0, void 0, function* () {
         const result = yield repository
@@ -85,6 +101,7 @@ function complexAsyncTransformExample(repository, pageOptions, services) {
             .paginateAndMap(pageOptions, {
             skipCount: false,
             transform: (items) => __awaiter(this, void 0, void 0, function* () {
+                // Step 1: Validate items
                 const validatedItems = yield Promise.all(items.map((item) => __awaiter(this, void 0, void 0, function* () {
                     try {
                         const isValid = yield services.validation.validate(item);
@@ -95,11 +112,14 @@ function complexAsyncTransformExample(repository, pageOptions, services) {
                         return null;
                     }
                 })));
+                // Filter out invalid items
                 const validItems = validatedItems.filter(item => item !== null);
+                // Step 2: Enrich with external data
                 const enrichedItems = yield Promise.all(validItems.map((item) => __awaiter(this, void 0, void 0, function* () {
                     const enrichmentData = yield services.enrichment.enrich(item.id);
                     return Object.assign(Object.assign({}, item), enrichmentData);
                 })));
+                // Step 3: Calculate derived fields
                 const finalItems = yield Promise.all(enrichedItems.map((item) => __awaiter(this, void 0, void 0, function* () {
                     const calculatedFields = yield services.calculation.calculate(item);
                     return Object.assign(Object.assign({}, item), calculatedFields);
@@ -110,6 +130,7 @@ function complexAsyncTransformExample(repository, pageOptions, services) {
         return result;
     });
 }
+// Example 6: Using iterate for large datasets
 function iterateExample(repository, processor) {
     return __awaiter(this, void 0, void 0, function* () {
         var _a, e_1, _b, _c;
@@ -117,6 +138,7 @@ function iterateExample(repository, processor) {
             .createQueryBuilder('entity')
             .where('entity.needsProcessing = :needsProcessing', { needsProcessing: true });
         try {
+            // Process large dataset in batches without loading everything into memory
             for (var _d = true, _e = __asyncValues(queryBuilder.iterate({ batchSize: 500 })), _f; _f = yield _e.next(), _a = _f.done, !_a; _d = true) {
                 _c = _f.value;
                 _d = false;
@@ -134,23 +156,27 @@ function iterateExample(repository, processor) {
         }
     });
 }
+// Example 7: Using eachBatch with individual processing
 function eachBatchSingleExample(repository, processor) {
     return __awaiter(this, void 0, void 0, function* () {
         yield repository
             .createQueryBuilder('entity')
             .where('entity.status = :status', { status: 'pending' })
             .eachBatch((entity) => __awaiter(this, void 0, void 0, function* () {
+            // Process each entity individually
             console.log(`Processing entity ${entity.id}`);
             yield processor.processOne(entity);
         }), { batchSize: 100, mode: 'single' });
     });
 }
+// Example 8: Using eachBatch with batch processing
 function eachBatchGroupExample(repository, processor) {
     return __awaiter(this, void 0, void 0, function* () {
         yield repository
             .createQueryBuilder('entity')
             .where('entity.status = :status', { status: 'pending' })
             .eachBatch((batch) => __awaiter(this, void 0, void 0, function* () {
+            // Process entire batch at once
             console.log(`Processing batch of ${batch.length} entities`);
             yield processor.processBatch(batch);
         }), { batchSize: 500, mode: 'batch' });

package/common/helpers/validation-metadata-helper.d.ts

@@ -0,0 +1,55 @@
+import type { Constructor } from '../types';
+/**
+ * 字段元数据接口（简化版）
+ * 用于在验证错误时生成友好的错误消息
+ */
+export interface ValidationMetadata {
+    /** 字段名称 */
+    fieldName?: string;
+    /** 字段标签（多语言）- 使用 fieldLabel 避免命名冲突 */
+    label?: string | {
+        zh?: string;
+        en?: string;
+        [lang: string]: string | undefined;
+    };
+    /** 字段描述（多语言）- 使用 fieldDescription 避免命名冲突 */
+    description?: string | {
+        zh?: string;
+        en?: string;
+        [lang: string]: string | undefined;
+    };
+    /** 是否为数组 */
+    each?: boolean;
+}
+/**
+ * 存储验证元数据到装饰器
+ *
+ * @param target - 目标类
+ * @param propertyKey - 属性名
+ * @param metadata - 验证元数据
+ */
+export declare function setValidationMetadata(target: Constructor<any>, propertyKey: string, metadata: ValidationMetadata): void;
+/**
+ * 获取验证元数据
+ *
+ * @param target - 目标类
+ * @param propertyKey - 属性名
+ * @returns 验证元数据
+ */
+export declare function getValidationMetadata(target: Constructor<any>, propertyKey: string): ValidationMetadata | undefined;
+/**
+ * 获取所有验证元数据
+ *
+ * @param target - 目标类
+ * @returns 所有验证元数据
+ */
+export declare function getAllValidationMetadata(target: Constructor<any>): Record<string, ValidationMetadata>;
+/**
+ * 获取字段的友好标签
+ * 根据语言环境返回对应的标签
+ *
+ * @param metadata - 验证元数据
+ * @param lang - 语言 (zh, en, 等)
+ * @returns 字段标签
+ */
+export declare function getFieldLabelForValidation(metadata: ValidationMetadata, lang?: string): string;

package/common/helpers/validation-metadata-helper.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setValidationMetadata = setValidationMetadata;
+exports.getValidationMetadata = getValidationMetadata;
+exports.getAllValidationMetadata = getAllValidationMetadata;
+exports.getFieldLabelForValidation = getFieldLabelForValidation;
+/**
+ * 验证元数据存储键
+ */
+const VALIDATION_METADATA_KEY = 'VALIDATION_METADATA_OPTIONS';
+/**
+ * 存储验证元数据到装饰器
+ *
+ * @param target - 目标类
+ * @param propertyKey - 属性名
+ * @param metadata - 验证元数据
+ */
+function setValidationMetadata(target, propertyKey, metadata) {
+    const existingMetadata = Reflect.getMetadata(VALIDATION_METADATA_KEY, target) || {};
+    existingMetadata[propertyKey] = metadata;
+    Reflect.defineMetadata(VALIDATION_METADATA_KEY, existingMetadata, target);
+}
+/**
+ * 获取验证元数据
+ *
+ * @param target - 目标类
+ * @param propertyKey - 属性名
+ * @returns 验证元数据
+ */
+function getValidationMetadata(target, propertyKey) {
+    const allMetadata = Reflect.getMetadata(VALIDATION_METADATA_KEY, target);
+    const metadata = allMetadata === null || allMetadata === void 0 ? void 0 : allMetadata[propertyKey];
+    return metadata;
+}
+/**
+ * 获取所有验证元数据
+ *
+ * @param target - 目标类
+ * @returns 所有验证元数据
+ */
+function getAllValidationMetadata(target) {
+    return Reflect.getMetadata(VALIDATION_METADATA_KEY, target) || {};
+}
+/**
+ * 获取字段的友好标签
+ * 根据语言环境返回对应的标签
+ *
+ * @param metadata - 验证元数据
+ * @param lang - 语言 (zh, en, 等)
+ * @returns 字段标签
+ */
+function getFieldLabelForValidation(metadata, lang = 'zh') {
+    if (!metadata.label) {
+        return metadata.fieldName || '';
+    }
+    if (typeof metadata.label === 'string') {
+        return metadata.label;
+    }
+    return metadata.label[lang] || metadata.label.zh || metadata.label.en || metadata.fieldName || '';
+}

package/common/index.d.ts

@@ -4,3 +4,4 @@ export * from './dto';
 export * from './types';
 export * from './snake-naming.strategy';
 export * from './boilerplate.polyfill';
+export * from './helpers/validation-metadata-helper';

package/common/index.js

@@ -20,3 +20,7 @@ __exportStar(require("./dto"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./snake-naming.strategy"), exports);
 __exportStar(require("./boilerplate.polyfill"), exports);
+// ========================================
+// Validation Metadata Helper
+// ========================================
+__exportStar(require("./helpers/validation-metadata-helper"), exports);

package/common/utils.d.ts

@@ -1,4 +1,19 @@
+/**
+ * generate hash from password or string
+ * @param {string} password
+ * @returns {string}
+ */
 export declare function generateHash(password: string): string;
+/**
+ * validate text with hash
+ * @param {string} password
+ * @param {string} hash
+ * @returns {Promise<boolean>}
+ */
 export declare function validateHash(password: string | undefined, hash: string | undefined): Promise<boolean>;
 export declare function getVariableName<TResult>(getVar: () => TResult): string;
+/**
+ * Generate a unique request ID
+ * @returns {string}
+ */
 export declare function generateRequestId(): string;

package/common/utils.js

@@ -5,9 +5,20 @@ exports.validateHash = validateHash;
 exports.getVariableName = getVariableName;
 exports.generateRequestId = generateRequestId;
 const bcrypt_1 = require("bcrypt");
+/**
+ * generate hash from password or string
+ * @param {string} password
+ * @returns {string}
+ */
 function generateHash(password) {
     return bcrypt_1.default.hashSync(password, 10);
 }
+/**
+ * validate text with hash
+ * @param {string} password
+ * @param {string} hash
+ * @returns {Promise<boolean>}
+ */
 function validateHash(password, hash) {
     if (!password || !hash) {
         return Promise.resolve(false);
@@ -23,6 +34,10 @@ function getVariableName(getVar) {
     const memberParts = fullMemberName.split('.');
     return memberParts[memberParts.length - 1];
 }
+/**
+ * Generate a unique request ID
+ * @returns {string}
+ */
 function generateRequestId() {
     return Math.random().toString(36).substring(2, 15) +
         Math.random().toString(36).substring(2, 15) +

package/constants/language-code.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.supportedLanguageCount = exports.LanguageCode = void 0;
+/* eslint-disable @typescript-eslint/naming-convention */
 var LanguageCode;
 (function (LanguageCode) {
     LanguageCode["en_US"] = "en-US";

package/decorators/field.decorators.d.ts

@@ -7,6 +7,52 @@ interface IFieldOptions {
     nullable?: boolean;
     group?: string[];
     message?: string;
+    skipValidation?: boolean;
+    /**
+     * 字段标签（多语言）
+     * 用于审计日志、验证错误消息、UI 显示等
+     */
+    fieldLabel?: string | {
+        zh?: string;
+        en?: string;
+        [lang: string]: string | undefined;
+    };
+    /**
+     * 字段描述（多语言）
+     * 用于 API 文档、审计日志等
+     */
+    fieldDescription?: string | {
+        zh?: string;
+        en?: string;
+        [lang: string]: string | undefined;
+    };
+    /**
+     * 示例值
+     * 用于 API 文档
+     */
+    fieldExample?: any;
+    /**
+     * 值标签映射（多语言）
+     * 用于枚举、布尔值的友好显示（审计日志、UI）
+     */
+    valueLabels?: {
+        [value: string]: string | {
+            zh?: string;
+            en?: string;
+            [lang: string]: string | undefined;
+        };
+    };
+    /**
+     * 格式化函数
+     * 用于自定义显示格式（审计日志）
+     * 注意：命名为 displayFormatter 避免与 ApiPropertyOptions.format 冲突
+     */
+    displayFormatter?: (value: any, language?: string) => string;
+    /**
+     * 是否敏感字段
+     * 用于审计日志脱敏
+     */
+    sensitive?: boolean;
 }
 interface INumberFieldOptions extends IFieldOptions {
     min?: number;
@@ -58,8 +104,6 @@ export declare function EnumFieldOptional<TEnum extends object>(getEnum: () => T
 export declare function ClassFieldOptional<TClass extends object>(getClass: () => TClass, options?: Omit<ApiPropertyOptions, 'type' | 'required'> & IClassFieldOptions): PropertyDecorator;
 export declare function EmailField(options?: Omit<ApiPropertyOptions, 'type'> & IStringFieldOptions & IEmailFieldOptions): PropertyDecorator;
 export declare function EmailFieldOptional(options?: Omit<ApiPropertyOptions, 'type'> & IStringFieldOptions & IEmailFieldOptions): PropertyDecorator;
-export declare function PhoneField(options?: Omit<ApiPropertyOptions, 'type'> & IFieldOptions): PropertyDecorator;
-export declare function PhoneFieldOptional(options?: Omit<ApiPropertyOptions, 'type' | 'required'> & IFieldOptions): PropertyDecorator;
 export declare function UUIDField(options?: Omit<ApiPropertyOptions, 'type' | 'format' | 'isArray'> & IFieldOptions): PropertyDecorator;
 export declare function UUIDFieldOptional(options?: Omit<ApiPropertyOptions, 'type' | 'required' | 'isArray'> & IFieldOptions): PropertyDecorator;
 export declare function URLField(options?: Omit<ApiPropertyOptions, 'type'> & IURLFieldOptions & IStringFieldOptions): PropertyDecorator;
@@ -69,11 +113,36 @@ export declare function FQDNFieldOptional(options?: Omit<ApiPropertyOptions, 'ty
 export declare function DateField(options?: Omit<ApiPropertyOptions, 'type'> & IDateFieldOptions): PropertyDecorator;
 export declare function DateFieldOptional(options?: Omit<ApiPropertyOptions, 'type' | 'required'> & IDateFieldOptions): PropertyDecorator;
 export declare function IpFieldOptional(options?: Omit<ApiPropertyOptions, 'type'> & IIPFieldOptions & IStringFieldOptions): PropertyDecorator;
-export declare function IpField(options: Omit<ApiPropertyOptions, 'type'> & IStringFieldOptions & IIPFieldOptions): PropertyDecorator;
+export declare function IpField(options?: Omit<ApiPropertyOptions, 'type'> & IStringFieldOptions & IIPFieldOptions): PropertyDecorator;
 export declare function ObjectField(options?: Omit<ApiPropertyOptions, 'type'> & IFieldOptions): PropertyDecorator;
 export declare function ObjectFieldOptional(options?: Omit<ApiPropertyOptions, 'type'> & IFieldOptions): PropertyDecorator;
 export declare function TimeZoneField(options?: Omit<ApiPropertyOptions, 'type'> & IStringFieldOptions): PropertyDecorator;
 export declare function TimeZoneFieldOptional(options?: Omit<ApiPropertyOptions, 'type'> & IStringFieldOptions): PropertyDecorator;
 export declare function LocaleField(options?: Omit<ApiPropertyOptions, 'type'> & IStringFieldOptions): PropertyDecorator;
 export declare function LocaleFieldOptional(options?: Omit<ApiPropertyOptions, 'type'> & IStringFieldOptions): PropertyDecorator;
+/**
+ * @Field 装饰器
+ *
+ * 用于只需要元数据（Swagger、审计、UI配置）而不需要验证的字段
+ *
+ * @example
+ * // 只需要 Swagger 文档和审计元数据，不需要验证
+ * @Field({
+ *   label: { zh: '备注', en: 'Remarks' },
+ *   description: { zh: '用户备注信息', en: 'User remarks' },
+ *   ui: { showInList: true, showInDetail: true },
+ * })
+ * remarks: string;
+ */
+export declare function Field(options?: Omit<ApiPropertyOptions, 'type'> & IFieldOptions & {
+    type?: 'string' | 'number' | 'boolean' | 'object' | 'array';
+}): PropertyDecorator;
+/**
+ * @FieldOptional 装饰器
+ *
+ * 可选的元数据专用字段
+ */
+export declare function FieldOptional(options?: Omit<ApiPropertyOptions, 'type' | 'required'> & IFieldOptions & {
+    type?: 'string' | 'number' | 'boolean' | 'object' | 'array';
+}): PropertyDecorator;
 export {};